Guías principales
Structured Outputs & Tool Calling
Devuelve JSON o permite que un modelo llame a funciones en tu aplicación
La salida estructurada solicita JSON a un modelo. La llamada a herramientas (tool calling) permite que el modelo solicite una función que tu aplicación ejecuta. Los campos disponibles dependen del formato de la API y del modelo, así que mantén un formato constante durante toda la conversación y valida cada valor producido por el modelo en tu aplicación.
Elige un formato de API
| Necesidad | API | Campos |
|---|---|---|
| Respuestas de objetos JSON portátiles | /v1/chat/completions | response_format: {"type": "json_object"} |
| Llamada a funciones compatible con OpenAI | /v1/chat/completions | tools: [{ "type": "function", "function": ... }] |
| Herramientas de respuestas de OpenAI | /v1/responses | Campos tools, tool_choice y text de las respuestas |
| Uso de herramientas o razonamiento nativo de Claude | /v1/messages | Esquema de herramientas de Anthropic Messages |
| Declaraciones de funciones o herramientas integradas de Gemini | /v1beta/models/:model:generateContent | tools y partes de contenido nativas de Gemini |
Utiliza las herramientas integradas solo con el formato de API que las documenta; TokenLab no convierte esas herramientas entre formatos.
Modo JSON
Para obtener un objeto JSON que funcione en muchos modelos de chat, utiliza el modo JSON de Chat Completions:
{
"model": "gpt-5.6-terra",
"messages": [
{
"role": "user",
"content": "Return a JSON object with city and weather."
}
],
"response_format": { "type": "json_object" }
}Los modelos que admiten el modo JSON listan json-mode en capabilities dentro de GET /v1/models. Chat Completions acepta text y json_object. json_schema y strict son específicos del modelo y del formato; úsalos solo cuando el modelo seleccionado documente su compatibilidad.
Analiza y valida siempre el JSON devuelto en tu servidor. El modo JSON no reemplaza la validación de esquemas a nivel de aplicación.
Completa una llamada a herramienta
TokenLab devuelve el nombre de la función y los argumentos; tu aplicación los ejecuta:
- Envía los mensajes junto con las definiciones de las herramientas.
- Lee la respuesta del modelo en busca de
tool_calls,function_call,tool_usede Anthropic o partes de llamadas a funciones de Gemini. - Ejecuta la herramienta en tu propio backend.
- Adjunta el resultado de la herramienta en el mismo formato de API.
- Continúa la conversación hasta que el modelo devuelva una respuesta final.
Mantén el mismo formato de API hasta que la llamada a la herramienta y la respuesta final se hayan completado. Los cuatro formatos representan el estado de la herramienta de manera diferente.
Ejemplo de Chat Completions
curl https://api.tokenlab.sh/v1/chat/completions \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-terra",
"messages": [
{
"role": "user",
"content": "Extract name and email as JSON. If needed, look up the customer."
}
],
"response_format": { "type": "json_object" },
"tools": [
{
"type": "function",
"function": {
"name": "lookup_customer",
"description": "Look up a customer by email",
"parameters": {
"type": "object",
"properties": {
"email": { "type": "string" }
},
"required": ["email"]
}
}
}
]
}'Escribe un esquema útil
- Mantén los esquemas pequeños y explícitos. Los esquemas anidados grandes añaden tokens y reducen la fiabilidad.
- Prefiere campos obligatorios para los valores sin los cuales tu producto no puede continuar.
- Usa enums para conjuntos cerrados de los que dependa tu interfaz o backend.
- Incluye ejemplos en el prompt cuando el modelo tenga dificultades con una estructura.
- Si un campo no es compatible, elimínalo o utiliza un formato de API que lo documente.
Antes de ejecutar una herramienta
- Registra el formato de la API, el modelo, los nombres de las herramientas y los nombres de los campos del esquema.
- Valida los argumentos de la herramienta antes de ejecutar cualquier efecto secundario.
- Aplica tus propias comprobaciones de permisos antes de la ejecución de la herramienta.
- Haz que la ejecución de la herramienta sea idempotente cuando un reintento del cliente pueda repetir la misma llamada a la herramienta.
- No registres secretos devueltos por herramientas en mensajes visibles para el modelo.
Referencia de la API
| Tema | Referencia |
|---|---|
| API multiformato | API multiformato |
| Crear Chat Completion | Crear Chat Completion |
| Crear respuesta | Crear respuesta |
| Crear mensaje | Crear mensaje |
| Generar contenido Gemini | Generar contenido Gemini |