Construindo um Loop de Uso de Ferramentas Multi-Turn

Repita trocas de tool_use e tool_result até que Claude retorne um end_turn.

Resumo

A API de Mensagens é sem estado - cada chamada é uma nova requisição sem memória de turnos anteriores, exceto o que você envia em messages. Quando Claude decide que uma ferramenta é necessária, ele não executa a ferramenta. Ele para de gerar, retorna um bloco tool_use descrevendo o que ele quer chamar e devolve o controle para o seu código.

Seu trabalho é executar a ferramenta, empacotar o resultado como um bloco tool_result e enviar a conversa inteira de volta. Claude então pede outra chamada de ferramenta ou produz sua resposta final. Muitas tarefas reais (pesquisar algo, agir com base no que foi encontrado, verificar o resultado) levam várias idas e vindas antes que Claude termine.

Essa troca é o "loop agêntico": chame a API, inspecione stop_reason, execute ferramentas se solicitado, anexe resultados, chame novamente. Ele termina quando response.stop_reason == "end_turn". Se você errar o loop - perder conteúdo, esquecer um stop_reason ou pular a guarda de iteração - você terá um crash na próxima chamada ou um agente que gira infinitamente.

Esta página constrói esse loop manualmente em Python com o SDK oficial anthropic, e depois mostra o atalho de nível superior Tool Runner assim que a versão manual for compreendida.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import anthropic
 
client = anthropic.Anthropic()
messages = [{"role": "user", "content": user_input}]
 
while True:
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=4096,
        tools=tools,
        messages=messages,
    )
 
    if response.stop_reason == "end_turn":
        break
 
    if response.stop_reason == "pause_turn":
        messages.append({"role": "assistant", "content": response.content})
        continue
 
    tool_use_blocks = [b for b in response.content if b.type == "tool_use"]
    messages.append({"role": "assistant", "content": response.content})
 
    tool_results = []
    for block in tool_use_blocks:
        result = execute_tool(block.name, block.input)
        tool_results.append({
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": result,
        })
    messages.append({"role": "user", "content": tool_results})
 
final_text = "".join(b.text for b in response.content if b.type == "text")

Quando usar isso:

• Claude precisa chamar uma ou mais ferramentas antes de poder dar uma resposta final (pesquisas, cálculos, efeitos colaterais).
• A tarefa pode exigir várias etapas dependentes - por exemplo, pesquisar, buscar um registro específico e depois resumir.
• Você está construindo um agente que roda sem supervisão e deve continuar funcionando até que Claude realmente termine, não apenas após uma chamada de ferramenta.
• Você deseja controle total sobre como as ferramentas são executadas (concorrência, retentativas, sandboxing) em vez de delegar isso a um framework.

Exemplo de Trabalho

import json
import anthropic
 
client = anthropic.Anthropic()
 
tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name, e.g. 'Denver'"},
            },
            "required": ["city"],
        },
    },
    {
        "name": "convert_temperature",
        "description": "Convert a temperature between Celsius and Fahrenheit.",
        "input_schema": {
            "type": "object",
            "properties": {
                "value": {"type": "number"},
                "from_unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
            },
            "required": ["value", "from_unit"],
        },
    },
]
 
 
def get_weather(city: str) -> str:
    # Stand-in for a real weather API call.
    fake_data = {"Denver": 8.0, "Miami": 29.0}
    celsius = fake_data.get(city, 20.0)
    return json.dumps({"city": city, "celsius": celsius})
 
 
def convert_temperature(value: float, from_unit: str) -> str:
    if from_unit == "celsius":
        result = value * 9 / 5 + 32
        return json.dumps({"fahrenheit": round(result, 1)})
    result = (value - 32) * 5 / 9
    return json.dumps({"celsius": round(result, 1)})
 
 
def execute_tool(name: str, tool_input: dict) -> str:
    if name == "get_weather":
        return get_weather(tool_input["city"])
    if name == "convert_temperature":
        return convert_temperature(tool_input["value"], tool_input["from_unit"])
    return json.dumps({"error": f"unknown tool: {name}"})
 
 
