Claude Agent SDK: como migrar do claude -p

Se o seu pipeline de automação é uma pilha de claude -p em scripts e cron jobs, presta atenção: o chão mudou hoje. A partir de 15 de junho de 2026, o jeito como o modo headless do Claude Code roda no seu plano de assinatura não é mais o mesmo, e o caminho recomendado para construir automação de verdade deixou de ser a CLI.

O sucessor já tem nome: Claude Agent SDK. É a mesma agent loop, as mesmas ferramentas e o mesmo gerenciamento de contexto que rodam o Claude Code, agora como biblioteca em Python e TypeScript. A boa notícia é que o que vem é melhor do que encadear flags de linha de comando.

Neste guia você vai entender o que muda no faturamento do seu plano hoje, o que é o Claude Agent SDK na prática, e como migrar um pipeline de claude -p para o SDK — incluindo como rodar agentes headless do jeito novo.

TL;DR

O que é: o Claude Agent SDK é a evolução do antigo Claude Code SDK — uma biblioteca para construir agentes que leem arquivos, rodam comandos, buscam na web e editam código, com a mesma engine do Claude Code.
Stack/Modelos: Python 3.10+ ou TypeScript/Node; modelos da família Claude (Opus, Sonnet, Haiku).
O que muda hoje: em planos de assinatura, claude -p e o Agent SDK passam a consumir um crédito mensal de Agent SDK separado do seu limite interativo (anúncio oficial).
Link útil: Guia de migração oficial.

O contexto — o que muda a partir de hoje, 15 de junho

Vamos separar duas coisas que estão acontecendo ao mesmo tempo, porque o hype vai misturar tudo.

Primeira: o claude -p não foi deletado. O comando continua existindo. O que aconteceu é que ele virou a pontinha de algo bem maior — o Anthropic renomeou o Claude Code SDK para Claude Agent SDK para deixar claro que aquela engine serve para construir qualquer tipo de agente, não só tarefas de código. Se você constrói automação séria, é para lá que o suporte e os recursos novos vão.

Segunda: a economia mudou. A partir de hoje, 15 de junho de 2026, em planos de assinatura, o uso do Agent SDK e do comando claude -p em modo não interativo passa a consumir um crédito mensal de Agent SDK separado do seu limite de uso interativo. A documentação é direta: "seus limites de uso da assinatura continuam os mesmos e seguem reservados para uso interativo do Claude Code, Claude Cowork e Claude" (fonte).

Os valores do crédito mensal por plano:

Pro: US$ 20/mês
Max 5x: US$ 100/mês
Max 20x: US$ 200/mês
Team (Standard): US$ 20/mês — Team (Premium): US$ 100/mês
Enterprise (premium seats): US$ 200/mês

O que não muda: o Claude Code interativo, no terminal e na IDE, continua puxando do limite normal da assinatura, exatamente como antes. E quem usa API key na plataforma não recebe crédito mensal — segue no pay-as-you-go de sempre (fonte).

Traduzindo para impacto em produto: se o seu CI tem um job que chama claude -p cem vezes por dia — pense numa revisão automatizada de PR —, esse consumo agora sai de um bolso separado e mensurável. Isso é bom — você para de competir com o seu próprio uso interativo. Mas é uma conta nova para planejar. E é o empurrão definitivo para parar de tratar claude -p como cola de shell e começar a tratar agente como software.

O que é o Claude Agent SDK

O claude -p resolve uma coisa: "manda esse prompt, me devolve a resposta, sem abrir a UI". Ótimo para um one-off. Péssimo como fundação de um pipeline, porque toda a lógica — loop, parsing, controle de ferramenta, retomada de sessão — fica na sua mão, no bash, sem tipo e sem teste.

O Claude Agent SDK sobe um nível. Ele te entrega a agent loop pronta: o Claude decide quais ferramentas usar, executa, lê o resultado, decide de novo, até terminar. Você só descreve o objetivo (overview oficial).

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Encontre e corrija o bug em auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)  # Claude lê o arquivo, acha o bug, edita


