Novembro passado entreguei a um cliente um agente alimentado por Claude que deveria fazer triagem de tickets de suporte inbound, roteá-los para o departamento certo e redigir respostas de primeira passada. Levei três semanas para construir. Ficou brilhante em staging. Primeiro dia em produção alucinava uma política de reembolso que não existe, roteava dezessete tickets para a fila errada e confiante dizia a um cliente que seu pedido chegaria "até quinta-feira" sem acesso algum a dados de envio.
Pois bem. Aprendi algumas coisas.
Este post é sobre o que sei agora, depois de reconstruir esse agente corretamente e de ter enviado vários outros desde então. Não é teoria. Decisões reais que tomei, ferramentas que usei e erros que não vou repetir. Se você é dono de uma agência ou freelancer tentando sair da fase de demo com o Claude Agent SDK, isto foi escrito para você.
---
O Que o Claude Agent SDK Realmente É (e Não É)
Antes de tudo: o SDK não é mágica. É uma forma estruturada de dar ao Claude acesso a ferramentas, gerenciar contexto de conversa em múltiplos turnos e orquestrar o que é essencialmente um loop de decisão. Claude raciocina sobre uma tarefa, decide se deve chamar uma ferramenta, recebe um resultado, raciocina novamente e então chama outra ferramenta ou produz uma resposta final.
Esse loop parece simples. É simples. A complexidade existe inteiramente no que você coloca ao redor dele.
O SDK oferece a tubulação. Você ainda é responsável pela pressão da água, pelo diâmetro do cano e se lembrou de desligar o registro antes de começar a furar. Já vi donos de agências entregarem o SDK a um dev júnior, esperarem um produto finalizado em um sprint e receberem algo que tecnicamente funciona mas desaba em qualquer entrada que não esteja no caminho feliz.
Como o Loop Fica na Prática
Você define ferramentas como esquemas JSON. Claude lê esses esquemas, decide quando usá-los, passa argumentos estruturados e seu código executa a lógica real. Claude nunca executa código diretamente. Ele pede. Seu sistema faz o trabalho. Depois Claude recebe o resultado e continua.
Essa separação importa muito mais do que a maioria das pessoas percebe. Significa que Claude é sempre um orquestrador, nunca um executor. E essa perspectiva deve moldar cada decisão arquitetural que você toma.
---
Projetando Ferramentas Que Claude Pode Realmente Usar
É aqui que a maioria das construções desaba. Revisei talvez quinze codebases de agentes de outros desenvolvedores no ano passado, e o problema mais comum não é engenharia de prompt ou escolha de modelo. São ferramentas mal projetadas.
Aqui está o que "mal projetado" significa na prática:
- Uma ferramenta chamada
process_dataque faz cinco coisas não relacionadas dependendo de quais parâmetros você passa - Descrições de ferramentas que parecem comentários de código interno ("chama o endpoint v2 com headers de autenticação")
- Parâmetros nomeados
typeoumodeque aceitam strings arbitrárias em vez de enums - Sem informação de erro no valor retornado, então Claude não tem ideia se a chamada funcionou
Lá em início de 2023, a Seahawk tinha um projeto de pipeline de conteúdo onde construímos uma ferramenta manage_content que aceitava um parâmetro action: create, update, delete, publish, unpublish, archive. Claude continuava escolhendo a ação errada porque as distinções não eram óbvias apenas pelo schema. Dividimos em seis ferramentas separadas. A precisão nessa decisão específica subiu de cerca de 60% para 94% em nossas avaliações internas. Uma mudança.
As Regras Que Sigo Agora
- Uma ferramenta, um trabalho. Se você não consegue descrever o propósito da ferramenta em uma única frase sem "e", divida-a.
- Use enums sempre que possível. Não deixe Claude adivinhar strings.
- Escreva a descrição para Claude, não para um desenvolvedor humano. Claude não conhece sua base de código. Conhece o que você diz a ele.
- Sempre retorne dados estruturados com um campo explícito de sucesso/falha. Nunca deixe Claude inferir pelo silêncio.
- Mantenha nomes de ferramentas começando com verbo. search_orders, create_draft, fetch_customer_record. Não orders, draft,
customer.
A documentação de tool use da Anthropic vai mais fundo em estrutura de schema e vale a pena ler com cuidado, não rapidamente.
---
Gerenciamento de Contexto É o Custo Oculto
Aqui está algo que ninguém fala o bastante. Tokens não são grátis, e agentes são gulosos.
Cada turno no loop inclui todo o histórico de conversação, todos os schemas de ferramentas, prompt de sistema e resultados de ferramentas. Um agente moderadamente complexo com dez ferramentas e um prompt de sistema detalhado pode começar cada sessão de usuário em 3.000-4.000 tokens antes do usuário ter digitado um único caractere. Adicione cinco ou seis chamadas de ferramentas com resultados, e você está olhando para 15.000-20.000 tokens por tarefa resolvida. Ao preço atual da API do Claude, isso se acumula rapidamente em qualquer volume.
Acompanho isso obsessivamente agora. Para cada agente que envio, executo um número de custo-por-resolução durante QA. Se estiver acima de um limite que concordei com o cliente antecipadamente, volto e aperto o prompt de sistema, reduzo schemas de ferramentas, ou vejo se posso fazer cache de contexto estático usando prompt caching, que a Anthropic adicionou e que realmente uso em todo projeto agora. Tokens elegíveis para cache custam cerca de 10% da taxa de entrada padrão em um cache hit. Em um agente ocupado que reexecuta o mesmo prompt de sistema milhares de vezes por dia, isto não é um erro de arredondamento.
Aparando Sem Quebrar As Coisas
A tentação é escrever um prompt de sistema rico e detalhado cobrindo todos os casos extremos. Resista. Cada linha que você adiciona custa tokens em cada turno. Escreva para o caso comum. Trate casos extremos em valores retornados pela ferramenta ou em instruções de contexto mais curtas injetadas no momento certo.
Também corto implacavelmente descrições de ferramentas depois que um agente está funcionando. Se uma descrição diz "Esta ferramenta busca o banco de dados de pedidos e retorna uma lista de pedidos correspondentes à consulta, incluindo ID do pedido, nome do cliente, itens de linha, status de envio e timestamps", vou reduzi-la para "Buscar pedidos por string de consulta. Retorna registros de pedidos correspondentes." Claude é inteligente o bastante. Não precisa da lista de campos na descrição da ferramenta se o schema de retorno documenta adequadamente esses campos.
---
Orquestração Multi-Agente: Quando Um Agente Não É Suficiente
Sistemas com um único agente quebram em um certo teto de complexidade. Atingi esse teto em um projeto para uma empresa de gestão de propriedades na primavera passada. O agente precisava lidar com solicitações de manutenção, comunicar com contratantes, atualizar um banco de dados Notion, enviar emails com template via SendGrid, e puxar dados de disponibilidade de uma API de calendário customizada. Sete ferramentas, várias das quais tinham sub-workflows.
Um agente tentando coordenar tudo aquilo ficou pouco confiável. O contexto ficou bagunçado. Claude ocasionalmente perdia a noção de qual sub-tarefa estava trabalhando no meio do loop.
A solução era óbvia em retrospectiva: orquestrador mais especialistas. Um agente Claude de nível superior lida com classificação de intenção e roteamento. Sub-agentes especialistas lidam com domínios específicos (comunicação, agendamento, atualizações de dados) e relatam resultados estruturados. O orquestrador nunca vê os internals do que cada especialista fez. Vê apenas a saída.
Esse padrão é descrito na própria orientação multi-agente da Anthropic e mapeia-se proximamente com como você projetaria um time humano. Um gerente de projeto não pessoalmente escreve todo email e atualiza toda planilha. Delega, espera confirmação, e segue adiante.
Notas Práticas sobre Design de Sub-Agente
- Dê a cada sub-agente um prompt de sistema apertado e específico. Nenhuma instrução entre domínios.
- Sub-agentes nunca devem ter mais ferramentas do que precisam para seu domínio. Excesso de ferramentas é tão perigoso em sub-agentes quanto no orquestrador principal.
- Passe contexto explicitamente. Não assuma que um sub-agente "sabe" o que aconteceu antes. Envie exatamente o que ele precisa, nada mais.
---
Tratando Falhas com Elegância (Porque Elas Vão Acontecer)
Agentes em produção falham. Expiram. APIs externas retornam 500s. Usuários enviam entradas que você nunca previu. Claude ocasionalmente malinterpreta um schema de ferramenta e passa um argumento malformado.
A pergunta não é se seu agente vai falhar. É se falha de forma segura.
Agora construo três coisas em todo agente, sem exceção:
- Lógica de retry com backoff em todas as chamadas de ferramentas externas. Não apenas em erros de rate limit. Em qualquer coisa que não seja 200.
- Um caminho alternativo quando o agente fez mais de N chamadas de ferramenta sem resolver a tarefa. N varia, mas raramente deixo passar oito. Nesse ponto, algo está errado e um humano deve se envolver.
- Tratamento explícito de incerteza no prompt do sistema. Digo ao Claude: se você não tem informação suficiente para agir com confiança, faça uma pergunta de esclarecimento em vez de prosseguir com suposições.
Esse terceiro ponto salvou o agente de triagem de tickets que mencionei no início. A versão reconstruída agora faz uma pergunta de esclarecimento quando tem dúvida sobre o roteamento. Usuários não se importam. Preferem responder uma pergunta a ter seu ticket enviado para a fila errada.
---
Evals: Você Não Pode Fazer Deploy Sem Eles
Não rodei evals adequados na primeira versão do agente de tickets de suporte. Esse foi o erro, na verdade. Tudo mais foi um sintoma disso.
Evals não precisam ser elaborados. O que faço agora é criar um conjunto de 40-60 entradas representativas antes de começar a construir, cobrindo casos normais, edge cases e entradas adversariais. Rodo o agente contra todas elas após cada mudança significativa. Rastreio três números: taxa de conclusão de tarefas, precisão de chamadas de ferramentas (chamou a ferramenta correta com os argumentos certos) e taxa de alucinação (afirmou algo não fundamentado nos resultados das ferramentas).
Para um agente em produção, não faço deploy abaixo de 88% de conclusão de tarefas e tolerância zero para alucinação em outputs críticos como mensagens voltadas para clientes com afirmações específicas (datas, preços, políticas).
O framework de benchmarking HELM da Stanford vale a pena consultar para inspiração no design de evals, mesmo se você não está rodando em escala acadêmica. As categorias que testam mapeiam bem para requisitos reais de produção.
---
O Prompt do Sistema É Load-Bearing
Mudei de ideia sobre isso no último ano. Costumava tratar o prompt do sistema como texto de configuração, algo que você escreve uma vez e esquece. Agora o trato como o arquivo mais importante do projeto.
Um prompt do sistema bem escrito faz quatro coisas:
- Define a identidade e escopo do agente claramente (o que faz e, criticamente, o que explicitamente não faz)
- Define expectativas de tom e formato de saída
- Trata os modos de falha mais comuns de forma proativa ("Se você não conseguir encontrar um pedido, diga explicitamente em vez de adivinhar")
- Estabelece critérios de escalação
A definição de escopo é a que a maioria dos desenvolvedores pula. Sem ela, Claude tentará ser útil de formas que você não pretendia. No agente de gerenciamento de propriedades, o primeiro prompt do sistema não excluía explicitamente aconselhamento financeiro. Um inquilino perguntou ao agente se deveria contestar uma cobrança. Claude helpfully weighed in. Isso não é o que o cliente pagou, e não é para o que o agente foi construído.
Uma frase corrigiu: "Você não está autorizado a fornecer aconselhamento sobre disputas financeiras, questões legais ou interpretação de contratos. Dirija usuários a contatar o escritório diretamente para esses tópicos."
Escreva essa frase para cada domínio que está fora do escopo. Não assuma que Claude vai inferir os limites.
---
FAQ
Como o Claude Agent SDK é diferente de usar a API do Claude diretamente?
A API oferece uma única requisição-resposta. O Agent SDK (e os padrões de agentes que a Anthropic documenta ao redor dele) oferece um loop estruturado onde Claude pode tomar múltiplas decisões, chamar ferramentas, receber resultados e continuar raciocínio entre turnos. É menos sobre um pacote de software distinto e mais sobre um padrão: definições de ferramentas, gerenciamento de contexto multi-turno e lógica de orquestração. Você está construindo a estrutura ao redor da API para habilitar esse loop.
Qual é um cronograma realista para lançar um agente pronto para produção?
Honestamente, quatro a seis semanas para qualquer coisa não trivial. Duas semanas disso é construir e conectar ferramentas. Uma semana é engenharia de prompt e iteração. Uma a duas semanas é evals, tratamento de casos extremos e QA. Qualquer um que prometa um agente em produção em uma semana ou nunca lançou um antes ou está entregando uma demo disfarçada de produto.
Devo usar Claude para todos os sub-agentes em um sistema multi-agente, ou misturar modelos?
Uso Claude para qualquer coisa que exija raciocínio matizado ou onde a qualidade do output importa para o usuário final. Para tarefas simples de classificação ou roteamento de alto volume e baixas apostas, um modelo menor e mais barato funciona. Mas misturar modelos adiciona overhead de integração e torna o debug mais difícil. Comece com Claude para tudo, depois otimize uma vez que você tenha dados reais de produção mostrando onde um modelo mais leve é suficiente.
Como evito que um agente saia do script?
Três coisas trabalhando juntas: system prompt apertado com declarações explícitas de fora do escopo, design de ferramentas que fisicamente previne certas ações (não dê ao agente uma ferramenta que ele não deveria usar), e validação de output em qualquer coisa voltada para o cliente. Você não pode contar apenas com o system prompt. Defesa em profundidade.
Qual é o maior erro que desenvolvedores cometem com memória de agente?
Tratar a context window como infinita. Não é. A maioria das falhas que vejo em agentes mal construídos vêm de contexto que cresceu inchado com histórico irrelevante, forçando Claude a raciocinar através de ruído. Pode agressivamente. Resuma onde puder. Apenas leve adiante o que o agente genuinamente precisa para completar a tarefa atual.
---
O resumo honesto é esse: o SDK não é a parte difícil. A parte difícil é a mesma coisa que sempre foi em software, pensar claramente sobre escopo, projetar para falha e testar antes de lançar. Claude é uma camada de raciocínio notavelmente capaz, mas não vai compensar um sistema mal projetado ao redor dela. Acerte o encanamento primeiro.