> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Salidas Estructuradas y Llamadas a Herramientas

> Utiliza el modo JSON, herramientas de función y rutas de herramientas nativas sin asumir que cada modelo soporta el mismo contrato.

Las salidas estructuradas y las llamadas a herramientas son contratos específicos de ruta. TokenLab reenvía varios formatos de API públicos, por lo que el patrón de producción más seguro es mantener cada forma nativa de herramienta del proveedor en la ruta que la posee y validar la salida del modelo en tu propia aplicación.

## Elegir La Ruta

| Necesidad                                                      | Ruta                                    | Usa esta forma                                       |
| -------------------------------------------------------------- | --------------------------------------- | ---------------------------------------------------- |
| Respuestas de objeto JSON portátiles                           | `/v1/chat/completions`                  | `response_format: {"type": "json_object"}`           |
| Llamadas a funciones compatibles con OpenAI                    | `/v1/chat/completions`                  | `tools: [{ "type": "function", "function": ... }]`   |
| Herramientas de Respuestas de OpenAI                           | `/v1/responses`                         | Campos de respuestas `tools`, `tool_choice` y `text` |
| Uso de herramientas nativas de Claude o pensamiento            | `/v1/messages`                          | Esquema de herramienta de Mensajes de Anthropic      |
| Declaraciones de funciones de Gemini o herramientas integradas | `/v1beta/models/:model:generateContent` | `tools` nativos de Gemini y partes de contenido      |

No envíes herramientas integradas nativas del proveedor a través de una ruta diferente y esperes que TokenLab las traduzca silenciosamente.

## Modo JSON

Para respuestas estructuradas portátiles, comienza con el modo JSON de Chat Completions:

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

La validación compartida estable para Chat Completions acepta `text` y `json_object`. Puede existir `json_schema`, `strict` y aplicación de esquemas específicos del proveedor para algunas rutas o caminos de conversión, pero no son una promesa generalizada en cada ruta y modelo de TokenLab. Verifícalos contra el modelo seleccionado antes de confiar en ellos.

Siempre analiza y valida el JSON devuelto en tu servidor. El modo JSON mejora la forma, pero no reemplaza la validación de esquema a nivel de aplicación.

## Bucle de Llamadas a Herramientas

TokenLab no ejecuta tus funciones. Tu aplicación posee el bucle:

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.

Mantén la misma ruta a lo largo de un bucle de herramientas. Mezclar Chat Completions, Responses, Messages y formatos de Gemini en una conversación generalmente crea errores sutiles de estado y esquema.

## Ejemplo de Chat Completions

```bash theme={null}
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

| Tema                        | Referencia                                                               |
| --------------------------- | ------------------------------------------------------------------------ |
| API de Múltiples Formatos   | [API de Múltiples Formatos](/es/guides/api-formats)                      |
| Crear Chat Completion       | [Crear Chat Completion](/es/api-reference/chat/create-completion)        |
| Crear Respuesta             | [Crear Respuesta](/es/api-reference/responses/create-response)           |
| Crear Mensaje               | [Crear Mensaje](/es/api-reference/messages/create-message)               |
| Generar Contenido de Gemini | [Generar Contenido de Gemini](/es/api-reference/gemini/generate-content) |