Referência do Agent SDK - Python

Referência completa da API para o Python Agent SDK, incluindo todas as funções, tipos e classes.

Instalação

Instale o pacote em um ambiente virtual. Em instalações recentes do Debian, Ubuntu e Homebrew Python, executar pip install contra o Python do sistema falha com error: externally-managed-environment.

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

Para uv, Windows PowerShell e configuração de chave de API, consulte Configuração no guia de início rápido do Agent SDK.

Escolhendo entre `query()` e `ClaudeSDKClient`

O SDK Python fornece duas maneiras de interagir com Claude Code:

Use ClaudeSDKClient para aplicações interativas, como interfaces de chat, ou quando a próxima ação depende da resposta de Claude.

Funções

`query()`

Cria uma nova sessão para cada interação com Claude Code por padrão. Retorna um iterador assíncrono que produz mensagens conforme chegam. Cada chamada para query() começa do zero sem memória de interações anteriores, a menos que você passe continue_conversation=True ou resume em ClaudeAgentOptions. Veja Sessions.

async def query(
    *,
    prompt: str | AsyncIterable[dict[str, Any]],
    options: ClaudeAgentOptions | None = None,
    transport: Transport | None = None
) -> AsyncIterator[Message]

Parâmetros

Retorna

Retorna um AsyncIterator[Message] que produz mensagens da conversa.

Exemplo - Com opções

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    options = ClaudeAgentOptions(
        system_prompt="You are an expert Python developer",
        permission_mode="acceptEdits",
    )

    async for message in query(prompt="Create a Python web server", options=options):
        print(message)


asyncio.run(main())

`tool()`

Decorador para definir ferramentas MCP com segurança de tipo.

def tool(
    name: str,
    description: str,
    input_schema: type | dict[str, Any],
    annotations: ToolAnnotations | None = None
) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]

Parâmetros

Opções de schema de entrada

1. Mapeamento de tipo simples (recomendado):

   {"text": str, "count": int, "enabled": bool}
   

2. Formato JSON Schema (para validação complexa):

   {
       "type": "object",
       "properties": {
           "text": {"type": "string"},
           "count": {"type": "integer", "minimum": 0},
       },
       "required": ["text"],
   }
   

Retorna

Uma função decoradora que envolve a implementação da ferramenta e retorna uma instância SdkMcpTool.

Exemplo

from claude_agent_sdk import tool
from typing import Any


@tool("greet", "Greet a user", {"name": str})
async def greet(args: dict[str, Any]) -> dict[str, Any]:
    return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}

`ToolAnnotations`

Dicas de comportamento para uma ferramenta, passadas como o argumento annotations de tool(). ToolAnnotations estende o mcp.types.ToolAnnotations do SDK MCP com um campo maxResultSizeChars, e você pode escrever cada dica em camelCase ou snake_case: ToolAnnotations(readOnlyHint=True) e ToolAnnotations(read_only_hint=True) são equivalentes. Você também pode passar um mcp.types.ToolAnnotations simples onde o SDK aceita anotações.

Os nomes snake_case e o campo maxResultSizeChars tipado requerem Python Agent SDK 0.2.140 ou posterior. As versões 0.1.31 a 0.2.139 re-exportam mcp.types.ToolAnnotations inalterado. Nas versões 0.1.55 a 0.2.139 você ainda pode passar maxResultSizeChars como um argumento de palavra-chave: a classe MCP aceita campos extras, e o SDK encaminha o valor para Claude Code.

Todos os campos são opcionais. Os clientes não devem confiar nas dicas para decisões de segurança.

from claude_agent_sdk import tool, ToolAnnotations
from typing import Any


@tool(
    "search",
    "Search the web",
    {"query": str},
    annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
)
async def search(args: dict[str, Any]) -> dict[str, Any]:
    return {"content": [{"type": "text", "text": f"Results for: {args['query']}"}]}

`create_sdk_mcp_server()`

Cria um servidor MCP em processo que é executado dentro de sua aplicação Python.

def create_sdk_mcp_server(
    name: str,
    version: str = "1.0.0",
    tools: list[SdkMcpTool[Any]] | None = None
) -> McpSdkServerConfig

Parâmetros

Retorna

Retorna um objeto McpSdkServerConfig que pode ser passado para ClaudeAgentOptions.mcp_servers.

Exemplo

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions


@tool("add", "Add two numbers", {"a": float, "b": float})
async def add(args):
    return {"content": [{"type": "text", "text": f"Sum: {args['a'] + args['b']}"}]}


@tool("multiply", "Multiply two numbers", {"a": float, "b": float})
async def multiply(args):
    return {"content": [{"type": "text", "text": f"Product: {args['a'] * args['b']}"}]}


calculator = create_sdk_mcp_server(
    name="calculator",
    version="2.0.0",
    tools=[add, multiply],  # Pass decorated functions
)

# Use with Claude
options = ClaudeAgentOptions(
    mcp_servers={"calc": calculator},
    allowed_tools=["mcp__calc__add", "mcp__calc__multiply"],
)

`list_sessions()`

Lista sessões passadas com metadados. Filtre por diretório de projeto ou liste sessões em todos os projetos. Síncrono; retorna imediatamente.

def list_sessions(
    directory: str | None = None,
    limit: int | None = None,
    offset: int = 0,
    include_worktrees: bool = True
) -> list[SDKSessionInfo]

Parâmetros

Tipo de retorno: `SDKSessionInfo`

Exemplo

Imprima as 10 sessões mais recentes para um projeto. Os resultados são classificados por last_modified descendente, então o primeiro item é o mais novo. Omita directory para pesquisar em todos os projetos.

from claude_agent_sdk import list_sessions

for session in list_sessions(directory="/path/to/project", limit=10):
    print(f"{session.summary} ({session.session_id})")

`get_session_messages()`

Recupera mensagens de uma sessão passada. Síncrono; retorna imediatamente.

def get_session_messages(
    session_id: str,
    directory: str | None = None,
    limit: int | None = None,
    offset: int = 0
) -> list[SessionMessage]

Parâmetros

Tipo de retorno: `SessionMessage`

Exemplo

from claude_agent_sdk import list_sessions, get_session_messages

sessions = list_sessions(limit=1)
if sessions:
    messages = get_session_messages(sessions[0].session_id)
    for msg in messages:
        print(f"[{msg.type}] {msg.uuid}")

`get_session_info()`

Lê metadados para uma única sessão por ID sem verificar o diretório do projeto completo. Síncrono; retorna imediatamente.

def get_session_info(
    session_id: str,
    directory: str | None = None,
) -> SDKSessionInfo | None

Parâmetros

Retorna SDKSessionInfo, ou None se a sessão não for encontrada.

Exemplo

Procure os metadados de uma única sessão sem verificar o diretório do projeto. Útil quando você já tem um ID de sessão de uma execução anterior.

from claude_agent_sdk import get_session_info

info = get_session_info("550e8400-e29b-41d4-a716-446655440000")
if info:
    print(f"{info.summary} (branch: {info.git_branch}, tag: {info.tag})")

`rename_session()`

Renomeia uma sessão anexando uma entrada de título personalizado. Chamadas repetidas são seguras; o título mais recente vence. Síncrono.

def rename_session(
    session_id: str,
    title: str,
    directory: str | None = None,
) -> None

Parâmetros

Lança ValueError se session_id não for um UUID válido ou title estiver vazio; FileNotFoundError se a sessão não puder ser encontrada.

Exemplo

Renomeie a sessão mais recente para que seja mais fácil encontrá-la depois. O novo título aparece em SDKSessionInfo.custom_title em leituras subsequentes.

from claude_agent_sdk import list_sessions, rename_session

sessions = list_sessions(directory="/path/to/project", limit=1)
if sessions:
    rename_session(sessions[0].session_id, "Refactor auth module")

`tag_session()`

Marca uma sessão. Passe None para limpar a tag. Chamadas repetidas são seguras; a tag mais recente vence. Síncrono.

def tag_session(
    session_id: str,
    tag: str | None,
    directory: str | None = None,
) -> None

Parâmetros

Lança ValueError se session_id não for um UUID válido ou tag estiver vazio após sanitização; FileNotFoundError se a sessão não puder ser encontrada.

Exemplo

Marque uma sessão e depois filtre por essa tag em uma leitura posterior. Passe None para limpar uma tag existente.

from claude_agent_sdk import list_sessions, tag_session

# Tag the most recent session
sessions = list_sessions(directory="/path/to/project", limit=1)
if sessions:
    tag_session(sessions[0].session_id, "needs-review")

# Later: find all sessions with that tag
for session in list_sessions(directory="/path/to/project"):
    if session.tag == "needs-review":
        print(session.summary)

Classes

`ClaudeSDKClient`

Mantém uma sessão de conversa em múltiplas trocas. Este é o equivalente Python de como a função query() do SDK TypeScript funciona internamente - cria um objeto cliente que pode continuar conversas. Veja a comparação com query().

class ClaudeSDKClient:
    def __init__(self, options: ClaudeAgentOptions | None = None, transport: Transport | None = None)
    async def connect(self, prompt: str | AsyncIterable[dict] | None = None) -> None
    async def query(self, prompt: str | AsyncIterable[dict], session_id: str = "default") -> None
    async def receive_messages(self) -> AsyncIterator[Message]
    async def receive_response(self) -> AsyncIterator[Message]
    async def interrupt(self) -> None
    async def set_permission_mode(self, mode: PermissionMode) -> None
    async def set_model(self, model: str | None = None) -> None
    async def rewind_files(self, user_message_id: str) -> None
    async def get_mcp_status(self) -> McpStatusResponse
    async def reconnect_mcp_server(self, server_name: str) -> None
    async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None
    async def stop_task(self, task_id: str) -> None
    async def get_server_info(self) -> dict[str, Any] | None
    async def disconnect(self) -> None

Métodos

Suporte a Gerenciador de Contexto

O cliente pode ser usado como um gerenciador de contexto assíncrono para gerenciamento automático de conexão:

import asyncio
from claude_agent_sdk import ClaudeSDKClient


async def main():
    async with ClaudeSDKClient() as client:
        await client.query("Hello Claude")
        async for message in client.receive_response():
            print(message)


asyncio.run(main())

Importante: Ao iterar sobre mensagens, evite usar break para sair cedo, pois isso pode causar problemas de limpeza do asyncio. Em vez disso, deixe a iteração ser concluída naturalmente ou use sinalizadores para rastrear quando você encontrou o que precisa.

Exemplo - Continuando uma conversa

import asyncio
from claude_agent_sdk import ClaudeSDKClient, AssistantMessage, TextBlock, ResultMessage


