Referencia del SDK de Agent - Python

Referencia completa de la API del SDK de Agent de Python, incluyendo todas las funciones, tipos y clases.

Instalación

Instale el paquete en un entorno virtual. En instalaciones recientes de Debian, Ubuntu y Homebrew Python, ejecutar pip install contra Python del sistema falla con error: externally-managed-environment.

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

Para uv, Windows PowerShell y configuración de claves API, consulte Configuración en la guía de inicio rápido del Agent SDK.

Elegir entre `query()` y `ClaudeSDKClient`

El SDK de Python proporciona dos formas de interactuar con Claude Code:

Utilice ClaudeSDKClient para aplicaciones interactivas como interfaces de chat, o cuando la siguiente acción dependa de la respuesta de Claude.

Funciones

`query()`

Crea una nueva sesión para cada interacción con Claude Code de forma predeterminada. Devuelve un iterador asincrónico que produce mensajes a medida que llegan. Cada llamada a query() comienza de nuevo sin memoria de interacciones anteriores a menos que pase continue_conversation=True o resume en ClaudeAgentOptions. Consulte Sessions.

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

Parámetros

Devuelve

Devuelve un AsyncIterator[Message] que produce mensajes de la conversación.

Ejemplo - Con opciones

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 herramientas MCP con seguridad de tipos.

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

Opciones de esquema de entrada

1. Mapeo de tipo simple (recomendado):

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

2. Formato JSON Schema (para validación compleja):

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

Devuelve

Una función decoradora que envuelve la implementación de la herramienta y devuelve una instancia de SdkMcpTool.

Ejemplo

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`

Sugerencias de comportamiento para una herramienta, pasadas como el argumento annotations de tool(). ToolAnnotations extiende mcp.types.ToolAnnotations del SDK de MCP con un campo maxResultSizeChars, y puede escribir cada sugerencia en camelCase o snake_case: ToolAnnotations(readOnlyHint=True) y ToolAnnotations(read_only_hint=True) son equivalentes. También puede pasar un mcp.types.ToolAnnotations simple dondequiera que el SDK acepte anotaciones.

Los nombres snake_case y el campo maxResultSizeChars tipado requieren Python Agent SDK 0.2.140 o posterior. Las versiones 0.1.31 a 0.2.139 re-exportan mcp.types.ToolAnnotations sin cambios. En las versiones 0.1.55 a 0.2.139 aún puede pasar maxResultSizeChars como argumento de palabra clave: la clase MCP acepta campos adicionales, y el SDK reenvía el valor a Claude Code.

Todos los campos son opcionales. Los clientes no deben depender de las sugerencias para decisiones de seguridad.

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()`

Crea un servidor MCP en proceso que se ejecuta dentro de su aplicación Python.

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

Parámetros

Devuelve

Devuelve un objeto McpSdkServerConfig que se puede pasar a ClaudeAgentOptions.mcp_servers.

Ejemplo

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 sesiones pasadas con metadatos. Filtre por directorio de proyecto o liste sesiones en todos los proyectos. Sincrónico; devuelve inmediatamente.

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`

Ejemplo

Imprima las 10 sesiones más recientes para un proyecto. Los resultados se ordenan por last_modified descendente, por lo que el primer elemento es el más nuevo. Omita directory para buscar en todos los proyectos.

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 mensajes de una sesión pasada. Sincrónico; devuelve inmediatamente.

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`

Ejemplo

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()`

Lee metadatos para una única sesión por ID sin escanear el directorio del proyecto completo. Sincrónico; devuelve inmediatamente.

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

Parámetros

Devuelve SDKSessionInfo, o None si la sesión no se encuentra.

Ejemplo

Busque los metadatos de una única sesión sin escanear el directorio del proyecto. Útil cuando ya tiene un ID de sesión de una ejecución 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()`

Renombra una sesión agregando una entrada de título personalizado. Las llamadas repetidas son seguras; el título más reciente gana. Sincrónico.

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

Parámetros

Genera ValueError si session_id no es un UUID válido o title está vacío; FileNotFoundError si la sesión no se puede encontrar.

Ejemplo

Renombre la sesión más reciente para que sea más fácil de encontrar más tarde. El nuevo título aparece en SDKSessionInfo.custom_title en lecturas posteriores.

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()`

Etiqueta una sesión. Pase None para borrar la etiqueta. Las llamadas repetidas son seguras; la etiqueta más reciente gana. Sincrónico.

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

Parámetros

Genera ValueError si session_id no es un UUID válido o tag está vacío después de la sanitización; FileNotFoundError si la sesión no se puede encontrar.

Ejemplo

Etiquete una sesión, luego filtre por esa etiqueta en una lectura posterior. Pase None para borrar una etiqueta 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)

Clases

`ClaudeSDKClient`

Mantiene una sesión de conversación en múltiples intercambios. Este es el equivalente de Python de cómo funciona internamente la función query() del SDK de TypeScript - crea un objeto cliente que puede continuar conversaciones. Consulte la comparación con 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: str) -> 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

Soporte de gestor de contexto

El cliente se puede usar como un gestor de contexto asincrónico para la gestión automática de conexiones:

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: Al iterar sobre mensajes, evite usar break para salir temprano ya que esto puede causar problemas de limpieza de asyncio. En su lugar, deje que la iteración se complete naturalmente o use banderas para rastrear cuándo ha encontrado lo que necesita.

Ejemplo - Continuar una conversación

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

Ejemplo - Entrada de streaming con 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())

Ejemplo - Usar interrupciones

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

Ejemplo - Control de permisos avanzado

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():
    # Don't also list the gated tools in allowed_tools: allow rules approve calls before can_use_tool runs
    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`

