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

NecesidadAPICampos
Respuestas de objetos JSON portátiles/v1/chat/completionsresponse_format: {"type": "json_object"}
Llamada a funciones compatible con OpenAI/v1/chat/completionstools: [{ "type": "function", "function": ... }]
Herramientas de respuestas de OpenAI/v1/responsesCampos tools, tool_choice y text de las respuestas
Uso de herramientas o razonamiento nativo de Claude/v1/messagesEsquema de herramientas de Anthropic Messages
Declaraciones de funciones o herramientas integradas de Gemini/v1beta/models/:model:generateContenttools 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:

  1. Envía los mensajes junto con las definiciones de las herramientas.
  2. Lee la respuesta del modelo en busca de tool_calls, function_call, tool_use de Anthropic o partes de llamadas a funciones de Gemini.
  3. Ejecuta la herramienta en tu propio backend.
  4. Adjunta el resultado de la herramienta en el mismo formato de API.
  5. 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

TemaReferencia
API multiformatoAPI multiformato
Crear Chat CompletionCrear Chat Completion
Crear respuestaCrear respuesta
Crear mensajeCrear mensaje
Generar contenido GeminiGenerar contenido Gemini

En esta página