Uso de ferramentas e chamada de funções

Permita que um modelo chame suas funções — o ciclo de requisições, ambos os formatos e os erros que custam tokens.

O uso de ferramentas permite que o modelo peça a você para executar uma função e depois continue com o resultado. Esse é o mecanismo por trás de todo agente de programação.

O ciclo

1. Você envia messages mais tools descrevendo o que está disponível.
2. O modelo responde com stop_reason: tool_use e um campo tool_use bloco que indica o nome da ferramenta e seus argumentos.
3. Você executa a ferramenta — o gateway nunca executa seu código.
4. Você envia de volta todo o histórico, mais um tool_result bloco.
5. O modelo produz sua resposta final ou solicita outra ferramenta.

Definir ferramentas (formato 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?"}]
}

Retornar um resultado

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

Formato OpenAI

O /v1/chat/completions o endpoint usa o formato da OpenAI tools / tool_calls em vez disso, com os resultados retornados como mensagens com o papel tool.

Quanto custa o uso de ferramentas

• As definições são reenviadas a cada turno. Vinte esquemas de ferramentas detalhados podem consumir a maior parte dos seus tokens de entrada antes mesmo de a conversa começar.
• Os resultados passam a fazer parte do contexto. Uma ferramenta que retorna 200 linhas de JSON inclui tudo isso na próxima solicitação e em todas as solicitações seguintes.
• Cada ciclo de solicitação e resposta é uma chamada cobrada. Uma tarefa com cinco ferramentas exige pelo menos seis solicitações.
• Limite o tamanho da saída das ferramentas e resuma antes de retornar. Reduzir um resultado ao que o modelo realmente precisa é a mudança de maior impacto na maioria dos ciclos de agentes.