Salidas Estructuradas y Llamadas a Herramientas

​

Elegir La Ruta

​

Modo JSON

{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "Devuelve un objeto JSON con ciudad y clima."
    }
  ],
  "response_format": { "type": "json_object" }
}

​

Bucle de Llamadas a Herramientas

1. Envía mensajes más definiciones de herramientas.
2. Lee la respuesta del modelo para tool_calls, function_call, tool_use de Anthropic o partes de llamada a función de Gemini.
3. Ejecuta la herramienta en tu propio backend.
4. Agrega el resultado de la herramienta en el formato requerido por la misma ruta.
5. Continúa la conversación hasta que el modelo devuelva una respuesta final.

​

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.4",
    "messages": [
      {
        "role": "user",
        "content": "Extrae nombre y correo electrónico como JSON. Si es necesario, busca al cliente."
      }
    ],
    "response_format": { "type": "json_object" },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_customer",
          "description": "Busca un cliente por correo electrónico",
          "parameters": {
            "type": "object",
            "properties": {
              "email": { "type": "string" }
            },
            "required": ["email"]
          }
        }
      }
    ]
  }'

​

Diseño de Esquema

• Mantén los esquemas pequeños y explícitos. Los esquemas anidados grandes añaden tokens y reducen la fiabilidad.
• Prefiere campos requeridos para valores sin los cuales tu producto no puede continuar.
• Usa enums para conjuntos cerrados de los que tu UI o backend dependen.
• Incluye ejemplos en el prompt cuando el modelo tiene dificultades con una forma.
• Trata los errores de campo no soportado como retroalimentación del contrato. Elimina el campo o utiliza la ruta nativa que lo documenta.

​

Lista de Verificación de Producción

• Registra la ruta, modelo, nombres de herramientas y forma de esquema saneada en los logs.
• Valida los argumentos de la herramienta antes de ejecutar cualquier efecto secundario.
• Aplica tus propias verificaciones 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 API