def run_agent(user_input: str, max_iterations: int = 12) -> str:
    messages = [{"role": "user", "content": user_input}]
    response = None
 
    for _ in range(max_iterations):
        response = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=4096,
            tools=tools,
            messages=messages,
        )
 
        if response.stop_reason == "end_turn":
            break
 
        if response.stop_reason == "pause_turn":
            messages.append({"role": "assistant", "content": response.content})
            continue
 
        if response.stop_reason == "max_tokens":
            raise RuntimeError("Response truncated at max_tokens; increase the limit.")
 
        if response.stop_reason == "refusal":
            raise RuntimeError(f"Claude declined the request: {response.stop_reason}")
 
        tool_use_blocks = [b for b in response.content if b.type == "tool_use"]
        messages.append({"role": "assistant", "content": response.content})
 
        if not tool_use_blocks:
            # No tool calls and no end_turn - nothing left to do safely.
            break
 
        tool_results = []
        for block in tool_use_blocks:
            result = execute_tool(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result,
            })
        messages.append({"role": "user", "content": tool_results})
    else:
        raise RuntimeError("Exceeded max_iterations without reaching end_turn.")
 
    return "".join(b.text for b in response.content if b.type == "text")
 
 
if __name__ == "__main__":
    answer = run_agent(
        "What's the weather in Denver right now, in Fahrenheit?"
    )
    print(answer)

O que isso demonstra:

• Um loop limitado (for _ in range(max_iterations)) que sempre termina, com um RuntimeError levantado pela cláusula for...else se Claude nunca atingir end_turn.
• O response.content completo - não apenas texto extraído - anexado como o turno do assistente para que os blocos tool_use que Claude emitiu sejam visíveis na próxima chamada.
• Um tool_use_id correspondente para cada bloco tool_use, agrupado em uma única mensagem user por turno (necessário quando Claude solicita chamadas de ferramentas paralelas).
• Tratamento explícito para pause_turn, max_tokens e refusal, juntamente com os dois caminhos "continuar loop" (tool_use e end_turn).
• Um único despachante execute_tool que mantém o roteamento de ferramentas em um só lugar, em vez de cadeias if/elif espalhadas perto da chamada da API.

Mergulho Profundo

Como Funciona

• Cada chamada client.messages.create() é independente. A API não tem estado de sessão - tudo o que Claude "lembra" é o que você incluiu em messages naquela chamada.
• Quando Claude quer uma ferramenta, ele para de gerar saída e retorna blocos de conteúdo - algum text (raro no meio do loop, mas possível), um ou mais blocos tool_use, e um stop_reason.
• Seu código executa a(s) ferramenta(s) solicitada(s) localmente (ou via um conector) e relata de volta com blocos tool_result, correspondendo à chamada original via tool_use_id.
• A próxima chamada messages.create() reenvia toda a conversa crescente - turno original do usuário, turno do assistente de Claude com blocos tool_use, seu turno user com blocos tool_result - para que Claude tenha o contexto completo para continuar ou concluir.
• O loop não é um "chame a ferramenta, obtenha a resposta" de tiro único; Claude pode encadear várias chamadas de ferramentas (pesquisar algo, agir sobre isso, verificar) antes de ter informações suficientes para responder, por isso o looping - não uma única requisição/resposta - é o modelo mental correto.

Valores de stop_reason e O Que Fazer

Formato da Mensagem em Cada Etapa

# After turn 1 (Claude requests a tool call):
messages == [
    {"role": "user", "content": "What's the weather in Denver?"},
    {"role": "assistant", "content": [ToolUseBlock(id="toolu_01...", name="get_weather", input={"city": "Denver"})]},
]
 