Definición para una herramienta MCP del SDK creada con el 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`

Clase base abstracta para implementaciones de transporte personalizado. Úsela para comunicarse con el proceso Claude a través de un canal personalizado (por ejemplo, una conexión remota en lugar de un subproceso 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: ...

Importar: from claude_agent_sdk import Transport

`ClaudeAgentOptions`

Dataclass de configuración para consultas de Claude Code.

@dataclass
class ClaudeAgentOptions:
    tools: list[str] | ToolsPreset | None = None
    allowed_tools: list[str] = field(default_factory=list)
    system_prompt: str | SystemPromptPreset | 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

Manejar respuestas de API lentas o estancadas

El subproceso CLI lee varias variables de entorno que controlan los tiempos de espera de API y la detección de estancamiento. Páselas a travé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: tiempo de espera por solicitud en el cliente de Anthropic, en milisegundos. Predeterminado 600000. Se aplica al bucle principal y a todos los subagentes.

• CLAUDE_CODE_MAX_RETRIES: máximo de reintentos de API. Predeterminado 10, limitado a 15. Cada reintento obtiene su propia ventana API_TIMEOUT_MS, por lo que el tiempo de pared en el peor caso es aproximadamente API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1) más backoff. Para ejecuciones desatendidas que necesitan esperar a través de interrupciones más largas, establezca CLAUDE_CODE_RETRY_WATCHDOG=1: reintentos de errores de capacidad transitorios indefinidamente y, en Claude Code v2.1.199 o posterior, eleva el valor predeterminado para otros errores transitorios a 300 y elimina el límite en esta variable.

• CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: perro guardián de estancamiento para subagentes. Mientras el perro guardián de flujo está activado, el predeterminado es CLAUDE_STREAM_IDLE_TIMEOUT_MS más 5 minutos, lo que suma 600000 a menos que aumente esa variable. Con el perro guardián de flujo desactivado, el predeterminado es 600000. Antes de v2.1.257, el predeterminado era siempre 600000.

  El temporizador se reinicia en cada evento de flujo. En caso de estancamiento, Claude Code aborta el subagente e informa el estancamiento al padre. Para un subagente de fondo, también marca la tarea como fallida y adjunta cualquier resultado parcial.

• CLAUDE_ENABLE_STREAM_WATCHDOG con CLAUDE_STREAM_IDLE_TIMEOUT_MS: perro guardián de flujo que aborta la solicitud cuando los encabezados han llegado pero el cuerpo de la respuesta deja de transmitir. El perro guardián está activado de forma predeterminada para todos los proveedores; establezca CLAUDE_ENABLE_STREAM_WATCHDOG=0 para desactivarlo. CLAUDE_STREAM_IDLE_TIMEOUT_MS tiene un valor predeterminado de 300000 y se fija a ese mínimo. Después de la cancelación, Reintentos automáticos cubre lo que Claude Code hace, según qué tan lejos haya progresado la respuesta.

  Mientras el perro guardián espera una respuesta que una puerta de enlace detrás de ANTHROPIC_BASE_URL mantiene abierta con pings de keep-alive, un host que establece include_partial_messages sigue recibiendo mensajes StreamEvent de ping. Lea esos fotogramas como vivacidad en lugar de agotar el tiempo de espera de la sesión en silencio. Antes de v2.1.257, los fotogramas se detenían 5 minutos después del último evento de flujo real.

`OutputFormat`

Configuración para validación de salida estructurada. Pase esto como un dict al campo output_format en ClaudeAgentOptions:

# Expected dict shape for output_format
{
    "type": "json_schema",
    "schema": {...},  # Your JSON Schema definition
}

`SystemPromptPreset`

Configuración para usar el prompt del sistema preset de Claude Code con adiciones opcionales.

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

`SystemPromptFile`

Configuración para cargar un prompt del sistema personalizado desde un archivo en lugar de pasarlo como una cadena. El SDK asigna esto a la bandera CLI --system-prompt-file. Use la forma de archivo cuando el prompt es grande: el SDK pasa un system_prompt de cadena en el argv del subproceso CLI, que está sujeto a límites de longitud de línea de comandos del SO antes de que el SDK envíe cualquier solicitud de API. En Linux, un único argumento más largo que aproximadamente 128 KB falla al generar el proceso con Argument list too long. En Windows, toda la línea de comandos está limitada a aproximadamente 32 KB, por lo que la forma de cadena falla en un umbral más bajo.

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

`SettingSource`

Controla qué fuentes de configuración basadas en el sistema de archivos carga el SDK.

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

Comportamiento predeterminado

Cuando setting_sources se omite o es None, query() carga la misma configuración del sistema de archivos que el CLI de Claude Code: usuario, proyecto y local. La configuración de política administrada se carga en todos los casos; la configuración administrada por servidor se obtiene cuando la sesión se autentica con una credencial de organización en una configuración elegible. Ver Qué settingSources no controla para entradas que se leen independientemente de esta opción, y cómo deshabilitarlas.

Por qué usar setting\_sources

Deshabilitar configuración del sistema de archivos:

# Do not load user, project, or local settings from disk
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())

Cargar solo fuentes de configuración específicas:

# Load only project settings, ignore user and 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"]  # Only .claude/settings.json
        ),
    ):
        print(message)


asyncio.run(main())

Aplicaciones solo SDK:

# Define everything programmatically.
# Pass [] to opt out of filesystem setting sources.
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 cargar instrucciones del proyecto CLAUDE.md, incluya "project" en setting_sources. Ver Modificar prompts del sistema para cómo la carga de CLAUDE.md interactúa con las opciones de prompt del sistema.

Precedencia de configuración

Cuando se cargan múltiples fuentes, la configuración se fusiona con esta precedencia (mayor a menor):

1. Configuración local (.claude/settings.local.json)
2. Configuración del proyecto (.claude/settings.json)
3. Configuración del usuario (~/.claude/settings.json)

Las opciones programáticas como agents y allowed_tools anulan la configuración del sistema de archivos de usuario, proyecto y local. La configuración de política administrada tiene precedencia sobre las opciones programáticas.

`AgentDefinition`

Configuración para un subagente definido programáticamente.

@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 permiso para controlar la ejecución de herramientas.

PermissionMode = Literal[
    "default",  # Standard permission behavior
    "acceptEdits",  # Auto-accept file edits
    "plan",  # Planning mode - explore without editing
    "dontAsk",  # Deny anything not pre-approved instead of prompting
    "bypassPermissions",  # Bypass permission checks; explicit ask rules still prompt (use with caution)
    "auto",  # Model classifier approves or denies permission prompts
]

`EffortLevel`

Niveles de esfuerzo para guiar la profundidad del pensamiento.

EffortLevel = Literal[
    "low",  # Minimal thinking, fastest responses
    "medium",  # Moderate thinking
    "high",  # Deep reasoning
    "xhigh",  # Extended reasoning; falls back to "high" on models that don't support it
    "max",  # Maximum effort
]

`CanUseTool`

Alias de tipo para funciones de devolución de llamada de permiso de herramienta.

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

La devolución de llamada recibe:

• tool_name: Nombre de la herramienta que se está llamando
• input_data: Los parámetros de entrada de la herramienta
• context: Un ToolPermissionContext con información adicional

Devuelve un PermissionResult (ya sea PermissionResultAllow o PermissionResultDeny).

La devolución de llamada es el reemplazo del SDK para el prompt de permiso interactivo: se invoca solo cuando el flujo de evaluación de permiso se resuelve en un prompt. Las llamadas de herramienta ya aprobadas por una entrada allowed_tools, una regla de permiso de configuración, o el modo de permiso, como acceptEdits o bypassPermissions, nunca la invocan. Para controlar cada llamada de herramienta, use un hook PreToolUse en su lugar.

Una regla de permiso no aprueba previamente las acciones que ningún modo aprueba automáticamente; ver Cómo se evalúan los permisos para cuál de ellas llega a la devolución de llamada y qué sucede en modo dontAsk y auto.

`ToolPermissionContext`

Información de contexto pasada a devoluciones de llamada de permiso de herramienta.

@dataclass
class ToolPermissionContext:
    signal: Any | None = None  # Future: abort signal support
    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ón para resultados de devolución de llamada de permiso.

PermissionResult = PermissionResultAllow | PermissionResultDeny

`PermissionResultAllow`

Resultado indicando que la llamada de herramienta debe permitirse.

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

`PermissionResultDeny`

Resultado indicando que la llamada de herramienta debe denegarse.

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

`PermissionUpdate`

Configuración para actualizar permisos programáticamente.

@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`

