Domínio 1 — Agentic Architecture & Orchestration · Lição 2 de 7

Tool use no loop: histórico, tool_result e paralelismo

Objetivos de aprendizagem

• Anexar corretamente o turno do assistente ao histórico: response.content inteiro, incluindo os blocos tool_use.
• Construir mensagens tool_result com o tool_use_id correspondente.
• Tratar chamadas paralelas de ferramentas: todos os resultados em uma única mensagem user.
• Sinalizar falhas de execução com is_error: true para que o modelo possa se recuperar.
• Implementar um loop manual completo em Python, do jeito que a prova espera.

Por que o histórico importa tanto

A Messages API é stateless: cada requisição envia a conversa inteira. No agentic loop, é o histórico acumulado que permite ao modelo incorporar os resultados das ferramentas ao raciocínio da próxima iteração. Entre uma iteração e outra, você anexa dois itens ao histórico:

1. O turno do assistente: {"role": "assistant", "content": response.content} — o response.content completo, com blocos de texto, thinking e tool_use. Se você anexar só o texto, os blocos tool_use se perdem e a API rejeita os tool_result seguintes, que ficariam órfãos (cada tool_result precisa referenciar um tool_use existente no histórico).
2. Os resultados: uma mensagem {"role": "user", "content": [ ...blocos tool_result... ]}.

Anatomia do tool_result

Cada bloco tool_result tem três campos que caem na prova:

• tool_use_id — obrigatório; deve ser exatamente o id do bloco tool_use que o originou. É assim que o modelo casa pedido e resposta.
• content — o resultado (string ou lista de blocos, inclusive imagens).
• is_error — opcional; true quando a execução falhou. O modelo então tenta outra abordagem ou explica o problema, em vez de tratar a mensagem de erro como dado válido.

Chamadas paralelas de ferramentas

Por padrão, o Claude pode pedir várias ferramentas no mesmo turno (vários blocos tool_use em um único response.content) quando as ações são independentes — por exemplo, consultar o cliente e o pedido ao mesmo tempo. As regras:

• Execute todas as chamadas pedidas (idealmente em paralelo, já que são independentes).
• Devolva todos os tool_result na mesma e única mensagem user — um bloco por tool_use, cada um com seu tool_use_id. Enviar cada resultado em uma mensagem user separada é anti-padrão e pode quebrar o pareamento pedido/resposta.
• Para forçar no máximo uma ferramenta por turno, use disable_parallel_tool_use: true dentro de tool_choice.

sequenceDiagram
    participant U as Aplicação
    participant C as Claude
    U->>C: messages.create(tools, histórico)
    C-->>U: stop_reason tool_use
2 blocos tool_use (get_customer, lookup_order)
    U->>U: executa as 2 ferramentas (em paralelo)
    U->>C: 1 mensagem user com 2 tool_result
(cada um com seu tool_use_id)
    C-->>U: stop_reason end_turn (resposta final)
  

Loop manual completo

Este é o esqueleto de referência que junta tudo: histórico completo, resultados paralelos em uma única mensagem user e is_error para falhas:

import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_customer",
        "description": "Retorna dados do cliente a partir do e-mail verificado. "
                       "Use antes de qualquer operacao de pedido ou reembolso.",
        "input_schema": {
            "type": "object",
            "properties": {"email": {"type": "string"}},
            "required": ["email"],
        },
    },
    {
        "name": "lookup_order",
        "description": "Busca detalhes de um pedido pelo numero. "
                       "Use quando o cliente mencionar um pedido especifico.",
        "input_schema": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
]

def execute_tool(name, tool_input):
    """Executa a ferramenta e retorna (conteudo, houve_erro)."""
    try:
        if name == "get_customer":
            return '{"customer_id": "C-981", "verified": true}', False
        if name == "lookup_order":
            return '{"order_id": "4412", "status": "shipped"}', False
        return "Ferramenta desconhecida: " + name, True
    except Exception as exc:
        return "Erro ao executar %s: %s" % (name, exc), True

messages = [{
    "role": "user",
    "content": "Sou ana@exemplo.com; o pedido 4412 chegou danificado.",
}]

while True:
    response = client.messages.create(
        model="claude-opus-5",
        max_tokens=8000,
        tools=tools,
        messages=messages,
    )

    if response.stop_reason != "tool_use":
        break  # end_turn (ou outro stop_reason tratado fora do exemplo)

    # 1) anexa o turno do assistente INTEIRO (texto + tool_use)
    messages.append({"role": "assistant", "content": response.content})

    # 2) executa todas as chamadas do turno e junta os resultados
    tool_results = []
    for block in response.content:
        if block.type == "tool_use":
            content, failed = execute_tool(block.name, block.input)
            result = {
                "type": "tool_result",
                "tool_use_id": block.id,  # casa com o pedido
                "content": content,
            }
            if failed:
                result["is_error"] = True
            tool_results.append(result)

    # 3) TODOS os resultados numa unica mensagem user
    messages.append({"role": "user", "content": tool_results})

final_text = next((b.text for b in response.content if b.type == "text"), "")
print(final_text)

Pegadinhas da prova

• Distrator típico: anexar ao histórico apenas o texto do assistente. Sem os blocos tool_use, os tool_result ficam órfãos → erro 400.
• Distrator típico: enviar cada tool_result de chamadas paralelas em mensagens user separadas. O correto é uma única mensagem user com todos os blocos.
• Distrator típico: em caso de falha da ferramenta, lançar exceção e abortar o loop, ou devolver o erro como se fosse resultado válido. O correto é tool_result com is_error: true e mensagem informativa — o modelo se recupera sozinho.
• Distrator típico: inventar um tool_use_id ou reutilizar o mesmo id para vários resultados. Cada resultado referencia exatamente o id do seu pedido.
• Distrator típico: "responda ao tool_use com uma mensagem assistant". tool_result sempre vai em mensagem com role: "user".

Resumo em 5 linhas

Documentação oficial

• Tool use overview
• Implement tool use
• Handling stop reasons

Questões de fixação