Agent SDK: Incorporando as Funcionalidades do Claude Code em Aplicações

📚 Navegação da Série: O capítulo anterior 44 GitHub Actions ensinou a integrar o Claude ao CI para automatizar revisões e execuções no Pull Request. Este capítulo avança para as integrações de desenvolvimento — veremos como utilizar o Claude Code como uma biblioteca de desenvolvimento (SDK), embutindo suas capacidades de execução diretamente nos seus programas e serviços corporativos. O Agent SDK fornece o canal de desenvolvimento oficial para instanciar o motor da CLI usando código.

Neste capítulo, abordaremos o uso do Claude Code sob a perspectiva de criação de ferramentas.

Nos capítulos anteriores, focamos em atuar como usuários da CLI — digitando claude no terminal, enviando instruções e acompanhando edições no código. Essa é a interface de console padrão (CLI). No entanto, as engrenagens internas da CLI — o loop do agente que realiza a leitura de arquivos, executa comandos de console e valida as edições — podem ser instanciadas programaticamente a partir de scripts customizados.

O Agent SDK (Software Development Kit que permite a chamadas às lógicas da CLI via Python ou TypeScript) converte o Claude Code de uma aplicação utilitária em uma biblioteca que pode ser acionada como uma função comum de código. Isso possibilita desenvolver agentes capazes de ler diretórios, modificar arquivos ou interagir com a internet em aplicações internas.

Esse recurso simplifica a criação de soluções como robôs de validação ou triagem de chamados. Tentar construir essas lógicas usando APIs brutas de modelo exige implementar manualmente a leitura de arquivos, o monitoramento de respostas de ferramentas (como "desejo ler o arquivo X"), a injeção física de dados e o loop de confirmação. Com o Agent SDK, a gestão técnica de chamadas é resolvida de forma nativa pela biblioteca.

Ao ler este capítulo, você obterá:

• O conceito do Agent SDK e quais recursos do Claude Code ele disponibiliza para desenvolvimento.
• As diferenças operacionais entre interagir via CLI e interagir via chamadas de SDK.
• O comparativo técnico entre o Agent SDK e as APIs comuns de modelos (Client SDK), evitando a reescrita de lógicas de loops de execução.
• As especificações de instalação para TypeScript e Python, com seus requisitos mínimos de versão.
• Um script básico comentado demonstrando como instanciar o agente para analisar e corrigir erros de código.
• As diretrizes para avaliar quando o uso do SDK é indicado para o seu cenário de desenvolvimento.

---

01 O Escopo Operacional do Agent SDK

O Agent SDK disponibiliza os mecanismos internos do Claude Code como uma biblioteca de desenvolvimento, permitindo instanciar programaticamente (em Python ou TypeScript) o mesmo agente de execução utilizado na CLI.

O loop do agente do Claude baseia-se no ciclo "Pensar → Agir → Observar" (Capítulo 3): analisar a demanda, disparar ferramentas locais (leitura de arquivos, comandos Bash) e avaliar o retorno dos dados para determinar a próxima ação. Na CLI padrão, esse ciclo roda sob supervisão humana.

O SDK disponibiliza essa automação para ser acionada via código. A documentação oficial detalha a paridade de recursos:

O Agent SDK disponibiliza as mesmas ferramentas, loops de execução e gerenciamento de contexto do Claude Code para integração programática em Python e TypeScript.

Analogia: Cafeteira industrial para estabelecimentos. O uso do CLI padrão se assemelha a ir a uma cafeteria e solicitar uma bebida ao barista. No entanto, se você deseja oferecer café aos clientes do seu próprio restaurante, você adquire e instala a mesma cafeteira industrial na sua cozinha. O motor de moagem, aquecimento e extração de água é idêntico, mas agora a cafeteira está integrada ao seu fluxo de atendimento, operando quando o seu sistema envia comandos e sendo servida com seus próprios produtos. O Agent SDK funciona como essa máquina integrada ao seu sistema local.

