Claude Agent SDK: tutorial para montar um agente de negócio

Claude Agent SDK: tutorial para montar um agente de negócio

Para montar um agente de negócio com o Claude Agent SDK, defina um fluxo único e estreito, dê ao agente poucas ferramentas, restrinja as permissões, escreva instruções claras, registre cada ação em log e só então rode um piloto com métrica combinada. O SDK entrega o laço do agente (modelo, ferramentas e contexto). O que torna o agente seguro para a empresa é o que você constrói em volta dele. Este tutorial segue a ordem em que recomendamos construir.

Principais pontos

• O SDK fornece o laço do agente e ferramentas prontas. Escopo, limites, logs e avaliação continuam sendo responsabilidade de quem implementa.
• Comece pelo processo, não pelo código: um fluxo real, com baseline e um critério de sucesso definido antes.
• Ferramentas e permissões são a principal alavanca de risco. Prefira leitura primeiro e exija aprovação humana para qualquer ação que altere dados ou fale com o cliente.
• Hooks e logs transformam regras escritas em regras aplicadas e deixam cada decisão auditável.
• Nomes de parâmetros e recursos mudam entre versões. Confirme sempre na documentação oficial do SDK antes de copiar uma configuração.

O que o Claude Agent SDK entrega e o que continua sendo seu trabalho

O Claude Agent SDK é uma biblioteca (há versões para Python e TypeScript) que permite rodar, dentro do seu próprio sistema, o mesmo tipo de agente que existe no Claude Code. Em termos práticos, você envia uma tarefa, o modelo decide quais ferramentas usar, o SDK executa essas ferramentas, devolve o resultado ao modelo e repete até concluir ou até atingir um limite que você definiu.

Isso significa que você não precisa escrever o laço de decisão, o gerenciamento de contexto básico nem as ferramentas mais comuns, como ler arquivos, buscar texto e executar comandos. A documentação oficial também descreve recursos como servidores MCP para conectar sistemas, subagentes, sessões que podem ser retomadas, modos de permissão e hooks.

O que o SDK não decide por você: qual processo vale automatizar, quais dados o agente pode ver, quais ações exigem aprovação, como medir se funcionou e quem responde quando algo dá errado. Essas decisões são de negócio. Se quiser a base conceitual por trás dessa divisão, o texto da Anthropic sobre como construir agentes eficazes distingue com clareza workflows previsíveis de agentes que decidem o caminho sozinhos, e recomenda a solução mais simples que resolva o problema.

Qual é o passo a passo para montar o agente?

Use esta sequência como plano de trabalho. Cada passo tem uma saída concreta que você consegue revisar antes de seguir.

• Passo 1, mapear: descreva o processo atual com as etapas, quem executa, que sistemas toca e onde as pessoas hesitam. Anote o baseline (como o processo funciona hoje) sem inventar números que você não mediu.
• Passo 2, delimitar: escolha um único fluxo e escreva em uma frase o que o agente faz e o que ele nunca faz.
• Passo 3, listar ferramentas: para cada etapa, defina qual ferramenta é necessária e se ela só lê ou também escreve.
• Passo 4, configurar permissões: libere explicitamente apenas o que o fluxo exige e bloqueie o restante.
• Passo 5, escrever instruções e contexto: regras do negócio, tom, casos de escalonamento e formato de saída.
• Passo 6, instrumentar: registre entrada, ferramenta chamada, parâmetros, resultado, decisão e custo por execução.
• Passo 7, avaliar: monte um conjunto de casos reais anonimizados, inclusive os difíceis, e rode antes de qualquer usuário real.
• Passo 8, pilotar e decidir: rode em um fluxo real com humano no circuito e decida entre expandir, ajustar ou parar.

Os passos um e dois não envolvem código e são os que mais evitam retrabalho. Se você ainda está escolhendo qual processo atacar primeiro, a matriz de decisão para escolher processos ajuda a priorizar sem apostar no fluxo mais ambicioso.

