Migrar para Claude Agent SDK

Guia para migrar os SDKs TypeScript e Python do Claude Code para o Claude Agent SDK

Visão Geral

O Claude Code SDK foi renomeado para o Claude Agent SDK e sua documentação foi reorganizada. Esta mudança reflete as capacidades mais amplas do SDK para construir agentes de IA além de apenas tarefas de codificação.

Migrando do OpenAI Agents SDK? A receita de migração do OpenAI Agents SDK mapeia cada primitivo para o Claude Agent SDK através de um único exemplo prático.

O Que Mudou

Etapas de Migração

Para Projetos TypeScript/JavaScript

1. Desinstale o pacote antigo:

npm uninstall @anthropic-ai/claude-code

2. Instale o novo pacote:

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

3. Atualize suas importações:

Altere todas as importações de @anthropic-ai/claude-code para @anthropic-ai/claude-agent-sdk:

// Antes
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";

// Depois
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

4. Atualize package.json:

Se @anthropic-ai/claude-code ainda estiver listado em seu package.json, substitua-o por @anthropic-ai/claude-agent-sdk e atualize também o intervalo de versão, por exemplo de "^0.0.42" para "^0.3.0".

5. Revise mudanças significativas

Faça as alterações de código necessárias para concluir a migração.

Para Projetos Python

1. Desinstale o pacote antigo:

pip uninstall -y claude-code-sdk

Se o pacote antigo não estiver instalado, pip imprime WARNING: Skipping claude-code-sdk as it is not installed. Isso é esperado e você pode continuar para a próxima etapa.

2. Instale o novo pacote:

pip install claude-agent-sdk

Se claude-code-sdk estiver listado em seu requirements.txt ou pyproject.toml, substitua-o por claude-agent-sdk.

3. Atualize suas importações:

Altere todas as importações de claude_code_sdk para claude_agent_sdk:

# Antes
from claude_code_sdk import query, ClaudeCodeOptions

# Depois
from claude_agent_sdk import query, ClaudeAgentOptions

4. Revise mudanças significativas

Faça as alterações de código necessárias para concluir a migração.

Mudanças significativas

Python: ClaudeCodeOptions renomeado para ClaudeAgentOptions

O que mudou: O tipo ClaudeCodeOptions do SDK Python foi renomeado para ClaudeAgentOptions.

Migração:

# 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")

System prompt não é mais padrão

O que mudou: O SDK não usa mais o system prompt do Claude Code por padrão.

Migração:

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

// ANTES (v0.0.x) - Usava o system prompt do Claude Code por padrão
const before = query({ prompt: "Hello" });

// DEPOIS (v0.1.0) - Usa um system prompt mínimo por padrão
// Para obter o comportamento anterior, solicite explicitamente a predefinição do Claude Code:
const presetResult = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});

// Ou use um system prompt personalizado:
const customResult = query({
prompt: "Hello",
options: {
systemPrompt: "You are a helpful coding assistant"
}
});

from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio


async def main():
# ANTES (v0.0.x) - Usava o system prompt do Claude Code por padrão
async for message in query(prompt="Hello"):
print(message)

# DEPOIS (v0.1.0) - Usa um system prompt mínimo por padrão
# Para obter o comportamento anterior, solicite explicitamente a predefinição do Claude Code:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
system_prompt={"type": "preset", "preset": "claude_code"}  # Use a predefinição
),
):
print(message)

# Ou use um system prompt personalizado:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),
):
print(message)


asyncio.run(main())

Padrão de fontes de configurações

Este padrão foi brevemente alterado em v0.1.0 para não carregar configurações do sistema de arquivos e depois foi revertido, portanto nenhuma ação de migração é necessária.

Comportamento atual: Omitir settingSources em query() carrega as configurações do usuário, projeto e sistema de arquivos local, correspondendo à CLI. Isso inclui ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, arquivos CLAUDE.md e comandos personalizados.

Para executar isolado das configurações do sistema de arquivos, passe settingSources: [], ou setting_sources=[] em Python. Consulte Control filesystem settings with settingSources para saber o que cada fonte carrega.

O isolamento é especialmente importante para pipelines de CI/CD, aplicações implantadas, ambientes de teste e sistemas multi-tenant, onde as personalizações locais não devem vazar.

Próximas Etapas

• Explore a Visão Geral do Agent SDK para aprender sobre os recursos disponíveis
• Confira a Referência do SDK TypeScript para documentação detalhada da API
• Revise a Referência do SDK Python para documentação específica do Python
• Aprenda sobre Ferramentas Personalizadas e Integração MCP