O SDK expõe as seguintes engrenagens internas da CLI para desenvolvimento:

• Ferramentas Nativas: As lógicas de Read (leitura), Write (escrita), Edit (edição), Bash, Glob, Grep e WebSearch estão inclusas de forma integrada, dispensando a implementação manual de escrita física no disco por parte do desenvolvedor.
• Loop de Agente: A orquestração do ciclo de decisões da IA é tratada internamente pela biblioteca.
• Gestão de Contexto: O histórico de arquivos lidos e discussões da sessão é monitorado de forma transparente.
• Pontos de Extensão: Habilidades de inicialização (hooks), subagentes, conexões MCP e regras de permissão podem ser configuradas via código.

Cenários comuns para aplicação do SDK:

• Robôs de atendimento corporativos: triagem e depuração automática de logs de erro enviados por usuários, indicando propostas de correção no repositório.
• Auditorias de código agendadas: scripts que analisam anotações TODO no projeto durante a noite e organizam relatórios de débitos técnicos.
• Soluções integradas de desenvolvimento: embutir assistentes de escrita especializados em produtos comerciais de software.

Para automações de execução em lote que rodam de forma independente, o uso da CLI se torna limitado. O SDK foi desenvolvido especificamente para atender a essas necessidades.

💡 Resumo em uma frase: O Agent SDK expõe a engine de execução do Claude Code (ferramentas locais, orquestração de chamadas e histórico) como biblioteca, permitindo embutir a IA em softwares locais e servidores.

---

02 Comparativo: CLI vs. Agent SDK

Embora a CLI e o SDK utilizem o mesmo core operacional, a escolha do ponto de acesso ideal depende do perfil de execução da tarefa.

A documentação resume a equivalência técnica:

Mesma engenharia, diferentes interfaces de interação.

Analogia: Carro de corrida manual vs. Carro automatizado de testes. A mecânica interna, motor e freios são idênticos. Na CLI (carro manual), o piloto está no cockpit controlando a direção a cada segundo — ideal para interações dinâmicas e ajustes de rota em tempo real. No SDK (carro de testes), o veículo segue comandos programados por um computador externo, rodando pistas de forma repetitiva e sem intervenção humana direta.

Tabela de diretrizes para escolha do canal:

Tipo de Tarefa	Canal Recomendado
Desenvolvimento interativo (escrever e validar códigos localmente).	CLI
Análises rápidas e perguntas pontuais de depuração.	CLI
Integração em esteiras de CI/CD corporativas.	SDK
Desenvolvimento de aplicações comerciais que consomem o agente.	SDK
Automações em lote e tarefas que rodam sem supervisão (daemons).	SDK

A regra de decisão baseia-se em responder: a tarefa exige que um humano interaja e aprove decisões em tempo real ou deve ser executada por automação de forma independente? Tarefas interativas demandam CLI; integrações e execuções em lote demandam o SDK.

As lógicas de prompts, restrições e padrões estruturais estudadas no console local aplicam-se integralmente no SDK. O conhecimento adquirido na escrita do CLAUDE.md e na validação de permissões é utilizado na modelagem das chamadas de código.

A relação dos canais de acesso com o motor de execução é ilustrada na imagem a seguir:

A imagem detalha que o CLI e o SDK funcionam como diferentes caminhos de entrada para o mesmo motor lógico de desenvolvimento, compartilhando as mesmas regras e ferramentas.

💡 Resumo em uma frase: A CLI atende ao desenvolvimento dinâmico monitorado pelo programador, enquanto o SDK é direcionado para automações e sistemas que gerenciam a IA de forma programática.

---

03 Diferença Crítica: Agent SDK vs. APIs de Modelos (Client SDK)

Evite confundir as chamadas do Agent SDK com as bibliotecas comuns de chamadas de modelo da Anthropic (geralmente referenciadas como Client SDK).