Una regla a agregar, reemplazar o eliminar en una actualización de permiso.

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

`ToolsPreset`

Configuración de herramientas preset para usar el conjunto de herramientas predeterminado de Claude Code.

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

`ThinkingConfig`

Controla el comportamiento de pensamiento extendido. Una unión de tres configuraciones:

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

El campo opcional display controla si el texto de pensamiento se devuelve "summarized" u "omitted". En Claude Opus 4.7 y posteriores, el valor predeterminado de la API es "omitted", por lo que establezca "summarized" para recibir contenido de pensamiento en salidas ThinkingBlock. Claude Code no envía display a Amazon Bedrock o a la Plataforma de Agentes de Google Cloud, por lo que en esos proveedores Opus 4.7 y posteriores devuelven salidas ThinkingBlock vacías incluso cuando establece display en "summarized".

Porque estas son clases TypedDict, son dicts simples en tiempo de ejecución. Construya cualquiera como literales de dict o llame a la clase como un constructor; ambos producen un dict. Acceda a campos con config["budget_tokens"], no config.budget_tokens:

from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled

# Option 1: dict literal (recommended, no import needed)
options = ClaudeAgentOptions(thinking={"type": "enabled", "budget_tokens": 20000})

# Option 2: constructor-style (returns a plain dict)
config = ThinkingConfigEnabled(type="enabled", budget_tokens=20000)
print(config["budget_tokens"])  # 20000
# config.budget_tokens would raise AttributeError

`TaskBudget`

Presupuesto de tarea del lado de la API en tokens, utilizado con el campo task_budget en ClaudeAgentOptions.

class TaskBudget(TypedDict):
    total: int

Porque esto es un TypedDict, páselo como un dict simple, como ClaudeAgentOptions(task_budget={"total": 50000}).

`SdkBeta`

Tipo literal para características beta del SDK.

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

Use con el campo betas en ClaudeAgentOptions para habilitar características beta.

`McpSdkServerConfig`

Configuración para servidores MCP del SDK creados con create_sdk_mcp_server().

class McpSdkServerConfig(TypedDict):
    type: Literal["sdk"]
    name: str
    instance: Any  # MCP Server instance

`McpServerConfig`

Tipo de unión para configuraciones de servidor MCP.

McpServerConfig = (
    McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig
)

`McpStdioServerConfig`

class McpStdioServerConfig(TypedDict):
    type: NotRequired[Literal["stdio"]]  # Optional for backwards compatibility
    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`

La configuración de un servidor MCP como se reporta por get_mcp_status(). Esta es la unión de todas las variantes de transporte McpServerConfig más una variante de salida única claudeai-proxy para servidores proxied a través de claude.ai.

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

McpSdkServerConfigStatus es la forma serializable de McpSdkServerConfig con solo campos type ("sdk") y name (str); la instance en proceso se omite. McpClaudeAIProxyServerConfig tiene campos type ("claudeai-proxy"), url (str), e id (str).

`McpStatusResponse`

Respuesta de ClaudeSDKClient.get_mcp_status(). Envuelve la lista de estados del servidor bajo la clave mcpServers.

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

`McpServerStatus`

Estado de un servidor MCP conectado, contenido en 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`

Configuración para cargar plugins en el SDK.

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

Ejemplo:

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

Para información completa sobre la creación y uso de plugins, ver Plugins.

Tipos de mensaje

`Message`

Tipo de unión de todos los mensajes posibles.

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

`UserMessage`

Mensaje de entrada del usuario.

@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

El SDK pasa tool_use_result a través de la CLI sin modificar. Para una herramienta en un servidor MCP externo cuyo resultado contiene bloques resource_link, el dict tiene una clave resourceLinks que contiene una lista de dicts con las claves del tipo TypeScript SDKMcpResourceLink. Claude recibe cada enlace como una línea de texto en el resultado de la herramienta. Para renderizar los archivos que devolvió el servidor, lea resourceLinks en lugar de analizar ese texto. La clave resourceLinks requiere Python Agent SDK 0.2.150 o posterior y Claude Code v2.1.257 o posterior; la CLI incluida con esa versión del SDK satisface el requisito de Claude Code.

