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

tool_choice e distribuição de ferramentas entre agentes

Objetivos de aprendizagem

• Configurar tool_choice (auto, any, tool forçado, none) e disable_parallel_tool_use.
• Usar seleção forçada para garantir que uma ferramenta específica seja chamada primeiro, processando os passos seguintes em turnos com auto.
• Conhecer a restrição dos modelos mais novos que rejeitam any/tool forçado com erro 400 — e as alternativas.
• Explicar por que dar muitas ferramentas a um agente (18 em vez de 4–5) degrada a confiabilidade da seleção.
• Escopar ferramentas por papel do agente, com ferramentas cross-role limitadas e substituição de ferramentas genéricas por alternativas restritas.

As quatro opções de tool_choice

Qualquer valor de tool_choice aceita "disable_parallel_tool_use": true, que limita o modelo a no máximo uma chamada de ferramenta por resposta (por padrão ele pode pedir várias em paralelo).

Forçando a primeira chamada e liberando as seguintes

Padrão de exame: garantir que extract_metadata rode antes das ferramentas de enriquecimento. A técnica é forçar a ferramenta no primeiro request e voltar a auto nos turnos seguintes:

import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "name": "extract_metadata",
        "description": "Extrai metadados estruturados de um documento. Deve rodar antes de qualquer enriquecimento.",
        "input_schema": {
            "type": "object",
            "properties": {"doc_id": {"type": "string", "description": "ID do documento"}},
            "required": ["doc_id"],
        },
    },
    {
        "name": "enrich_entities",
        "description": "Enriquece entidades ja extraidas com dados externos. Requer metadados previos.",
        "input_schema": {
            "type": "object",
            "properties": {"entities": {"type": "array", "items": {"type": "string"}}},
            "required": ["entities"],
        },
    },
]

messages = [{"role": "user", "content": "Processe o documento DOC-991."}]

# Turno 1: forca extract_metadata (funciona em claude-opus-5;
# em Opus 5.5 / Fable 5.1 retornaria 400 — la, use auto + instrucao no prompt)
first = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "extract_metadata"},
    messages=messages,
)

tool_use = next(b for b in first.content if b.type == "tool_use")
metadata_result = {"title": "Relatorio Q3", "entities": ["ACME", "Q3-2026"]}

messages.append({"role": "assistant", "content": first.content})
messages.append({
    "role": "user",
    "content": [{
        "type": "tool_result",
        "tool_use_id": tool_use.id,
        "content": str(metadata_result),
    }],
})

# Turnos seguintes: auto — o modelo decide os proximos passos
followup = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto"},
    messages=messages,
)
print(followup.stop_reason)

Muitas ferramentas degradam a seleção

Dar a um agente 18 ferramentas em vez de 4–5 aumenta a complexidade da decisão a cada turno e degrada a confiabilidade da seleção — mais descrições parecidas competindo, mais chances de misrouting e de uso indevido. Agentes com ferramentas fora da sua especialização tendem a usá-las mal: um agente de síntese com acesso a web search tende a sair pesquisando em vez de sintetizar.

Princípios de distribuição em sistemas multi-agente:

• Escopo por papel: cada subagente recebe apenas as ferramentas do seu papel (o agente de pesquisa tem busca; o de síntese, não).
• Cross-role limitado: para necessidades de alta frequência, dê uma ferramenta escopada — ex.: um verify_fact simples para o agente de síntese resolver 85% das verificações localmente, roteando os casos complexos pelo coordenador.
• Substitua genéricas por restritas: troque fetch_url (busca qualquer URL) por load_document que valida URLs de documentos permitidos — a restrição vira contrato, não torcida.

flowchart TD
    C[Coordenador] --> P[Agente de pesquisa\nweb_search, load_document]
    C --> A[Agente de análise\nextract_data_points, summarize_content]
    C --> S[Agente de síntese\ncompose_report, verify_fact*]
    S -. verificações complexas .-> C
  

Pegadinhas da prova

• Distrator típico: "dê ao agente de síntese acesso a todas as ferramentas de busca para eliminar round-trips". Viola separação de responsabilidades; a resposta certa é a ferramenta cross-role escopada para o caso frequente.
• Distrator típico: confundir any ("alguma ferramenta, obrigatoriamente") com auto ("o modelo decide"). Só any/tool garantem chamada — mas lembre da restrição 400 nos modelos mais novos.
• Pegadinha: disable_parallel_tool_use: true limita a uma chamada por resposta; não força sequência específica entre ferramentas nem garante ordem entre turnos.
• Pegadinha: em Opus 5.5/Fable 5.1, auto + disable_parallel_tool_use significa "no máximo uma" chamada; a combinação "exatamente uma" (com any) não existe mais nesses modelos.
• Distrator típico: resolver seleção ruim entre 18 ferramentas com um modelo maior. O problema é a superfície de decisão, não a capacidade — reduza e escope o conjunto de ferramentas.

Resumo em 5 linhas

Documentação oficial

• Implement tool use — tool_choice
• Tool use — Overview
• Structured outputs (alternativa ao tool forçado para JSON)

Questões de fixação