Ambas interagem com modelos Claude, mas os escopos de desenvolvimento são distintos:

As APIs de modelo (Client SDK) fornecem acesso direto aos endpoints: você envia prompts e deve implementar manualmente a execução física das ferramentas. O Agent SDK fornece a estrutura do Claude integrada com execução automática de ferramentas e gestão de arquivos.

Analogia: Compra de matéria-prima vs. Maquinário industrial. Usar o Client SDK equivale a comprar chapas de aço e motores avulsos (modelos de linguagem brutas) — os materiais são de alta qualidade, mas para construir um dispositivo útil, você precisa projetar a montagem, soldar as peças e gerenciar a eletricidade manualmente. O Agent SDK entrega a máquina montada e funcional — você aciona o botão de início e os componentes internos executam a usinagem física do material, gerenciando as etapas.

A diferença estrutural pode ser observada no código a seguir:

# Abordagem via Client SDK (API Comum): controle manual de chamadas
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    # O desenvolvedor precisa programar a execução física da ferramenta no disco
    result = execute_disk_tool(response.tool_use)
    # E devolver o retorno para a API em uma nova chamada
    response = client.messages.create(tool_result=result, **params)

# Abordagem via Agent SDK: processamento transparente
async for message in query(prompt="Fix the bug in auth.py"):
    # O Claude Code executa as leituras e edições físicas de forma autônoma
    print(message)

No Client SDK, a IA apenas "informa" que deseja ler o arquivo auth.py, e cabe ao desenvolvedor escrever as linhas de código que abrem o arquivo físico no disco, coletam o texto e o injetam em uma nova requisição na API em um loop while.

No Agent SDK, esse loop de chamadas e a escrita física em disco são tratados por trás da chamada query(). A IA determina que precisa do arquivo, aciona a ferramenta de leitura interna, processa as alterações de diff e edita o código de forma autônoma, restando ao desenvolvedor apenas monitorar o fluxo de logs gerados.

Mapeamento comparativo de escopos:

Funcionalidade	Client SDK (APIs de Modelo)	Agent SDK (Claude Code)
Tipo de Retorno	Respostas de texto e chamadas de intenções de ferramentas.	Execução física de alterações de arquivos e comandos.
Escrita em Disco	Implementada manualmente pelo desenvolvedor.	Executada de forma nativa pelas ferramentas internas.
Loop de Ferramentas	Controlado via estruturas de repetição (while) no código do usuário.	Gerenciado de forma transparente pela biblioteca.
Integração OS	Sem acesso padrão ao sistema de arquivos local.	Integrado com ferramentas de leitura, escrita e terminal local.

💡 Resumo em uma frase: Use o Agent SDK quando precisar de um agente capaz de ler, editar e rodar testes em disco de forma autônoma; o Client SDK serve para interações simples de texto sem acesso físico ao sistema operacional.

---

04 Instalação e Requisitos das Bibliotecas

O Agent SDK está disponível nas linguagens de desenvolvimento TypeScript e Python. As definições e lógicas são idênticas entre ambas.

Requisitos e Comandos de Instalação

As especificações de ambiente exigidas por cada biblioteca são descritas a seguir:

Especificação	TypeScript	Python
Comando de Instalação	npm install @anthropic-ai/claude-agent-sdk	pip install claude-agent-sdk
Ambiente Mínimo	Node.js v18 ou superior	Python v3.10 ou superior
Dependências Físicas	Inclui os binários da CLI de forma integrada.	Requer instalação e versões do Python compatíveis.

A biblioteca de TypeScript inclui os binários compilados do Claude Code como dependências opcionais do pacote. Não é necessário instalar a CLI local globalmente para rodar a biblioteca em TypeScript.

Para desenvolvedores Python, certifique-se de que a versão local seja igual ou superior a 3.10 para evitar falhas de ausência de dependências durante a instalação com o gerenciador de pacotes pip:

# Validar versão local do interpretador
python3 --version

Chave de Autenticação da API