async def main():
    async with ClaudeSDKClient() as client:
        # First question
        await client.query("What's the capital of France?")

        # Process response
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")

        # Follow-up question - the session retains the previous context
        await client.query("What's the population of that city?")

        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")

        # Another follow-up - still in the same conversation
        await client.query("What are some famous landmarks there?")

        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")


asyncio.run(main())

Exemplo - Entrada em streaming com ClaudeSDKClient

import asyncio
from claude_agent_sdk import ClaudeSDKClient


async def message_stream():
    """Generate messages dynamically."""
    yield {
        "type": "user",
        "message": {"role": "user", "content": "Analyze the following data:"},
    }
    await asyncio.sleep(0.5)
    yield {
        "type": "user",
        "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"},
    }
    await asyncio.sleep(0.5)
    yield {
        "type": "user",
        "message": {"role": "user", "content": "What patterns do you see?"},
    }


async def main():
    async with ClaudeSDKClient() as client:
        # Stream input to Claude
        await client.query(message_stream())

        # Process response
        async for message in client.receive_response():
            print(message)

        # Follow-up in same session
        await client.query("Should we be concerned about these readings?")

        async for message in client.receive_response():
            print(message)


asyncio.run(main())

Exemplo - Usando interrupções

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, ResultMessage


async def interruptible_task():
    options = ClaudeAgentOptions(allowed_tools=["Bash"], permission_mode="acceptEdits")

    async with ClaudeSDKClient(options=options) as client:
        # Start a long-running task
        await client.query("Count from 1 to 100 slowly, using the bash sleep command")

        # Let it run for a bit
        await asyncio.sleep(2)

        # Interrupt the task
        await client.interrupt()
        print("Task interrupted!")

        # Drain the interrupted task's messages (including its ResultMessage)
        async for message in client.receive_response():
            if isinstance(message, ResultMessage):
                print(f"Interrupted task: terminal_reason={message.terminal_reason!r}")
                # terminal_reason is "aborted_streaming" or "aborted_tools"
                # for interrupted turns

        # Send a new command
        await client.query("Just say hello instead")

        # Now receive the new response
        async for message in client.receive_response():
            if isinstance(message, ResultMessage) and message.subtype == "success":
                print(f"New result: {message.result}")


asyncio.run(interruptible_task())

Exemplo - Controle avançado de permissão

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import (
    PermissionResultAllow,
    PermissionResultDeny,
    ToolPermissionContext,
)


async def custom_permission_handler(
    tool_name: str, input_data: dict, context: ToolPermissionContext
) -> PermissionResultAllow | PermissionResultDeny:
    """Custom logic for tool permissions."""

    # Block writes to system directories
    if tool_name == "Write" and input_data.get("file_path", "").startswith("/system/"):
        return PermissionResultDeny(
            message="System directory write not allowed", interrupt=True
        )

    # Redirect sensitive file operations
    if tool_name in ["Write", "Edit"] and "config" in input_data.get("file_path", ""):
        safe_path = f"./sandbox/{input_data['file_path']}"
        return PermissionResultAllow(
            updated_input={**input_data, "file_path": safe_path}
        )

    # Allow everything else
    return PermissionResultAllow(updated_input=input_data)


async def main():
    # Não liste também as ferramentas controladas em allowed_tools: as regras de permissão aprovam chamadas antes que can_use_tool seja executado
    options = ClaudeAgentOptions(can_use_tool=custom_permission_handler)

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Update the system config file")

        async for message in client.receive_response():
            # Will use sandbox path instead
            print(message)


asyncio.run(main())

Tipos

`SdkMcpTool`

Definição para uma ferramenta MCP do SDK criada com o decorador @tool.

@dataclass
class SdkMcpTool(Generic[T]):
    name: str
    description: str
    input_schema: type[T] | dict[str, Any]
    handler: Callable[[T], Awaitable[dict[str, Any]]]
    annotations: ToolAnnotations | None = None

`Transport`

Classe base abstrata para implementações de transporte personalizadas. Use isto para se comunicar com o processo Claude através de um canal personalizado (por exemplo, uma conexão remota em vez de um subprocesso local).

from abc import ABC, abstractmethod
from collections.abc import AsyncIterator
from typing import Any


class Transport(ABC):
    @abstractmethod
    async def connect(self) -> None: ...

    @abstractmethod
    async def write(self, data: str) -> None: ...

    @abstractmethod
    def read_messages(self) -> AsyncIterator[dict[str, Any]]: ...

    @abstractmethod
    async def close(self) -> None: ...

    @abstractmethod
    def is_ready(self) -> bool: ...

    @abstractmethod
    async def end_input(self) -> None: ...

Importação: from claude_agent_sdk import Transport

`ClaudeAgentOptions`

Dataclass de configuração para consultas Claude Code.

@dataclass
class ClaudeAgentOptions:
    tools: list[str] | ToolsPreset | None = None
    allowed_tools: list[str] = field(default_factory=list)
    system_prompt: str | SystemPromptPreset | SystemPromptCustom | SystemPromptFile | None = None
    mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
    strict_mcp_config: bool = False
    permission_mode: PermissionMode | None = None
    continue_conversation: bool = False
    resume: str | None = None
    session_id: str | None = None
    max_turns: int | None = None
    max_budget_usd: float | None = None
    disallowed_tools: list[str] = field(default_factory=list)
    model: str | None = None
    fallback_model: str | None = None
    betas: list[SdkBeta] = field(default_factory=list)
    output_format: dict[str, Any] | None = None
    permission_prompt_tool_name: str | None = None
    cwd: str | Path | None = None
    cli_path: str | Path | None = None
    settings: str | None = None
    add_dirs: list[str | Path] = field(default_factory=list)
    env: dict[str, str] = field(default_factory=dict)
    extra_args: dict[str, str | None] = field(default_factory=dict)
    max_buffer_size: int | None = None
    debug_stderr: Any = sys.stderr  # Deprecated
    stderr: Callable[[str], None] | None = None
    can_use_tool: CanUseTool | None = None
    hooks: dict[HookEvent, list[HookMatcher]] | None = None
    user: str | None = None
    include_partial_messages: bool = False
    include_hook_events: bool = False
    forward_subagent_text: bool = False
    fork_session: bool = False
    resume_session_at: str | None = None
    resume_drops_turn: str | None = None
    agents: dict[str, AgentDefinition] | None = None
    setting_sources: list[SettingSource] | None = None
    skills: list[str] | Literal["all"] | None = None
    sandbox: SandboxSettings | None = None
    plugins: list[SdkPluginConfig] = field(default_factory=list)
    max_thinking_tokens: int | None = None  # Deprecated: use thinking instead
    thinking: ThinkingConfig | None = None
    effort: EffortLevel | None = None
    enable_file_checkpointing: bool = False
    session_store: SessionStore | None = None
    session_store_flush: SessionStoreFlushMode = "batched"
    load_timeout_ms: int = 60_000
    task_budget: TaskBudget | None = None

Lidar com respostas de API lentas ou travadas

O subprocesso CLI lê várias variáveis de ambiente que controlam timeouts de API e detecção de travamento. Passe-as através de ClaudeAgentOptions.env:

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    env={
        "API_TIMEOUT_MS": "120000",
        "CLAUDE_CODE_MAX_RETRIES": "2",
        "CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS": "120000",
    },
)

• API_TIMEOUT_MS: timeout por requisição no cliente Anthropic, em milissegundos. Padrão 600000. Aplica-se ao loop principal e todos os subagentes.

• CLAUDE_CODE_MAX_RETRIES: máximo de tentativas de API. Padrão 10, limitado a 15. Cada tentativa obtém sua própria janela API_TIMEOUT_MS, então o tempo de parede no pior caso é aproximadamente API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1) mais backoff. Para execuções sem supervisão que precisam esperar por interrupções mais longas, defina CLAUDE_CODE_RETRY_WATCHDOG=1: ele tenta novamente erros de capacidade transitória indefinidamente e, no Claude Code v2.1.199 ou posterior, aumenta o padrão para outros erros transitórios para 300 e remove o limite nesta variável.

• CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: watchdog de travamento para subagentes. Enquanto o watchdog de stream está ativo, o padrão é CLAUDE_STREAM_IDLE_TIMEOUT_MS mais 5 minutos, o que resulta em 600000 a menos que você aumente essa variável. Com o watchdog de stream desativado, o padrão é 600000. Antes de v2.1.257, o padrão era sempre 600000.

  O temporizador é redefinido em cada evento de stream. Em um travamento, Claude Code aborta o subagente e relata o travamento ao pai. Para um subagente em background, também marca a tarefa como falhada e anexa qualquer resultado parcial.

• CLAUDE_ENABLE_STREAM_WATCHDOG com CLAUDE_STREAM_IDLE_TIMEOUT_MS: watchdog de stream que aborta a requisição quando os headers chegaram mas o corpo da resposta para de fazer stream. O watchdog está ativado por padrão para todos os provedores; defina CLAUDE_ENABLE_STREAM_WATCHDOG=0 para desativá-lo. CLAUDE_STREAM_IDLE_TIMEOUT_MS padrão é 300000 e é limitado a esse mínimo. Após o aborto, Tentativas automáticas cobre o que Claude Code faz, baseado em quão longe a resposta havia progredido.

  Enquanto o watchdog aguarda uma resposta que um gateway atrás de ANTHROPIC_BASE_URL mantém aberta com pings keep-alive, um host que define include_partial_messages continua recebendo mensagens ping StreamEvent. Leia esses frames como vivacidade em vez de fazer timeout da sessão no silêncio. Antes de v2.1.257, os frames paravam 5 minutos após o último evento de stream real.

`OutputFormat`

Configuração para validação de saída estruturada. Passe isto como um dict para o campo output_format em ClaudeAgentOptions:

# Forma de dict esperada para output_format
{
    "type": "json_schema",
    "schema": {...},  # Sua definição JSON Schema
}

`SystemPromptPreset`

Configuração para usar o prompt do sistema predefinido do Claude Code com adições opcionais.

class SystemPromptPreset(TypedDict):
    type: Literal["preset"]
    preset: Literal["claude_code"]
    append: NotRequired[str]
    exclude_dynamic_sections: NotRequired[bool]
    snapshot: NotRequired[bool]

`SystemPromptCustom`

Um prompt do sistema personalizado em forma de objeto, equivalente a passar uma string como system_prompt, que também pode definir snapshot. Requer claude-agent-sdk v0.2.153 ou posterior.

class SystemPromptCustom(TypedDict):
    type: Literal["custom"]
    prompt: str
    snapshot: NotRequired[bool]

`SystemPromptFile`

