Uso de herramientas y llamadas a funciones

Permite que un modelo llame a tus funciones: el ciclo de solicitudes, ambos formatos y los errores que cuestan tokens.

El uso de herramientas permite que el modelo te pida ejecutar una función y después continuar con el resultado. Es el mecanismo en el que se basa todo agente de programación.

El ciclo

1. Envías messages junto con tools que describen lo que está disponible.
2. El modelo responde con stop_reason: tool_use y un tool_use bloque que indica el nombre de la herramienta y sus argumentos.
3. Tú lo ejecutas: la pasarela nunca ejecuta tu código.
4. Envías de nuevo todo el historial junto con un tool_result bloque.
5. El modelo produce su respuesta final o solicita otra herramienta.

Definir herramientas (formato de Messages)

Copy{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "tools": [{
    "name": "get_weather",
    "description": "Current weather for a city. Use when the user asks about weather.",
    "input_schema": {
      "type": "object",
      "properties": {"city": {"type": "string", "description": "City name"}},
      "required": ["city"]
    }
  }],
  "messages": [{"role": "user", "content": "Weather in Paris?"}]
}

Devolver un resultado

Copy{
  "role": "user",
  "content": [{
    "type": "tool_result",
    "tool_use_id": "toolu_01ABC...",
    "content": "18C, light rain"
  }]
}

Formato de OpenAI

El /v1/chat/completions el endpoint utiliza el formato de OpenAI tools / tool_calls en su lugar, con los resultados devueltos como mensajes con el rol tool.

Cuánto cuesta el uso de herramientas

• Las definiciones se vuelven a enviar en cada turno. Veinte esquemas de herramientas extensos pueden consumir la mayor parte de los tokens de entrada antes incluso de que comience la conversación.
• Los resultados pasan a formar parte del contexto. Una herramienta que devuelve 200 filas de JSON incluye todo ese contenido en la siguiente solicitud y en todas las posteriores.
• Cada intercambio es una llamada facturada. Una tarea con cinco herramientas requiere al menos seis solicitudes.
• Limita la longitud de la salida de las herramientas y resúmela antes de devolverla. Recortar un resultado para incluir solo lo que el modelo realmente necesita es el cambio con mayor impacto en la mayoría de los bucles de agentes.