Ambas as versões necessitam da credencial ANTHROPIC_API_KEY para autenticar as chamadas de inteligência artificial. Insira o segredo no arquivo .env local do diretório:

# Arquivo .env local
ANTHROPIC_API_KEY=sua_chave_de_api_aqui

Adicione o arquivo .env na lista de exclusão do seu .gitignore para evitar o compartilhamento indesejado do token na nuvem (Capítulo 4).

Considere a seguinte regra de faturamento para automações:

As chamadas enviadas pelo Agent SDK e execuções não interativas (claude -p) são tarifadas sobre cotas mensais de faturamento específicas da API, não utilizando os limites de assinaturas de contas Pro/Max da CLI padrão (Capítulo 6).

---

05 Código de Exemplo: A Função query()

O principal canal de entrada do SDK é a função assíncrona query(). Ela gerencia a inicialização e o tráfego do agente.

Exemplo mínimo de inicialização do agente em Python:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    # Inicializa o agente assíncrono consumindo o prompt e ferramentas liberadas
    async for message in query(
        prompt="Identify and resolve bugs in utils.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)

asyncio.run(main())

Implementação equivalente em TypeScript:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Identify and resolve bugs in utils.ts",
  options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
  console.log(message);
}

Análise dos componentes estruturais:

• query(): Função assíncrona que retorna um iterador de fluxo de dados. Ele emite cada evento técnico processado pelo agente (reflexões de lógica, chamadas físicas de ferramentas e resultados).
• prompt: Instrução operacional enviada para o agente, nos mesmos moldes do terminal local.
• options (allowed_tools / allowedTools): Especifica a lista de permissões de escrita e leitura de ferramentas locais cedidas ao agente.

Gerenciar quais ferramentas são passadas no array allowed_tools define os limites de segurança da automação (Capítulo 20):

Permissões de Ferramentas	Capacidade Operacional do Agente
["Read", "Glob", "Grep"]	Modo de Apenas Leitura: Analisa logs e código sem permissões de modificação física.
["Read", "Edit", "Glob"]	Modo de Escrita Seguro: Permite propor e salvar edições de código sem acesso a comandos Bash.
["Read", "Edit", "Bash", "Glob"]	Modo de Automação Completo: Permite ler, editar arquivos e rodar testes de terminal localmente.

Se a sua aplicação exigir a manutenção de sessões ativas e sequenciais de chats na mesma conversa, desenvolvedores Python podem utilizar o wrapper ClaudeSDKClient para gerenciar a persistência de históricos e IDs de sessões locais de forma simplificada.

💡 Resumo em uma frase: A função query() gerencia o agente retornando um fluxo de logs de execução; restrinja as capacidades do agente gerenciando a lista de ferramentas declaradas no parâmetro allowed_tools.

---

06 Prática: Criando um Agente Local de Correção Automática

Desenvolveremos um agente local em Python para localizar e corrigir erros lógicos em um arquivo do repositório.

Requisitos: interpretador Python v3.10 ou superior configurado no sistema, token de API da Anthropic ativo.

Passo 1: Criar o diretório de testes (no terminal local)

mkdir my-agent && cd my-agent

Passo 2: Configurar o ambiente virtual e instalar o SDK

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

Configure o arquivo contendo a credencial de autenticação:

# Gravar a chave no arquivo .env
echo "ANTHROPIC_API_KEY=sua_chave_aqui" > .env

Resultado esperado: O instalador conclui a gravação das dependências. Em caso de erros de compilação, valide a versão do seu interpretador (python3 --version).

Passo 3: Criar um arquivo contendo falhas lógicas

Crie o arquivo de testes utils.py com o seguinte código (que contém problemas de divisão por zero e checagem de objetos nulos):

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)

def get_user_name(user):
    return user["name"].upper()

Passo 4: Criar o script de execução do agente

Crie o arquivo agent.py contendo o código a seguir:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")

asyncio.run(main())