Configuração para carregar um prompt do sistema personalizado de um arquivo em vez de passá-lo como uma string. O SDK mapeia isto para a flag CLI --system-prompt-file. Use a forma de arquivo quando o prompt é grande: o SDK passa um system_prompt string no argv do subprocesso CLI, que está sujeito a limites de comprimento de linha de comando do SO antes do SDK enviar qualquer requisição de API. No Linux um único argumento mais longo que aproximadamente 128 KB falha no spawn do processo com Argument list too long. No Windows toda a linha de comando é limitada a aproximadamente 32 KB, então a forma de string falha em um limite mais baixo.

class SystemPromptFile(TypedDict):
    type: Literal["file"]
    path: str

`SettingSource`

Controla quais fontes de configuração baseadas em sistema de arquivos o SDK carrega configurações.

SettingSource = Literal["user", "project", "local"]

Comportamento padrão

Quando setting_sources é omitido ou None e skills não está definido, query() carrega as mesmas configurações do sistema de arquivos que a CLI Claude Code: usuário, projeto e local. Com skills definido, a linha setting_sources descreve o padrão atual. Política gerenciada por endpoint é carregada em todos os casos; configurações gerenciadas por servidor são buscadas quando a sessão se autentica com uma credencial de organização em uma configuração elegível. Para mais informações, veja O que settingSources não controla.

Por que usar setting\_sources

Desabilitar configurações do sistema de arquivos:

# Não carregar configurações de usuário, projeto ou local do disco
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Analyze this code",
        options=ClaudeAgentOptions(
            setting_sources=[]
        ),
    ):
        print(message)


asyncio.run(main())

Carregar apenas fontes de configuração específicas:

# Carregar apenas configurações de projeto, ignorar usuário e local
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Run CI checks",
        options=ClaudeAgentOptions(
            setting_sources=["project"]  # Apenas .claude/settings.json
        ),
    ):
        print(message)


asyncio.run(main())

Aplicações apenas SDK:

# Definir tudo programaticamente.
# Passe [] para optar por não usar fontes de configuração do sistema de arquivos.
import asyncio
from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, query


async def main():
    async for message in query(
        prompt="Review this PR",
        options=ClaudeAgentOptions(
            setting_sources=[],
            agents={
                "code-reviewer": AgentDefinition(
                    description="Reviews code changes",
                    prompt="You are a code reviewer. Report issues in the diff.",
                ),
            },
            allowed_tools=["Read", "Grep", "Glob"],
        ),
    ):
        print(message)


asyncio.run(main())

Para carregar instruções de projeto CLAUDE.md, inclua "project" em setting_sources. Veja Modificar prompts do sistema para como o carregamento de CLAUDE.md interage com as opções de prompt do sistema.

Precedência de configurações

Quando múltiplas fontes são carregadas, as configurações são mescladas com esta precedência (maior para menor):

1. Configurações locais (.claude/settings.local.json)
2. Configurações de projeto (.claude/settings.json)
3. Configurações do usuário (~/.claude/settings.json)

Opções programáticas como agents, allowed_tools, e settings substituem configurações do sistema de arquivos de usuário, projeto e local. Configurações de política gerenciada têm precedência sobre opções programáticas.

`AgentDefinition`

Configuração para um subagente definido programaticamente.

@dataclass
class AgentDefinition:
    description: str
    prompt: str
    tools: list[str] | None = None
    disallowedTools: list[str] | None = None
    model: str | None = None
    skills: list[str] | None = None
    memory: Literal["user", "project", "local"] | None = None
    mcpServers: list[str | dict[str, Any]] | None = None
    initialPrompt: str | None = None
    maxTurns: int | None = None
    background: bool | None = None
    effort: EffortLevel | int | None = None
    permissionMode: PermissionMode | None = None

`PermissionMode`

Modos de permissão para controlar execução de ferramentas.

PermissionMode = Literal[
    "default",  # Comportamento de permissão padrão
    "acceptEdits",  # Auto-aceitar edições de arquivo
    "plan",  # Modo de planejamento - explorar sem editar
    "dontAsk",  # Negar qualquer coisa não pré-aprovada em vez de solicitar
    "bypassPermissions",  # Contornar verificações de permissão; regras de ask explícitas ainda solicitam (use com cuidado)
    "auto",  # Classificador de modelo aprova ou nega prompts de permissão
]

`EffortLevel`

Níveis de esforço para guiar profundidade de pensamento.

EffortLevel = Literal[
    "low",  # Pensamento mínimo, respostas mais rápidas
    "medium",  # Pensamento moderado
    "high",  # Raciocínio profundo
    "xhigh",  # Raciocínio estendido; volta para "high" em modelos que não suportam
    "max",  # Esforço máximo
]

`CanUseTool`

Alias de tipo para funções de callback de permissão de ferramenta.

CanUseTool = Callable[
    [str, dict[str, Any], ToolPermissionContext], Awaitable[PermissionResult]
]

O callback recebe:

• tool_name: Nome da ferramenta sendo chamada
• input_data: Os parâmetros de entrada da ferramenta
• context: Um ToolPermissionContext com informações adicionais

Retorna um PermissionResult (ou PermissionResultAllow ou PermissionResultDeny).

O callback é a substituição SDK para o prompt de permissão interativo: é invocado apenas quando o fluxo de avaliação de permissão se resolve em um prompt. Chamadas de ferramenta já aprovadas por uma entrada allowed_tools, uma regra de permissão de configurações, ou o modo de permissão, como acceptEdits ou bypassPermissions, nunca o invocam. Para controlar cada chamada de ferramenta, use um hook PreToolUse em vez disso.

Uma regra de permissão não pré-aprova as ações que nenhum modo aprova automaticamente; veja Como permissões são avaliadas para qual delas chega ao callback e o que acontece em modo dontAsk e auto.

`ToolPermissionContext`

Informações de contexto passadas para callbacks de permissão de ferramenta.

@dataclass
class ToolPermissionContext:
    signal: Any | None = None  # Futuro: suporte a sinal de aborto
    suggestions: list[PermissionUpdate] = field(default_factory=list)
    tool_use_id: str | None = None
    agent_id: str | None = None
    blocked_path: str | None = None
    decision_reason: str | None = None
    title: str | None = None
    display_name: str | None = None
    description: str | None = None

`PermissionResult`

Tipo de união para resultados de callback de permissão.

PermissionResult = PermissionResultAllow | PermissionResultDeny

`PermissionResultAllow`

Resultado indicando que a chamada de ferramenta deve ser permitida.

@dataclass
class PermissionResultAllow:
    behavior: Literal["allow"] = "allow"
    updated_input: dict[str, Any] | None = None
    updated_permissions: list[PermissionUpdate] | None = None

`PermissionResultDeny`

Resultado indicando que a chamada de ferramenta deve ser negada.

@dataclass
class PermissionResultDeny:
    behavior: Literal["deny"] = "deny"
    message: str = ""
    interrupt: bool = False

`PermissionUpdate`

Configuração para atualizar permissões programaticamente.

@dataclass
class PermissionUpdate:
    type: Literal[
        "addRules",
        "replaceRules",
        "removeRules",
        "setMode",
        "addDirectories",
        "removeDirectories",
    ]
    rules: list[PermissionRuleValue] | None = None
    behavior: Literal["allow", "deny", "ask"] | None = None
    mode: PermissionMode | None = None
    directories: list[str] | None = None
    destination: (
        Literal["userSettings", "projectSettings", "localSettings", "session"] | None
    ) = None

`PermissionRuleValue`

Uma regra para adicionar, substituir ou remover em uma atualização de permissão.

@dataclass
class PermissionRuleValue:
    tool_name: str
    rule_content: str | None = None

`ToolsPreset`

Configuração de ferramentas predefinidas para usar o conjunto de ferramentas padrão do Claude Code.

class ToolsPreset(TypedDict):
    type: Literal["preset"]
    preset: Literal["claude_code"]

`ThinkingConfig`

Controla comportamento de pensamento estendido. Uma união de três configurações:

ThinkingDisplay = Literal["summarized", "omitted"]


class ThinkingConfigAdaptive(TypedDict):
    type: Literal["adaptive"]
    display: NotRequired[ThinkingDisplay]


class ThinkingConfigEnabled(TypedDict):
    type: Literal["enabled"]
    budget_tokens: int
    display: NotRequired[ThinkingDisplay]


class ThinkingConfigDisabled(TypedDict):
    type: Literal["disabled"]


ThinkingConfig = ThinkingConfigAdaptive | ThinkingConfigEnabled | ThinkingConfigDisabled

O campo display opcional controla se o texto de pensamento é retornado "summarized" ou "omitted". No Claude Opus 4.7 e posterior, o padrão da API é "omitted", então defina "summarized" para receber conteúdo de pensamento em saídas ThinkingBlock. Claude Code não envia display para Amazon Bedrock ou Google Cloud's Agent Platform, então nesses provedores Opus 4.7 e posterior retornam saídas ThinkingBlock vazias mesmo quando você define display para "summarized".

Como estas são classes TypedDict, elas são dicts simples em tempo de execução. Construa-as como literais de dict ou chame a classe como um construtor; ambos produzem um dict. Acesse campos com config["budget_tokens"], não config.budget_tokens:

from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled

# Opção 1: literal de dict (recomendado, sem importação necessária)
options = ClaudeAgentOptions(thinking={"type": "enabled", "budget_tokens": 20000})

# Opção 2: estilo construtor (retorna um dict simples)
config = ThinkingConfigEnabled(type="enabled", budget_tokens=20000)
print(config["budget_tokens"])  # 20000
# config.budget_tokens levantaria AttributeError

`TaskBudget`

Orçamento de tarefa do lado da API em tokens, usado com o campo task_budget em ClaudeAgentOptions.

class TaskBudget(TypedDict):
    total: int

Como isto é um TypedDict, passe-o como um dict simples, como ClaudeAgentOptions(task_budget={"total": 50000}).

`SdkBeta`

Tipo literal para recursos beta do SDK.

SdkBeta = Literal["context-1m-2025-08-07"]

Use com o campo betas em ClaudeAgentOptions para ativar recursos beta.

`McpSdkServerConfig`

Configuração para servidores MCP do SDK criados com create_sdk_mcp_server().

class McpSdkServerConfig(TypedDict):
    type: Literal["sdk"]
    name: str
    instance: Any  # Instância do servidor MCP

`McpServerConfig`

Tipo de união para configurações de servidor MCP.

McpServerConfig = (
    McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig
)

`McpStdioServerConfig`

class McpStdioServerConfig(TypedDict):
    type: NotRequired[Literal["stdio"]]  # Opcional para compatibilidade com versões anteriores
    command: str
    args: NotRequired[list[str]]
    env: NotRequired[dict[str, str]]

`McpSSEServerConfig`

class McpSSEServerConfig(TypedDict):
    type: Literal["sse"]
    url: str
    headers: NotRequired[dict[str, str]]

`McpHttpServerConfig`

class McpHttpServerConfig(TypedDict):
    type: Literal["http"]
    url: str
    headers: NotRequired[dict[str, str]]

