o problema
Quem escreveu um agente em cima de uma API de modelo em 2024 escreveu, sem querer, um interpretador. O modelo devolve um pedido de ferramenta; você despacha, captura a saída, decide o que cabe na janela, decide o que jogar fora quando não cabe, decide se a tarefa acabou, decide o que fazer quando a ferramenta falha, e volta ao topo. O loop é curto de escrever e longo de acertar. Cada equipe reescreveu o mesmo laço e errou nos mesmos lugares: truncar o histórico no ponto errado, deixar um comando destrutivo rodar sem confirmação, perder o estado quando o processo cai.
A Anthropic já tinha esse laço testado em produção — é o Claude Code. Só que ele vinha embrulhado num binário de terminal, feito para uma pessoa digitando. Quem quisesse a mesma máquina dentro do próprio produto tinha duas opções ruins: dirigir a CLI por cima com pipes e esperança, ou reimplementar o harness do zero contra a API crua.
a ideia
O Agent SDK desembrulha o Claude Code. As mesmas ferramentas, o mesmo agent loop e o mesmo gerenciamento de contexto viram uma biblioteca que roda no seu processo, em Python ou TypeScript. Você não escreve o laço; você configura o que ele pode fazer e escuta o que ele fez.
O jeito mais rápido de situar o SDK é pela tabela de comparação que a própria documentação abre. São quatro coisas parecidas com nomes parecidos, separadas por uma pergunta cada. Client SDK: acesso direto à API, e o tool loop é seu. CLI: interface de terminal, para uso interativo do dia a dia. Managed Agents: um produto à parte, REST hospedado, em que a Anthropic roda o agente e o sandbox. Agent SDK: o loop pronto, mas rodando na sua máquina, no seu processo, sob a sua responsabilidade.
como funciona
O que o SDK expõe é menos uma API de chat e mais um conjunto de pontos de controle sobre um laço que já existe.
As ferramentas embutidas são as do Claude Code: ler, escrever e editar arquivos, rodar comandos, buscar na web. Permissions define quais delas disparam sozinhas e quais param para aprovação — é onde mora a diferença entre um agente que abre um pull request e um que roda rm às três da manhã. Hooks executam código seu em pontos da vida do agente, o que serve tanto para telemetria quanto para vetar uma ação antes que ela aconteça. Sessions mantém contexto entre trocas, com resume e fork depois; fork é o detalhe interessante, porque transforma uma conversa em ponto de partida ramificável em vez de fila linear.
Para dividir trabalho, subagents lança agentes especializados em subtarefas, cada um com o próprio contexto. Para alcançar o mundo, MCP conecta ferramentas e fontes de dados externas pelo Model Context Protocol. E plugins empacotam skills, agentes, hooks e servidores MCP num artefato só, carregado por caminho local.
O ponto que mais surpreende na integração: skills, comandos e memória são carregados automaticamente de .claude/ no projeto e de ~/.claude/ no home, exatamente como a CLI faz. O agente herda a configuração do ambiente onde está rodando, quer você tenha pensado nisso ou não.
Se o seu serviço é Rust ou Go, a saída documentada não é bindings: é rodar a CLI como subprocesso em modo headless, com -p e --output-format json. Funciona, e deixa claro que a biblioteca é uma conveniência de duas linguagens sobre um executável.
o que isso custou
O SDK entrega o loop e nada além do loop. Rodar no seu processo significa que isolamento, sandbox, segredos e infraestrutura de sessão de longa duração continuam inteiramente com você — a documentação é explícita ao apontar Managed Agents como o produto separado para quem não quer esse trabalho.
O suporte de primeira classe para em Python e TypeScript. O caminho por subprocesso existe, mas quem sai da lista paga em serialização e em ferramentas de debug piores.
Há restrições que não são técnicas e mesmo assim mudam o projeto. Salvo aprovação prévia, não é permitido oferecer login ou rate limit de claude.ai aos seus usuários finais: autenticação é por API key, então o custo de inferência dos seus clientes é seu. A marca também é limitada — “Claude Agent” e “{SeuProduto} Powered by Claude” são permitidos, “Claude Code” e imitações visuais do Claude Code não são. E o uso é regido pelos Termos Comerciais da Anthropic, inclusive quando o SDK vira base de um produto que você revende.
onde isso aparece hoje
A consequência mais direta é que “harness” virou uma camada com nome próprio, separada do modelo e vendável sem ele. A documentação aponta para um texto da equipe do Claude Code sobre workflows dinâmicos orquestrando muitos subagentes ao mesmo tempo — a orquestração deixou de ser truque de aplicação e virou assunto do harness.
A outra consequência está no formato: .claude/, skills e plugins deixaram de ser configuração de uma ferramenta de terminal e viraram formato de distribuição. O que você escreve para o seu Claude Code local roda igual dentro de um agente em produção, e o repositório de demos existe justamente para mostrar essa passagem.