Use the Anthropic SDK and Claude Code Agent SDK to automate real tasks in your development workflow
Quando comecei a automatizar partes do meu SDLC harness, a interface de chat do Claude.ai rapidamente atingiu um limite. Precisava acionar análises de IA a partir de um script, passar entradas estruturadas e roteá-las de volta para um pipeline — nada disso é possível de forma interativa. Foi então que o SDK se tornou essencial.
Existem dois SDKs para entender, e escolher o errado é um erro comum no início.
O Anthropic SDK (@anthropic-ai/sdk) conversa diretamente com a API do Claude. Você constrói uma mensagem, envia e recebe uma resposta. Sem acesso ao sistema de arquivos, sem ferramentas — apenas uma conversa. É a escolha certa quando você está chamando o Claude a partir do código da sua aplicação: resumindo um diff, classificando um ticket, gerando uma mensagem de commit.
O Claude Code Agent SDK (@anthropic-ai/claude-agent-sdk) executa o Claude Code como um subprocesso. O agente pode usar ferramentas reais — Read, Edit, Bash, Glob — e iterar até que uma tarefa seja concluída. É o que alimenta meu SDLC harness quando preciso que o Claude realmente faça algo no repositório, não apenas diga algo sobre ele.
Pense assim: o Anthropic SDK é um consultor especializado que você chama pelo telefone. O Agent SDK é esse mesmo consultor sentado na sua mesa com acesso à sua base de código. Situações diferentes exigem modos diferentes.
Qual usar? Se você precisa de uma resposta em texto para uma pergunta em texto, use @anthropic-ai/sdk. Se precisa que o Claude leia, edite ou execute arquivos, use @anthropic-ai/claude-agent-sdk. A maioria dos fluxos de trabalho reais usa os dois.
No meu sistema de orquestração, uso o Anthropic SDK para etapas de tomada de decisão — "esta tarefa deve aguardar revisão?" — e o Agent SDK para etapas de execução — "execute a revisão e edite o relatório". Separar essas duas preocupações mantém a arquitetura limpa e testável.
O Agent SDK tem um único ponto de entrada: o async iterable query(). Você itera seu stream de saída, e cada mensagem informa o que o agente está fazendo. O Anthropic SDK usa o familiar padrão messages.create() que você pode já conhecer.
Instale os dois: npm install @anthropic-ai/sdk @anthropic-ai/claude-agent-sdk
A chamada mais simples possível ao Anthropic SDK tem esta aparência. Uso esse padrão sempre que preciso do raciocínio do Claude incorporado em um script maior — sem classe, sem framework, apenas uma chamada de função.
Observe: new Anthropic() (não new Client()), e a resposta vem em response.content[0]. O id do modelo claude-haiku-4-5 é rápido e barato — ideal para tarefas de automação de alta frequência.
Para tarefas agentivas que precisam de acesso real a arquivos, mude para o Agent SDK:
Não confunda os dois. Usar o Anthropic SDK quando você precisa de acesso a arquivos significa que terá que ler e injetar os conteúdos dos arquivos você mesmo — complicado e propenso a erros em escala. Use o Agent SDK quando a tarefa for inerentemente agentiva.
Veja como uso esses SDKs no meu SDLC harness. O harness precisa revisar alterações de código após a conclusão de cada tarefa. Vou mostrar a construção desse revisor em três estágios para que você possa ver como o padrão cresce.
Estágio 1 — A função principal. Comece com o mínimo: receba uma string de diff, retorne uma revisão.
Estágio 2 — Adicionar integração com git. A revisão é mais útil se souber quais arquivos mudaram e qual contexto de branch existe.
Estágio 3 — Integrar com o pipeline SDLC. No meu harness, o revisor executa como uma etapa no pipeline de tarefas. O resultado é escrito em um arquivo de relatório para que o orquestrador possa lê-lo.
Esse é o padrão que uso. Sem classes utilitárias inventadas, sem frameworks complexos — apenas funções composáveis chamando a API e escrevendo saída em arquivos que o orquestrador pode consumir.
Prompt reflexivo: No Estágio 3, estou pedindo ao Claude para classificar sua própria saída de revisão. Qual falha isso introduz e como você se protegeria contra ela?
Composição sobre classes. Manter chamadas SDK em funções simples facilita o teste em isolamento. Você pode mockar client.messages.create() nos testes sem precisar de uma hierarquia de classes completa para substituir.
Antes de prosseguir para o quiz, verifique seu entendimento:
runCodeReviewStep chama o Claude duas vezes. Para que servem as duas chamadas e você poderia combiná-las em uma?allowedTools: ['Read', 'Glob', 'Bash'] realmente controla no Agent SDK?Essas não são retóricas — esboce suas respostas antes de continuar. O quiz testa os mesmos conceitos.
Padrão para lembrar: Anthropic SDK = seu código chama Claude para obter uma decisão. Agent SDK = Claude executa com ferramentas para completar uma tarefa. Os dois se compõem naturalmente em um pipeline.
1. Você precisa resumir o conteúdo de um arquivo e retorná-lo como string no seu script Node.js. Qual SDK é a escolha certa?
Correct Answer: B
Para uma tarefa simples de leitura e resumo, o Anthropic SDK é a escolha certa. Você lê o arquivo com o módulo fs do Node, injeta o conteúdo no prompt e recebe uma resposta em texto. O Agent SDK é para tarefas onde você precisa que o Claude use ferramentas autonomamente — exagero aqui.
2. No Agent SDK, o que iterar o async iterable `query()` fornece?
Correct Answer: B
O Agent SDK é um async iterable de streaming. Cada iteração pode ser uma chamada de ferramenta, um resultado de ferramenta, uma etapa de raciocínio intermediária ou o resultado final. Você verifica 'result' in message para detectar a saída final.
3. Você chama `new Anthropic()` mas esquece de definir ANTHROPIC_API_KEY no ambiente. O que acontece?
Correct Answer: A
O construtor do cliente Anthropic não valida a chave — apenas lê a variável de ambiente. O erro aparece na primeira chamada real à API quando o servidor rejeita a chave ausente ou inválida.
4. No Estágio 2 da construção em etapas, `git diff main...HEAD` usa três pontos. O que a sintaxe de três pontos faz diferente de dois pontos?
Correct Answer: B
Três pontos (`main...HEAD`) mostra alterações introduzidas pela branch atual desde que divergiu de main — equivalente à visão 'apenas esta branch'. Dois pontos (`main..HEAD`) pode incluir commits acessíveis do HEAD mas não de main, o que se comporta diferentemente em repositórios com histórico complexo.
5. A função `reviewDiff` passa um prompt `system`. Qual propósito ele serve que colocar o mesmo texto na mensagem do usuário não serviria?
Correct Answer: C
O prompt system estabelece instruções persistentes (papel, estilo, restrições) que se aplicam a cada turno. Colocar o mesmo texto na mensagem do usuário funciona para chamadas de turno único, mas conforme você adiciona contexto multi-turno ou tentativas novamente, o prompt system mantém o enquadramento estável sem repeti-lo em cada mensagem do usuário.
6. Por que `runCodeReviewStep` escreve a revisão em um arquivo em vez de retorná-la diretamente ao chamador?
Correct Answer: B
Em um pipeline onde múltiplos agentes e etapas se coordenam, um sistema de arquivos compartilhado geralmente é o contrato de integração mais simples. O orquestrador sabe que deve procurar `reports/{taskName}-review.md` — sem acoplamento direto de chamada de função necessário. Este é o mesmo padrão usado no meu SDLC harness.
7. Você quer testar `reviewDiff` no Jest sem fazer chamadas reais à API. Qual é a abordagem mais limpa?
Correct Answer: B
A abordagem mais limpa é mockar `client.messages.create` (ou o módulo `@anthropic-ai/sdk` inteiro) para retornar um objeto de resposta previsível. Isso permite testar o comportamento da função — analisar a resposta, lidar com diffs vazios, escrever o arquivo — sem uma chave de API ativa ou chamada de rede.