Como dar ferramentas ao agente sem abrir demais?

O SDK oferece ferramentas nativas e permite criar ferramentas próprias, normalmente expostas como um servidor MCP (Model Context Protocol, o padrão aberto para conectar modelos a sistemas e dados). A pergunta de negócio é a mesma nos dois casos: o que esse agente realmente precisa tocar?

Um bom critério é separar as ferramentas em três grupos:

• Leitura: consultar status de pedido, buscar um cadastro, ler um documento de política. Risco baixo, comece por aqui.
• Escrita reversível: criar um rascunho, abrir um chamado, registrar uma observação. Aceitável com log e revisão.
• Escrita irreversível ou externa: enviar mensagem ao cliente, alterar valor, cancelar, emitir. Exige aprovação humana no início.

Sobre o desenho de cada ferramenta, a Anthropic publicou orientações sobre como escrever ferramentas para agentes. Os pontos que mais importam no dia a dia são nomes e descrições claros, parâmetros sem ambiguidade, respostas enxutas que não despejam dados desnecessários no contexto e mensagens de erro que ajudam o agente a corrigir a próxima tentativa. Uma ferramenta mal descrita gera chamadas erradas, e isso é lido como defeito do modelo quando na verdade é defeito de interface.

Se o sistema interno ainda não tem uma API adequada, vale ler o guia sobre como criar um servidor MCP para o sistema interno, que defende começar apenas com leitura. Para integrações de terceiros, trate o servidor como código que roda com credenciais da empresa e audite antes de instalar.

Como configurar permissões e hooks para o agente não passar do limite?

O SDK trabalha com a ideia de ferramentas permitidas e negadas e com modos de permissão que definem o que o agente pode fazer sem pedir confirmação. A documentação oficial descreve os modos disponíveis e como cada um se comporta. Nossa recomendação de método é simples: parta do mais restritivo e abra por exceção, nunca o contrário. Um modo que aprova tudo automaticamente serve para experimentos em ambiente isolado, não para um agente ligado a dados de clientes.

Além da lista de permissões, o SDK suporta hooks: pontos em que o seu código roda antes ou depois de uma ferramenta ser usada. É onde uma regra de negócio vira regra aplicada. Exemplos de uso:

• Antes de uma ferramenta de escrita, verificar se o valor está dentro do limite combinado e, se não estiver, bloquear e escalar para uma pessoa.
• Antes de qualquer envio externo, exigir aprovação registrada.
• Depois de cada chamada, gravar o evento no log com identificador da execução.
• Mascarar dados pessoais que não precisam chegar ao modelo, em linha com o princípio de minimização da LGPD.

O conceito é o mesmo discutido em hooks no Claude Code, e a camada de validação de entrada, saída e ação está detalhada em guardrails para agentes de IA. Um ponto de atenção: texto vindo de e-mails, páginas ou mensagens de clientes pode conter instruções disfarçadas. A lista OWASP Top 10 para aplicações com LLM trata isso como risco central, e a defesa não é só um prompt melhor, é limitar o que o agente consegue fazer mesmo que seja enganado.

Por fim, credenciais. O agente não deve ter chaves de uso amplo. Use contas de serviço com o menor acesso possível, mantenha os segredos fora do código e do contexto do modelo e tenha um plano de rotação.

Que instruções e contexto o agente precisa receber?

O agente trabalha com o que está no contexto. No SDK, isso inclui o prompt de sistema, os arquivos de instrução do projeto (como um CLAUDE.md, se você optar por carregá-lo nas configurações) e o que as ferramentas devolvem. A Anthropic tem um texto sobre engenharia de contexto para agentes cuja ideia central é útil para o negócio: contexto é um recurso limitado, então entregue o mínimo de informação de alto sinal em vez de colar o manual inteiro da empresa.

Um conjunto de instruções enxuto para um agente de negócio costuma ter:

• Papel e objetivo em poucas frases.
• O que ele pode fazer e o que está proibido.
• Quando parar e chamar uma pessoa, com exemplos concretos.
• Formato de saída esperado, para facilitar validação automática.
• Fonte de verdade: de onde vêm preços, prazos e políticas (nunca da memória do modelo).

Essa última regra reduz respostas inventadas. Se uma informação muda, ela deve ser buscada por ferramenta, não escrita no prompt. Para a redação do prompt em atendimento, há um guia específico sobre instruções para agente de atendimento.

Como registrar, avaliar e pilotar antes de colocar em produção?

Sem log, você só consegue dizer que o agente parece funcionar. Com log, consegue responder o que ele fez, por quê e com que custo. Registre por execução: identificador, entrada (com dados sensíveis mascarados), cada chamada de ferramenta com parâmetros e resultado, saída final, se houve escalonamento, tempo e uso de tokens. Os conceitos de traços, métricas e logs do primer de observabilidade do OpenTelemetry se aplicam diretamente, e a ideia de tratar cada execução como um traço com etapas ajuda na depuração.

Sobre avaliação, o material da Anthropic sobre evals para agentes insiste em um ponto prático: avalie o resultado e o caminho, com tarefas realistas e casos de borda, e leia as transcrições para entender falhas em vez de olhar só uma nota agregada. Monte o conjunto de casos antes do piloto e rode de novo a cada mudança de instrução, ferramenta ou modelo.

Cenário ilustrativo: uma distribuidora quer que um agente prepare respostas para dúvidas de clientes sobre status de pedido. Mapeia o fluxo atual, define que o agente só lê o sistema de pedidos e redige um rascunho, e que uma pessoa aprova o envio. O hook bloqueia qualquer ferramenta de escrita. O log guarda pedido consultado, rascunho gerado e se a pessoa editou ou aprovou. Depois do período de piloto, a equipe olha os rascunhos mais editados, ajusta as instruções e decide se libera envio automático para um tipo simples de dúvida, mantém como está ou encerra. Nenhum número entra nesse exemplo porque ele é só um desenho de processo.

É aqui que nosso método se aplica de forma direta: mapear o processo e o baseline, limitar dados e ações, pilotar um fluxo real com logs e uma métrica de sucesso combinada, e então transferir a operação e decidir entre expandir, ajustar ou parar. Para definir métricas e critérios de decisão do piloto, veja como medir um piloto de automação com IA.

Perguntas frequentes

Preciso saber programar para usar o Claude Agent SDK? Sim, o SDK é uma biblioteca para Python ou TypeScript, então alguém da equipe precisa escrever e manter o código. A parte de negócio, como mapear o processo, definir limites e avaliar resultados, pode e deve ser conduzida por quem conhece a operação.

O Claude Agent SDK serve para agentes de WhatsApp? Ele pode ser o núcleo de decisão de um agente que atende por WhatsApp, mas o canal é outra camada: recebimento de mensagens, filas, janelas de atendimento e regras da plataforma ficam fora do SDK. Trate o canal e o agente como componentes separados, com logs em ambos.

Quanto controle humano é necessário no começo? Para qualquer ação que altere dados, envie mensagem ao cliente ou envolva dinheiro, comece com aprovação humana em cada caso. Conforme os logs e a avaliação mostrarem comportamento estável em um tipo específico de tarefa, você pode reduzir a aprovação apenas para aquele tipo, mantendo a possibilidade de reverter.

O que muda em relação à LGPD ao usar um agente com o SDK? O agente passa a ser mais um tratamento de dados pessoais, então valem finalidade, minimização, controle de acesso e registro. Defina quais dados chegam ao modelo, mascare o que não for necessário, documente o fluxo e, se o caso for sensível, avalie com o jurídico se um relatório de impacto é recomendável. A ANPD é a fonte oficial para orientações no Brasil.

Fontes

• Anthropic: Building effective agents
• Anthropic: Writing effective tools for agents
• Anthropic: Demystifying evals for AI agents
• OpenTelemetry: observability concepts