`McpServerStatusConfig`

A configuração de um servidor MCP conforme relatado por get_mcp_status(). Esta é a união de todas as variantes de transporte McpServerConfig mais uma variante de saída única claudeai-proxy para servidores proxied através de claude.ai.

McpServerStatusConfig = (
    McpStdioServerConfig
    | McpSSEServerConfig
    | McpHttpServerConfig
    | McpSdkServerConfigStatus
    | McpClaudeAIProxyServerConfig
)

McpSdkServerConfigStatus é a forma serializável de McpSdkServerConfig com apenas campos type ("sdk") e name (str); a instance em processo é omitida. McpClaudeAIProxyServerConfig tem campos type ("claudeai-proxy"), url (str), e id (str).

`McpStatusResponse`

Resposta de ClaudeSDKClient.get_mcp_status(). Envolve a lista de status de servidor sob a chave mcpServers.

class McpStatusResponse(TypedDict):
    mcpServers: list[McpServerStatus]

`McpServerStatus`

Status de um servidor MCP conectado, contido em McpStatusResponse.

class McpServerStatus(TypedDict):
    name: str
    status: McpServerConnectionStatus  # "connected" | "failed" | "needs-auth" | "pending" | "disabled"
    serverInfo: NotRequired[McpServerInfo]
    error: NotRequired[str]
    config: NotRequired[McpServerStatusConfig]
    scope: NotRequired[str]
    tools: NotRequired[list[McpToolInfo]]

`SdkPluginConfig`

Configuração para carregar plugins no SDK.

class SdkPluginConfig(TypedDict):
    type: Literal["local"]
    path: str

Exemplo:

plugins = [
    {"type": "local", "path": "./my-plugin"},
    {"type": "local", "path": "/absolute/path/to/plugin"},
]

Para informações completas sobre criação e uso de plugins, veja Plugins.

Tipos de Mensagem

`Message`

Tipo de união de todas as mensagens possíveis.

Message = (
    UserMessage
    | AssistantMessage
    | SystemMessage
    | ResultMessage
    | StreamEvent
    | RateLimitEvent
    | ConversationResetMessage
)

`UserMessage`

Mensagem de entrada do usuário.

@dataclass
class UserMessage:
    content: str | list[ContentBlock]
    uuid: str | None = None
    parent_tool_use_id: str | None = None
    tool_use_result: dict[str, Any] | None = None
    origin: MessageOrigin | None = None

O SDK passa tool_use_result através da CLI sem modificação. Para uma ferramenta em um servidor MCP externo cujo resultado contém blocos resource_link, o dict tem uma chave resourceLinks contendo uma lista de dicts com as chaves do tipo TypeScript SDKMcpResourceLink. Claude recebe cada link como uma linha de texto no resultado da ferramenta. Para renderizar os arquivos que o servidor retornou, leia resourceLinks em vez de analisar esse texto. A chave resourceLinks requer Python Agent SDK 0.2.150 ou posterior e Claude Code v2.1.257 ou posterior; a CLI agrupada com essa versão do SDK satisfaz o requisito do Claude Code.

A CLI omite a chave quando o resultado não tem links e em resultados de subagentes. A CLI mantém no máximo 50 links por resultado e para de adicionar links quando a lista atinge 64 KiB de JSON serializado. Uma ferramenta que você define em processo com tool() nunca produz a chave, porque o SDK achata seus blocos resource_link em texto antes da CLI ver o resultado.

`AssistantMessage`

Mensagem de resposta do assistente com blocos de conteúdo.

@dataclass
class AssistantMessage:
    content: list[ContentBlock]
    model: str
    parent_tool_use_id: str | None = None
    error: AssistantMessageError | None = None
    usage: dict[str, Any] | None = None
    message_id: str | None = None
    stop_reason: str | None = None
    session_id: str | None = None
    uuid: str | None = None

`AssistantMessageError`

Possíveis tipos de erro para mensagens do assistente.

AssistantMessageError = Literal[
    "authentication_failed",
    "billing_error",
    "rate_limit",
    "invalid_request",
    "server_error",
    "unknown",
]

O processo CLI subjacente pode emitir tipos de erro que este Literal não lista, como max_output_tokens. O SDK passa o valor através sem modificação, então trate strings fora desta lista da forma que você trata unknown. O tipo TypeScript SDKAssistantMessageError lista o conjunto completo de valores que a CLI pode emitir.

`SystemMessage`

Mensagem do sistema com metadados.

@dataclass
class SystemMessage:
    subtype: str
    data: dict[str, Any]

`ResultMessage`

Mensagem de resultado final com informações de custo e uso.

@dataclass
class ResultMessage:
    subtype: str
    duration_ms: int
    duration_api_ms: int
    is_error: bool
    num_turns: int
    session_id: str
    stop_reason: str | None = None
    total_cost_usd: float | None = None
    usage: dict[str, Any] | None = None
    result: str | None = None
    structured_output: Any = None
    model_usage: dict[str, ModelUsage] | None = None
    permission_denials: list[Any] | None = None
    deferred_tool_use: DeferredToolUse | None = None
    errors: list[str] | None = None
    api_error_status: int | None = None
    uuid: str | None = None
    terminal_reason: str | None = None
    origin: MessageOrigin | None = None

O campo subtype determina quais outros campos são preenchidos. É um de "success", "error_during_execution", "error_max_turns", "error_max_budget_usd" ou "error_max_structured_output_retries". A dataclass Python achata todas as variantes em uma forma, portanto campos que não se aplicam ao subtipo retornado são None.

Vários campos carregam detalhes de diagnóstico sobre como a conversa terminou:

• is_error: True quando a conversa terminou em um estado de erro. Sempre True nos subtipos error_*. Em subtype="success" é True quando a solicitação final do modelo falhou, significando que o loop do agente foi concluído mas a última chamada da API retornou um erro.
• api_error_status: o código de status HTTP do erro de API de encerramento. None quando o turno terminou sem um. Preenchido apenas em subtype="success".
• result: texto da mensagem final do assistente em subtype="success", ou None nos subtipos error_*. Quando subtype="success" e is_error=True, isso contém a string de erro da API se uma estiver disponível mas pode estar vazio, então verifique api_error_status e o conteúdo anterior de AssistantMessage para detalhes.
• errors: strings de erro no nível do loop, como a mensagem de máximo de turnos. Preenchido apenas nos subtipos error_*.
• terminal_reason: por que o loop de consulta terminou, como "completed", "max_turns", "api_error", "aborted_streaming" ou "aborted_tools". Um valor de "aborted_streaming" ou "aborted_tools" significa que o turno foi abortado antes de ser concluído. As causas comuns são interrupt() e um callback de permissão retornando PermissionResultDeny com interrupt=True. None em versões da CLI que antecedem o campo, em resultados de comandos locais como /voice ou /usage, que contornam o loop de consulta, ou em resultados de erro sintetizados emitidos quando a sessão falha fatalmente. Espelha o SDKResultMessage.terminal_reason do SDK TypeScript, que lista o conjunto completo de valores.
• origin: origem da mensagem do usuário que acionou este turno. Em modo de entrada de streaming, verifique isso para distinguir o resultado do seu próprio prompt, onde origin é None ou {"kind": "human"}, do resultado de um turno injetado, como uma notificação de tarefa de fundo. Requer Python Agent SDK 0.2.137 ou posterior.

O dict usage cobre apenas o loop do agente principal e exclui subagentes e outras chamadas de modelo aninhadas ou auxiliares. Em modo de entrada de streaming, os valores são por turno. Prefira model_usage para contabilidade de token e custo. O dict usage contém as seguintes chaves quando presentes:

O dict model_usage mapeia nomes de modelo para uso por modelo. Ele cobre cada chamada de modelo feita através do pipeline de consulta: o loop principal, subagentes e chamadas internas como compactação e agentes Workflow. Chamadas auxiliares fora desse pipeline, como o classificador de permissão e solicitações de contagem de tokens, são excluídas de model_usage. Trate model_usage como uma estimativa, não como um extrato de faturamento.

Em modo de entrada de streaming, model_usage e total_cost_usd são cumulativos entre turnos, então leia o resultado mais recente em vez de somar entre resultados. Uma chamada que retoma uma sessão também conta os totais restaurados das chamadas anteriores da sessão. Veja Rastrear custos em modo de entrada de streaming para redefinições e Recuperar totais após uma falha de sessão para resultados zerados.

Cada valor em model_usage é um TypedDict ModelUsage, importado via from claude_agent_sdk.types import ModelUsage. Suas chaves usam camelCase porque o SDK passa o valor através sem modificação do processo CLI subjacente, correspondendo ao tipo TypeScript ModelUsage:

`StreamEvent`

Evento de fluxo para atualizações de mensagem parcial durante streaming. Apenas recebido quando include_partial_messages=True em ClaudeAgentOptions. Importe via from claude_agent_sdk.types import StreamEvent.

@dataclass
class StreamEvent:
    uuid: str
    session_id: str
    event: dict[str, Any]  # The raw Claude API stream event
    parent_tool_use_id: str | None = None

`RateLimitEvent`

Emitido quando o status do limite de taxa muda (por exemplo, de "allowed" para "allowed_warning"). Use isso para avisar usuários antes de atingirem um limite rígido, ou para recuar quando o status é "rejected".

@dataclass
class RateLimitEvent:
    rate_limit_info: RateLimitInfo
    uuid: str
    session_id: str

`RateLimitInfo`

Estado de limite de taxa carregado por RateLimitEvent.

RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]
RateLimitType = Literal[
    "five_hour", "seven_day", "seven_day_opus", "seven_day_sonnet", "overage"
]


@dataclass
class RateLimitInfo:
    status: RateLimitStatus
    resets_at: int | None = None
    rate_limit_type: RateLimitType | None = None
    utilization: float | None = None
    overage_status: RateLimitStatus | None = None
    overage_resets_at: int | None = None
    overage_disabled_reason: str | None = None
    raw: dict[str, Any] = field(default_factory=dict)

`ConversationResetMessage`

Emitido quando a conversa é substituída sem encerrar a conexão, como após /clear. Veja Rastrear custos em modo de entrada de streaming para como uma redefinição afeta os totais em execução em objetos ResultMessage posteriores. Requer Python Agent SDK 0.2.137 ou posterior.

@dataclass
class ConversationResetMessage:
    new_conversation_id: str
    uuid: str
    session_id: str

`TaskStartedMessage`

Emitido quando uma tarefa de fundo começa. Uma tarefa de fundo é qualquer coisa rastreada fora do turno principal: um comando Bash em fundo, um watch de Monitor, um subagente gerado via ferramenta Agent, ou um agente remoto. O campo task_type diz qual. Esta nomenclatura não está relacionada à renomeação de ferramenta Task-para-Agent.