asyncio.run(main())

Compare com o que isso seria via API crua: você implementaria o loop de tool use na mão (while response.stop_reason == "tool_use": ...). O SDK faz isso por você (comparação oficial). E vem com ferramentas embutidas — Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch — então o agente já sai trabalhando sem você escrever executor de ferramenta nenhum.

Conceito técnico: é a engine do Claude Code exposta como lib. Aplicação prática: você escreve um agente de SRE, de code review ou de atendimento em algumas dezenas de linhas. Impacto em produto: dá para colocar isso em produção, com hooks, subagents, MCP e controle fino de permissão — coisas que no claude -p você não tinha.

Migração na prática — passo a passo

A migração tem uma parte mecânica (trocar pacote e imports) e uma parte que morde (mudanças de comportamento). Vamos pelas duas.

Passo 1: trocar o pacote

No TypeScript:

npm uninstall @anthropic-ai/claude-code
npm install @anthropic-ai/claude-agent-sdk

No Python:

pip uninstall claude-code-sdk
pip install claude-agent-sdk

O pacote Python exige Python 3.10 ou superior. Se o pip reclamar de No matching distribution found, seu interpretador é mais velho que isso.

Passo 2: atualizar imports e tipos

A troca de nome é literal. No TypeScript, só o caminho do import muda. No Python, muda o import e o tipo de options:

# Antes (claude-code-sdk)
from claude_code_sdk import query, ClaudeCodeOptions
options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

# Depois (claude-agent-sdk)
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

ClaudeCodeOptions virou ClaudeAgentOptions. Se você esquecer essa, o import quebra na cara. É o erro mais comum da migração (guia oficial).

Passo 3: o system prompt não vem mais de graça

Essa é a mudança de comportamento que pega gente desprevenida. Na v0.1.0, o SDK não usa mais o system prompt do Claude Code por padrão. Ele sobe com um system prompt mínimo. Se o seu agente dependia do comportamento CLI-focado do Claude Code, você precisa pedir o preset de propósito:

from claude_agent_sdk import query, ClaudeAgentOptions

# Para reproduzir o comportamento antigo, peça o preset explicitamente:
async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(
        system_prompt={"type": "preset", "preset": "claude_code"}
    ),
):
    print(message)

Ou — e é o que você provavelmente quer num agente próprio — passe o seu próprio system prompt: ClaudeAgentOptions(system_prompt="Você é um assistente de..."). A intenção do Anthropic aqui é isolamento: dá para construir um agente com comportamento sob medida sem herdar as instruções de CLI do Claude Code (fonte).

Passo 4: isolar o ambiente em CI/CD

Por padrão, o SDK carrega as configurações de filesystem — ~/.claude/settings.json, .claude/settings.json, CLAUDE.md e comandos customizados — igual à CLI. Em produção, num pipeline ou em sistema multi-tenant, isso é um vazamento esperando para acontecer: a config local da máquina entra no agente sem você pedir.

A trava é passar uma lista vazia:

async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(setting_sources=[]),  # nenhuma config de filesystem
):
    print(message)

Detalhe que custa caro se ignorado: o Python SDK 0.1.59 e anteriores tratavam setting_sources=[] como se você tivesse omitido a opção. Atualize antes de confiar no isolamento (fonte).

▪ Clã Beer and Code

Tutorial te mostra o caminho — no Clã você constrói junto. Aula ao vivo toda semana, projetos reais de Engenharia de IA, ao lado de quem já está em produção.

Entrar no Clã

Rodando agentes headless do jeito novo

Aqui está o ponto que importa para quem vive de claude -p: o modo headless não sumiu, ele virou uma chamada de biblioteca. Um agente que lista arquivos e devolve só o resultado final:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Quais arquivos existem neste diretório?",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

