Claude Agent SDK (Python)

Sobre

SDK oficial da Anthropic (claude-agent-sdk) que permite usar o agente do Claude Code dentro de aplicações Python. Na prática, é uma interface Python sobre o próprio Claude Code: o pacote traz o CLI embutido e o SDK o controla programaticamente. Repositório público, licença MIT, uso sujeito aos Commercial Terms da Anthropic.

Relação com o Claude Code

• CLI incluído (bundled): não é preciso instalar o Claude Code separadamente; o SDK usa o CLI do pacote por padrão.
  • Alternativas: instalar à parte (curl -fsSL https://claude.ai/install.sh | bash) ou apontar ClaudeAgentOptions(cli_path="/caminho/para/claude").
• Mesmas ferramentas nativas: Read, Write, Edit, Bash etc. ficam disponíveis ao agente por padrão.
• Mesmo loop de agente: hooks são chamados pela aplicação Claude Code (não pelo modelo) em pontos do loop, como PreToolUse.
• Sessões e system prompt: o Claude Code grava o system prompt na primeira requisição e o reutiliza ao retomar a sessão. Para reconstruí-lo a cada requisição, use snapshot: False (exige CLI 2.1.257+).
• Settings, subagents e forking: o guia de migração cita isolamento de settings e controle explícito, além de subagents programáticos e session forking.
• Limitação: CLAUDE.md, .claude/, slash commands e skills não são detalhados na página do repositório; consultar a documentação oficial do Claude Code e do Agent SDK.

Instalação e requisitos

pip install claude-agent-sdk

• Python 3.10+
• Claude Code CLI (já incluído no pacote)

Funcionamento

query()

Função assíncrona simples; retorna um AsyncIterator de mensagens. Indicada para consultas pontuais.

import anyio
from claude_agent_sdk import query
 
async def main():
    async for message in query(prompt="What is 2 + 2?"):
        print(message)
 
anyio.run(main)

ClaudeSDKClient

Conversa bidirecional e interativa. Além do que query() faz, habilita ferramentas customizadas e hooks definidos em Python.

async with ClaudeSDKClient(options=options) as client:
    await client.query("Greet Alice")
    async for msg in client.receive_response():
        print(msg)

ClaudeAgentOptions

Opção	Função
system_prompt	Prompt de sistema (string ou dict)
allowed_tools	Ferramentas aprovadas automaticamente
disallowed_tools	Ferramentas bloqueadas
permission_mode	Política geral, ex.: acceptEdits
max_turns	Limite de turnos
cwd	Diretório de trabalho
mcp_servers	Servidores MCP (in-process ou externos)
hooks	Hooks por evento
cli_path	Caminho do binário do Claude Code

Principais Recursos

Ferramentas customizadas (MCP in-process)

Funções Python expostas ao Claude como servidor MCP no mesmo processo, sem subprocesso nem IPC.

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions
 
@tool("greet", "Greet a user", {"name": str})
async def greet_user(args):
    return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}
 
server = create_sdk_mcp_server(name="my-tools", version="1.0.0", tools=[greet_user])
options = ClaudeAgentOptions(
    mcp_servers={"tools": server},
    allowed_tools=["mcp__tools__greet"],
)

• É possível combinar servidores in-process com externos ({"type": "stdio", "command": "..."}).

Hooks

Funções Python para processamento determinístico, como bloquear comandos.

async def check_bash_command(input_data, tool_use_id, context):
    if input_data["tool_name"] != "Bash":
        return {}
    if "foo.sh" in input_data["tool_input"].get("command", ""):
        return {"hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason": "Command contains invalid pattern",
        }}
    return {}
 
options = ClaudeAgentOptions(
    allowed_tools=["Bash"],
    hooks={"PreToolUse": [HookMatcher(matcher="Bash", hooks=[check_bash_command])]},
)

Permissões

• allowed_tools: allowlist de aprovação automática; não remove ferramentas do conjunto disponível.
• disallowed_tools: forma de bloquear ferramentas.
• permission_mode e can_use_tool decidem o que não está na allowlist.

Casos de Uso

• Embutir um agente com as capacidades do Claude Code em serviços e automações Python.
• Expor funções internas da aplicação como ferramentas do agente.
• Aplicar políticas de segurança via hooks (ex.: negar comandos Bash específicos).

Limitações

• O conteúdo da página não informa a versão atual do pacote nem a do CLI embutido.
• Detalhes de CLAUDE.md, skills, slash commands e arquivos de settings não constam no README.

Tratamento de Erros

ClaudeSDKError (base), CLINotFoundError, CLIConnectionError, ProcessError, ResultError (subclasse de ProcessError) e CLIJSONDecodeError.

Referências

• Repositório claude-agent-sdk-python
• Documentação do Agent SDK (Python)
• Guia de permissões
• Ferramentas disponíveis no Claude Code
• Exemplos no repo: examples/quick_start.py, streaming_mode.py, mcp_calculator.py, hooks.py
• Nota relacionada: Claude Code