# After you execute the tool and append the result:
messages == [
    {"role": "user", "content": "What's the weather in Denver?"},
    {"role": "assistant", "content": [ToolUseBlock(...)]},
    {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "toolu_01...", "content": "..."}]},
]

Notas Python

# Prefer a dispatch dict over long if/elif chains as the tool count grows:
TOOL_HANDLERS = {
    "get_weather": lambda i: get_weather(i["city"]),
    "convert_temperature": lambda i: convert_temperature(i["value"], i["from_unit"]),
}
 
def execute_tool(name: str, tool_input: dict) -> str:
    handler = TOOL_HANDLERS.get(name)
    if handler is None:
        return json.dumps({"error": f"unknown tool: {name}"})
    try:
        return handler(tool_input)
    except Exception as exc:
        # Report failures back to Claude as data, not a crashed process.
        return json.dumps({"error": str(exc)})

Parâmetros e Valores de Retorno

Armadilhas

• Anexar apenas o texto extraído, não response.content. Se você enviar {"role": "assistant", "content": final_text} em vez dos blocos de conteúdo brutos, a próxima solicitação de Claude perderá os blocos tool_use que sua mensagem tool_result deveria responder, e a API rejeitará a mensagem tool_result de acompanhamento porque ela não corresponde a uma chamada de ferramenta anterior. Correção: sempre anexe response.content inalterado como o turno do assistente.
• Sem limite de iteração. Um loop que só sai em end_turn girará para sempre se uma ferramenta continuar retornando dados ambíguos ou se o modelo ficar preso solicitando a mesma chamada repetidamente. Correção: envolva o loop em for _ in range(max_iterations) (10-15 é um padrão razoável) e levante/registre um timeout quando ele estiver esgotado.
• Tratar pause_turn como um turno normal de tool_use. Enviar uma nova mensagem de usuário "Continuar" após pause_turn (em vez de reenviar o turno pausado como está) confunde o estado da ferramenta do lado do servidor retomada. Correção: anexe response.content e chame a API novamente imediatamente, sem mensagem de usuário adicional.
• tool_use_id incompatível ou ausente. Cada tool_result deve referenciar o id do bloco tool_use ao qual responde; pular um bloco (por exemplo, quando Claude solicita duas chamadas paralelas, mas você lida apenas com uma) deixa a API esperando por uma chamada de ferramenta não resolvida. Correção: itere sobre todos os blocos tool_use na resposta e produza exatamente um tool_result por bloco, agrupado em uma única mensagem user.
• Deixar uma exceção de ferramenta travar o loop. Uma exceção não capturada dentro de execute_tool mata toda a requisição em vez de dar a Claude a chance de se recuperar (por exemplo, retentar com argumentos diferentes). Correção: capture exceções por ferramenta e retorne-as como conteúdo tool_result (por exemplo, {"error": "..."}) para que Claude possa reagir.
• Ignorar max_tokens como um motivo de parada. Tratar max_tokens como end_turn envia silenciosamente uma resposta truncada ao usuário. Correção: verifique explicitamente e levante max_tokens na próxima chamada ou mude para streaming.
• Retentar cegamente em refusal. Repetir o mesmo prompt após uma recusa de segurança desperdiça chamadas e não mudará o resultado. Correção: inspecione stop_details, ajuste a solicitação ou escale para um humano em vez de retentar verbatim.

Alternativas

FAQs

Relacionados

• Lidando com Requisições tool_use e Retornando Blocos tool_result - a mecânica de turno único que este loop repete em cada iteração.
• Executando Chamadas de Ferramentas Paralelas em um Único Turno - como lidar com múltiplos blocos tool_use retornados em um único turno.
• Noções Básicas de Uso de Ferramentas - os conceitos fundamentais (ferramentas, tool_choice, esquemas) nos quais esta página se baseia.
• Melhores Práticas - orientação mais ampla para uso de ferramentas confiável e pronto para produção.

Versões da Pilha: Escrito contra a linha de modelos Claude atualizada em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o SDK oficial anthropic para Python (última versão 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.