La CLI omite la clave cuando el resultado no tiene enlaces y en resultados de subagentes. La CLI mantiene como máximo 50 enlaces por resultado y deja de agregar enlaces una vez que la lista alcanza 64 KiB de JSON serializado. Una herramienta que define en proceso con tool() nunca produce la clave, porque el SDK aplana sus bloques resource_link a texto antes de que la CLI vea el resultado.

`AssistantMessage`

Mensaje de respuesta del asistente con bloques de contenido.

@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`

Posibles tipos de error para mensajes del asistente.

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

El proceso CLI subyacente puede emitir tipos de error que este Literal no enumera, como max_output_tokens. El SDK pasa el valor sin modificar, así que trate las cadenas fuera de esta lista de la manera que trata unknown. El tipo TypeScript SDKAssistantMessageError enumera el conjunto completo de valores que la CLI puede emitir.

`SystemMessage`

Mensaje del sistema con metadatos.

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

`ResultMessage`

Mensaje de resultado final con información de costo y 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

El campo subtype determina cuáles otros campos se rellenan. Es uno de "success", "error_during_execution", "error_max_turns", "error_max_budget_usd", o "error_max_structured_output_retries". La clase de datos de Python aplana todas las variantes en una forma, por lo que los campos que no se aplican al subtipo devuelto son None.

Varios campos llevan detalle de diagnóstico sobre cómo terminó la conversación:

• is_error: True cuando la conversación terminó en un estado de error. Siempre True en los subtipos error_*. En subtype="success" es True cuando la solicitud del modelo final falló, lo que significa que el bucle del agente se completó pero la última llamada a la API devolvió un error.
• api_error_status: el código de estado HTTP del error de API de terminación. None cuando el turno terminó sin uno. Se rellena solo en subtype="success".
• result: texto del mensaje del asistente final en subtype="success", o None en los subtipos error_*. Cuando subtype="success" e is_error=True, esto contiene la cadena de error de API si una está disponible pero puede estar vacía, así que verifique api_error_status y el contenido anterior de AssistantMessage para obtener detalles.
• errors: cadenas de error a nivel de bucle como el mensaje de máx-turnos. Se rellena solo en los subtipos error_*.
• terminal_reason: por qué terminó el bucle de consulta, como "completed", "max_turns", "api_error", "aborted_streaming", o "aborted_tools". Un valor de "aborted_streaming" o "aborted_tools" significa que el turno fue abortado antes de completarse. Las causas comunes son interrupt() y una devolución de llamada de permiso que devuelve PermissionResultDeny con interrupt=True. None en versiones de CLI que preceden al campo, en resultados de comandos locales como /voice o /usage, que omiten el bucle de consulta, o en resultados de error sintetizados emitidos cuando la sesión falla fatalmente. Refleja el SDKResultMessage.terminal_reason del SDK de TypeScript, que enumera el conjunto completo de valores.
• origin: origen del mensaje del usuario que activó este turno. En modo de entrada de streaming, verifique esto para distinguir el resultado de su propio prompt, donde origin es None o {"kind": "human"}, del resultado de un turno inyectado como una notificación de tarea de fondo. Requiere Python Agent SDK 0.2.137 o posterior.

El dict usage cubre solo el bucle del agente principal y excluye subagentes y otras llamadas de modelo anidadas o auxiliares. En modo de entrada de streaming, los valores son por turno. Prefiera model_usage para contabilidad de token y costo. El dict usage contiene las siguientes claves cuando está presente:

El dict model_usage asigna nombres de modelo a uso por modelo. Cubre cada llamada de modelo realizada a través de la canalización de consulta: el bucle principal, subagentes y llamadas internas como compactación y agentes de Workflow. Las llamadas auxiliares fuera de esa canalización, como el clasificador de permisos y solicitudes de conteo de tokens, se excluyen de model_usage. Trate model_usage como una estimación, no como un estado de facturación.

En modo de entrada de streaming, model_usage y total_cost_usd son acumulativos entre turnos, así que lea el resultado más reciente en lugar de sumar entre resultados. Vea Rastrear costos en modo de entrada de streaming para reiniciaciones y Recuperar totales después de un bloqueo de sesión para resultados puestos a cero.

Cada valor en model_usage es un TypedDict ModelUsage, importado vía from claude_agent_sdk.types import ModelUsage. Sus claves usan camelCase porque el SDK pasa el valor sin modificar desde el proceso CLI subyacente, coincidiendo con el tipo TypeScript ModelUsage:

`StreamEvent`

Evento de flujo para actualizaciones de mensaje parcial durante el streaming. Solo se recibe cuando include_partial_messages=True en ClaudeAgentOptions. Importar vía 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 cuando el estado del límite de velocidad cambia (por ejemplo, de "allowed" a "allowed_warning"). Use esto para advertir a los usuarios antes de que alcancen un límite duro, o para retroceder cuando el estado es "rejected".

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

`RateLimitInfo`

Estado del límite de velocidad llevado 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 cuando la conversación se reemplaza sin terminar la conexión, como después de /clear. Vea Rastrear costos en modo de entrada de streaming para cómo un reinicio afecta los totales en ejecución en objetos ResultMessage posteriores. Requiere Python Agent SDK 0.2.137 o posterior.

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

`TaskStartedMessage`

Emitido cuando comienza una tarea de fondo. Una tarea de fondo es cualquier cosa rastreada fuera del turno principal: un comando Bash en segundo plano, un reloj de Monitor, un subagente generado a través de la herramienta Agent, o un agente remoto. El campo task_type le dice cuál. Este nombre no está relacionado con el cambio de nombre de herramienta Task-a-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`

Datos de token y tiempo para una tarea de fondo.

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

`TaskProgressMessage`

Emitido periódicamente con actualizaciones de progreso para una tarea de fondo en ejecución.

