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

Quatro formas de construir um agente

Objetivos de aprendizagem

• Comparar as quatro abordagens: loop manual (Messages API), Tool Runner do SDK, Claude Agent SDK e Managed Agents.
• Identificar, em cada uma, quem fornece o harness (o loop, as ferramentas, o controle) e quem fornece o deployment (onde o agente roda).
• Escolher a abordagem certa para o nível de controle, esforço e infraestrutura de cada cenário.
• Aplicar limites de iteração e task budgets como guarda-corpos de custo/segurança — sem transformá-los em mecanismo primário de parada.

O espectro: de "faço tudo" a "a Anthropic faz tudo"

Um agente sempre tem duas metades: o harness (o loop agêntico, a execução de ferramentas, o gerenciamento de contexto) e o deployment (a infraestrutura onde isso roda). As quatro abordagens se diferenciam por quem assume cada metade:

flowchart LR
    subgraph voce[Você fornece]
      A[Loop manual
harness: você
deploy: você]
      B[Tool Runner
harness: SDK
deploy: você]
      C[Claude Agent SDK
harness: Anthropic
deploy: você]
    end
    subgraph anthropic[Anthropic fornece]
      D[Managed Agents
harness: Anthropic
deploy: Anthropic]
    end
    A -- menos abstração --> B -- --> C -- mais abstração --> D
  

Tool Runner em 20 linhas

O runner elimina o loop manual: você declara as ferramentas como funções tipadas e itera pelas mensagens. A iteração termina sozinha quando o Claude para de chamar ferramentas:

import anthropic
from anthropic import beta_tool

client = anthropic.Anthropic()

@beta_tool
def lookup_order(order_id: str) -> str:
    """Busca o status de um pedido pelo numero.

    Args:
        order_id: Numero do pedido, ex. 4412.
    """
    return '{"order_id": "%s", "status": "shipped"}' % order_id

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=8000,
    max_iterations=20,  # guarda-corpo de custo, NAO o criterio de parada
    tools=[lookup_order],
    messages=[{"role": "user", "content": "Qual o status do pedido 4412?"}],
)

last = None
for message in runner:
    # cada iteracao entrega a mensagem do assistente ANTES das tools rodarem:
    # da para inspecionar, aprovar/negar ou modificar o resultado aqui.
    last = message

if last is not None:
    final_text = next((b.text for b in last.content if b.type == "text"), "")
    print(final_text)

Claude Agent SDK: o harness do Claude Code como biblioteca

O Claude Agent SDK (Python/TypeScript) empacota o mesmo harness que move o Claude Code: loop agêntico pronto, ferramentas de filesystem e shell, subagentes (Task), hooks de ciclo de vida, sessões persistentes, skills e integração MCP. Você configura via ClaudeAgentOptions (ferramentas permitidas, system prompt, agentes, hooks) e chama query() — o SDK executa o loop inteiro na sua máquina. As lições 5, 6 e 7 aprofundam subagentes, hooks e sessões.

Limites de iteração e task budgets

• max_iterations (Tool Runner): limita quantas voltas o loop pode dar. É proteção contra runaway (custo e latência) — o término normal continua sendo o modelo parar de chamar ferramentas.
• max_continuations (padrão de código no loop manual): limite de retomadas de pause_turn para não retomar indefinidamente.
• Task budgets (beta): orçamentos declarativos de esforço/custo por tarefa (ex.: teto de tokens ou de chamadas para uma tarefa delegada). Sinalize como recurso beta; a ideia arquitetural cobrada é a mesma: orçamento como guarda-corpo, decisão de parada com o modelo.

Pegadinhas da prova

• Distrator típico: "para ter aprovação humana antes de ferramentas destrutivas, é obrigatório escrever o loop manual". Falso — o Tool Runner permite gate dentro da função da ferramenta ou interceptação por iteração.
• Distrator típico: confundir Claude Agent SDK (harness da Anthropic rodando na sua infra, com acesso ao seu filesystem) com Managed Agents (harness e sandbox hospedados pela Anthropic).
• Distrator típico: reimplementar do zero loop + ferramentas de arquivo + subagentes quando o cenário descreve exatamente o que o Claude Agent SDK já entrega (over-engineering).
• Distrator típico: tratar max_iterations como critério de conclusão da tarefa, em vez de guarda-corpo de custo.
• Distrator típico: esquecer que Tool Runner, Managed Agents e task budgets são recursos beta — a alternativa que apresenta um deles como GA sem ressalva pode ser a errada em questões de "qual afirmação é correta".

Resumo em 5 linhas

Documentação oficial

• Tool use overview (inclui tool runner)
• Claude Agent SDK overview
• Handling stop reasons

Questões de fixação