Claude -p vai morrer: como migrar para o Claude Agent SDK

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).

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.