@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 cuando una tarea de fondo se completa, falla o se detiene. Las tareas de fondo incluyen comandos Bash run_in_background, relojes de Monitor y subagentes de fondo.

@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

Cuando la CLI mueve una llamada de herramienta MCP larga al fondo, el resultado de la herramienta para esa llamada contiene solo un marcador de posición y el resultado real de la llamada llega en este mensaje. En una notificación "completed" para tal llamada, la CLI agrega una clave resource_links que enumera los archivos que devolvió la herramienta por referencia, con las mismas entradas y límites que la clave resourceLinks en UserMessage.tool_use_result. La clave resource_links requiere Python Agent SDK 0.2.150 o posterior y Claude Code v2.1.257 o posterior; la CLI incluida con esa versión del SDK satisface el requisito de Claude Code.

La clase de datos no tiene campo para resource_links. Léalo del dict data que el mensaje hereda de SystemMessage: message.data.get("resource_links"). Haga coincidir la notificación con la llamada usando tool_use_id. La CLI omite la clave cuando el resultado no tenía enlaces y en notificaciones para tareas que no son llamadas de herramienta MCP.

Tipos de bloque de contenido

`ContentBlock`

Tipo de unión de todos los bloques de contenido.

ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock

`TextBlock`

Bloque de contenido de texto.

@dataclass
class TextBlock:
    text: str

`ThinkingBlock`

Bloque de contenido de pensamiento (para modelos con capacidad de pensamiento).

@dataclass
class ThinkingBlock:
    thinking: str
    signature: str

`ToolUseBlock`

Bloque de solicitud de uso de herramienta.

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

`ToolResultBlock`

Bloque de resultado de ejecución de herramienta.

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

Tipos de error

Los tipos a continuación definen lo que su código detecta. Para entradas vinculadas a los mensajes de error que estos tipos generan, con la causa y la solución para cada uno, consulte Solución de problemas.

`ClaudeSDKError`

Clase de excepción base para todos los errores del SDK.

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

Cuando una consulta query() de un solo turno termina con un resultado de error, por ejemplo un error de límite de turnos, el SDK genera una ResultError después de ceder el mensaje de resultado final. Las versiones del SDK del Agente Python anteriores a 0.2.140 generaban una Exception simple que no era una subclase de ClaudeSDKError.

`CLINotFoundError`

Se genera cuando Claude Code CLI no está instalado o no se encuentra.

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`

Se genera cuando la conexión a Claude Code falla.

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

`ProcessError`

Se genera cuando el proceso de Claude Code falla.

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`

Se genera después del ResultMessage final cuando el proceso de Claude Code se cierra porque la ejecución terminó con un resultado de error, como un error de límite de turnos o un error de API. ResultError es una subclase de ProcessError, por lo que un controlador except ProcessError existente también lo detecta. Sus atributos llevan los campos de ese mensaje de resultado, por lo que puede ramificarse según por qué falló la ejecución sin analizar el texto del mensaje. Requiere Python Agent SDK 0.2.140 o 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 los fallos, compruebe terminal_reason antes de subtype. Cuando la solicitud final falla, como en un error de API, Claude Code informa subtype "success" con la causa en terminal_reason, por ejemplo "api_error"; cuando un límite que establece termina la ejecución, como max_turns o max_budget_usd, informa un subtipo error_*.

`CLIJSONDecodeError`

Se genera cuando el análisis JSON falla.

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 una guía completa sobre el uso de hooks con ejemplos y patrones comunes, ver la Guía de Hooks.

`HookEvent`

Tipos de evento de hook soportados.

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`

Definición de tipo para funciones de devolución de llamada de hook.

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

Parámetros:

• input: Entrada de hook fuertemente tipada con uniones discriminadas basadas en hook_event_name (ver HookInput)
• tool_use_id: Identificador de uso de herramienta opcional (para hooks relacionados con herramientas)
• context: Contexto de hook con información adicional

Devuelve un HookJSONOutput.

`HookContext`

Información de contexto pasada a devoluciones de llamada de hook.

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

`HookMatcher`

Configuración para hacer coincidir hooks con eventos o herramientas 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ón de todos los tipos de entrada de hook. El tipo real depende del campo hook_event_name.

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

`BaseHookInput`

Campos base presentes en todos los tipos de entrada de hook.

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

`PreToolUseHookInput`

Datos 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`

Datos 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`

Datos de entrada para eventos de hook PostToolUseFailure. Se llama cuando la ejecución de una herramienta falla.

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`

Datos de entrada para eventos de hook UserPromptSubmit.

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

`StopHookInput`

Datos de entrada para eventos de hook Stop.

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

`SubagentStopHookInput`

Datos 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`

Datos de entrada para eventos de hook PreCompact.

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

`NotificationHookInput`

Datos de entrada para eventos de hook Notification.

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

`SubagentStartHookInput`

Datos de entrada para eventos de hook SubagentStart.

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

`PermissionRequestHookInput`

Datos de entrada para eventos de hook PermissionRequest. Permite que los hooks manejen decisiones de permiso programáticamente.

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ón para valores de retorno de devolución de llamada de hook.

HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput

`SyncHookJSONOutput`

Salida de hook sincrónico con campos de control y decisión.

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`