@dataclass
class TaskStartedMessage(SystemMessage):
    task_id: str
    description: str
    uuid: str
    session_id: str
    tool_use_id: str | None = None
    task_type: str | None = None

`TaskUsage`

Dados de token e tempo para uma tarefa de fundo.

class TaskUsage(TypedDict):
    total_tokens: int
    tool_uses: int
    duration_ms: int

`TaskProgressMessage`

Emitido periodicamente com atualizações de progresso para uma tarefa de fundo em execução.

@dataclass
class TaskProgressMessage(SystemMessage):
    task_id: str
    description: str
    usage: TaskUsage
    uuid: str
    session_id: str
    tool_use_id: str | None = None
    last_tool_name: str | None = None

`TaskNotificationMessage`

Emitido quando uma tarefa de fundo é concluída, falha ou é parada. Tarefas de fundo incluem comandos Bash run_in_background, watches de Monitor e subagentes em fundo.

@dataclass
class TaskNotificationMessage(SystemMessage):
    task_id: str
    status: TaskNotificationStatus  # "completed" | "failed" | "stopped"
    output_file: str
    summary: str
    uuid: str
    session_id: str
    tool_use_id: str | None = None
    usage: TaskUsage | None = None

Quando a CLI move uma chamada de ferramenta MCP longa para o fundo, o resultado da ferramenta para essa chamada contém apenas um espaço reservado e o resultado real da chamada chega nesta mensagem. Em uma notificação "completed" para tal chamada, a CLI adiciona uma chave resource_links listando os arquivos que a ferramenta retornou por referência, com as mesmas entradas e limites que a chave resourceLinks em UserMessage.tool_use_result. A chave resource_links requer Python Agent SDK 0.2.150 ou posterior e Claude Code v2.1.257 ou posterior; a CLI agrupada com essa versão do SDK satisfaz o requisito do Claude Code.

A dataclass não tem campo para resource_links. Leia-o do dict data que a mensagem herda de SystemMessage: message.data.get("resource_links"). Corresponda a notificação à chamada com tool_use_id. A CLI omite a chave quando o resultado não tinha links e em notificações para tarefas que não são chamadas de ferramenta MCP.

Tipos de Bloco de Conteúdo

`ContentBlock`

Tipo de união de todos os blocos de conteúdo.

ContentBlock = (
    TextBlock
    | ThinkingBlock
    | ToolUseBlock
    | ToolResultBlock
    | ServerToolUseBlock
    | ServerToolResultBlock
)

`TextBlock`

Bloco de conteúdo de texto.

@dataclass
class TextBlock:
    text: str

`ThinkingBlock`

Bloco de conteúdo de pensamento (para modelos com capacidade de pensamento).

@dataclass
class ThinkingBlock:
    thinking: str
    signature: str

`ToolUseBlock`

Bloco de solicitação de uso de ferramenta.

@dataclass
class ToolUseBlock:
    id: str
    name: str
    input: dict[str, Any]

`ToolResultBlock`

Bloco de resultado de execução de ferramenta.

@dataclass
class ToolResultBlock:
    tool_use_id: str
    content: str | list[dict[str, Any]] | None = None
    is_error: bool | None = None

Tipos de Erro

Os tipos abaixo definem o que seu código captura. Para entradas com chave nas mensagens de erro que esses tipos levantam, com a causa e correção para cada um, consulte Troubleshooting.

`ClaudeSDKError`

Classe de exceção base para todos os erros do SDK.

class ClaudeSDKError(Exception):
    """Base error for Claude SDK."""

Quando uma query() de uma única tentativa termina com um resultado de erro, por exemplo um erro de limite de turnos, o SDK levanta um ResultError após ceder a mensagem de resultado final. As versões do Python Agent SDK anteriores a 0.2.140 levantavam uma Exception simples que não era uma subclasse de ClaudeSDKError.

`CLINotFoundError`

Levantado quando Claude Code CLI não está instalado ou não é encontrado.

class CLINotFoundError(CLIConnectionError):
    def __init__(
        self, message: str = "Claude Code not found", cli_path: str | None = None
    ):
        """
        Args:
            message: Error message (default: "Claude Code not found")
            cli_path: Optional path to the CLI that was not found
        """

`CLIConnectionError`

Levantado quando a conexão com Claude Code falha.

class CLIConnectionError(ClaudeSDKError):
    """Failed to connect to Claude Code."""

`ProcessError`

Levantado quando o processo Claude Code falha.

class ProcessError(ClaudeSDKError):
    def __init__(
        self, message: str, exit_code: int | None = None, stderr: str | None = None
    ):
        self.exit_code = exit_code
        self.stderr = stderr

`ResultError`

Levantado após a ResultMessage final quando o processo Claude Code sai porque a execução terminou com um resultado de erro, como um erro de limite de turnos ou um erro de API. ResultError é uma subclasse de ProcessError, portanto um manipulador except ProcessError existente também o captura. Seus atributos carregam os campos dessa mensagem de resultado, para que você possa ramificar o motivo da falha da execução sem analisar o texto da mensagem. Requer Python Agent SDK 0.2.140 ou posterior.

class ResultError(ProcessError):
    subtype: str | None  # "error_max_turns", "error_during_execution", ...; "success" when the run ended on a failed request
    errors: list[str]  # an empty list when the result message reported none
    result: str | None
    api_error_status: int | None
    terminal_reason: str | None  # "max_turns", "api_error", ...; check this before subtype
    session_id: str | None
    data: dict[str, Any]  # the raw result message payload

Para distinguir falhas, verifique terminal_reason antes de subtype. Quando a solicitação final falha, como em um erro de API, Claude Code relata subtype "success" com a causa em terminal_reason, por exemplo "api_error"; quando um limite que você definiu encerra a execução, como max_turns ou max_budget_usd, ele relata um subtipo error_*.

`CLIJSONDecodeError`

Levantado quando a análise JSON falha.

class CLIJSONDecodeError(ClaudeSDKError):
    def __init__(self, line: str, original_error: Exception):
        """
        Args:
            line: The line that failed to parse
            original_error: The original JSON decode exception
        """
        self.line = line
        self.original_error = original_error

Tipos de Hook

Para um guia abrangente sobre o uso de hooks com exemplos e padrões comuns, veja o Guia de Hooks.

`HookEvent`

Tipos de evento de hook suportados.

HookEvent = Literal[
    "PreToolUse",  # Called before tool execution
    "PostToolUse",  # Called after tool execution
    "PostToolUseFailure",  # Called when a tool execution fails
    "UserPromptSubmit",  # Called when user submits a prompt
    "Stop",  # Called when stopping execution
    "SubagentStop",  # Called when a subagent stops
    "PreCompact",  # Called before message compaction
    "Notification",  # Called for notification events
    "SubagentStart",  # Called when a subagent starts
    "PermissionRequest",  # Called when a permission decision is needed
]

`HookCallback`

Definição de tipo para funções de callback de hook.

HookCallback = Callable[[HookInput, str | None, HookContext], Awaitable[HookJSONOutput]]

Parâmetros:

• input: Entrada de hook fortemente tipada com uniões discriminadas baseadas em hook_event_name (veja HookInput)
• tool_use_id: Identificador de uso de ferramenta opcional (para hooks relacionados a ferramentas)
• context: Contexto de hook com informações adicionais

Retorna um HookJSONOutput.

`HookContext`

Informações de contexto passadas para callbacks de hook.

class HookContext(TypedDict):
    signal: Any | None  # Future: abort signal support

`HookMatcher`

Configuração para corresponder hooks a eventos ou ferramentas específicas.

@dataclass
class HookMatcher:
    matcher: str | None = (
        None  # Tool name or pattern to match (e.g., "Bash", "Write|Edit")
    )
    hooks: list[HookCallback] = field(
        default_factory=list
    )  # List of callbacks to execute
    timeout: float | None = (
        None  # Timeout in seconds. When omitted, the per-event default applies:
        # 600 for most events, 30 for UserPromptSubmit
    )

`HookInput`

Tipo de união de todos os tipos de entrada de hook. O tipo real depende do campo hook_event_name.

HookInput = (
    PreToolUseHookInput
    | PostToolUseHookInput
    | PostToolUseFailureHookInput
    | UserPromptSubmitHookInput
    | StopHookInput
    | SubagentStopHookInput
    | PreCompactHookInput
    | NotificationHookInput
    | SubagentStartHookInput
    | PermissionRequestHookInput
)

`BaseHookInput`

Campos base presentes em todos os tipos de entrada de hook.

class BaseHookInput(TypedDict):
    session_id: str
    transcript_path: str
    cwd: str
    permission_mode: NotRequired[str]

`PreToolUseHookInput`

Dados de entrada para eventos de hook PreToolUse.

class PreToolUseHookInput(BaseHookInput):
    hook_event_name: Literal["PreToolUse"]
    tool_name: str
    tool_input: dict[str, Any]
    tool_use_id: str
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

`PostToolUseHookInput`

Dados de entrada para eventos de hook PostToolUse.

class PostToolUseHookInput(BaseHookInput):
    hook_event_name: Literal["PostToolUse"]
    tool_name: str
    tool_input: dict[str, Any]
    tool_response: Any
    tool_use_id: str
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

`PostToolUseFailureHookInput`

Dados de entrada para eventos de hook PostToolUseFailure. Chamado quando uma execução de ferramenta falha.

class PostToolUseFailureHookInput(BaseHookInput):
    hook_event_name: Literal["PostToolUseFailure"]
    tool_name: str
    tool_input: dict[str, Any]
    tool_use_id: str
    error: str
    is_interrupt: NotRequired[bool]
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

`UserPromptSubmitHookInput`

Dados de entrada para eventos de hook UserPromptSubmit.

class UserPromptSubmitHookInput(BaseHookInput):
    hook_event_name: Literal["UserPromptSubmit"]
    prompt: str

`StopHookInput`

Dados de entrada para eventos de hook Stop.

class StopHookInput(BaseHookInput):
    hook_event_name: Literal["Stop"]
    stop_hook_active: bool

`SubagentStopHookInput`

Dados de entrada para eventos de hook SubagentStop.

class SubagentStopHookInput(BaseHookInput):
    hook_event_name: Literal["SubagentStop"]
    stop_hook_active: bool
    agent_id: str
    agent_transcript_path: str
    agent_type: str

`PreCompactHookInput`

Dados de entrada para eventos de hook PreCompact.

class PreCompactHookInput(BaseHookInput):
    hook_event_name: Literal["PreCompact"]
    trigger: Literal["manual", "auto"]
    custom_instructions: str | None

`NotificationHookInput`

Dados de entrada para eventos de hook Notification.

class NotificationHookInput(BaseHookInput):
    hook_event_name: Literal["Notification"]
    message: str
    title: NotRequired[str]
    notification_type: str