Nota: O parâmetro permission_mode="acceptEdits" instrui o SDK a aceitar alterações físicas no código do projeto de forma automática, dispensando prompts interativos durante a execução da ferramenta.

Passo 5: Rodar o script localmente

Execute o arquivo no seu console de comando:

python agent.py

Resultado esperado: O console exibe o fluxo de pensamentos do Claude Code localizando as falhas de divisão por zero e a leitura de dicionários vazios, seguido pelas chamadas das ferramentas Read e Edit. O processo é encerrado com a mensagem Done: success.

Passo 6: Verificar as edições do arquivo

Abra o arquivo utils.py no seu editor.

Resultado esperado: O código original foi modificado pelo agente, que inseriu verificações de tamanho de listas e existência de chaves de dicionários de forma preventiva para evitar crashes. O agente concluiu a depuração física no disco.

💡 Resumo em uma frase: O teste prático demonstra como instanciar o SDK para analisar arquivos físicos locais e aplicar refatorações sem a necessidade de intervenção humana interativa, usando o modo de permissão de escrita automatizada.

---

07 Diretrizes para Uso do SDK

O Agent SDK expande as possibilidades de uso do Claude Code, mas deve ser adotado de forma planejada.

Identifique a maturidade do seu cenário comparando as opções:

Necessidade do Projeto	Melhor Caminho
Desenvolvimento de features locais assistido por inteligência artificial.	❌ CLI local standard
Automação de linters e testes unitários em Pull Requests abertos.	✅ GitHub Actions / CI pipeline
Criação de portais internos corporativos para auditorias de código.	✅ Agent SDK
Escalabilidade corporativa de agentes com isolamento de sessões em servidores (Managed Agents).	✅ Agent SDK (Maturidade para Managed Agents)

O fluxo de evolução recomendado para desenvolvimento consiste em iniciar os testes lógicos do agente localmente com o Agent SDK e, ao validar a consistência e segurança, migrar a execução para Agentes Gerenciados (Managed Agents) para herdar o gerenciamento de sessões na nuvem e o isolamento de infraestrutura física.

💡 Resumo em uma frase: O Agent SDK serve para prototipar soluções e automações locais que interagem com o sistema de arquivos local; para implantações comerciais escaláveis, planeje a migração para infraestruturas gerenciadas.

---

08 Resumo

O Agent SDK disponibiliza a engine de execução, contexto e ferramentas locais do Claude Code em formato de biblioteca para desenvolvimento de soluções de software.

Conceitos centrais revisados neste capítulo:

Tópico	Detalhe
Core	Expõe as ferramentas da CLI (Read, Edit, Bash) para integração programática em Python e TypeScript.
Abordagem	O SDK automatiza a execução de tarefas em lote e sistemas, enquanto a CLI atende ao fluxo de trabalho interativo do dia a dia.
API	O Agent SDK gerencia de forma integrada as chamadas físicas locais de leitura e gravação no disco, simplificando as lógicas em relação a Client APIs de modelos comuns.
Configuração	Requer chaves de autenticação nos ambientes locais e restrinja as capacidades declarando as chaves em allowed_tools.
Evolução	Projete protótipos locais consumindo o SDK e adote Agentes Gerenciados (Managed Agents) para escalabilidade em ambientes produtivos de nuvem.

Integrar o Agent SDK ao seu portfólio de engenharia permite construir soluções sob medida para as tarefas de desenvolvimento do seu time.

---

O próximo capítulo, 46 "Configurações de Desenvolvimento", ensinará a gerenciar configurações e variáveis de ambiente em diferentes instâncias operacionais. Veremos como configurar servidores MCP, definir arquivos locais de chaves e otimizar a inicialização do Claude Code. Nos vemos no próximo capítulo!

---

Leituras Recomendadas

• Gerenciando Concorrência e Worktrees
• Instalação e Primeiros Passos da CLI
• Trabalhando com Atalhos do Console

---