Domínio 2 — Tool Design & MCP Integration · Lição 4 de 6

Ferramentas server-side, programmatic tool calling e tool search

Objetivos de aprendizagem

• Diferenciar ferramentas server-side (executam na infraestrutura da Anthropic) de client-side (seu código executa e devolve tool_result).
• Declarar web search, web fetch e code execution e tratar o stop_reason: "pause_turn" do loop server-side.
• Explicar programmatic tool calling (PTC): o script no container chama ferramentas com allowed_callers e só o resultado final volta ao contexto do modelo.
• Usar tool search com defer_loading para bibliotecas grandes de ferramentas sem carregar todos os schemas no contexto.
• Saber quais desses recursos são beta e devem ser sinalizados como tal.

Server-side vs client-side

Declarações atuais (server-side não têm input_schema — só type versionado e name):

[
  { "type": "web_search_20260209", "name": "web_search" },
  { "type": "web_fetch_20260209", "name": "web_fetch" },
  { "type": "code_execution_20260120", "name": "code_execution" }
]

• Web search / web fetch (_20260209): incluem dynamic filtering — o modelo filtra resultados via código antes de entrarem no contexto, sem precisar declarar code_execution à parte.
• Code execution: container isolado (Python 3.11, sem internet), persiste 30 dias e pode ser reutilizado passando container=container_id; dá acesso a sub-tools de bash e edição de arquivos.

Programmatic tool calling (beta)

No tool use padrão, cada chamada é um round trip: chamada → resultado no contexto → raciocínio → próxima chamada. Com PTC, o modelo escreve um script que roda no container de code execution; quando o script invoca uma ferramenta, o container pausa, a chamada executa e o resultado volta para o código em execução — não para o contexto do modelo. Loops, filtros e agregações acontecem em código, e só a saída final retorna ao modelo.

Para permitir que uma ferramenta custom seja chamada de dentro do container, marque-a com allowed_callers apontando para a ferramenta de code execution (recurso beta):

{
  "name": "get_order",
  "description": "Retorna um pedido pelo ID.",
  "input_schema": {
    "type": "object",
    "properties": { "order_id": { "type": "string" } },
    "required": ["order_id"]
  },
  "allowed_callers": ["code_execution_20260120"]
}

Quando usar: muitas chamadas encadeadas, ou resultados intermediários grandes que devem ser filtrados antes de chegar ao contexto (ex.: iterar 500 pedidos e devolver só o agregado). O custo de tokens escala com a saída final, não com os intermediários.

flowchart TD
    M[Modelo] -->|escreve script| CE[Container de code execution]
    CE -->|invoca get_order em loop| T[Ferramenta client-side]
    T -->|resultado volta ao script| CE
    CE -->|apenas saída final| M
  

Tool search com defer_loading (beta)

Com centenas de ferramentas, carregar todos os schemas no contexto é caro e degrada a seleção. O tool search (recurso beta) deixa o modelo descobrir ferramentas sob demanda: você declara as ferramentas com "defer_loading": true — elas ficam conhecidas pelo request, mas fora do contexto — e inclui a ferramenta de busca; o modelo pesquisa e apenas os schemas relevantes são carregados.

{
  "tools": [
    { "type": "tool_search_tool_20251119", "name": "tool_search_tool" },
    {
      "name": "get_weather",
      "description": "Clima atual por cidade.",
      "input_schema": { "type": "object", "properties": { "city": { "type": "string" } } },
      "defer_loading": true
    }
  ]
}

Exemplo Python: code execution com pause_turn

import anthropic

client = anthropic.Anthropic()

tools = [{"type": "code_execution_20260120", "name": "code_execution"}]
user_query = "Calcule media e desvio padrao de [3, 7, 8, 12, 14] e explique."
messages = [{"role": "user", "content": user_query}]

max_continuations = 5
continuations = 0

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    thinking={"type": "adaptive"},
    tools=tools,
    messages=messages,
)

# O loop server-side pode pausar: reenvie para o servidor retomar
while response.stop_reason == "pause_turn" and continuations < max_continuations:
    continuations += 1
    messages = [
        {"role": "user", "content": user_query},
        {"role": "assistant", "content": response.content},
    ]
    response = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        thinking={"type": "adaptive"},
        tools=tools,
        messages=messages,
    )

for block in response.content:
    if block.type == "text":
        print(block.text)
    elif block.type == "bash_code_execution_tool_result":
        print("stdout:", block.content.stdout)

Pegadinhas da prova

• Distrator típico: "implemente a função de web_search no cliente e devolva tool_result". Server tools executam na Anthropic — não há função para implementar; basta declarar.
• Pegadinha: pause_turn não é erro nem fim da conversa: reenvie usuário + resposta do assistant, sem mensagem "Continue" extra.
• Distrator típico: resolver "resultados intermediários enormes no contexto" com um modelo de janela maior. PTC é a resposta: intermediários ficam no container e só o final volta ao modelo.
• Pegadinha: tool search anexa schemas (preserva cache); trocar o array tools entre turnos invalida o prefixo do cache inteiro.
• Pegadinha de versão: web search/fetch _20260209 já filtram dinamicamente — declarar code_execution junto sem necessidade própria cria um segundo ambiente de execução e pode confundir o modelo.

Resumo em 5 linhas

Documentação oficial

• Code execution tool
• Web search tool
• Programmatic tool calling
• Tool search tool

Questões de fixação