`SubagentStartHookInput`

Dados de entrada para eventos de hook SubagentStart.

class SubagentStartHookInput(BaseHookInput):
    hook_event_name: Literal["SubagentStart"]
    agent_id: str
    agent_type: str

`PermissionRequestHookInput`

Dados de entrada para eventos de hook PermissionRequest. Permite que hooks manipulem decisões de permissão programaticamente.

class PermissionRequestHookInput(BaseHookInput):
    hook_event_name: Literal["PermissionRequest"]
    tool_name: str
    tool_input: dict[str, Any]
    permission_suggestions: NotRequired[list[Any]]
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

`HookJSONOutput`

Tipo de união para valores de retorno de callback de hook.

HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput

`SyncHookJSONOutput`

Saída de hook síncrona com campos de controle e decisão.

class SyncHookJSONOutput(TypedDict):
    # Control fields
    continue_: NotRequired[bool]  # Whether to proceed (default: True)
    suppressOutput: NotRequired[bool]  # Hide stdout from transcript
    stopReason: NotRequired[str]  # Message when continue is False

    # Decision fields
    decision: NotRequired[Literal["block"]]
    systemMessage: NotRequired[str]  # Warning message for user
    reason: NotRequired[str]  # Feedback for Claude

    # Hook-specific output
    hookSpecificOutput: NotRequired[HookSpecificOutput]

`HookSpecificOutput`

Uma união discriminada de tipos de saída específicos do evento TypedDict. O campo hookEventName determina quais campos são válidos. Para detalhes completos sobre campos disponíveis por evento de hook, veja Controlar execução com hooks.

class PreToolUseHookSpecificOutput(TypedDict):
    hookEventName: Literal["PreToolUse"]
    permissionDecision: NotRequired[Literal["allow", "deny", "ask", "defer"]]
    permissionDecisionReason: NotRequired[str]
    updatedInput: NotRequired[dict[str, Any]]
    additionalContext: NotRequired[str]


class PostToolUseHookSpecificOutput(TypedDict):
    hookEventName: Literal["PostToolUse"]
    additionalContext: NotRequired[str]
    updatedToolOutput: NotRequired[Any]
    updatedMCPToolOutput: NotRequired[Any]  # Deprecated: use updatedToolOutput, which works for all tools


class PostToolUseFailureHookSpecificOutput(TypedDict):
    hookEventName: Literal["PostToolUseFailure"]
    additionalContext: NotRequired[str]


class UserPromptSubmitHookSpecificOutput(TypedDict):
    hookEventName: Literal["UserPromptSubmit"]
    additionalContext: NotRequired[str]


class NotificationHookSpecificOutput(TypedDict):
    hookEventName: Literal["Notification"]
    additionalContext: NotRequired[str]


class SubagentStartHookSpecificOutput(TypedDict):
    hookEventName: Literal["SubagentStart"]
    additionalContext: NotRequired[str]


class PermissionRequestHookSpecificOutput(TypedDict):
    hookEventName: Literal["PermissionRequest"]
    decision: dict[str, Any]


HookSpecificOutput = (
    PreToolUseHookSpecificOutput
    | PostToolUseHookSpecificOutput
    | PostToolUseFailureHookSpecificOutput
    | UserPromptSubmitHookSpecificOutput
    | NotificationHookSpecificOutput
    | SubagentStartHookSpecificOutput
    | PermissionRequestHookSpecificOutput
)

`AsyncHookJSONOutput`

Saída de hook assíncrona que adia a execução do hook.

class AsyncHookJSONOutput(TypedDict):
    async_: Literal[True]  # Set to True to defer execution
    asyncTimeout: NotRequired[int]  # Timeout in milliseconds

Exemplo de Uso de Hook

Este exemplo registra dois hooks: um que bloqueia comandos bash perigosos como rm -rf /, e outro que registra todo o uso de ferramenta para auditoria. O hook de segurança funciona apenas em comandos Bash (via matcher), enquanto o hook de registro funciona em todas as ferramentas.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, HookContext
from typing import Any


async def validate_bash_command(
    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
) -> dict[str, Any]:
    """Validate and potentially block dangerous bash commands."""
    if input_data["tool_name"] == "Bash":
        command = input_data["tool_input"].get("command", "")
        if "rm -rf /" in command:
            return {
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason": "Dangerous command blocked",
                }
            }
    return {}


async def log_tool_use(
    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
) -> dict[str, Any]:
    """Log all tool usage for auditing."""
    print(f"Tool used: {input_data.get('tool_name')}")
    return {}


options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [
            HookMatcher(
                matcher="Bash", hooks=[validate_bash_command], timeout=120
            ),  # 2 min for validation
            HookMatcher(
                hooks=[log_tool_use]
            ),  # Applies to all tools (per-event default timeout)
        ],
        "PostToolUse": [HookMatcher(hooks=[log_tool_use])],
    }
)

async def main():
    async for message in query(prompt="Analyze this codebase", options=options):
        print(message)


asyncio.run(main())

Tipos de Entrada/Saída de Ferramenta

Documentação de schemas de entrada/saída para todas as ferramentas Claude Code integradas. Embora o SDK Python não exporte esses como tipos, eles representam a estrutura de entradas e saídas de ferramenta em mensagens.

Agent

Nome da ferramenta: Agent. O nome anterior Task ainda é aceito como alias, e a lista tools na SystemMessage de inicialização relata essa ferramenta como Task para compatibilidade com versões anteriores.

Entrada:

{
    "description": str,  # Uma descrição breve (3-5 palavras) da tarefa
    "prompt": str,  # A tarefa para o agente executar
    "subagent_type": str | None,  # O tipo de agente especializado a usar
    "model": "sonnet" | "opus" | "haiku" | "fable" | None,  # Substituição de modelo para este agente
    "run_in_background": bool | None,  # Agentes executam em segundo plano por padrão; defina como False para executar sincronamente
    "name": str | None,  # Nome para o agente gerado
    "team_name": str | None,  # Descontinuado; ignorado
    "mode": "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan" | None,  # Descontinuado; ignorado. As regras de herança de subagente decidem o modo de permissão de um subagente
    "isolation": "worktree" | "remote" | None,  # Modo de isolamento para as alterações do agente
}

Inicia um novo agente para lidar com tarefas complexas e multi-etapas autonomamente.

Saída (status: "completed"):

{
    "status": "completed",
    "agentId": str,  # ID do agente que foi executado
    "agentType": str | None,  # O tipo de subagente que tratou a tarefa
    "content": [  # Blocos de conteúdo de resultado
        {
            "type": "text",
            "text": str,
            "citations": list | None,
        }
    ],
    "resolvedModel": str | None,  # Modelo em que o subagente iniciou
    "modelsUsed": list[str] | None,  # Modelos usados em ordem, com repetições consecutivas colapsadas
    "totalToolUseCount": int,  # Número de chamadas de ferramenta que o agente fez
    "totalDurationMs": int,  # Duração da execução em milissegundos
    "totalTokens": int,  # Contagem de tokens da solicitação final da API, não de toda a execução
    "usage": {  # Estatísticas de uso de tokens
        "input_tokens": int,
        "output_tokens": int,
        "cache_creation_input_tokens": int | None,
        "cache_read_input_tokens": int | None,
        "server_tool_use": {"web_search_requests": int, "web_fetch_requests": int} | None,
        "service_tier": str | None,
        "cache_creation": {"ephemeral_1h_input_tokens": int, "ephemeral_5m_input_tokens": int} | None,
        "inference_geo": str | None,
        "speed": str | None,
        "iterations": Any | None,
        "output_tokens_details": {"thinking_tokens": int | None} | None,
    },
    "toolStats": {  # Atividade de ferramenta agregada para a execução
        "readCount": int,
        "searchCount": int,
        "bashCount": int,
        "editFileCount": int,
        "linesAdded": int,
        "linesRemoved": int,
        "otherToolCount": int,
        "frameCount": int | None,
    } | None,
    "prompt": str,  # O prompt que o agente executou
    "worktreePath": str | None,  # Presente quando Claude Code manteve a worktree do subagente
    "worktreeBranch": str | None,  # Presente quando Claude Code criou essa worktree com git
}

Saída (status: "async_launched"):

{
    "status": "async_launched",
    "isAsync": bool | None,  # True em lançamentos em segundo plano
    "agentId": str,  # ID do agente lançado
    "description": str,  # A descrição da tarefa
    "resolvedModel": str | None,  # Modelo em uso na transição de backgrounding
    "modelsUsed": list[str] | None,  # Modelos usados antes do backgrounding, em ordem, com repetições consecutivas colapsadas
    "prompt": str,  # O prompt que o agente executa
    "outputFile": str,  # Caminho do arquivo onde a saída do agente é escrita
    "canReadOutputFile": bool | None,  # Se o arquivo de saída pode ser lido diretamente
}

Saída (status: "remote_launched"):

{
    "status": "remote_launched",
    "taskId": str,  # ID da tarefa despachada
    "sessionUrl": str,  # Link para a sessão em nuvem
    "description": str,  # A descrição da tarefa
    "prompt": str,  # O prompt que o agente executa
    "outputFile": str,  # Caminho do arquivo onde a saída do agente é escrita
}

Retorna o resultado do subagente. A saída é discriminada no campo status: "completed" para tarefas concluídas, "async_launched" para tarefas em segundo plano, e "remote_launched" para tarefas que Claude Code despachou para uma sessão em nuvem, onde sessionUrl vincula a essa sessão e taskId a identifica. Se Claude Code manteve a worktree isolada do subagente, worktreePath na variante completed é onde encontrá-la, e worktreeBranch é seu branch quando Claude Code criou a worktree com git.

Na variante completed, resolvedModel nomeia o modelo em que o subagente iniciou, que pode diferir do model de entrada solicitado quando availableModels ou outra substituição se aplica. Este campo requer Claude Code v2.1.174 ou posterior. Na variante async_launched, resolvedModel nomeia o modelo em uso quando o agente se moveu para o segundo plano, então uma troca que aconteceu antes do backgrounding é refletida lá. O campo modelsUsed em ambas as variantes lista os modelos usados em ordem, com repetições consecutivas colapsadas; é definido apenas quando o modelo foi trocado durante a execução. modelsUsed e o comportamento de resolvedModel no tempo de backgrounding requerem Claude Code v2.1.212 ou posterior.

Claude Code preenche usage e totalTokens da solicitação final da API do subagente, não de toda a execução. Quando presente, thinking_tokens sob output_tokens_details em usage é o número de tokens de saída dessa solicitação que eram tokens de pensamento. A chave output_tokens_details requer Python SDK v0.2.136 ou posterior, que agrupa Claude Code v2.1.228.

AskUserQuestion

