Pular para o conteúdo principal

Construindo Agentes na API

Avançado
What you'll learn
  • Definir o que um agente realmente é: um modelo executando em um loop
  • Aplicar o teste de decisão para escolher entre chamada única, workflow ou agente
  • Projetar um loop de agente mínimo com as proteções certas
  • Saber quando recorrer ao Claude Agent SDK em vez de montar tudo na mão
  • Tornar um agente robusto: limite-o, trate falhas, restrinja privilégios, avalie-o

Um agente é um modelo executando em um loop: ele persegue um objetivo chamando ferramentas, observando resultados e decidindo o próximo passo até concluir. Antes de construir um, escolha a coisa mais simples que funciona.

O teste de decisão (não exagere na construção)​

Nem toda tarefa precisa de um agente. Percorra esta árvore primeiro — a maioria das tarefas para no topo.

Três opções, da mais simples primeiro:

  • Chamada única — um único prompt resolve. A maioria das tarefas. Mais barata e mais confiável.
  • Workflow — você orquestra uma sequência fixa de chamadas no código (fluxo de controle determinístico). Use quando os passos são conhecidos.
  • Agente — o modelo decide os passos dinamicamente. Use somente quando o caminho realmente não pode ser codificado de forma fixa.
Watch out

Recorra a um agente quando a adaptabilidade for o ponto central — não porque soa impressionante. Um workflow que você controla é mais fácil de testar e depurar.

Projetando o loop​

Um agente personalizado mínimo é só quatro partes móveis. Construa-as nesta ordem:

Guided walkthrough1 of 4
  1. Declare o objetivo, as restrições e as ferramentas disponíveis. É contra isso que o modelo raciocina a cada turno.

O Claude Agent SDK te dá esse loop — ferramentas, permissões, tratamento de contexto — tudo incluído, para que você não precise implementá-lo manualmente.

Pro tip

Antes de escrever seu próprio loop, pergunte se o Agent SDK já cobre isso. Ele já traz o loop, as permissões e o tratamento de contexto, para que você possa focar nas ferramentas e no objetivo.

Torne-o robusto​

Um loop que pode chamar ferramentas também pode se comportar mal. Quatro hábitos mantêm um agente confiável:

  • Limite tudo: iterações, tempo, custo. Agentes podem entrar em loop.
  • Trate falhas de ferramentas com elegância (retorne o erro como um resultado).
  • Privilégio mínimo + humano no loop para ações arriscadas — veja Protegendo Agentes.
  • Avalie-o em casos reais antes de confiar nele — veja Evals.
Key takeaways
  • Um agente é um modelo em um loop chamando ferramentas rumo a um objetivo — use um só quando o caminho não pode ser codificado de forma fixa
  • Ordem de decisão: chamada única → workflow → agente → agentes gerenciados; prefira o mais simples que funciona
  • Um loop mínimo = system prompt + loop de tool_use/tool_result + proteções + gerenciamento de contexto
  • O Claude Agent SDK já entrega o loop, as ferramentas, as permissões e o tratamento de contexto para você
  • Robustez = limitar iterações/tempo/custo, tratar falhas de ferramentas, privilégio mínimo + humano no loop, e avaliar antes de confiar

Teste-se​

Teste-se

0/5
  1. O que melhor descreve um agente neste contexto?
  2. A tarefa tem passos fixos e conhecidos. Para o que você deve recorrer?
  3. Quando um agente personalizado é realmente justificado?
  4. No loop, o que acontece quando o modelo responde com um tool_use?
  5. Qual NÃO é uma das proteções para tornar um agente robusto?

Próximo​