Sobre autenticação, leia com atenção porque é onde mora a pegadinha do plano. Para construir aplicações com o Agent SDK, o caminho suportado é API key (export ANTHROPIC_API_KEY=...), ou os provedores Bedrock, Vertex AI e Azure Foundry via variável de ambiente. O Anthropic é explícito: sem aprovação prévia, terceiros não podem oferecer login do claude.ai ou os limites da assinatura em produtos próprios, incluindo agentes construídos no SDK (overview).

Ou seja: o crédito mensal de Agent SDK do seu plano é para o seu uso — seus scripts, seu CI, seu claude -p. Construir um produto que serve outros usuários é território de API key e billing próprio. Não confunda os dois bolsos.

Quando usar SDK e quando usar CLI? A própria doc resume: CLI para desenvolvimento interativo e tarefas one-off; SDK para CI/CD, aplicações customizadas e automação de produção. Muita gente usa os dois — CLI no dia a dia, SDK em produção — e os fluxos traduzem direto entre eles (fonte).

Limitações e pontos de atenção

Onde você vai se queimar se não souber:

O system prompt default mudou. Se o seu agente "ficou burro" depois da migração, provavelmente é isso: ele perdeu o preset claude_code. Decida conscientemente entre o preset e um system prompt próprio.
setting_sources=[] em versões antigas não isola nada. Atualize o SDK antes de confiar no isolamento em CI. Subir uma config local em produção por engano é o tipo de bug que só aparece no ambiente errado.
API key não recebe crédito mensal. O crédito de Agent SDK é benefício de plano de assinatura. Quem está em pay-as-you-go continua pagando por token, sem mudança.
claude.ai login é proibido para terceiros. Agente que você distribui para clientes precisa de autenticação por API key e billing seu, não os limites da sua assinatura.

Esse bloco não é detalhe burocrático. É a diferença entre um piloto que roda na sua máquina e um agente que aguenta produção.

FAQ rápido

O claude -p vai parar de funcionar? Não hoje. O comando continua existindo e funcionando. O que mudou é o faturamento dele em planos de assinatura (agora puxa do crédito de Agent SDK) e o fato de que o investimento da plataforma está no SDK. Trate claude -p como legado e planeje a migração.

Preciso reescrever todos os meus prompts? Não. A lógica do prompt continua a mesma. A migração é trocar pacote, ajustar imports/tipos e decidir sobre system prompt e setting_sources. O conteúdo do que você pede ao Claude não muda.

Dá para rodar agente headless sem pagar por token, só no meu plano? Em plano de assinatura, sim — dentro do crédito mensal de Agent SDK (US$ 20 no Pro, US$ 100 no Max 5x, US$ 200 no Max 20x). Acima disso ou com API key, é cobrança por uso.

Claude Agent SDK ou Managed Agents? O SDK roda a agent loop dentro do seu processo, na sua infra, mexendo nos seus arquivos. Managed Agents é uma API REST hospedada onde o Anthropic roda o agente e o sandbox. Prototipe com o SDK; mova para Managed Agents quando precisar de sessões longas e assíncronas sem operar infraestrutura (comparação oficial).

Conclusão

O claude -p não morre de uma vez — ele vira legado. O recado de hoje é claro: a Anthropic moveu a fundação de automação para o Claude Agent SDK e separou a conta de quem roda agente da conta de quem usa o Claude no chat. Para você, dev, isso significa parar de costurar shell e começar a tratar agente como o software que ele é: com system prompt deliberado, ambiente isolado, ferramentas controladas e billing previsível.

A migração mecânica é de uma tarde. A virada de cabeça — de "mando um prompt" para "construo um harness" — é o que separa um script frágil de um agente que aguenta produção. É exatamente esse caminho que a gente percorre passo a passo no workshop Do Prompt ao Harness: construindo um agente de vendas, saindo do prompt até o harness de um agente rodando em produção. Se este post fez sentido, é a continuação natural.

O próximo passo é abrir o seu pipeline de claude -p, identificar onde está a lógica costurada no bash, e mover a primeira peça para o SDK. Comece pelo job de CI que mais te dá dor de cabeça.