Nome da ferramenta: AskUserQuestion

Faz perguntas de esclarecimento ao usuário durante a execução. Veja Lidar com aprovações e entrada do usuário para detalhes de uso.

Entrada:

{
    "questions": [  # Perguntas a fazer ao usuário (1-4 perguntas)
        {
            "question": str,  # A pergunta completa a fazer ao usuário
            "header": str,  # Rótulo muito breve exibido como chip/tag (máx 12 caracteres)
            "options": [  # As escolhas disponíveis (2-4 opções)
                {
                    "label": str,  # Texto de exibição para esta opção (1-5 palavras)
                    "description": str,  # Explicação do que esta opção significa
                    "preview": str | None,  # Conteúdo de visualização renderizado quando a opção está em foco
                }
            ],
            "multiSelect": bool,  # Defina como true para permitir múltiplas seleções
        }
    ],
    "answers": dict[str, str] | None,
    # Respostas do usuário preenchidas pelo sistema de permissões. Respostas
    # de múltipla seleção são uma string separada por vírgula dos rótulos selecionados; uma
    # lista de rótulos é aceita na entrada e coagida para essa forma
    "annotations": dict[str, dict] | None,
    # Anotações por pergunta do usuário, indexadas por texto da pergunta.
    # Cada valor pode conter "preview" (conteúdo de visualização da opção selecionada)
    # e "notes" (notas de texto livre na seleção)
    "metadata": dict | None,  # Metadados de análise, como {"source": "remember"}; não exibido ao usuário
}

Saída:

{
    "questions": [  # As perguntas que foram feitas
        {
            "question": str,
            "header": str,
            "options": [{"label": str, "description": str, "preview": str | None}],
            "multiSelect": bool,
        }
    ],
    "answers": dict[str, str],  # Mapeia texto da pergunta para string de resposta
    # Respostas de múltipla seleção são separadas por vírgula
    "response": str | None,
    # Resposta de forma livre digitada em vez de responder às perguntas; quando definido,
    # Claude recebe "O usuário respondeu: ..." no lugar da lista de respostas
    "annotations": dict[str, dict] | None,  # "preview" e "notes" por pergunta das seleções do usuário
    "afkTimeoutMs": int | None,  # Definido quando o diálogo se resolveu automaticamente após este muitos milissegundos de inatividade do usuário; ausente quando o usuário respondeu
}

Bash

Nome da ferramenta: Bash

Entrada:

{
    "command": str,  # O comando a executar
    "timeout": int | None,  # Tempo limite opcional em milissegundos (máx 600000; valores maiores são limitados ao máximo)
    "description": str | None,  # Descrição clara e concisa (5-10 palavras)
    "run_in_background": bool | None,  # Defina como true para executar em segundo plano
}

Saída:

{
    "stdout": str,  # Saída do comando; stdout e stderr chegam mesclados neste fluxo intercalado
    "stderr": str,  # Avisos que a própria ferramenta adiciona, não o stderr do comando
    "interrupted": bool,  # Se o comando foi interrompido
    "isImage": bool | None,  # Se stdout contém dados de imagem
    "backgroundTaskId": str | None,  # ID da tarefa em segundo plano se o comando está executando em segundo plano
}

Monitor

Nome da ferramenta: Monitor

Executa uma fonte de fundo e entrega cada evento para Claude para que ele possa reagir sem polling: command executa um script e emite um evento por linha stdout, e ws abre um WebSocket e emite um evento por frame de texto. Forneça exatamente um de command ou ws.

Quando Monitor executa um comando, ele segue as mesmas regras de permissão que Bash; uma observação de WebSocket solicita aprovação separadamente. A fonte ws requer Claude Code v2.1.195 ou posterior. Veja a referência da ferramenta Monitor para comportamento e disponibilidade de provedor.

Entrada:

{
    "command": str | None,  # Script de shell; cada linha stdout é um evento, exit encerra a observação
    "ws": dict | None,  # Fonte WebSocket: {"url": str, "protocols": list[str] | None}; cada frame de texto é um evento
    "description": str,  # Descrição breve mostrada em notificações
    "timeout_ms": int | None,  # Prazo em milissegundos (padrão 300000, máx 3600000; o prazo efetivo é no máximo 1800000)
}

Saída:

{
    "taskId": str,  # ID da tarefa de monitor de fundo
    "timeoutMs": int,  # O prazo efetivo da observação em milissegundos
    "persistent": bool | None,  # False: cada observação tem um prazo
}

Edit

Nome da ferramenta: Edit

Entrada:

{
    "file_path": str,  # O caminho absoluto do arquivo a modificar
    "old_string": str,  # O texto a substituir
    "new_string": str,  # O texto para substituir por
    "replace_all": bool | None,  # Substituir todas as ocorrências (padrão False)
}

Saída:

{
    "message": str,  # Mensagem de confirmação
    "replacements": int,  # Número de substituições realizadas
    "file_path": str,  # Caminho do arquivo que foi editado
}

Read

Nome da ferramenta: Read

Entrada:

{
    "file_path": str,  # O caminho absoluto do arquivo a ler
    "offset": int | None,  # O número da linha para começar a ler
    "limit": int | None,  # O número de linhas a ler
}

Saída (Arquivos de texto):

{
    "content": str,  # Conteúdo do arquivo com números de linha
    "total_lines": int,  # Número total de linhas no arquivo
    "lines_returned": int,  # Linhas realmente retornadas
}

Saída (Imagens):

{
    "image": str,  # Dados de imagem codificados em Base64
    "mime_type": str,  # Tipo MIME da imagem
    "file_size": int,  # Tamanho do arquivo em bytes
}

Write

Nome da ferramenta: Write

Entrada:

{
    "file_path": str,  # O caminho absoluto do arquivo a escrever
    "content": str,  # O conteúdo a escrever no arquivo
}

Saída:

{
    "message": str,  # Mensagem de sucesso
    "bytes_written": int,  # Número de bytes escritos
    "file_path": str,  # Caminho do arquivo que foi escrito
}

Glob

Nome da ferramenta: Glob

Entrada:

{
    "pattern": str,  # O padrão glob para corresponder arquivos
    "path": str | None,  # O diretório a pesquisar (padrão cwd)
}

Saída:

{
    "matches": list[str],  # Array de caminhos de arquivo correspondentes
    "count": int,  # Número de correspondências encontradas
    "search_path": str,  # Diretório de pesquisa usado
}

Grep

Nome da ferramenta: Grep

Entrada:

{
    "pattern": str,  # O padrão de expressão regular
    "path": str | None,  # Arquivo ou diretório a pesquisar
    "glob": str | None,  # Padrão glob para filtrar arquivos
    "type": str | None,  # Tipo de arquivo a pesquisar
    "output_mode": str | None,  # "content", "files_with_matches", ou "count"
    "-i": bool | None,  # Pesquisa insensível a maiúsculas/minúsculas
    "-n": bool | None,  # Mostrar números de linha
    "-B": int | None,  # Linhas a mostrar antes de cada correspondência
    "-A": int | None,  # Linhas a mostrar após cada correspondência
    "-C": int | None,  # Linhas a mostrar antes e depois
    "head_limit": int | None,  # Limitar saída às primeiras N linhas/entradas
    "multiline": bool | None,  # Ativar modo multilinha
}

Saída (modo content):

{
    "matches": [
        {
            "file": str,
            "line_number": int | None,
            "line": str,
            "before_context": list[str] | None,
            "after_context": list[str] | None,
        }
    ],
    "total_matches": int,
}

Saída (modo files_with_matches):

{
    "files": list[str],  # Arquivos contendo correspondências
    "count": int,  # Número de arquivos com correspondências
}

NotebookEdit

Nome da ferramenta: NotebookEdit

Entrada:

{
    "notebook_path": str,  # Caminho absoluto para o notebook Jupyter
    "cell_id": str | None,  # O ID da célula a editar
    "new_source": str,  # A nova fonte para a célula
    "cell_type": "code" | "markdown" | None,  # O tipo da célula
    "edit_mode": "replace" | "insert" | "delete" | None,  # Tipo de operação de edição
}

Saída:

{
    "message": str,  # Mensagem de sucesso
    "edit_type": "replaced" | "inserted" | "deleted",  # Tipo de edição realizada
    "cell_id": str | None,  # ID da célula que foi afetada
    "total_cells": int,  # Total de células no notebook após edição
}

WebFetch

Nome da ferramenta: WebFetch

Entrada:

{
    "url": str,  # A URL para buscar conteúdo
    "prompt": str,  # O prompt a executar no conteúdo buscado
}

Saída:

{
    "bytes": int,  # Tamanho do conteúdo buscado em bytes
    "code": int,  # Código de resposta HTTP
    "codeText": str,  # Texto do código de resposta HTTP
    "result": str,  # Resultado processado da aplicação do prompt ao conteúdo
    "durationMs": int,  # Tempo para buscar e processar o conteúdo, em milissegundos
    "url": str,  # URL que foi buscada
}

WebSearch

Nome da ferramenta: WebSearch

Entrada:

{
    "query": str,  # A consulta de pesquisa a usar
    "allowed_domains": list[str] | None,  # Incluir apenas resultados desses domínios
    "blocked_domains": list[str] | None,  # Nunca incluir resultados desses domínios
}

Saída:

{
    "query": str,  # A consulta de pesquisa
    "results": list[str | {"tool_use_id": str, "content": list[{"title": str, "url": str}]}],
    "durationSeconds": float,  # Duração da pesquisa em segundos
}

TodoWrite

Nome da ferramenta: TodoWrite

Entrada:

{
    "todos": [
        {
            "content": str,  # A descrição da tarefa
            "status": "pending" | "in_progress" | "completed",  # Status da tarefa
            "activeForm": str,  # Forma ativa da descrição
        }
    ]
}

Saída:

{
    "message": str,  # Mensagem de sucesso
    "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},
}

TaskCreate

Nome da ferramenta: TaskCreate

Entrada:

{
    "subject": str,  # Título breve da tarefa
    "description": str,  # Corpo detalhado da tarefa
    "activeForm": str | None,  # Rótulo em tempo presente mostrado enquanto em progresso
    "metadata": dict | None,  # Metadados arbitrários do chamador
}

Saída:

{
    "task": {"id": str, "subject": str},  # Tarefa criada com ID atribuído
}

TaskUpdate

Nome da ferramenta: TaskUpdate

Entrada:

{
    "taskId": str,  # ID da tarefa a corrigir
    "status": Literal["pending", "in_progress", "completed", "deleted"] | None,
    "subject": str | None,
    "description": str | None,
    "activeForm": str | None,
    "addBlocks": list[str] | None,  # IDs de tarefas que esta tarefa agora bloqueia
    "addBlockedBy": list[str] | None,  # IDs de tarefas que agora bloqueiam esta tarefa
    "owner": str | None,
    "metadata": dict | None,
}

