Herramientas de servidor
Las herramientas de servidor son capacidades que Synthorai ejecuta por ti dentro de una sola petición: el modelo pide algo, hacemos el trabajo y el resultado vuelve en la misma respuesta. Añades una entrada a tools — no hay segundo endpoint ni callback que implementar.
Herramientas disponibles
Cada herramienta de servidor se identifica con el prefijo synthorai:, así que nunca colisiona con tus propios nombres de herramientas:
| Parámetro | Descripción | Precio |
|---|---|---|
synthorai:web_search | Buscar en la web y leer los resultados. | $0.01 |
synthorai:web_fetch | Leer el texto completo de una página cuya URL ya tienes. | $0.01 |
El contrato compartido
Toda herramienta de servidor se comporta igual, así que lo que aprendes de una aplica a la siguiente:
- Solo opt-in. Nada se ejecuta salvo que pongas la herramienta en
tools. Una petición sin ella es una petición ordinaria. - Un solo viaje de ida y vuelta. Nosotros conducimos el bucle de herramientas por ti; recibes una única respuesta con la actividad de la herramienta y la respuesta ya incluidas.
- Tus propias herramientas siguen funcionando. Las herramientas de servidor y tus herramientas function pueden declararse juntas — cuando el modelo llama a una de las tuyas, te devolvemos el control con un honesto
stop_reason: tool_use. (Una excepción: los nombres que inyectamos están reservados — ver abajo.) - Precio por llamada, visible en usage. Los contadores quedan en
usage.server_tool_usey el cargo enusage.cost, así cada petición puede conciliarse con su factura. max_useses un tope real. Limita lo que una sola petición puede gastar, y se mantiene a través de los reintentos internos.
Los tokens son la otra mitad del coste
La tarifa por llamada de una herramienta de servidor es solo parte de lo que cuesta una petición. Lo que la herramienta trae — fragmentos de búsqueda, el cuerpo de una página — entra en la conversación como tokens de entrada y se factura a la tarifa normal del modelo. En páginas largas ese coste en tokens suele ser el número mayor. Y como el gateway ejecuta el bucle internamente, usage.input_tokens es la suma de todos los turnos internos, notablemente mayor que el prompt que enviaste. Es el coste real de devolver resultados al modelo, no doble facturación.
Continuar la conversación
Vuelve a añadir el mensaje assistant a messages exactamente como lo recibiste, incluidos los bloques de herramientas. Sigue declarando la misma herramienta de servidor en las peticiones siguientes para que el historial conserve su forma más rica; si quitas la herramienta, los resultados anteriores se aplanan a texto plano y el modelo sigue viendo el contenido.
Nombres de herramienta reservados
Mientras usas un parámetro synthorai:, el nombre desnudo correspondiente queda reservado: declarar tu propia herramienta llamada web_search junto a synthorai:web_search (o web_fetch junto a synthorai:web_fetch) devuelve un 400 que nombra la herramienta. Renombra la tuya, o quita el parámetro synthorai:.
La razón es que inyectamos la herramienta de servidor con ese nombre exacto: dos herramientas llegarían al modelo con un solo nombre y nadie podría saber de quién es la llamada que vuelve — los argumentos de tu herramienta podrían ir a nuestro proveedor de búsqueda, y tu llamada podría perderse. Rechazar la petición es la única respuesta honesta. Declarar una herramienta propia con cualquiera de los nombres sin el parámetro synthorai: correspondiente no se ve afectado: no inyectamos nada, así que nada colisiona.
Los fallos no se cobran
La tarifa por llamada se cobra por llamadas que produjeron un resultado. Una llamada que rechazamos antes de salir de nuestra red — URL rechazada, dominio bloqueado, backend sin configurar — no te cuesta nada. Una llamada que llegó al proveedor y falló allí se cobra, porque el proveedor nos cobró. En ambos casos la ronda cuenta contra tu presupuesto de max_uses, así que un modelo reintentando una URL rota no puede iterar gratis.
Qué endpoints lo soportan
Las herramientas de servidor funcionan en /v1/messages, /v1/chat/completions y /v1/responses. Enviar un parámetro synthorai: a un endpoint que no las admite — un endpoint Gemini — devuelve un 400 que te lo dice. Preferimos rechazar antes que pasar una herramienta desconocida aguas arriba, donde el mejor caso es un error confuso de terceros y el peor es que se ignore en silencio, la búsqueda nunca ocurra y pagues una petición normal que calladamente hizo menos de lo pedido.
Disponibilidad
Las herramientas de servidor se habilitan por clave de API. Si una herramienta no está habilitada para tu clave, recibes un 400 explícito que la nombra, en lugar de un parámetro ignorado en silencio. Contáctanos para activarla.