Una unión discriminada de tipos de salida específicos del evento TypedDict. El campo hookEventName determina qué campos son válidos. Para detalles completos sobre campos disponibles por evento de hook, ver Control execution with 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`

Salida de hook asincrónico que difiere la ejecución del hook.

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

Ejemplo de uso de hook

Este ejemplo registra dos hooks: uno que bloquea comandos bash peligrosos como rm -rf /, y otro que registra todo el uso de herramientas para auditoría. El hook de seguridad solo se ejecuta en comandos Bash (a través del matcher), mientras que el hook de registro se ejecuta en todas las herramientas.

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/salida de herramienta

Documentación de esquemas de entrada/salida para todas las herramientas integradas de Claude Code. Aunque el SDK de Python no exporta estos como tipos, representan la estructura de entradas y salidas de herramientas en mensajes.

Agent

Nombre de herramienta: Agent. El nombre anterior Task aún se acepta como alias, y la lista tools en el SystemMessage de inicialización reporta esta herramienta como Task para compatibilidad hacia atrás.

Entrada:

{
    "description": str,  # A short (3-5 word) description of the task
    "prompt": str,  # The task for the agent to perform
    "subagent_type": str | None,  # The type of specialized agent to use
    "model": "sonnet" | "opus" | "haiku" | "fable" | None,  # Model override for this agent
    "run_in_background": bool | None,  # Agents run in the background by default; set to False to run synchronously
    "name": str | None,  # Name for the spawned agent
    "team_name": str | None,  # Deprecated; ignored
    "mode": "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan" | None,  # Deprecated; ignored. The subagent inheritance rules decide a subagent's permission mode
    "isolation": "worktree" | "remote" | None,  # Isolation mode for the agent's changes
}

Lanza un nuevo agente para manejar tareas complejas y multietapa de forma autónoma.

Salida (estado: "completed"):

{
    "status": "completed",
    "agentId": str,  # ID of the agent that ran
    "agentType": str | None,  # The subagent type that handled the task
    "content": [  # Result content blocks
        {
            "type": "text",
            "text": str,
            "citations": list | None,
        }
    ],
    "resolvedModel": str | None,  # Model the subagent started on
    "modelsUsed": list[str] | None,  # Models used in order, with consecutive repeats collapsed
    "totalToolUseCount": int,  # Number of tool calls the agent made
    "totalDurationMs": int,  # Execution duration in milliseconds
    "totalTokens": int,  # Token count from the final API request, not the whole run
    "usage": {  # Token usage statistics
        "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": {  # Aggregate tool activity for the run
        "readCount": int,
        "searchCount": int,
        "bashCount": int,
        "editFileCount": int,
        "linesAdded": int,
        "linesRemoved": int,
        "otherToolCount": int,
        "frameCount": int | None,
    } | None,
    "prompt": str,  # The prompt the agent ran
    "worktreePath": str | None,  # Present when Claude Code kept the subagent's worktree
    "worktreeBranch": str | None,  # Present when Claude Code created that worktree with git
}

Salida (estado: "async_launched"):

{
    "status": "async_launched",
    "isAsync": bool | None,  # True on background launches
    "agentId": str,  # ID of the launched agent
    "description": str,  # The task description
    "resolvedModel": str | None,  # Model in use at the backgrounding transition
    "modelsUsed": list[str] | None,  # Models used before backgrounding, in order, with consecutive repeats collapsed
    "prompt": str,  # The prompt the agent runs
    "outputFile": str,  # File path where the agent's output is written
    "canReadOutputFile": bool | None,  # Whether the output file can be read directly
}

Salida (estado: "remote_launched"):

{
    "status": "remote_launched",
    "taskId": str,  # ID of the remote task
    "sessionUrl": str,  # Link to the remote cloud session
    "description": str,  # The task description
    "prompt": str,  # The prompt the agent runs
    "outputFile": str,  # File path where the agent's output is written
}

Devuelve el resultado del subagente. La salida se discrimina en el campo status: "completed" para tareas terminadas, "async_launched" para tareas en segundo plano, y "remote_launched" para tareas que Claude Code envió a una sesión en la nube remota, donde sessionUrl enlaza a esa sesión y taskId la identifica. Si Claude Code mantuvo el worktree aislado del subagente, worktreePath en la variante completed es donde encontrarlo, y worktreeBranch es su rama cuando Claude Code creó el worktree con git.

En la variante completed, resolvedModel nombra el modelo en el que comenzó el subagente, que puede diferir del model de entrada solicitado cuando availableModels u otra anulación se aplica. Este campo requiere Claude Code v2.1.174 o posterior. En la variante async_launched, resolvedModel nombra el modelo en uso cuando el agente se movió al segundo plano, por lo que un cambio que ocurrió antes del envío a segundo plano se refleja allí. El campo modelsUsed en ambas variantes enumera los modelos utilizados en orden, con repeticiones consecutivas colapsadas; se establece solo cuando el modelo se cambió durante la ejecución. modelsUsed y el comportamiento de resolvedModel en el momento del envío a segundo plano requieren Claude Code v2.1.212 o posterior.

Claude Code completa usage y totalTokens desde la solicitud final de API del subagente, no desde toda la ejecución. Cuando está presente, thinking_tokens bajo output_tokens_details en usage es el número de tokens de salida de esa solicitud que fueron tokens de pensamiento. La clave output_tokens_details requiere Python SDK v0.2.136 o posterior, que incluye Claude Code v2.1.228.

AskUserQuestion

Nombre de herramienta: AskUserQuestion

Hace preguntas aclaratorias al usuario durante la ejecución. Ver Manejar aprobaciones e entrada del usuario para detalles de uso.

Entrada:

{
    "questions": [  # Questions to ask the user (1-4 questions)
        {
            "question": str,  # The complete question to ask the user
            "header": str,  # Very short label displayed as a chip/tag (max 12 chars)
            "options": [  # The available choices (2-4 options)
                {
                    "label": str,  # Display text for this option (1-5 words)
                    "description": str,  # Explanation of what this option means
                    "preview": str | None,  # Preview content rendered when the option is focused
                }
            ],
            "multiSelect": bool,  # Set to true to allow multiple selections
        }
    ],
    "answers": dict[str, str] | None,
    # User answers populated by the permission system. Multi-select
    # answers are a comma-joined string of the selected labels; a
    # list of labels is accepted on input and coerced to that form
    "annotations": dict[str, dict] | None,
    # Per-question annotations from the user, keyed by question text.
    # Each value can carry "preview" (the selected option's preview
    # content) and "notes" (free-text notes on the selection)
    "metadata": dict | None,  # Analytics metadata, such as {"source": "remember"}; not displayed to the user
}

Salida:

{
    "questions": [  # The questions that were asked
        {
            "question": str,
            "header": str,
            "options": [{"label": str, "description": str, "preview": str | None}],
            "multiSelect": bool,
        }
    ],
    "answers": dict[str, str],  # Maps question text to answer string
    # Multi-select answers are comma-separated
    "response": str | None,
    # Freeform reply typed instead of answering the questions; when set,
    # Claude receives "The user responded: ..." in place of the answer list
    "annotations": dict[str, dict] | None,  # Per-question "preview" and "notes" from the user's selections
    "afkTimeoutMs": int | None,  # Set when the dialog auto-resolved after this many milliseconds of user inactivity; absent when the user answered
}

Bash

Nombre de herramienta: Bash

Entrada:

{
    "command": str,  # The command to execute
    "timeout": int | None,  # Optional timeout in milliseconds (max 600000; higher values are clamped to the max)
    "description": str | None,  # Clear, concise description (5-10 words)
    "run_in_background": bool | None,  # Set to true to run in background
}

Salida:

{
    "stdout": str,  # The command's output; stdout and stderr arrive merged into this one interleaved stream
    "stderr": str,  # Notices the tool itself adds, not the command's stderr
    "interrupted": bool,  # Whether the command was interrupted
    "isImage": bool | None,  # Whether stdout contains image data
    "backgroundTaskId": str | None,  # ID of the background task if command is running in background
}

Monitor

Nombre de herramienta: Monitor

Ejecuta una fuente de fondo y entrega cada evento a Claude para que pueda reaccionar sin sondeo: command ejecuta un script y emite un evento por línea stdout, y ws abre un WebSocket y emite un evento por marco de texto. Proporcione exactamente uno de command o ws.

Cuando Monitor ejecuta un comando, sigue las mismas reglas de permiso que Bash; una vigilancia de WebSocket solicita aprobación por separado. La fuente ws requiere Claude Code v2.1.195 o posterior. Ver la referencia de herramienta Monitor para comportamiento y disponibilidad de proveedor.

Entrada:

{
    "command": str | None,  # Shell script; each stdout line is an event, exit ends the watch
    "ws": dict | None,  # WebSocket source: {"url": str, "protocols": list[str] | None}; each text frame is an event
    "description": str,  # Short description shown in notifications
    "timeout_ms": int | None,  # Kill after this deadline (default 300000, max 3600000)
    "persistent": bool | None,  # Run for the lifetime of the session; stop with TaskStop
}

Salida:

{
    "taskId": str,  # ID of the background monitor task
    "timeoutMs": int,  # Timeout deadline in milliseconds (0 when persistent)
    "persistent": bool | None,  # True when running until TaskStop or session end
}

Edit

Nombre de herramienta: Edit

Entrada:

{
    "file_path": str,  # The absolute path to the file to modify
    "old_string": str,  # The text to replace
    "new_string": str,  # The text to replace it with
    "replace_all": bool | None,  # Replace all occurrences (default False)
}

Salida:

{
    "message": str,  # Confirmation message
    "replacements": int,  # Number of replacements made
    "file_path": str,  # File path that was edited
}

Read

Nombre de herramienta: Read

Entrada:

{
    "file_path": str,  # The absolute path to the file to read
    "offset": int | None,  # The line number to start reading from
    "limit": int | None,  # The number of lines to read
}

Salida (archivos de texto):

{
    "content": str,  # File contents with line numbers
    "total_lines": int,  # Total number of lines in file
    "lines_returned": int,  # Lines actually returned
}

Salida (imágenes):

{
    "image": str,  # Base64 encoded image data
    "mime_type": str,  # Image MIME type
    "file_size": int,  # File size in bytes
}

Write

Nombre de herramienta: Write

Entrada:

{
    "file_path": str,  # The absolute path to the file to write
    "content": str,  # The content to write to the file
}

Salida:

{
    "message": str,  # Success message
    "bytes_written": int,  # Number of bytes written
    "file_path": str,  # File path that was written
}

Glob

Nombre de herramienta: Glob

Entrada:

{
    "pattern": str,  # The glob pattern to match files against
    "path": str | None,  # The directory to search in (defaults to cwd)
}

Salida:

{
    "matches": list[str],  # Array of matching file paths
    "count": int,  # Number of matches found
    "search_path": str,  # Search directory used
}

Grep

Nombre de herramienta: Grep

Entrada:

{
    "pattern": str,  # The regular expression pattern
    "path": str | None,  # File or directory to search in
    "glob": str | None,  # Glob pattern to filter files
    "type": str | None,  # File type to search
    "output_mode": str | None,  # "content", "files_with_matches", or "count"
    "-i": bool | None,  # Case insensitive search
    "-n": bool | None,  # Show line numbers
    "-B": int | None,  # Lines to show before each match
    "-A": int | None,  # Lines to show after each match
    "-C": int | None,  # Lines to show before and after
    "head_limit": int | None,  # Limit output to first N lines/entries
    "multiline": bool | None,  # Enable multiline mode
}

Salida (modo content):

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

Salida (modo files_with_matches):

{
    "files": list[str],  # Files containing matches
    "count": int,  # Number of files with matches
}

NotebookEdit

Nombre de herramienta: NotebookEdit

Entrada:

{
    "notebook_path": str,  # Absolute path to the Jupyter notebook
    "cell_id": str | None,  # The ID of the cell to edit
    "new_source": str,  # The new source for the cell
    "cell_type": "code" | "markdown" | None,  # The type of the cell
    "edit_mode": "replace" | "insert" | "delete" | None,  # Edit operation type
}

Salida:

{
    "message": str,  # Success message
    "edit_type": "replaced" | "inserted" | "deleted",  # Type of edit performed
    "cell_id": str | None,  # Cell ID that was affected
    "total_cells": int,  # Total cells in notebook after edit
}

WebFetch

Nombre de herramienta: WebFetch

Entrada:

{
    "url": str,  # The URL to fetch content from
    "prompt": str,  # The prompt to run on the fetched content
}

Salida:

{
    "bytes": int,  # Size of the fetched content in bytes
    "code": int,  # HTTP response code
    "codeText": str,  # HTTP response code text
    "result": str,  # Processed result from applying the prompt to the content
    "durationMs": int,  # Time to fetch and process the content, in milliseconds
    "url": str,  # URL that was fetched
}

WebSearch

Nombre de herramienta: WebSearch

Entrada:

{
    "query": str,  # The search query to use
    "allowed_domains": list[str] | None,  # Only include results from these domains
    "blocked_domains": list[str] | None,  # Never include results from these domains
}

Salida:

{
    "query": str,  # The search query
    "results": list[str | {"tool_use_id": str, "content": list[{"title": str, "url": str}]}],
    "durationSeconds": float,  # Search duration in seconds
}

TodoWrite

Nombre de herramienta: TodoWrite

Entrada:

{
    "todos": [
        {
            "content": str,  # The task description
            "status": "pending" | "in_progress" | "completed",  # Task status
            "activeForm": str,  # Active form of the description
        }
    ]
}

Salida:

{
    "message": str,  # Success message
    "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},
}

TaskCreate

Nombre de herramienta: TaskCreate

Entrada:

{
    "subject": str,  # Short task title
    "description": str,  # Detailed task body
    "activeForm": str | None,  # Present-tense label shown while in progress
    "metadata": dict | None,  # Arbitrary caller metadata
}

Salida:

{
    "task": {"id": str, "subject": str},  # Created task with assigned ID
}

TaskUpdate

Nombre de herramienta: TaskUpdate

Entrada:

{
    "taskId": str,  # ID of the task to patch
    "status": Literal["pending", "in_progress", "completed", "deleted"] | None,
    "subject": str | None,
    "description": str | None,
    "activeForm": str | None,
    "addBlocks": list[str] | None,  # Task IDs this task now blocks
    "addBlockedBy": list[str] | None,  # Task IDs that now block this task
    "owner": str | None,
    "metadata": dict | None,
}

Salida:

{
    "success": bool,
    "taskId": str,
    "updatedFields": list[str],  # Names of fields that changed
    "error": str | None,
    "statusChange": {"from": str, "to": str} | None,
}

TaskGet

Nombre de herramienta: TaskGet

Entrada:

{
    "taskId": str,  # ID of the task to read
}

Salida:

{
    "task": {
        "id": str,
        "subject": str,
        "description": str,
        "status": Literal["pending", "in_progress", "completed"],
        "blocks": list[str],
        "blockedBy": list[str],
    } | None,  # None when the ID is not found
}

TaskList

Nombre de herramienta: TaskList

Entrada:

{}

Salida:

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

TaskOutput

Nombre de herramienta: TaskOutput. El nombre anterior BashOutput aún se acepta como alias.

Entrada:

{
    "task_id": str,  # The task ID to get output from
    "block": bool,  # Whether to wait for completion (default True)
    "timeout": int,  # Max wait time in ms (default 30000)
}

Salida:

{
    "retrieval_status": "success" | "timeout" | "not_ready",  # Whether the output was retrieved
    "task": dict | None,  # Task details: task_id, task_type, status, description, output, plus type-specific fields such as exitCode
}

TaskStop

Nombre de herramienta: TaskStop. Los nombres anteriores KillShell y KillBash aún se aceptan como alias.

Entrada:

{
    "task_id": str | None,  # The ID of the background task to stop
    "shell_id": str | None,  # Deprecated: use task_id instead
}

Salida:

{
    "message": str,  # Status message about the operation
    "task_id": str,  # The ID of the task that was stopped
    "task_type": str,  # The type of the task that was stopped
    "command": str | None,  # The command or description of the stopped task
}

ExitPlanMode

Nombre de herramienta: ExitPlanMode

Entrada:

{
    "plan": str  # The plan to run by the user for approval
}

Salida:

{
    "message": str,  # Confirmation message
    "approved": bool | None,  # Whether user approved the plan
}

ListMcpResources

Nombre de herramienta: ListMcpResourcesTool

Entrada:

{
    "server": str | None  # Optional server name to filter resources by
}

Salida:

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

ReadMcpResource

Nombre de herramienta: ReadMcpResourceTool

Entrada:

{
    "server": str,  # The MCP server name
    "uri": str,  # The resource URI to read
}

Salida:

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

Construir una interfaz de conversación continua

El siguiente ejemplo mantiene un ClaudeSDKClient conectado a través de turnos, para que Claude recuerde los mensajes anteriores. Escriba new para desconectar y reconectar para una sesión nueva, o exit para terminar la conversación.

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

Manejo de errores

El siguiente ejemplo envuelve una llamada a query() en manejadores para cuatro de los tipos de error que el SDK genera.

Este ejemplo captura ResultError, que requiere Python Agent SDK 0.2.140 o 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())

Configuración de sandbox

`SandboxSettings`

Configuración para el comportamiento de sandbox. Use esto para habilitar el sandboxing de comandos y configurar restricciones de red programáticamente.

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

Ejemplo 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`

Configuración específica de red para modo sandbox. Estas configuraciones se aplican a comandos Bash en sandbox cuando enabled es True en la SandboxSettings principal. No restringen la herramienta WebFetch, que utiliza reglas de permisos en su lugar.

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`

Configuración para ignorar violaciones de sandbox específicas.

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

Respaldo de permisos para comandos sin sandbox

Cuando allowUnsandboxedCommands está habilitado, el modelo puede solicitar ejecutar comandos fuera del sandbox estableciendo dangerouslyDisableSandbox: True en la entrada de la herramienta. Estas solicitudes vuelven al sistema de permisos existente, lo que significa que se invocará su controlador can_use_tool, permitiéndole implementar lógica de autorización personalizada. Los comandos listados en excludedCommands en su lugar evitan el sandbox automáticamente, sin participación del modelo; consulte SandboxSettings.

El siguiente ejemplo registra cada solicitud sin sandbox y la deniega a menos que su propia lógica de autorización la 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())

Ver también

• SDK overview - Conceptos generales del SDK
• TypeScript SDK reference - Documentación del SDK de TypeScript
• Custom tools - Define herramientas MCP en proceso para que Claude llame
• CLI reference - Interfaz de línea de comandos
• Common workflows - Guías paso a paso