Saída:

{
    "success": bool,
    "taskId": str,
    "updatedFields": list[str],  # Nomes dos campos que mudaram
    "error": str | None,
    "statusChange": {"from": str, "to": str} | None,
}

TaskGet

Nome da ferramenta: TaskGet

Entrada:

{
    "taskId": str,  # ID da tarefa a ler
}

Saída:

{
    "task": {
        "id": str,
        "subject": str,
        "description": str,
        "status": Literal["pending", "in_progress", "completed"],
        "blocks": list[str],
        "blockedBy": list[str],
    } | None,  # None quando o ID não é encontrado
}

TaskList

Nome da ferramenta: TaskList

Entrada:

{}

Saída:

{
    "tasks": [
        {
            "id": str,
            "subject": str,
            "status": Literal["pending", "in_progress", "completed"],
            "owner": str | None,
            "blockedBy": list[str],
        }
    ],
}

TaskOutput

Removido em Claude Code v2.1.277. Anteriormente recuperava saída de uma tarefa de fundo em execução ou concluída, com BashOutput aceito como alias; Claude lê o arquivo de saída de uma tarefa de fundo com Read em seu lugar.

Uma entrada disallowed_tools ou uma regra de negação que ainda nomeia qualquer um dos nomes é ignorada sem um aviso.

TaskStop

Nome da ferramenta: TaskStop. Os nomes anteriores KillShell e KillBash ainda são aceitos como aliases.

Entrada:

{
    "task_id": str | None,  # O ID da tarefa de fundo a parar
    "shell_id": str | None,  # Descontinuado: use task_id em seu lugar
}

Saída:

{
    "message": str,  # Mensagem de status sobre a operação
    "task_id": str,  # O ID da tarefa que foi parada
    "task_type": str,  # O tipo da tarefa que foi parada
    "command": str | None,  # O comando ou descrição da tarefa parada
}

ExitPlanMode

Nome da ferramenta: ExitPlanMode

Entrada:

{
    "plan": str  # O plano a executar pelo usuário para aprovação
}

Saída:

{
    "message": str,  # Mensagem de confirmação
    "approved": bool | None,  # Se o usuário aprovou o plano
}

ListMcpResources

Nome da ferramenta: ListMcpResourcesTool

Entrada:

{
    "server": str | None  # Nome de servidor opcional para filtrar recursos por
}

Saída:

{
    "resources": [
        {
            "uri": str,
            "name": str,
            "description": str | None,
            "mimeType": str | None,
            "server": str,
        }
    ],
    "total": int,
}

ReadMcpResource

Nome da ferramenta: ReadMcpResourceTool

Entrada:

{
    "server": str,  # O nome do servidor MCP
    "uri": str,  # A URI do recurso a ler
}

Saída:

{
    "contents": [
        {"uri": str, "mimeType": str | None, "text": str | None, "blob": str | None}
    ],
    "server": str,
}

Construir uma interface de conversa contínua

O exemplo a seguir mantém um ClaudeSDKClient conectado entre turnos, para que Claude se lembre das mensagens anteriores. Digite new para desconectar e reconectar para uma nova sessão, ou exit para encerrar a conversa.

from claude_agent_sdk import (
    ClaudeSDKClient,
    ClaudeAgentOptions,
    AssistantMessage,
    TextBlock,
)
import asyncio


class ConversationSession:
    """Maintains a single conversation session with Claude."""

    def __init__(self, options: ClaudeAgentOptions | None = None):
        self.client = ClaudeSDKClient(options)
        self.turn_count = 0

    async def start(self):
        await self.client.connect()
        print("Starting conversation session. Claude will remember context.")
        print(
            "Commands: 'exit' to quit, 'interrupt' to stop current task, 'new' for new session"
        )

        while True:
            user_input = input(f"\n[Turn {self.turn_count + 1}] You: ")

            if user_input.lower() == "exit":
                break
            elif user_input.lower() == "interrupt":
                await self.client.interrupt()
                print("Task interrupted!")
                continue
            elif user_input.lower() == "new":
                # Disconnect and reconnect for a fresh session
                await self.client.disconnect()
                await self.client.connect()
                self.turn_count = 0
                print("Started new conversation session (previous context cleared)")
                continue

            # Send message - the session retains all previous messages
            await self.client.query(user_input)
            self.turn_count += 1

            # Process response
            print(f"[Turn {self.turn_count}] Claude: ", end="")
            async for message in self.client.receive_response():
                if isinstance(message, AssistantMessage):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(block.text, end="")
            print()  # New line after response

        await self.client.disconnect()
        print(f"Conversation ended after {self.turn_count} turns.")


async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Bash"], permission_mode="acceptEdits"
    )
    session = ConversationSession(options)
    await session.start()


# Example conversation:
# Turn 1 - You: "Create a file called hello.py"
# Turn 1 - Claude: "I'll create a hello.py file for you..."
# Turn 2 - You: "What's in that file?"
# Turn 2 - Claude: "The hello.py file I just created contains..." (remembers!)
# Turn 3 - You: "Add a main function to it"
# Turn 3 - Claude: "I'll add a main function to hello.py..." (knows which file!)

asyncio.run(main())

Tratamento de erros

O exemplo a seguir envolve uma chamada query() em manipuladores para quatro dos tipos de erro que o SDK levanta.

Este exemplo captura ResultError, que requer Python Agent SDK 0.2.140 ou posterior.

import asyncio

from claude_agent_sdk import (
    query,
    CLINotFoundError,
    ProcessError,
    ResultError,
    CLIJSONDecodeError,
)


async def main():
    try:
        async for message in query(prompt="Hello"):
            print(message)
    except CLINotFoundError:
        print(
            "Claude Code CLI not found. Try reinstalling: pip install --force-reinstall claude-agent-sdk"
        )
    # Catch ResultError before ProcessError, which it subclasses. Its message
    # carries the error text. A failed final request, such as an API error,
    # arrives with subtype "success", so branch on terminal_reason first.
    except ResultError as e:
        if e.terminal_reason == "api_error":
            print(f"API request failed: {e}")
        else:
            print(f"Query ended with an error result ({e.terminal_reason or e.subtype}): {e}")
    except ProcessError as e:
        print(f"Process failed with exit code: {e.exit_code}")
    except CLIJSONDecodeError as e:
        print(f"Failed to parse response: {e}")


asyncio.run(main())

Configuração de Sandbox

`SandboxSettings`

Configuração para comportamento de sandbox. Use isso para ativar sandboxing de comando e configurar restrições de rede programaticamente.

class SandboxSettings(TypedDict, total=False):
    enabled: bool
    autoAllowBashIfSandboxed: bool
    excludedCommands: list[str]
    allowUnsandboxedCommands: bool
    network: SandboxNetworkConfig
    ignoreViolations: SandboxIgnoreViolations
    enableWeakerNestedSandbox: bool

Exemplo de uso

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

sandbox_settings = {
    "enabled": True,
    "autoAllowBashIfSandboxed": True,
    "failIfUnavailable": True,
    "network": {"allowLocalBinding": True},
}


async def main():
    try:
        async for message in query(
            prompt="Build and test my project",
            options=ClaudeAgentOptions(sandbox=sandbox_settings),
        ):
            print(message)
    except Exception as error:
        # A single-shot query() raises after yielding an error result,
        # such as when failIfUnavailable is set and the sandbox can't start.
        print(f"Session ended with an error: {error}")


asyncio.run(main())

`SandboxNetworkConfig`

Configuração específica de rede para modo sandbox. Essas configurações se aplicam a comandos Bash em sandbox quando enabled é True na SandboxSettings pai. Elas não restringem a ferramenta WebFetch, que usa regras de permissão em vez disso.

class SandboxNetworkConfig(TypedDict, total=False):
    allowedDomains: list[str]
    deniedDomains: list[str]
    allowManagedDomainsOnly: bool
    allowUnixSockets: list[str]
    allowAllUnixSockets: bool
    allowLocalBinding: bool
    allowMachLookup: list[str]
    httpProxyPort: int
    socksProxyPort: int

`SandboxIgnoreViolations`

Configuração para ignorar violações de sandbox específicas.

class SandboxIgnoreViolations(TypedDict, total=False):
    file: list[str]
    network: list[str]

Fallback de Permissões para Comandos Sem Sandbox

Quando allowUnsandboxedCommands está ativado, o modelo pode solicitar executar comandos fora do sandbox definindo dangerouslyDisableSandbox: True na entrada da ferramenta. Essas solicitações voltam para o sistema de permissões existente, significando que seu manipulador can_use_tool será invocado, permitindo que você implemente lógica de autorização personalizada.

Suas entradas excludedCommands em vez disso contornam o sandbox com nenhum envolvimento do modelo; sandbox.excludedCommands cobre quando uma entrada se aplica.

O exemplo a seguir registra cada solicitação sem sandbox e a nega a menos que sua própria lógica de autorização a permita:

import asyncio
from claude_agent_sdk import (
    query,
    ClaudeAgentOptions,
    HookMatcher,
    PermissionResultAllow,
    PermissionResultDeny,
    ToolPermissionContext,
)


def is_command_authorized(command: str | None) -> bool:
    # Replace with your own authorization logic
    return False



async def can_use_tool(
    tool: str, input: dict, context: ToolPermissionContext
) -> PermissionResultAllow | PermissionResultDeny:
    # Check if the model is requesting to bypass the sandbox
    if tool == "Bash" and input.get("dangerouslyDisableSandbox"):
        # The model is requesting to run this command outside the sandbox
        print(f"Unsandboxed command requested: {input.get('command')}")

        if is_command_authorized(input.get("command")):
            return PermissionResultAllow()
        return PermissionResultDeny(
            message="Command not authorized for unsandboxed execution"
        )
    return PermissionResultAllow()


# Required: dummy hook keeps the stream open for can_use_tool
async def dummy_hook(input_data, tool_use_id, context):
    return {"continue_": True}


async def prompt_stream():
    yield {
        "type": "user",
        "message": {"role": "user", "content": "Deploy my application"},
    }


async def main():
    async for message in query(
        prompt=prompt_stream(),
        options=ClaudeAgentOptions(
            sandbox={
                "enabled": True,
                "allowUnsandboxedCommands": True,  # Model can request unsandboxed execution
            },
            permission_mode="default",
            can_use_tool=can_use_tool,
            hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},
        ),
    ):
        print(message)


asyncio.run(main())

Veja também

• SDK overview - Conceitos gerais do SDK
• TypeScript SDK reference - Documentação do SDK TypeScript
• Custom tools - Defina ferramentas MCP em processo para Claude chamar
• CLI reference - Interface de linha de comando
• Common workflows - Guias passo a passo