Pular para o conteúdo principal

Uso de Ferramentas / Function Calling

Intermediário

O uso de ferramentas permite que o Claude chame funções que você define — busca, uma calculadora, seu banco de dados, qualquer API — e use os resultados. É a base de todo agente.

What you'll learn
  • Como funciona o loop agêntico de quatro etapas, das definições de ferramentas até a resposta final
  • Como definir uma ferramenta em Python com nome, descrição e entrada em JSON-Schema
  • Por que as descrições de ferramentas funcionam como prompts que moldam quando e como o Claude as chama
  • Como validar entradas, retornar erros como resultados e usar ferramentas server-side com segurança

O loop​

O uso de ferramentas é uma conversa, não uma única chamada. Você entrega ao Claude um cardápio de ferramentas; o Claude escolhe uma e faz uma pausa; você a executa e reporta de volta; o Claude integra o resultado em sua resposta — repetindo conforme necessário.

Guided walkthrough1 of 4
  1. Você inclui uma lista de definições de ferramentas — cada uma com um nome, uma descrição e uma entrada em JSON-Schema.

Definindo uma ferramenta (Python)​

A definição de uma ferramenta é apenas um nome, uma descrição em linguagem natural e um JSON-Schema para a entrada. Passe-a em tools, depois verifique stop_reason para saber quando o Claude quer agir.

ferramenta get_weather + primeira chamada

tools = [{
  "name": "get_weather",
  "description": "Get current weather for a city.",
  "input_schema": {
      "type": "object",
      "properties": {"city": {"type": "string"}},
      "required": ["city"],
  },
}]

msg = client.messages.create(
  model="claude-sonnet-5", max_tokens=1024,
  tools=tools,
  messages=[{"role": "user", "content": "What's the weather in Rome?"}],
)
# If msg.stop_reason == "tool_use": run the tool, then send a tool_result back.

Dicas​

Pequenas escolhas em como você define e trata as ferramentas fazem uma enorme diferença na confiabilidade.

  • Descrições são prompts. Uma description clara da ferramenta e a documentação dos parâmetros melhoram enormemente quando/como o Claude a chama.
  • Valide as entradas que você recebe antes de executar — nunca confie nelas cegamente.
  • Retorne erros como resultados. Se uma ferramenta falhar, envie um tool_result descrevendo o erro para que o Claude possa se recuperar.
  • Ferramentas server-side. A Anthropic também oferece ferramentas integradas (por exemplo, busca na web, execução de código, uso do computador) — confira a documentação para o menu atual.

:::warning Ferramentas = ações = risco Uma ferramenta que executa ações reais herda um modelo de segurança. Aplique o privilégio mínimo e mantenha um humano no loop para chamadas arriscadas — veja Protegendo Agentes e Ferramentas. :::

Vocabulário de uso de ferramentas
Pressione Enter ou Espaço para virar o cartão. Use as setas esquerda e direita para navegar entre os cartões.Termo exibido.
1 / 4

Teste seu conhecimento

0/3
  1. Depois que o Claude retorna um bloco tool_use, quem executa a ferramenta?
  2. Uma ferramenta que você definiu falha em tempo de execução. Qual é a atitude recomendada?
  3. Por que uma descrição clara da ferramenta importa tanto?
Key takeaways
  • O uso de ferramentas é um loop: envie as definições de ferramentas, o Claude retorna um bloco tool_use e para, você executa e retorna um tool_result, o Claude continua até responder.
  • A definição de uma ferramenta é um nome, uma descrição e uma entrada em JSON-Schema — passe-a em tools e verifique stop_reason == tool_use.
  • Descrições são prompts; valide as entradas antes de executar; retorne falhas como erros tool_result para que o Claude possa se recuperar.
  • A Anthropic também oferece ferramentas server-side, e qualquer ferramenta que executa ações reais precisa de privilégio mínimo mais um humano no loop.

Próximo​