Lição 1 de 3 · 10 minutos

Chame ferramentas

Descreva as suas funções, execute as chamadas que o modelo pede e envie os resultados de volta até ele responder.

Descreva as suas funções em tools, e o modelo responde com uma chamada a uma delas, como uma consulta ao banco de dados, em vez de adivinhar. O modelo nunca executa nada sozinho: o seu app executa a função e envia o resultado de volta, e então o modelo escreve a resposta final.

curl https://api.phaseo.app/v1/chat/completions \
  -H "Authorization: Bearer $PHASEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-astra",
    "messages": [
      { "role": "user", "content": "What is the weather in London?" }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get current weather by city",
          "parameters": {
            "type": "object",
            "properties": {
              "city": { "type": "string" }
            },
            "required": ["city"]
          }
        }
      }
    ]
  }'

No Chat Completions, a resposta tem finish_reason: "tool_calls" e uma lista tool_calls na mensagem do assistente, cada item com um id, o name da função e arguments como string JSON. Execute cada chamada e envie uma nova solicitação que repete a conversa, a mensagem do assistente sem alterações e uma mensagem role: "tool" por chamada, associada por tool_call_id. Envie tools de novo. O modelo responde ou chama outra ferramenta, e você repete o processo. Em /v1/responses, a chamada é um item function_call e o seu resultado é um item function_call_output com o mesmo call_id; em /v1/messages, são blocos tool_use e tool_result.

tool_choice controla se o modelo pode chamar ferramentas: none para só texto, auto (ou omita o campo) para deixar o modelo decidir, required para forçar uma chamada, ou um objeto que indica uma ferramenta. Defina parallel_tool_calls como false quando as suas ferramentas precisarem rodar uma de cada vez.

Trate cada chamada como entrada não confiável. Confira o nome da ferramenta em uma lista de permissão, rejeite nomes desconhecidos e valide os argumentos interpretados antes de executar qualquer coisa. Se a validação falhar, não execute a ferramenta: envie um erro curto como resultado da ferramenta e deixe o modelo tentar de novo. Com stream: true, junte todos os deltas dos argumentos antes de interpretá-los. As ferramentas cujo tipo começa com phaseo:, como phaseo:web_search ou phaseo:datetime, rodam do lado do Phaseo, então você recebe a resposta final sem escrever um executor. Essas ferramentas de servidor estão em Beta.

Confira o que você aprendeu

O modelo retorna uma chamada para delete_user com {"id": "42"}. O seu app só define get_weather. O que o seu código deve fazer?

Aplique

O seu bot de suporte chama get_order e depois responde. O loop de um colega envia só a mensagem role: "tool" na nova solicitação, e o provedor a rejeita. O que está faltando?

Mostrar a resposta

A nova solicitação precisa repetir a conversa, depois a mensagem do assistente com os tool_calls sem alterações e depois uma mensagem role: "tool" por chamada, com o tool_call_id correspondente. Envie tools de novo também. Um resultado de ferramenta sem uma chamada antes dele não tem com o que ser associado.

Resumo

O modelo pede, o seu app valida e executa a chamada, e você envia o resultado de volta com o ID da chamada até o modelo dar uma resposta final.

Links relacionados

O progresso fica salvo neste navegador.

Verificado em 17 de novembro de 2026