Source: https://aiprimetech.io/pt/docs/api-reference/tool-use/

[Início](/pt/) / [Documentação](/pt/docs/) / Uso de ferramentas e chamada de funções 

# 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. 

 Copiar página [ Ver como Markdown](/pt/docs/api-reference/tool-use.md) [ Perguntar ao ChatGPT](https://chatgpt.com/?q=Read%20https%3A//aiprimetech.io/docs/api-reference/tool-use.md%20and%20answer%20questions%20about%20it.%20Start%20with%20a%20short%20summary.) [ Perguntar no Claude](https://claude.ai/new?q=Read%20https%3A//aiprimetech.io/docs/api-reference/tool-use.md%20and%20answer%20questions%20about%20it.%20Start%20with%20a%20short%20summary.)   

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 
- Você envia messages mais tools descrevendo o que está disponível.
- O modelo responde com stop_reason: tool_use e um campo tool_use bloco que indica o nome da ferramenta e seus argumentos.
- Você executa a ferramenta — o gateway nunca executa seu código.
- Você envia de volta todo o histórico, mais um tool_result bloco.
- 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"
  }]
}
```

tool_result é incluído em uma mensagem com o papel user e tool_use_id deve corresponder exatamente ao id da solicitação do modelo. Ids que não correspondem são rejeitados como uma solicitação inválida. 

## 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. 

Os esquemas de ferramentas permanecem estáveis entre os turnos, o que os torna um forte [o cache de prompts](/pt/docs/guides/prompt-caching/) candidato, junto com o prompt do sistema. 

[API de mensagensReferência básica](/pt/docs/api-reference/messages/)[Controle de custosOnde os tokens dos agentes são gastos](/pt/docs/guides/cost-control/)[Servidores MCPFerramentas prontas para Claude Code](/pt/docs/guides/mcp-servers/) 

[AnteriorLimites de requisições](/pt/docs/api-reference/rate-limits/)[PróximoVisão e entrada de imagens](/pt/docs/api-reference/vision/)