44 Funciones44 Funciones
45</h2>45</h2>
46 46
47<Note>Los bloques de firma y fragmentos desnudos de `async for` / `async with` en esta página son ilustrativos. Para ejecutarlos, envuelva el cuerpo en `async def main(): ...` y llame a `asyncio.run(main())`.</Note>47<Note>Los bloques de firma y fragmentos desnudos de `async for` / `async with` en esta página son ilustrativos. Para ejecutarlos, envuelve el cuerpo en `async def main(): ...` y llama a `asyncio.run(main())`.</Note>
48 48
49<h3 id="query">49<h3 id="query">
50 `query()`50 `query()`
51</h3>51</h3>
52 52
53Crea 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`](#claudeagentoptions). Consulte [Sessions](/docs/es/agent-sdk/sessions).53Crea 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 pases `continue_conversation=True` o `resume` en [`ClaudeAgentOptions`](#claudeagentoptions). Consulta [Sessions](/docs/es/agent-sdk/sessions).
54 54
55```python theme={null}55```python theme={null}
56async def query(56async def query(
122| :- | :- | :- |122| :- | :- | :- |
123| `name` | `str` | Identificador único para la herramienta |123| `name` | `str` | Identificador único para la herramienta |
124| `description` | `str` | Descripción legible de lo que hace la herramienta |124| `description` | `str` | Descripción legible de lo que hace la herramienta |
125| `input_schema` | `type \| dict[str, Any]` | Esquema que define los parámetros de entrada de la herramienta. Consulte [Opciones de esquema de entrada](#input-schema-options) |125| `input_schema` | `type \| dict[str, Any]` | Esquema que define los parámetros de entrada de la herramienta. Consulta [Opciones de esquema de entrada](#input-schema-options) |
126| `annotations` | [`ToolAnnotations`](#toolannotations)` \| None` | Anotaciones opcionales de herramienta MCP que proporcionan sugerencias de comportamiento a los clientes |126| `annotations` | [`ToolAnnotations`](#toolannotations)` \| None` | Anotaciones opcionales de herramienta MCP que proporcionan sugerencias de comportamiento a los clientes |
127 127
128<h4 id="input-schema-options">128<h4 id="input-schema-options">
194 `ToolAnnotations`194 `ToolAnnotations`
195</h4>195</h4>
196 196
197Sugerencias de comportamiento para una herramienta, pasadas como el argumento `annotations` de [`tool()`](#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.197Sugerencias de comportamiento para una herramienta, pasadas como el argumento `annotations` de [`tool()`](#tool). `ToolAnnotations` extiende `mcp.types.ToolAnnotations` del SDK de MCP con un campo `maxResultSizeChars`, y puedes escribir cada sugerencia en camelCase o snake\_case: `ToolAnnotations(readOnlyHint=True)` y `ToolAnnotations(read_only_hint=True)` son equivalentes. Para volver a leer una sugerencia desde el objeto, usa la escritura que declara tu paquete `mcp` instalado: `.readOnlyHint` en `mcp` 1.x y `.read_only_hint` en 2.x, mientras que `.maxResultSizeChars` funciona en ambas. También puedes pasar un `mcp.types.ToolAnnotations` simple dondequiera que el SDK acepte anotaciones.
198 198
199Los 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.199Los 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 puedes pasar `maxResultSizeChars` como argumento de palabra clave: la clase MCP acepta campos adicionales, y el SDK reenvía el valor a Claude Code.
200 200
201Todos los campos son opcionales. Los clientes no deben depender de las sugerencias para decisiones de seguridad.201Todos los campos son opcionales. Los clientes no deben depender de las sugerencias para decisiones de seguridad.
202 202
207| `destructiveHint` | `bool \| None` | `True` | Si es `True`, la herramienta puede realizar actualizaciones destructivas (solo significativo cuando `readOnlyHint` es `False`) |207| `destructiveHint` | `bool \| None` | `True` | Si es `True`, la herramienta puede realizar actualizaciones destructivas (solo significativo cuando `readOnlyHint` es `False`) |
208| `idempotentHint` | `bool \| None` | `False` | Si es `True`, las llamadas repetidas con los mismos argumentos no tienen efecto adicional (solo significativo cuando `readOnlyHint` es `False`) |208| `idempotentHint` | `bool \| None` | `False` | Si es `True`, las llamadas repetidas con los mismos argumentos no tienen efecto adicional (solo significativo cuando `readOnlyHint` es `False`) |
209| `openWorldHint` | `bool \| None` | `True` | Si es `True`, la herramienta interactúa con entidades externas (por ejemplo, búsqueda web). Si es `False`, el dominio de la herramienta es cerrado (por ejemplo, una herramienta de memoria) |209| `openWorldHint` | `bool \| None` | `True` | Si es `True`, la herramienta interactúa con entidades externas (por ejemplo, búsqueda web). Si es `False`, el dominio de la herramienta es cerrado (por ejemplo, una herramienta de memoria) |
210| `maxResultSizeChars` | `int \| None` | `None` | Número de caracteres hasta los cuales Claude Code mantiene el resultado de texto de esta herramienta en línea en la conversación en lugar de guardarlo en un archivo, hasta 500.000. Los resultados que contienen imágenes no se ven afectados. Una configuración de Claude Code en lugar de una sugerencia MCP: el SDK la envía en `_meta` de la herramienta como `anthropic/maxResultSizeChars`. Consulte [Raise the limit for a specific tool](/docs/es/mcp#raise-the-limit-for-a-specific-tool) |210| `maxResultSizeChars` | `int \| None` | `None` | Número de caracteres hasta los cuales Claude Code mantiene el resultado de texto de esta herramienta en línea en la conversación en lugar de guardarlo en un archivo, hasta 500.000. Los resultados que contienen imágenes no se ven afectados. Un ajuste de Claude Code en lugar de una sugerencia MCP: el SDK lo envía en `_meta` de la herramienta como `anthropic/maxResultSizeChars`. Consulta [Raise the limit for a specific tool](/docs/es/mcp#raise-the-limit-for-a-specific-tool) |
211 211
212```python theme={null}212```python theme={null}
213from claude_agent_sdk import tool, ToolAnnotations213from claude_agent_sdk import tool, ToolAnnotations
228 `create_sdk_mcp_server()`228 `create_sdk_mcp_server()`
229</h3>229</h3>
230 230
231Crea un servidor MCP en proceso que se ejecuta dentro de su aplicación Python.231Crea un servidor MCP en proceso que se ejecuta dentro de tu aplicación Python.
232 232
233```python theme={null}233```python theme={null}
234def create_sdk_mcp_server(234def create_sdk_mcp_server(
289 `list_sessions()`289 `list_sessions()`
290</h3>290</h3>
291 291
292Lista sesiones pasadas con metadatos. Filtre por directorio de proyecto o liste sesiones en todos los proyectos. Sincrónico; devuelve inmediatamente.292Lista sesiones pasadas con metadatos. Filtra por directorio de proyecto o lista sesiones en todos los proyectos. Sincrónico; devuelve inmediatamente.
293 293
294```python theme={null}294```python theme={null}
295def list_sessions(295def list_sessions(
308| :- | :- | :- | :- |308| :- | :- | :- | :- |
309| `directory` | `str \| None` | `None` | Directorio para listar sesiones. Cuando se omite, devuelve sesiones en todos los proyectos |309| `directory` | `str \| None` | `None` | Directorio para listar sesiones. Cuando se omite, devuelve sesiones en todos los proyectos |
310| `limit` | `int \| None` | `None` | Número máximo de sesiones a devolver |310| `limit` | `int \| None` | `None` | Número máximo de sesiones a devolver |
311| `offset` | `int` | `0` | Número de sesiones a omitir desde el inicio de los resultados ordenados. Úselo con `limit` para paginación |311| `offset` | `int` | `0` | Número de sesiones a omitir desde el inicio de los resultados ordenados. Úsalo con `limit` para paginación |
312| `include_worktrees` | `bool` | `True` | Cuando `directory` está dentro de un repositorio git, incluya sesiones de todas las rutas de worktree |312| `include_worktrees` | `bool` | `True` | Cuando `directory` está dentro de un repositorio git, incluye sesiones de todas las rutas de worktree |
313 313
314<h4 id="return-type-sdksessioninfo">314<h4 id="return-type-sdksessioninfo">
315 Tipo de retorno: `SDKSessionInfo`315 Tipo de retorno: `SDKSessionInfo`
318| Propiedad | Tipo | Descripción |318| Propiedad | Tipo | Descripción |
319| :- | :- | :- |319| :- | :- | :- |
320| `session_id` | `str` | Identificador único de sesión |320| `session_id` | `str` | Identificador único de sesión |
321| `summary` | `str` | Título de visualización: título personalizado, resumen generado automáticamente o primer prompt |321| `summary` | `str` | Título de visualización: título personalizado, prompt más reciente, resumen generado automáticamente o primer prompt |
322| `last_modified` | `int` | Última hora de modificación en milisegundos desde la época |322| `last_modified` | `int` | Última hora de modificación en milisegundos desde la época |
323| `file_size` | `int \| None` | Tamaño del archivo de sesión en bytes (`None` para backends de almacenamiento remoto) |323| `file_size` | `int \| None` | Tamaño del archivo de sesión en bytes (`None` para backends de almacenamiento remoto) |
324| `custom_title` | `str \| None` | Título de sesión establecido por el usuario |324| `custom_title` | `str \| None` | Título de sesión: el título establecido por el usuario, o el título generado automáticamente cuando no se ha establecido ninguno |
325| `first_prompt` | `str \| None` | Primer prompt de usuario significativo en la sesión |325| `first_prompt` | `str \| None` | Primer prompt de usuario significativo en la sesión |
326| `git_branch` | `str \| None` | Rama de Git al final de la sesión |326| `git_branch` | `str \| None` | Rama de Git al final de la sesión |
327| `cwd` | `str \| None` | Directorio de trabajo para la sesión |327| `cwd` | `str \| None` | Directorio de trabajo para la sesión |
332 Ejemplo332 Ejemplo
333</h4>333</h4>
334 334
335Imprima 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.335Imprime 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. Omite `directory` para buscar en todos los proyectos.
336 336
337```python theme={null}337```python theme={null}
338from claude_agent_sdk import list_sessions338from claude_agent_sdk import list_sessions
422 Ejemplo422 Ejemplo
423</h4>423</h4>
424 424
425Busque 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.425Busca los metadatos de una única sesión sin escanear el directorio del proyecto. Útil cuando ya tienes un ID de sesión de una ejecución anterior.
426 426
427```python theme={null}427```python theme={null}
428from claude_agent_sdk import get_session_info428from claude_agent_sdk import get_session_info
462 Ejemplo462 Ejemplo
463</h4>463</h4>
464 464
465Renombre 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`](#return-type-sdksessioninfo) en lecturas posteriores.465Renombra 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`](#return-type-sdksessioninfo) en lecturas posteriores.
466 466
467```python theme={null}467```python theme={null}
468from claude_agent_sdk import list_sessions, rename_session468from claude_agent_sdk import list_sessions, rename_session
476 `tag_session()`476 `tag_session()`
477</h3>477</h3>
478 478
479Etiqueta una sesión. Pase `None` para borrar la etiqueta. Las llamadas repetidas son seguras; la etiqueta más reciente gana. Sincrónico.479Etiqueta una sesión. Pasa `None` para borrar la etiqueta. Las llamadas repetidas son seguras; la etiqueta más reciente gana. Sincrónico.
480 480
481```python theme={null}481```python theme={null}
482def tag_session(482def tag_session(
502 Ejemplo502 Ejemplo
503</h4>503</h4>
504 504
505Etiquete una sesión, luego filtre por esa etiqueta en una lectura posterior. Pase `None` para borrar una etiqueta existente.505Etiqueta una sesión y luego filtra por esa etiqueta en una lectura posterior. Pasa `None` para borrar una etiqueta existente.
506 506
507```python theme={null}507```python theme={null}
508from claude_agent_sdk import list_sessions, tag_session508from claude_agent_sdk import list_sessions, tag_session
813 `Transport`813 `Transport`
814</h3>814</h3>
815 815
816Clase base abstracta para implementaciones de transporte personalizadas. Utilícela 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).816Clase base abstracta para implementaciones de transporte personalizadas. Úsala para comunicarte con el proceso de Claude a través de un canal personalizado (por ejemplo, una conexión remota en lugar de un subproceso local).
817 817
818<Warning>818<Warning>
819 Esta es una API interna de bajo nivel. La interfaz puede cambiar en futuras versiones. Las implementaciones personalizadas deben actualizarse para coincidir con cualquier cambio de interfaz.819 Esta es una API interna de bajo nivel. La interfaz puede cambiar en futuras versiones. Las implementaciones personalizadas deben actualizarse para coincidir con cualquier cambio de interfaz.
852| `read_messages()` | Iterador asincrónico que produce mensajes JSON analizados |852| `read_messages()` | Iterador asincrónico que produce mensajes JSON analizados |
853| `close()` | Cerrar la conexión y limpiar recursos |853| `close()` | Cerrar la conexión y limpiar recursos |
854| `is_ready()` | Devuelve `True` si el transporte puede enviar y recibir |854| `is_ready()` | Devuelve `True` si el transporte puede enviar y recibir |
855| `end_input()` | Cerrar el flujo de entrada (por ejemplo, cerrar stdin para transportes de subproceso) |855| `end_input()` | Cerrar el stream de entrada (por ejemplo, cerrar stdin para transportes de subproceso) |
856 856
857Importación: `from claude_agent_sdk import Transport`857Importación: `from claude_agent_sdk import Transport`
858 858
918 918
919| Propiedad | Tipo | Predeterminado | Descripción |919| Propiedad | Tipo | Predeterminado | Descripción |
920| :- | :- | :- | :- |920| :- | :- | :- | :- |
921| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Configuración de herramientas. Utilice `{"type": "preset", "preset": "claude_code"}` para las herramientas predeterminadas de Claude Code |921| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Configuración de herramientas. Usa `{"type": "preset", "preset": "claude_code"}` para las herramientas predeterminadas de Claude Code |
922| `allowed_tools` | `list[str]` | `[]` | Herramientas para aprobar automáticamente sin solicitar. Esto no restringe Claude solo a estas herramientas. Si nombra una de las [herramientas de seguimiento de tareas](/docs/es/agent-sdk/todo-tracking#model-availability) aquí, Claude Code también opta por la sesión. Otras herramientas no listadas se transfieren a `permission_mode` y `can_use_tool`. Utilice `disallowed_tools` para bloquear herramientas. Consulte [Permisos](/docs/es/agent-sdk/permissions#allow-and-deny-rules) |922| `allowed_tools` | `list[str]` | `[]` | Herramientas que se aprueban automáticamente sin pedir confirmación. Esto no restringe a Claude solo a estas herramientas. Si nombras aquí una de las [herramientas de seguimiento de tareas](/docs/es/agent-sdk/todo-tracking#model-availability), Claude Code también habilita esa función en la sesión. Las demás herramientas no listadas pasan a `permission_mode` y `can_use_tool`. Usa `disallowed_tools` para bloquear herramientas. Consulta [Permisos](/docs/es/agent-sdk/permissions#allow-and-deny-rules) |
923| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | Configuración de indicación del sistema. Pase una cadena para un indicador personalizado, `{"type": "preset", "preset": "claude_code"}` para el indicador del sistema de Claude Code con `"append"` opcional, `{"type": "custom", "prompt": "..."}` para un indicador personalizado que también puede establecer `"snapshot"`, o `{"type": "file", "path": "..."}` para cargar un indicador grande desde el disco. Consulte [`SystemPromptPreset`](#systempromptpreset), [`SystemPromptCustom`](#systempromptcustom), y [`SystemPromptFile`](#systempromptfile) |923| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | Configuración del prompt del sistema. Pasa una cadena para un prompt personalizado, `{"type": "preset", "preset": "claude_code"}` para el prompt del sistema de Claude Code con `"append"` opcional, `{"type": "custom", "prompt": "..."}` para un prompt personalizado que también puede establecer `"snapshot"`, o `{"type": "file", "path": "..."}` para cargar un prompt grande desde el disco. Consulta [`SystemPromptPreset`](#systempromptpreset), [`SystemPromptCustom`](#systempromptcustom) y [`SystemPromptFile`](#systempromptfile) |
924| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | Configuraciones de servidor MCP o ruta al archivo de configuración |924| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | Configuraciones de servidores MCP o ruta al archivo de configuración |
925| `strict_mcp_config` | `bool` | `False` | Cuando es `True`, utilice solo los servidores pasados en `mcp_servers` e ignore el proyecto `.mcp.json`, la configuración del usuario, los servidores MCP proporcionados por plugins, y los [conectores de claude.ai](/docs/es/mcp#use-mcp-servers-from-claude-ai). Se asigna a la bandera CLI `--strict-mcp-config` |925| `strict_mcp_config` | `bool` | `False` | Cuando es `True`, usa solo los servidores pasados en `mcp_servers` e ignora el `.mcp.json` del proyecto, la configuración del usuario, los servidores MCP proporcionados por plugins y los [conectores de claude.ai](/docs/es/mcp#use-mcp-servers-from-claude-ai). Corresponde al flag de la CLI `--strict-mcp-config` |
926| `permission_mode` | `PermissionMode \| None` | `None` | Modo de permiso para el uso de herramientas |926| `permission_mode` | `PermissionMode \| None` | `None` | Modo de permisos para el uso de herramientas |
927| `continue_conversation` | `bool` | `False` | Continuar la conversación más reciente |927| `continue_conversation` | `bool` | `False` | Continuar la conversación más reciente |
928| `resume` | `str \| None` | `None` | ID de sesión para reanudar |928| `resume` | `str \| None` | `None` | ID de sesión para reanudar |
929| `session_id` | `str \| None` | `None` | Utilice un ID de sesión específico en lugar de uno generado automáticamente. Debe ser un UUID válido. No se puede combinar con `continue_conversation` o `resume` a menos que `fork_session` también esté configurado |929| `session_id` | `str \| None` | `None` | Usar un ID de sesión específico en lugar de uno generado automáticamente. Debe ser un UUID válido. No se puede combinar con `continue_conversation` o `resume` a menos que `fork_session` también esté establecido |
930| `max_turns` | `int \| None` | `None` | Máximo de turnos agentes (viajes de ronda de uso de herramientas) |930| `max_turns` | `int \| None` | `None` | Máximo de turnos agénticos (ciclos de ida y vuelta de uso de herramientas) |
931| `max_budget_usd` | `float \| None` | `None` | Detener la consulta cuando la estimación de costo del lado del cliente alcance este valor en USD. Se compara con la misma estimación que `total_cost_usd`. Para advertencias de precisión y comportamiento de reinicio, consulte [Rastrear costo y uso](/docs/es/agent-sdk/cost-tracking) |931| `max_budget_usd` | `float \| None` | `None` | Detener la consulta cuando la estimación de costo del lado del cliente alcance este valor en USD. Cuenta solo el gasto propio de la llamada; los totales restaurados de una sesión reanudada no cuentan. Para advertencias de precisión y comportamiento de reinicio, consulta [Rastrear costo y uso](/docs/es/agent-sdk/cost-tracking) |
932| `disallowed_tools` | `list[str]` | `[]` | Herramientas a denegar. Un nombre simple como `"Bash"` elimina la herramienta del contexto de Claude. Una regla con alcance como `"Bash(rm *)"` deja la herramienta disponible y deniega llamadas coincidentes en cada modo de permiso, incluido `bypassPermissions`, para el comando [tal como está escrito](/docs/es/permissions#bash-rule-limits). Consulte [Permisos](/docs/es/agent-sdk/permissions#allow-and-deny-rules) |932| `disallowed_tools` | `list[str]` | `[]` | Herramientas a denegar. Un nombre simple como `"Bash"` elimina la herramienta del contexto de Claude. Una regla con alcance como `"Bash(rm *)"` deja la herramienta disponible y deniega las llamadas coincidentes en todos los modos de permisos, incluido `bypassPermissions`, para el comando [tal como está escrito](/docs/es/permissions#bash-rule-limits). Consulta [Permisos](/docs/es/agent-sdk/permissions#allow-and-deny-rules) |
933| `enable_file_checkpointing` | `bool` | `False` | Habilitar el seguimiento de cambios de archivo para rebobinar. Consulte [Punto de control de archivo](/docs/es/agent-sdk/file-checkpointing) |933| `enable_file_checkpointing` | `bool` | `False` | Habilitar el seguimiento de cambios de archivos para rebobinar. Consulta [Checkpointing de archivos](/docs/es/agent-sdk/file-checkpointing) |
934| `model` | `str \| None` | `None` | Alias de modelo Claude o nombre de modelo completo. Consulte [valores aceptados e IDs específicos del proveedor](/docs/es/model-config#available-models) |934| `model` | `str \| None` | `None` | Alias de modelo de Claude o nombre de modelo completo. Consulta [valores aceptados e IDs específicos del proveedor](/docs/es/model-config#available-models) |
935| `fallback_model` | `str \| None` | `None` | Modelo de respaldo a utilizar si el modelo principal falla. Acepta una lista separada por comas. Para orientación, consulte [Elegir un modelo](/docs/es/agent-sdk/configuration#choose-a-model) |935| `fallback_model` | `str \| None` | `None` | Modelo de respaldo a usar si el modelo principal falla. Acepta una lista separada por comas. Para orientación, consulta [Elegir un modelo](/docs/es/agent-sdk/configuration#choose-a-model) |
936| `betas` | `list[SdkBeta]` | `[]` | Características beta para habilitar. Consulte [`SdkBeta`](#sdkbeta) para opciones disponibles |936| `betas` | `list[SdkBeta]` | `[]` | Características beta para habilitar. Consulta [`SdkBeta`](#sdkbeta) para ver las opciones disponibles |
937| `output_format` | `dict[str, Any] \| None` | `None` | Formato de salida para respuestas estructuradas (por ejemplo, `{"type": "json_schema", "schema": {...}}`). Consulte [Salidas estructuradas](/docs/es/agent-sdk/structured-outputs) para detalles |937| `output_format` | `dict[str, Any] \| None` | `None` | Formato de salida para respuestas estructuradas (por ejemplo, `{"type": "json_schema", "schema": {...}}`). Consulta [Salidas estructuradas](/docs/es/agent-sdk/structured-outputs) para más detalles |
938| `permission_prompt_tool_name` | `str \| None` | `None` | Nombre de herramienta MCP para indicadores de permiso |938| `permission_prompt_tool_name` | `str \| None` | `None` | Nombre de herramienta MCP para solicitudes de permiso |
939| `cwd` | `str \| Path \| None` | `None` | Directorio de trabajo actual |939| `cwd` | `str \| Path \| None` | `None` | Directorio de trabajo actual |
940| `cli_path` | `str \| Path \| None` | `None` | Ruta personalizada al ejecutable CLI de Claude Code |940| `cli_path` | `str \| Path \| None` | `None` | Ruta personalizada al ejecutable de la CLI de Claude Code |
941| `settings` | `str \| None` | `None` | Ruta a un archivo de configuración o una cadena JSON en línea |941| `settings` | `str \| None` | `None` | Ruta a un archivo de configuración o una cadena JSON en línea |
942| `add_dirs` | `list[str \| Path]` | `[]` | Directorios adicionales a los que Claude puede acceder. El SDK pasa cada entrada a Claude Code como `--add-dir`, por lo que con la fuente de configuración `project` Claude Code también [carga las skills, comandos y subagentes del directorio](/docs/es/permissions#additional-directories-grant-file-access-not-configuration) |942| `add_dirs` | `list[str \| Path]` | `[]` | Directorios adicionales a los que Claude puede acceder. El SDK pasa cada entrada a Claude Code como `--add-dir`, por lo que con la fuente de configuración `project` Claude Code también [carga los skills, comandos y subagentes del directorio](/docs/es/permissions#additional-directories-grant-file-access-not-configuration) |
943| `env` | `dict[str, str]` | `{}` | Variables de entorno fusionadas en la parte superior del entorno de proceso heredado. Consulte [Variables de entorno](/docs/es/env-vars) para variables que lee la CLI subyacente, y [Manejar respuestas API lentas o estancadas](#handle-slow-or-stalled-api-responses) para variables relacionadas con tiempos de espera. Establezca `CLAUDE_AGENT_SDK_CLIENT_APP` para identificar su aplicación en el encabezado User-Agent |943| `env` | `dict[str, str]` | `{}` | Variables de entorno que se fusionan sobre el entorno de proceso heredado. Consulta [Variables de entorno](/docs/es/env-vars) para ver las variables que lee la CLI subyacente, y [Manejar respuestas de API lentas o estancadas](#handle-slow-or-stalled-api-responses) para las variables relacionadas con tiempos de espera. Establece `CLAUDE_AGENT_SDK_CLIENT_APP` para identificar tu aplicación en el encabezado User-Agent |
944| `extra_args` | `dict[str, str \| None]` | `{}` | Argumentos CLI adicionales para pasar directamente a la CLI |944| `extra_args` | `dict[str, str \| None]` | `{}` | Argumentos de CLI adicionales para pasar directamente a la CLI |
945| `max_buffer_size` | `int \| None` | `None` | Máximo de bytes al almacenar en búfer la salida estándar de CLI |945| `max_buffer_size` | `int \| None` | `None` | Máximo de bytes al almacenar en búfer la salida estándar de la CLI |
946| `debug_stderr` | `Any` | `sys.stderr` | *Obsoleto* - El SDK ignora este valor. Utilice la devolución de llamada `stderr` para salida de stderr de CLI |946| `debug_stderr` | `Any` | `sys.stderr` | *Obsoleto* - El SDK ignora este valor. Usa el callback `stderr` para la salida stderr de la CLI |
947| `stderr` | `Callable[[str], None] \| None` | `None` | Función de devolución de llamada para salida de stderr desde CLI |947| `stderr` | `Callable[[str], None] \| None` | `None` | Función de callback para la salida stderr de la CLI |
948| `can_use_tool` | [`CanUseTool`](#canusetool) ` \| None` | `None` | Devolución de llamada de permiso de herramienta, invocada solo cuando el [flujo de permiso](/docs/es/agent-sdk/permissions#how-permissions-are-evaluated) se transfiere a un indicador. No se invoca para llamadas aprobadas automáticamente por `allowed_tools`, reglas de permiso, o `permission_mode`. Una regla de permiso no aprueba previamente las [acciones que ningún modo aprueba automáticamente](/docs/es/permission-modes#actions-no-mode-auto-approves). Consulte [`CanUseTool`](#canusetool) para detalles |948| `can_use_tool` | [`CanUseTool`](#canusetool) ` \| None` | `None` | Callback de permisos de herramientas, que se invoca solo cuando el [flujo de permisos](/docs/es/agent-sdk/permissions#how-permissions-are-evaluated) termina en una solicitud de permiso. No se invoca para llamadas aprobadas automáticamente por `allowed_tools`, reglas de permiso o `permission_mode`. Una regla de permiso no aprueba previamente las [acciones que ningún modo aprueba automáticamente](/docs/es/permission-modes#actions-no-mode-auto-approves). Consulta [`CanUseTool`](#canusetool) para más detalles |
949| `hooks` | `dict[HookEvent, list[HookMatcher]] \| None` | `None` | Configuraciones de hooks para interceptar eventos |949| `hooks` | `dict[HookEvent, list[HookMatcher]] \| None` | `None` | Configuraciones de hooks para interceptar eventos |
950| `user` | `str \| None` | `None` | En plataformas POSIX, la cuenta de usuario del SO bajo la cual se ejecuta el subproceso de Claude Code. Claude Code mantiene el entorno del proceso padre, incluido `HOME`, y se ejecuta en `cwd` |950| `user` | `str \| None` | `None` | En plataformas POSIX, la cuenta de usuario del SO con la que se ejecuta el subproceso de Claude Code. Claude Code mantiene el entorno del proceso padre, incluido `HOME`, y se ejecuta en `cwd` |
951| `include_partial_messages` | `bool` | `False` | Incluir eventos de transmisión de mensajes parciales. Cuando está habilitado, se producen mensajes [`StreamEvent`](#streamevent) |951| `include_partial_messages` | `bool` | `False` | Incluir eventos de streaming de mensajes parciales. Cuando está habilitado, se producen mensajes [`StreamEvent`](#streamevent) |
952| `include_hook_events` | `bool` | `False` | Incluir eventos del ciclo de vida de hooks en el flujo de mensajes como objetos `HookEventMessage` |952| `include_hook_events` | `bool` | `False` | Incluir eventos del ciclo de vida de hooks en el stream de mensajes como objetos `HookEventMessage` |
953| `forward_subagent_text` | `bool` | `False` | Reenviar bloques de texto y pensamiento de subagentes en el flujo de mensajes. Sin esta opción, Claude Code emite bloques `tool_use` y `tool_result` de subagentes pero no texto ni pensamiento. Requiere Python Agent SDK 0.2.140 o posterior |953| `forward_subagent_text` | `bool` | `False` | Reenviar bloques de texto y de pensamiento de subagentes en el stream de mensajes. Sin esta opción, Claude Code emite bloques `tool_use` y `tool_result` de subagentes, pero no texto ni pensamiento. Requiere Python Agent SDK 0.2.140 o posterior |
954| `verbatim_prompts` | `bool` | `False` | Entregar cada indicador tal como está escrito. El SDK envía cada mensaje del usuario con `client_composed` establecido en `True`. Consulte [`client_composed`](/docs/es/agent-sdk/typescript#sdkusermessage) para ver qué omite Claude Code en esos mensajes. Utilice esta opción cuando el texto del indicador incluya contenido que el usuario final no escribió. Para control por turno, déjelo desactivado y establezca `"client_composed": True` en mensajes individuales transmitidos en su lugar. Mientras la opción está activada, el SDK sobrescribe cualquier valor `client_composed` que establezca. Requiere Python Agent SDK 0.2.158 o posterior y Claude Code v2.1.248 o posterior; la CLI incluida en esas versiones de SDK satisface el requisito de Claude Code |954| `verbatim_prompts` | `bool` | `False` | Entregar cada prompt tal como está escrito. El SDK envía cada mensaje del usuario con `client_composed` establecido en `True`. Consulta [`client_composed`](/docs/es/agent-sdk/typescript#sdkusermessage) para ver qué omite Claude Code en esos mensajes. Usa esta opción cuando el texto de tu prompt incluya contenido que el usuario final no escribió. Para control por turno, déjala desactivada y, en su lugar, establece `"client_composed": True` en mensajes individuales enviados en streaming. Mientras la opción está activada, el SDK sobrescribe cualquier valor de `client_composed` que establezcas. Requiere Python Agent SDK 0.2.158 o posterior y Claude Code v2.1.248 o posterior; la CLI incluida en esas versiones del SDK cumple el requisito de Claude Code |
955| `fork_session` | `bool` | `False` | Al reanudar con `resume`, bifurcar a un nuevo ID de sesión en lugar de continuar la sesión original |955| `fork_session` | `bool` | `False` | Al reanudar con `resume`, bifurcar a un nuevo ID de sesión en lugar de continuar la sesión original |
956| `resume_session_at` | `str \| None` | `None` | Al reanudar, cargar la conversación solo hasta e incluyendo el mensaje con este UUID. Utilice con `resume`, y generalmente `fork_session`, para ramificar desde un punto anterior. Requiere Python Agent SDK 0.2.137 o posterior |956| `resume_session_at` | `str \| None` | `None` | Al reanudar, cargar la conversación solo hasta el mensaje con este UUID, inclusive. Úsalo con `resume`, y normalmente con `fork_session`, para crear una rama desde un punto anterior. Requiere Python Agent SDK 0.2.137 o posterior |
957| `resume_drops_turn` | `str \| None` | `None` | UUID del indicador del usuario cuyo turno descarta un truncamiento `resume_session_at`. Cuando se establece, la CLI rechaza la reanudación si el rango descartado contiene entradas no atribuibles a ese turno. Requiere Python Agent SDK 0.2.137 o posterior y Claude Code v2.1.223 o posterior; la CLI incluida en esas versiones de SDK satisface el requisito de Claude Code |957| `resume_drops_turn` | `str \| None` | `None` | UUID del prompt del usuario cuyo turno descarta un truncamiento de `resume_session_at`. Cuando se establece, la CLI rechaza la reanudación si el rango descartado contiene entradas no atribuibles a ese turno. Requiere Python Agent SDK 0.2.137 o posterior y Claude Code v2.1.223 o posterior; la CLI incluida en esas versiones del SDK cumple el requisito de Claude Code |
958| `agents` | `dict[str, AgentDefinition] \| None` | `None` | Subagentes definidos programáticamente |958| `agents` | `dict[str, AgentDefinition] \| None` | `None` | Subagentes definidos programáticamente |
959| `plugins` | `list[SdkPluginConfig]` | `[]` | Cargar plugins personalizados desde rutas locales. Consulte [Plugins](/docs/es/agent-sdk/plugins) para detalles |959| `plugins` | `list[SdkPluginConfig]` | `[]` | Cargar plugins personalizados desde rutas locales. Consulta [Plugins](/docs/es/agent-sdk/plugins) para más detalles |
960| `sandbox` | [`SandboxSettings`](#sandboxsettings) ` \| None` | `None` | Configurar el comportamiento del sandbox programáticamente. Consulte [Configuración de sandbox](#sandboxsettings) para detalles |960| `sandbox` | [`SandboxSettings`](#sandboxsettings) ` \| None` | `None` | Configurar el comportamiento del sandbox programáticamente. Consulta [Configuración del sandbox](#sandboxsettings) para más detalles |
961| `setting_sources` | `list[SettingSource] \| None` | `None` (Valores predeterminados de CLI: todas las fuentes) | Controlar qué configuración del sistema de archivos cargar. Pase `[]` para deshabilitar la configuración de usuario, proyecto y local. Con `skills` establecido y este campo sin establecer, solo se cargan las fuentes de usuario y proyecto. Establezca `setting_sources` explícitamente para mantener la configuración local. La política administrada por punto final se carga independientemente; 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](/docs/es/server-managed-settings#platform-availability). Para entradas leídas independientemente de esta opción, consulte [Lo que settingSources no controla](/docs/es/agent-sdk/claude-code-features#what-settingsources-does-not-control) |961| `setting_sources` | `list[SettingSource] \| None` | `None` (valores predeterminados de la CLI: todas las fuentes) | Controlar qué configuración del sistema de archivos se carga. Pasa `[]` para deshabilitar la configuración de usuario, de proyecto y local. Con `skills` establecido y este campo sin establecer, solo se cargan las fuentes de usuario y de proyecto. Establece `setting_sources` explícitamente para mantener la configuración local. La política administrada por endpoint se carga de todos modos; 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](/docs/es/server-managed-settings#platform-availability). Para las entradas que se leen independientemente de esta opción, consulta [Lo que settingSources no controla](/docs/es/agent-sdk/claude-code-features#what-settingsources-does-not-control) |
962| `skills` | `list[str] \| Literal["all"] \| None` | `None` | Skills disponibles para la sesión. Pase `"all"` para habilitar cada skill descubierto, o una lista de nombres de skills. Pase solo nombres exactos. El SDK rechaza nombres mal formados y en forma de comodín con un `ValueError` antes de iniciar el proceso de Claude Code; esta verificación requiere Python Agent SDK 0.2.129 o posterior. Cuando se establece, el SDK agrega automáticamente la herramienta Skill a `allowed_tools`. Si también pasa `tools`, incluya `"Skill"` en esa lista. Consulte [Skills](/docs/es/agent-sdk/skills) |962| `skills` | `list[str] \| Literal["all"] \| None` | `None` | Skills disponibles para la sesión. Pasa `"all"` para habilitar todos los skills descubiertos, o una lista de nombres de skills. Pasa solo nombres exactos. El SDK rechaza los nombres mal formados y con comodines con un `ValueError` antes de iniciar el proceso de Claude Code; esta verificación requiere Python Agent SDK 0.2.129 o posterior. Cuando se establece, el SDK agrega automáticamente la herramienta Skill a `allowed_tools`. Si también pasas `tools`, incluye `"Skill"` en esa lista. Consulta [Skills](/docs/es/agent-sdk/skills) |
963| `max_thinking_tokens` | `int \| None` | `None` | *Obsoleto* - Máximo de tokens para bloques de pensamiento. Utilice `thinking` en su lugar |963| `max_thinking_tokens` | `int \| None` | `None` | *Obsoleto* - Máximo de tokens para bloques de pensamiento. Usa `thinking` en su lugar |
964| `thinking` | [`ThinkingConfig`](#thinkingconfig) ` \| None` | `None` | Controla el comportamiento del pensamiento extendido. Tiene precedencia sobre `max_thinking_tokens` |964| `thinking` | [`ThinkingConfig`](#thinkingconfig) ` \| None` | `None` | Controla el comportamiento del pensamiento extendido. Tiene precedencia sobre `max_thinking_tokens` |
965| `effort` | [`EffortLevel`](#effortlevel) ` \| None` | `None` | Nivel de esfuerzo para la profundidad del pensamiento. Consulte [ajustar el nivel de esfuerzo](/docs/es/model-config#adjust-effort-level) |965| `effort` | [`EffortLevel`](#effortlevel) ` \| None` | `None` | Nivel de esfuerzo para la profundidad del pensamiento. Consulta [ajustar el nivel de esfuerzo](/docs/es/model-config#adjust-effort-level) |
966| `session_store` | [`SessionStore`](/docs/es/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | Reflejar transcripciones de sesión en un backend externo para que otro host pueda reanudarlas. Consulte [Persistir sesiones en almacenamiento externo](/docs/es/agent-sdk/session-storage) |966| `session_store` | [`SessionStore`](/docs/es/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | Replicar las transcripciones de sesión en un backend externo para que otro host pueda reanudarlas. Consulta [Persistir sesiones en almacenamiento externo](/docs/es/agent-sdk/session-storage) |
967| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | Cuándo vaciar entradas de transcripción reflejadas a `session_store`. `"batched"` vacía una vez por turno o cuando el búfer se llena; `"eager"` activa un vaciado en segundo plano después de cada fotograma. Se ignora cuando `session_store` es `None` |967| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | Cuándo volcar las entradas de transcripción replicadas en `session_store`. `"batched"` vuelca una vez por turno o cuando el búfer se llena; `"eager"` activa un volcado en segundo plano después de cada frame. Se ignora cuando `session_store` es `None` |
968| `load_timeout_ms` | `int` | `60000` | Tiempo de espera por llamada para `session_store.load()` y `list_subkeys()` durante la materialización de reanudación, en milisegundos |968| `load_timeout_ms` | `int` | `60000` | Tiempo de espera por llamada para `session_store.load()` y `list_subkeys()` durante la materialización de la reanudación, en milisegundos |
969| `task_budget` | `TaskBudget \| None` | `None` | Presupuesto de tokens del lado de la API. Se envía como `output_config.task_budget` con el encabezado beta `task-budgets-2026-03-13`. Pase `{"total": <int>}`. |969| `task_budget` | `TaskBudget \| None` | `None` | Presupuesto de tokens del lado de la API. Se envía como `output_config.task_budget` con el encabezado beta `task-budgets-2026-03-13`. Pasa `{"total": <int>}`. |
970 970
971<h4 id="handle-slow-or-stalled-api-responses">971<h4 id="handle-slow-or-stalled-api-responses">
972 Manejar respuestas API lentas o estancadas972 Manejar respuestas de API lentas o estancadas
973</h4>973</h4>
974 974
975El 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`:975El subproceso de la CLI lee varias variables de entorno que controlan los tiempos de espera de la API y la detección de estancamientos. Pásalas a través de `ClaudeAgentOptions.env`:
976 976
977```python theme={null}977```python theme={null}
978from claude_agent_sdk import ClaudeAgentOptions978from claude_agent_sdk import ClaudeAgentOptions
987```987```
988 988
989* `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.989* `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.
990* `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`](/docs/es/errors#tune-retry-behavior): reintenta errores de capacidad transitoria indefinidamente y, en Claude Code v2.1.199 o posterior, eleva el predeterminado para otros errores transitorios a `300` y elimina el límite en esta variable.990* `CLAUDE_CODE_MAX_RETRIES`: máximo de reintentos de la API. Predeterminado `10`, limitado a `15`. Cada reintento obtiene su propia ventana de `API_TIMEOUT_MS`, por lo que el tiempo real en el peor caso es aproximadamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` más el backoff. Para ejecuciones desatendidas que necesitan esperar durante interrupciones más largas, establece [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/es/errors#tune-retry-behavior): reintenta indefinidamente los errores transitorios de capacidad y, en Claude Code v2.1.199 o posterior, eleva el predeterminado para otros errores transitorios a `300` y elimina el límite de esta variable.
991* `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 eleve esa variable. Con el perro guardián de flujo desactivado, el predeterminado es `600000`. Antes de v2.1.257, el predeterminado era siempre `600000`.991* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog de estancamiento para subagentes. Mientras el watchdog de stream está activado, el predeterminado es `CLAUDE_STREAM_IDLE_TIMEOUT_MS` más 5 minutos, lo que da `600000` a menos que aumentes esa variable. Con el watchdog de stream desactivado, el predeterminado es `600000`. Antes de v2.1.257, el predeterminado era siempre `600000`.
992 992
993 El temporizador se reinicia en cada evento de flujo. En un estancamiento, Claude Code aborta el subagente e informa el estancamiento al padre. Para un subagente en segundo plano, también marca la tarea como fallida y adjunta cualquier resultado parcial.993 El temporizador se reinicia con cada evento de stream. Ante un estancamiento, Claude Code aborta el subagente e informa el estancamiento al padre. Para un subagente en segundo plano, también marca la tarea como fallida y adjunta cualquier resultado parcial.
994* `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 respuesta deja de transmitirse. 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 predeterminado de `300000` y se fija a ese mínimo. Después del aborto, [Reintentos automáticos](/docs/es/errors#automatic-retries) cubre lo que Claude Code hace, según qué tan lejos haya progresado la respuesta.994* `CLAUDE_ENABLE_STREAM_WATCHDOG` con `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: watchdog de stream que aborta la solicitud cuando los encabezados han llegado pero el cuerpo de la respuesta deja de transmitirse en streaming. El watchdog está activado de forma predeterminada para todos los proveedores; establece `CLAUDE_ENABLE_STREAM_WATCHDOG=0` para desactivarlo. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` tiene un predeterminado de `300000` y se ajusta a ese mínimo. Después del aborto, [Reintentos automáticos](/docs/es/errors#automatic-retries) explica lo que hace Claude Code según cuánto haya avanzado la respuesta.
995 995
996 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`](#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.996 Mientras el watchdog espera una respuesta que un gateway detrás de `ANTHROPIC_BASE_URL` mantiene abierta con pings de keep-alive, un host que establece `include_partial_messages` sigue recibiendo mensajes [`StreamEvent`](#streamevent) de tipo `ping`. Interpreta esos frames como señal de actividad en lugar de agotar el tiempo de espera de la sesión por silencio. Antes de v2.1.257, los frames se detenían 5 minutos después del último evento de stream real.
997 997
998<h3 id="outputformat">998<h3 id="outputformat">
999 `OutputFormat`999 `OutputFormat`
1000</h3>1000</h3>
1001 1001
1002Configuración para validación de salida estructurada. Pase esto como un `dict` al campo `output_format` en `ClaudeAgentOptions`:1002Configuración para la validación de salida estructurada. Pásala como un `dict` al campo `output_format` de `ClaudeAgentOptions`:
1003 1003
1004```python theme={null}1004```python theme={null}
1005# Forma de dict esperada para output_format1005# Forma de dict esperada para output_format
1006{1006{
1007 "type": "json_schema",1007 "type": "json_schema",
1008 "schema": {...}, # Su definición de JSON Schema1008 "schema": {...}, # Tu definición de JSON Schema
1009}1009}
1010```1010```
1011 1011
1012| Campo | Requerido | Descripción |1012| Campo | Requerido | Descripción |
1013| :- | :- | :- |1013| :- | :- | :- |
1014| `type` | Sí | Debe ser `"json_schema"` para validación de JSON Schema |1014| `type` | Sí | Debe ser `"json_schema"` para la validación con JSON Schema |
1015| `schema` | Sí | Definición de JSON Schema para validación de salida |1015| `schema` | Sí | Definición de JSON Schema para la validación de salida |
1016 1016
1017<h3 id="systempromptpreset">1017<h3 id="systempromptpreset">
1018 `SystemPromptPreset`1018 `SystemPromptPreset`
1019</h3>1019</h3>
1020 1020
1021Configuración para usar el indicador del sistema preestablecido de Claude Code con adiciones opcionales.1021Configuración para usar el prompt del sistema preestablecido de Claude Code con adiciones opcionales.
1022 1022
1023```python theme={null}1023```python theme={null}
1024class SystemPromptPreset(TypedDict):1024class SystemPromptPreset(TypedDict):
1031 1031
1032| Campo | Requerido | Descripción |1032| Campo | Requerido | Descripción |
1033| :- | :- | :- |1033| :- | :- | :- |
1034| `type` | Sí | Debe ser `"preset"` para usar un indicador del sistema preestablecido |1034| `type` | Sí | Debe ser `"preset"` para usar un prompt del sistema preestablecido |
1035| `preset` | Sí | Debe ser `"claude_code"` para usar el indicador del sistema de Claude Code |1035| `preset` | Sí | Debe ser `"claude_code"` para usar el prompt del sistema de Claude Code |
1036| `append` | No | Instrucciones adicionales para agregar al indicador del sistema preestablecido |1036| `append` | No | Instrucciones adicionales para agregar al prompt del sistema preestablecido |
1037| `exclude_dynamic_sections` | No | Mover contexto por usuario, como la ubicación de memoria automática, del indicador del sistema al primer mensaje del usuario. Mejora la reutilización de caché de indicadores entre usuarios y máquinas. Consulte [Modificar indicadores del sistema](/docs/es/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |1037| `exclude_dynamic_sections` | No | Mover el contexto por usuario, como la ubicación de la memoria automática, del prompt del sistema al primer mensaje del usuario. Mejora la reutilización de la caché de prompts entre usuarios y máquinas. Consulta [Modificar prompts del sistema](/docs/es/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |
1038| `snapshot` | No | Establezca en `False` para reconstruir el indicador del sistema en cada solicitud en lugar de [reutilizar el indicador que la sesión registró en su primera solicitud](/docs/es/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session). Requiere `claude-agent-sdk` v0.2.153 o posterior |1038| `snapshot` | No | Establécelo en `False` para reconstruir el prompt del sistema en cada solicitud en lugar de [reutilizar el prompt que la sesión registró en su primera solicitud](/docs/es/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session). Requiere `claude-agent-sdk` v0.2.153 o posterior |
1039 1039
1040<h3 id="systempromptcustom">1040<h3 id="systempromptcustom">
1041 `SystemPromptCustom`1041 `SystemPromptCustom`
1042</h3>1042</h3>
1043 1043
1044Un indicador del sistema personalizado en forma de objeto, equivalente a pasar una cadena como `system_prompt`, que también puede establecer `snapshot`. Requiere `claude-agent-sdk` v0.2.153 o posterior.1044Un prompt del sistema personalizado en forma de objeto, equivalente a pasar una cadena como `system_prompt`, que también puede establecer `snapshot`. Requiere `claude-agent-sdk` v0.2.153 o posterior.
1045 1045
1046```python theme={null}1046```python theme={null}
1047class SystemPromptCustom(TypedDict):1047class SystemPromptCustom(TypedDict):
1053| Campo | Requerido | Descripción |1053| Campo | Requerido | Descripción |
1054| :- | :- | :- |1054| :- | :- | :- |
1055| `type` | Sí | Debe ser `"custom"` |1055| `type` | Sí | Debe ser `"custom"` |
1056| `prompt` | Sí | El texto del indicador del sistema. Se pasa a la CLI como un argumento de línea de comandos, por lo que se aplican los [límites de longitud de línea de comandos](#systempromptfile) |1056| `prompt` | Sí | El texto del prompt del sistema. Se pasa a la CLI como un argumento de línea de comandos, por lo que se aplican los [límites de longitud de la línea de comandos](#systempromptfile) |
1057| `snapshot` | No | Igual que [`SystemPromptPreset.snapshot`](#systempromptpreset), aplicado a `prompt` |1057| `snapshot` | No | Igual que [`SystemPromptPreset.snapshot`](#systempromptpreset), aplicado a `prompt` |
1058 1058
1059<h3 id="systempromptfile">1059<h3 id="systempromptfile">
1060 `SystemPromptFile`1060 `SystemPromptFile`
1061</h3>1061</h3>
1062 1062
1063Configuración para cargar un indicador del sistema personalizado desde un archivo en lugar de pasarlo como una cadena. El SDK asigna esto a la bandera CLI [`--system-prompt-file`](/docs/es/cli-reference#system-prompt-flags). Utilice la forma de archivo cuando el indicador 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.1063Configuración para cargar un prompt del sistema personalizado desde un archivo en lugar de pasarlo como una cadena. El SDK lo asigna al flag de la CLI [`--system-prompt-file`](/docs/es/cli-reference#system-prompt-flags). Usa la forma de archivo cuando el prompt sea grande: el SDK pasa un `system_prompt` de tipo cadena en el argv del subproceso de la CLI, que está sujeto a los límites de longitud de la línea de comandos del SO antes de que el SDK envíe cualquier solicitud a la API. En Linux, un único argumento de más de 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 con un umbral más bajo.
1064 1064
1065```python theme={null}1065```python theme={null}
1066class SystemPromptFile(TypedDict):1066class SystemPromptFile(TypedDict):
1070 1070
1071| Campo | Requerido | Descripción |1071| Campo | Requerido | Descripción |
1072| :- | :- | :- |1072| :- | :- | :- |
1073| `type` | Sí | Debe ser `"file"` para cargar el indicador desde el disco |1073| `type` | Sí | Debe ser `"file"` para cargar el prompt desde el disco |
1074| `path` | Sí | Ruta a un archivo que contiene el indicador del sistema |1074| `path` | Sí | Ruta a un archivo que contiene el prompt del sistema |
1075 1075
1076<h3 id="settingsource">1076<h3 id="settingsource">
1077 `SettingSource`1077 `SettingSource`
1078</h3>1078</h3>
1079 1079
1080Controla qué fuentes de configuración basadas en el sistema de archivos carga el SDK.1080Controla desde qué fuentes de configuración basadas en el sistema de archivos carga el SDK la configuración.
1081 1081
1082```python theme={null}1082```python theme={null}
1083SettingSource = Literal["user", "project", "local"]1083SettingSource = Literal["user", "project", "local"]
1086| Valor | Descripción | Ubicación |1086| Valor | Descripción | Ubicación |
1087| :- | :- | :- |1087| :- | :- | :- |
1088| `"user"` | Configuración global del usuario | `~/.claude/settings.json` |1088| `"user"` | Configuración global del usuario | `~/.claude/settings.json` |
1089| `"project"` | Configuración del proyecto compartido (controlada por versión) | `.claude/settings.json` |1089| `"project"` | Configuración compartida del proyecto (bajo control de versiones) | `.claude/settings.json` |
1090| `"local"` | Configuración del proyecto local, ignorada en git cuando Claude Code guarda una configuración en ella | `.claude/settings.local.json` |1090| `"local"` | Configuración local del proyecto, ignorada por git cuando Claude Code guarda un ajuste en ella | `.claude/settings.local.json` |
1091 1091
1092<h4 id="default-behavior">1092<h4 id="default-behavior">
1093 Comportamiento predeterminado1093 Comportamiento predeterminado
1094</h4>1094</h4>
1095 1095
1096Cuando `setting_sources` se omite o es `None` y `skills` no está establecido, `query()` carga la misma configuración del sistema de archivos que la CLI de Claude Code: usuario, proyecto y local. Con `skills` establecido, la fila [`setting_sources`](#claudeagentoptions) describe el predeterminado actual. La política administrada por punto final 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](/docs/es/server-managed-settings#platform-availability). Para más información, consulte [Lo que settingSources no controla](/docs/es/agent-sdk/claude-code-features#what-settingsources-does-not-control).1096Cuando `setting_sources` se omite o es `None` y `skills` no está establecido, `query()` carga la misma configuración del sistema de archivos que la CLI de Claude Code: de usuario, de proyecto y local. Con `skills` establecido, la fila [`setting_sources`](#claudeagentoptions) describe el predeterminado actual. La política administrada por endpoint 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](/docs/es/server-managed-settings#platform-availability). Para más información, consulta [Lo que settingSources no controla](/docs/es/agent-sdk/claude-code-features#what-settingsources-does-not-control).
1097 1097
1098<h4 id="why-use-setting_sources">1098<h4 id="why-use-setting_sources">
1099 Por qué usar setting\_sources1099 Por qué usar setting\_sources
1100</h4>1100</h4>
1101 1101
1102**Deshabilitar configuración del sistema de archivos:**1102**Deshabilitar la configuración del sistema de archivos:**
1103 1103
1104```python theme={null}1104```python theme={null}
1105# No cargar configuración de usuario, proyecto o local desde el disco1105# No cargar configuración de usuario, proyecto o local desde el disco
1121```1121```
1122 1122
1123<Note>1123<Note>
1124 En Python SDK 0.1.59 y anterior, una lista vacía se trataba igual que omitir la opción, por lo que `setting_sources=[]` no deshabilitaba la configuración del sistema de archivos. Actualice a una versión más reciente si necesita que una lista vacía tenga efecto. El SDK de TypeScript no se ve afectado.1124 En Python SDK 0.1.59 y anteriores, una lista vacía se trataba igual que omitir la opción, por lo que `setting_sources=[]` no deshabilitaba la configuración del sistema de archivos. Actualiza a una versión más reciente si necesitas que una lista vacía tenga efecto. El SDK de TypeScript no se ve afectado.
1125</Note>1125</Note>
1126 1126
1127**Cargar solo fuentes de configuración específicas:**1127**Cargar solo fuentes de configuración específicas:**
1145asyncio.run(main())1145asyncio.run(main())
1146```1146```
1147 1147
1148**Aplicaciones solo SDK:**1148**Aplicaciones solo con SDK:**
1149 1149
1150```python theme={null}1150```python theme={null}
1151# Definir todo programáticamente.1151# Definir todo programáticamente.
1152# Pase [] para optar por no usar fuentes de configuración del sistema de archivos.1152# Pasa [] para excluir las fuentes de configuración del sistema de archivos.
1153import asyncio1153import asyncio
1154from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, query1154from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, query
1155 1155
1174asyncio.run(main())1174asyncio.run(main())
1175```1175```
1176 1176
1177Para cargar instrucciones del proyecto CLAUDE.md, incluya `"project"` en `setting_sources`. Consulte [Modificar indicadores del sistema](/docs/es/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions) para ver cómo la carga de CLAUDE.md interactúa con las opciones de indicador del sistema.1177Para cargar las instrucciones del proyecto de CLAUDE.md, incluye `"project"` en `setting_sources`. Consulta [Modificar prompts del sistema](/docs/es/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions) para ver cómo interactúa la carga de CLAUDE.md con las opciones del prompt del sistema.
1178 1178
1179<h4 id="settings-precedence">1179<h4 id="settings-precedence">
1180 Precedencia de configuración1180 Precedencia de configuración
1181</h4>1181</h4>
1182 1182
1183Cuando se cargan múltiples fuentes, la configuración se fusiona con esta precedencia (mayor a menor):1183Cuando se cargan varias fuentes, la configuración se fusiona con esta precedencia (de mayor a menor):
1184 1184
11851. Configuración local (`.claude/settings.local.json`)11851. Configuración local (`.claude/settings.local.json`)
11862. Configuración del proyecto (`.claude/settings.json`)11862. Configuración del proyecto (`.claude/settings.json`)
11873. Configuración del usuario (`~/.claude/settings.json`)11873. Configuración del usuario (`~/.claude/settings.json`)
1188 1188
1189Las opciones programáticas como `agents`, `allowed_tools` y `settings` 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.1189Las opciones programáticas como `agents`, `allowed_tools` y `settings` sobrescriben la configuración del sistema de archivos de usuario, de proyecto y local. La configuración de política administrada tiene precedencia sobre las opciones programáticas.
1190 1190
1191<h3 id="agentdefinition">1191<h3 id="agentdefinition">
1192 `AgentDefinition`1192 `AgentDefinition`
1215| Campo | Requerido | Descripción |1215| Campo | Requerido | Descripción |
1216| :- | :- | :- |1216| :- | :- | :- |
1217| `description` | Sí | Descripción en lenguaje natural de cuándo usar este agente |1217| `description` | Sí | Descripción en lenguaje natural de cuándo usar este agente |
1218| `prompt` | Sí | El indicador del sistema del agente |1218| `prompt` | Sí | El prompt del sistema del agente |
1219| `tools` | No | Matriz de nombres de herramientas permitidas. Si se omite, hereda cada [herramienta disponible para subagentes](/docs/es/sub-agents#available-tools) |1219| `tools` | No | Array de nombres de herramientas permitidas. Si se omite, hereda todas las [herramientas disponibles para subagentes](/docs/es/sub-agents#available-tools) |
1220| `disallowedTools` | No | Matriz de nombres de herramientas a eliminar del conjunto de herramientas del agente. También se aceptan patrones a nivel de servidor MCP: `mcp__server` o `mcp__server__*` elimina cada herramienta de ese servidor, y `mcp__*` elimina cada herramienta MCP de cualquier servidor |1220| `disallowedTools` | No | Array de nombres de herramientas que se eliminan del conjunto de herramientas del agente. También se aceptan patrones a nivel de servidor MCP: `mcp__server` o `mcp__server__*` elimina todas las herramientas de ese servidor, y `mcp__*` elimina todas las herramientas MCP de cualquier servidor |
1221| `model` | No | Anulación de modelo para este agente. Acepta un alias como `"sonnet"`, `"opus"`, `"haiku"`, o `"inherit"`, o un ID de modelo completo. Cuando lo omite, Claude Code elige el modelo en el [orden de modelo de subagente](/docs/es/sub-agents#choose-a-model) |1221| `model` | No | Sobrescritura del modelo para este agente. Acepta un alias como `"sonnet"`, `"opus"`, `"haiku"` o `"inherit"`, o un ID de modelo completo. Cuando lo omites, Claude Code elige el modelo según el [orden de modelos de subagentes](/docs/es/sub-agents#choose-a-model) |
1222| `skills` | No | Lista de nombres de skills para precargar en el contexto del agente al inicio. Las skills no listadas siguen siendo invocables a través de la herramienta Skill |1222| `skills` | No | Lista de nombres de skills para precargar en el contexto del agente al inicio. Los skills no listados siguen siendo invocables a través de la herramienta Skill |
1223| `memory` | No | Fuente de memoria para este agente: `"user"`, `"project"`, o `"local"` |1223| `memory` | No | Fuente de memoria para este agente: `"user"`, `"project"` o `"local"` |
1224| `mcpServers` | No | Servidores MCP disponibles para este agente. Cada entrada es un nombre de servidor o un dict `{name: config}` en línea |1224| `mcpServers` | No | Servidores MCP disponibles para este agente. Cada entrada es un nombre de servidor o un dict `{name: config}` en línea |
1225| `initialPrompt` | No | Se envía automáticamente como el primer turno del usuario cuando este agente se ejecuta como el agente del hilo principal |1225| `initialPrompt` | No | Se envía automáticamente como el primer turno del usuario cuando este agente se ejecuta como el agente del hilo principal |
1226| `maxTurns` | No | Número máximo de turnos agentes antes de que el agente se detenga |1226| `maxTurns` | No | Número máximo de turnos agénticos antes de que el agente se detenga |
1227| `background` | No | Ejecutar este agente como una tarea de fondo no bloqueante cuando se invoca |1227| `background` | No | Ejecutar este agente como una tarea en segundo plano no bloqueante cuando se invoca |
1228| `effort` | No | Nivel de esfuerzo de razonamiento para este agente. Acepta un nivel nombrado o un entero. Consulte [`EffortLevel`](#effortlevel) |1228| `effort` | No | Nivel de esfuerzo de razonamiento para este agente. Acepta un nivel con nombre o un entero. Consulta [`EffortLevel`](#effortlevel) |
1229| `permissionMode` | No | Modo de permiso para la ejecución de herramientas dentro de este agente. Las [reglas de herencia de subagentes](/docs/es/agent-sdk/permissions#available-modes) deciden cuándo se aplica. Consulte [`PermissionMode`](#permissionmode) |1229| `permissionMode` | No | Modo de permisos para la ejecución de herramientas dentro de este agente. Las [reglas de herencia de subagentes](/docs/es/agent-sdk/permissions#available-modes) deciden cuándo se aplica. Consulta [`PermissionMode`](#permissionmode) |
1230 1230
1231<Note>1231<Note>
1232 Los nombres de campo `AgentDefinition` utilizan camelCase, como `disallowedTools`, `permissionMode` y `maxTurns`. Estos nombres se asignan directamente al formato de cable compartido con el SDK de TypeScript. Esto difiere de `ClaudeAgentOptions`, que utiliza snake\_case de Python para los campos de nivel superior equivalentes como `disallowed_tools` y `permission_mode`. Debido a que `AgentDefinition` es una dataclass, pasar una palabra clave snake\_case genera un `TypeError` en el tiempo de construcción.1232 Los nombres de campo de `AgentDefinition` usan camelCase, como `disallowedTools`, `permissionMode` y `maxTurns`. Estos nombres corresponden directamente al formato de transmisión compartido con el SDK de TypeScript. Esto difiere de `ClaudeAgentOptions`, que usa snake\_case de Python para los campos de nivel superior equivalentes, como `disallowed_tools` y `permission_mode`. Como `AgentDefinition` es una dataclass, pasar una palabra clave en snake\_case genera un `TypeError` al construirla.
1233</Note>1233</Note>
1234 1234
1235<h3 id="permissionmode">1235<h3 id="permissionmode">
1236 `PermissionMode`1236 `PermissionMode`
1237</h3>1237</h3>
1238 1238
1239Modos de permiso para controlar la ejecución de herramientas.1239Modos de permisos para controlar la ejecución de herramientas.
1240 1240
1241```python theme={null}1241```python theme={null}
1242PermissionMode = Literal[1242PermissionMode = Literal[
1243 "default", # Comportamiento de permiso estándar1243 "default", # Comportamiento de permisos estándar
1244 "acceptEdits", # Aceptar automáticamente ediciones de archivo1244 "acceptEdits", # Aceptar automáticamente ediciones de archivos
1245 "plan", # Modo de planificación - explorar sin editar1245 "plan", # Modo de planificación - explorar sin editar
1246 "dontAsk", # Denegar cualquier cosa no preaprobada en lugar de solicitar1246 "dontAsk", # Denegar todo lo no preaprobado en lugar de pedir confirmación
1247 "bypassPermissions", # Omitir verificaciones de permiso; las reglas de solicitud explícita aún solicitan (usar con cuidado)1247 "bypassPermissions", # Omitir verificaciones de permisos; las reglas ask explícitas siguen pidiendo confirmación (usar con cuidado)
1248 "auto", # El clasificador del modelo aprueba o deniega indicadores de permiso1248 "auto", # Un clasificador de modelo revisa acciones como comandos de shell y solicitudes de red
1249]1249]
1250```1250```
1251 1251
1260 "low", # Pensamiento mínimo, respuestas más rápidas1260 "low", # Pensamiento mínimo, respuestas más rápidas
1261 "medium", # Pensamiento moderado1261 "medium", # Pensamiento moderado
1262 "high", # Razonamiento profundo1262 "high", # Razonamiento profundo
1263 "xhigh", # Razonamiento extendido; vuelve a "high" en modelos que no lo admiten1263 "xhigh", # Razonamiento extendido; recurre a "high" en modelos que no lo admiten
1264 "max", # Esfuerzo máximo1264 "max", # Esfuerzo máximo
1265]1265]
1266```1266```
1269 `CanUseTool`1269 `CanUseTool`
1270</h3>1270</h3>
1271 1271
1272Alias de tipo para funciones de devolución de llamada de permiso de herramienta.1272Alias de tipo para funciones de callback de permisos de herramientas.
1273 1273
1274```python theme={null}1274```python theme={null}
1275CanUseTool = Callable[1275CanUseTool = Callable[
1277]1277]
1278```1278```
1279 1279
1280La devolución de llamada recibe:1280El callback recibe:
1281 1281
1282* `tool_name`: Nombre de la herramienta que se está llamando1282* `tool_name`: Nombre de la herramienta que se está llamando
1283* `input_data`: Los parámetros de entrada de la herramienta1283* `input_data`: Los parámetros de entrada de la herramienta
1285 1285
1286Devuelve un `PermissionResult` (ya sea `PermissionResultAllow` o `PermissionResultDeny`).1286Devuelve un `PermissionResult` (ya sea `PermissionResultAllow` o `PermissionResultDeny`).
1287 1287
1288La devolución de llamada es el reemplazo del SDK para el indicador de permiso interactivo: se invoca solo cuando el [flujo de evaluación de permiso](/docs/es/agent-sdk/permissions#how-permissions-are-evaluated) se resuelve en un indicador. 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, utilice un [hook `PreToolUse`](/docs/es/agent-sdk/hooks) en su lugar.1288El callback es el reemplazo del SDK para la solicitud de permiso interactiva: se invoca solo cuando el [flujo de evaluación de permisos](/docs/es/agent-sdk/permissions#how-permissions-are-evaluated) termina en una solicitud de permiso. Las llamadas a herramientas ya aprobadas por una entrada de `allowed_tools`, una regla allow de la configuración o el modo de permisos, como `acceptEdits` o `bypassPermissions`, nunca lo invocan. Para controlar cada llamada a herramienta, usa en su lugar un [hook `PreToolUse`](/docs/es/agent-sdk/hooks).
1289 1289
1290Una regla de permiso no aprueba previamente las [acciones que ningún modo aprueba automáticamente](/docs/es/permission-modes#actions-no-mode-auto-approves); consulte [Cómo se evalúan los permisos](/docs/es/agent-sdk/permissions#how-permissions-are-evaluated) para ver cuál de ellas llega a la devolución de llamada y qué sucede en modo `dontAsk` y `auto`.1290Una regla allow no aprueba previamente las [acciones que ningún modo aprueba automáticamente](/docs/es/permission-modes#actions-no-mode-auto-approves); consulta [Cómo se evalúan los permisos](/docs/es/agent-sdk/permissions#how-permissions-are-evaluated) para ver cuáles de ellas llegan al callback y qué sucede en los modos `dontAsk` y `auto`.
1291 1291
1292<h3 id="toolpermissioncontext">1292<h3 id="toolpermissioncontext">
1293 `ToolPermissionContext`1293 `ToolPermissionContext`
1294</h3>1294</h3>
1295 1295
1296Información de contexto pasada a devoluciones de llamada de permiso de herramienta.1296Información de contexto que se pasa a los callbacks de permisos de herramientas.
1297 1297
1298```python theme={null}1298```python theme={null}
1299@dataclass1299@dataclass
1311 1311
1312| Campo | Tipo | Descripción |1312| Campo | Tipo | Descripción |
1313| :- | :- | :- |1313| :- | :- | :- |
1314| `signal` | `Any \| None` | Reservado para soporte futuro de señal de aborto |1314| `signal` | `Any \| None` | Reservado para el futuro soporte de señal de aborto |
1315| `suggestions` | `list[PermissionUpdate]` | Sugerencias de actualización de permiso de la CLI. Los indicadores de Bash incluyen una sugerencia con el destino `localSettings`, por lo que devolverla en `updated_permissions` escribe la regla en `.claude/settings.local.json` y persiste entre sesiones. |1315| `suggestions` | `list[PermissionUpdate]` | Sugerencias de actualización de permisos de la CLI. Las solicitudes de permiso de Bash incluyen una sugerencia con el destino `localSettings`, por lo que devolverla en `updated_permissions` escribe la regla en `.claude/settings.local.json` y persiste entre sesiones. |
1316| `tool_use_id` | `str \| None` | Identificador de la llamada de herramienta específica para la que es este indicador. Siempre se completa cuando se entrega a `can_use_tool` |1316| `tool_use_id` | `str \| None` | Identificador de la llamada a herramienta específica a la que corresponde esta solicitud. Siempre se completa cuando se entrega a `can_use_tool` |
1317| `agent_id` | `str \| None` | ID del subagente cuando la llamada se origina desde un subagente; `None` para el agente principal |1317| `agent_id` | `str \| None` | ID del subagente cuando la llamada se origina en un subagente; `None` para el agente principal |
1318| `blocked_path` | `str \| None` | Ruta de archivo que activó la solicitud de permiso, cuando sea aplicable. Por ejemplo, cuando un comando Bash intenta acceder a una ruta fuera de directorios permitidos |1318| `blocked_path` | `str \| None` | Ruta de archivo que activó la solicitud de permiso, cuando corresponda. Por ejemplo, cuando un comando de Bash intenta acceder a una ruta fuera de los directorios permitidos |
1319| `decision_reason` | `str \| None` | Razón por la que se activó esta solicitud de permiso. Reenviado desde el `permissionDecisionReason` de un hook PreToolUse cuando el hook devolvió `"ask"` |1319| `decision_reason` | `str \| None` | Motivo por el que se activó esta solicitud de permiso. Se reenvía desde el `permissionDecisionReason` de un hook PreToolUse cuando el hook devolvió `"ask"` |
1320| `title` | `str \| None` | Oración de indicador de permiso completo, como `Claude wants to read foo.txt`. Utilice como texto de indicador principal cuando esté presente |1320| `title` | `str \| None` | Oración completa de la solicitud de permiso, como `Claude wants to read foo.txt`. Úsala como texto principal de la solicitud cuando esté presente |
1321| `display_name` | `str \| None` | Frase de sustantivo corto para la acción de herramienta, como `Read file`, adecuada para etiquetas de botón |1321| `display_name` | `str \| None` | Frase nominal corta para la acción de la herramienta, como `Read file`, adecuada para etiquetas de botones |
1322| `description` | `str \| None` | Subtítulo legible por humanos para la interfaz de usuario de permiso |1322| `description` | `str \| None` | Subtítulo legible por humanos para la interfaz de permisos |
1323 1323
1324<h3 id="permissionresult">1324<h3 id="permissionresult">
1325 `PermissionResult`1325 `PermissionResult`
1326</h3>1326</h3>
1327 1327
1328Tipo de unión para resultados de devolución de llamada de permiso.1328Tipo de unión para los resultados del callback de permisos.
1329 1329
1330```python theme={null}1330```python theme={null}
1331PermissionResult = PermissionResultAllow | PermissionResultDeny1331PermissionResult = PermissionResultAllow | PermissionResultDeny
1335 `PermissionResultAllow`1335 `PermissionResultAllow`
1336</h3>1336</h3>
1337 1337
1338Resultado indicando que la llamada de herramienta debe permitirse.1338Resultado que indica que la llamada a herramienta debe permitirse.
1339 1339
1340```python theme={null}1340```python theme={null}
1341@dataclass1341@dataclass
1348| Campo | Tipo | Predeterminado | Descripción |1348| Campo | Tipo | Predeterminado | Descripción |
1349| :- | :- | :- | :- |1349| :- | :- | :- | :- |
1350| `behavior` | `Literal["allow"]` | `"allow"` | Debe ser "allow" |1350| `behavior` | `Literal["allow"]` | `"allow"` | Debe ser "allow" |
1351| `updated_input` | `dict[str, Any] \| None` | `None` | Entrada modificada a usar en lugar de la original |1351| `updated_input` | `dict[str, Any] \| None` | `None` | Entrada modificada que se usa en lugar de la original |
1352| `updated_permissions` | `list[PermissionUpdate] \| None` | `None` | Actualizaciones de permiso a aplicar |1352| `updated_permissions` | `list[PermissionUpdate] \| None` | `None` | Actualizaciones de permisos que se aplican |
1353 1353
1354<h3 id="permissionresultdeny">1354<h3 id="permissionresultdeny">
1355 `PermissionResultDeny`1355 `PermissionResultDeny`
1356</h3>1356</h3>
1357 1357
1358Resultado indicando que la llamada de herramienta debe denegarse.1358Resultado que indica que la llamada a herramienta debe denegarse.
1359 1359
1360```python theme={null}1360```python theme={null}
1361@dataclass1361@dataclass
1368| Campo | Tipo | Predeterminado | Descripción |1368| Campo | Tipo | Predeterminado | Descripción |
1369| :- | :- | :- | :- |1369| :- | :- | :- | :- |
1370| `behavior` | `Literal["deny"]` | `"deny"` | Debe ser "deny" |1370| `behavior` | `Literal["deny"]` | `"deny"` | Debe ser "deny" |
1371| `message` | `str` | `""` | Mensaje explicando por qué se denegó la herramienta |1371| `message` | `str` | `""` | Mensaje que explica por qué se denegó la herramienta |
1372| `interrupt` | `bool` | `False` | Si se debe interrumpir la ejecución actual |1372| `interrupt` | `bool` | `False` | Si se debe interrumpir la ejecución actual |
1373 1373
1374<h3 id="permissionupdate">1374<h3 id="permissionupdate">
1399 1399
1400| Campo | Tipo | Descripción |1400| Campo | Tipo | Descripción |
1401| :- | :- | :- |1401| :- | :- | :- |
1402| `type` | `Literal[...]` | El tipo de operación de actualización de permiso |1402| `type` | `Literal[...]` | El tipo de operación de actualización de permisos |
1403| `rules` | `list[PermissionRuleValue] \| None` | Reglas para operaciones de agregar/reemplazar/eliminar |1403| `rules` | `list[PermissionRuleValue] \| None` | Reglas para operaciones de agregar/reemplazar/eliminar |
1404| `behavior` | `Literal["allow", "deny", "ask"] \| None` | Comportamiento para operaciones basadas en reglas |1404| `behavior` | `Literal["allow", "deny", "ask"] \| None` | Comportamiento para operaciones basadas en reglas |
1405| `mode` | `PermissionMode \| None` | Modo para operación setMode |1405| `mode` | `PermissionMode \| None` | Modo para la operación setMode |
1406| `directories` | `list[str] \| None` | Directorios para operaciones de agregar/eliminar directorio |1406| `directories` | `list[str] \| None` | Directorios para operaciones de agregar/eliminar directorios |
1407| `destination` | `Literal[...] \| None` | Dónde aplicar la actualización de permiso |1407| `destination` | `Literal[...] \| None` | Dónde aplicar la actualización de permisos |
1408 1408
1409<h3 id="permissionrulevalue">1409<h3 id="permissionrulevalue">
1410 `PermissionRuleValue`1410 `PermissionRuleValue`
1411</h3>1411</h3>
1412 1412
1413Una regla a agregar, reemplazar o eliminar en una actualización de permiso.1413Una regla para agregar, reemplazar o eliminar en una actualización de permisos.
1414 1414
1415```python theme={null}1415```python theme={null}
1416@dataclass1416@dataclass
1423 `ToolsPreset`1423 `ToolsPreset`
1424</h3>1424</h3>
1425 1425
1426Configuración de herramientas preestablecidas para usar el conjunto de herramientas predeterminado de Claude Code.1426Configuración de herramientas preestablecida para usar el conjunto de herramientas predeterminado de Claude Code.
1427 1427
1428```python theme={null}1428```python theme={null}
1429class ToolsPreset(TypedDict):1429class ToolsPreset(TypedDict):
1461 1461
1462| Variante | Campos | Descripción |1462| Variante | Campos | Descripción |
1463| :- | :- | :- |1463| :- | :- | :- |
1464| `adaptive` | `type`, `display` | Claude decide adaptativamente cuándo pensar |1464| `adaptive` | `type`, `display` | Claude decide de forma adaptativa cuándo pensar |
1465| `enabled` | `type`, `budget_tokens`, `display` | Habilitar pensamiento con un presupuesto de token específico |1465| `enabled` | `type`, `budget_tokens`, `display` | Habilitar el pensamiento con un presupuesto de tokens específico |
1466| `disabled` | `type` | Deshabilitar pensamiento |1466| `disabled` | `type` | Deshabilitar el pensamiento |
1467 1467
1468El campo `display` opcional controla si el texto de pensamiento se devuelve `"summarized"` u `"omitted"`. En Claude Opus 4.7 y posterior, el predeterminado de API es `"omitted"`, por lo que establezca `"summarized"` para recibir contenido de pensamiento en salidas [`ThinkingBlock`](#thinkingblock). Claude Code no envía `display` a Amazon Bedrock ni a la Plataforma de Agentes de Google Cloud, por lo que en esos proveedores Opus 4.7 y posterior devuelven salidas `ThinkingBlock` vacías incluso cuando establece `display` en `"summarized"`.1468El campo opcional `display` controla si el texto del pensamiento se devuelve `"summarized"` u `"omitted"`. En Claude Opus 4.7 y posteriores, el predeterminado de la API es `"omitted"`, así que establece `"summarized"` para recibir el contenido del pensamiento en las salidas [`ThinkingBlock`](#thinkingblock). Claude Code no incluye `display` en las solicitudes a algunos proveedores, como Amazon Bedrock y Agent Platform de Google Cloud. En esos proveedores, Opus 4.7 y posteriores devuelven salidas `ThinkingBlock` vacías incluso cuando estableces `display` en `"summarized"`.
1469 1469
1470Debido a que estas son clases `TypedDict`, son dicts simples en tiempo de ejecución. Construyalas como literales de dict o llame a la clase como un constructor; ambos producen un `dict`. Acceda a los campos con `config["budget_tokens"]`, no `config.budget_tokens`:1470Como estas son clases `TypedDict`, son dicts simples en tiempo de ejecución. Puedes construirlas como literales de dict o llamar a la clase como un constructor; ambas formas producen un `dict`. Accede a los campos con `config["budget_tokens"]`, no con `config.budget_tokens`:
1471 1471
1472```python theme={null}1472```python theme={null}
1473from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled1473from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled
1485 `TaskBudget`1485 `TaskBudget`
1486</h3>1486</h3>
1487 1487
1488Presupuesto de tarea del lado de la API en tokens, utilizado con el campo `task_budget` en `ClaudeAgentOptions`.1488Presupuesto de tarea del lado de la API en tokens, que se usa con el campo `task_budget` de `ClaudeAgentOptions`.
1489 1489
1490```python theme={null}1490```python theme={null}
1491class TaskBudget(TypedDict):1491class TaskBudget(TypedDict):
1494 1494
1495| Campo | Tipo | Descripción |1495| Campo | Tipo | Descripción |
1496| :- | :- | :- |1496| :- | :- | :- |
1497| `total` | `int` | Presupuesto de token total para la tarea |1497| `total` | `int` | Presupuesto total de tokens para la tarea |
1498 1498
1499Debido a que esto es un `TypedDict`, páselo como un dict simple, como `ClaudeAgentOptions(task_budget={"total": 50000})`.1499Como es un `TypedDict`, pásalo como un dict simple, por ejemplo `ClaudeAgentOptions(task_budget={"total": 50000})`.
1500 1500
1501<h3 id="sdkbeta">1501<h3 id="sdkbeta">
1502 `SdkBeta`1502 `SdkBeta`
1503</h3>1503</h3>
1504 1504
1505Tipo literal para características beta del SDK.1505Tipo literal para las características beta del SDK.
1506 1506
1507```python theme={null}1507```python theme={null}
1508SdkBeta = Literal["context-1m-2025-08-07"]1508SdkBeta = Literal["context-1m-2025-08-07"]
1509```1509```
1510 1510
1511Utilice con el campo `betas` en `ClaudeAgentOptions` para habilitar características beta.1511Úsalo con el campo `betas` de `ClaudeAgentOptions` para habilitar características beta.
1512 1512
1513<Warning>1513<Warning>
1514 En la Claude API, la beta `context-1m-2025-08-07` está retirada para Claude Sonnet 4.5 y Claude Sonnet 4. Si todavía la pasas con cualquiera de esos modelos, las solicitudes que superan la ventana de contexto estándar de 200K tokens devuelven un error, así que elimínala de `betas`. Para ejecutar una sesión con una ventana de contexto de 1M tokens, establece `model` en un modelo que [se ejecute con la ventana de 1M de forma predeterminada](/docs/es/model-config#extended-context), como `claude-sonnet-5-5` o `claude-opus-5-5`. Para un modelo que alcanza 1M solo mediante su variante `[1m]`, agrega el sufijo al ID del modelo, como en `claude-opus-4-6[1m]`.1514 En la Claude API, la beta `context-1m-2025-08-07` está retirada para Claude Sonnet 4.5 y Claude Sonnet 4. Si todavía la pasas con cualquiera de esos modelos, las solicitudes que superan la ventana de contexto estándar de 200K tokens devuelven un error, así que elimínala de `betas`. Para ejecutar una sesión con una ventana de contexto de 1M tokens, establece `model` en un modelo que [se ejecute con la ventana de 1M de forma predeterminada](/docs/es/model-config#extended-context), como `claude-sonnet-5-5` o `claude-opus-5-5`. Para un modelo que alcanza 1M solo mediante su variante `[1m]`, agrega el sufijo al ID del modelo, como en `claude-opus-4-6[1m]`.
1531 `McpServerConfig`1531 `McpServerConfig`
1532</h3>1532</h3>
1533 1533
1534Tipo de unión para configuraciones de servidor MCP.1534Tipo de unión para configuraciones de servidores MCP.
1535 1535
1536```python theme={null}1536```python theme={null}
1537McpServerConfig = (1537McpServerConfig = (
1545 1545
1546```python theme={null}1546```python theme={null}
1547class McpStdioServerConfig(TypedDict):1547class McpStdioServerConfig(TypedDict):
1548 type: NotRequired[Literal["stdio"]] # Opcional para compatibilidad hacia atrás1548 type: NotRequired[Literal["stdio"]] # Opcional para compatibilidad con versiones anteriores
1549 command: str1549 command: str
1550 args: NotRequired[list[str]]1550 args: NotRequired[list[str]]
1551 env: NotRequired[dict[str, str]]1551 env: NotRequired[dict[str, str]]
1577 `McpServerStatusConfig`1577 `McpServerStatusConfig`
1578</h3>1578</h3>
1579 1579
1580La configuración de un servidor MCP tal como se informa mediante [`get_mcp_status()`](#methods). Esta es la unión de todas las variantes de transporte [`McpServerConfig`](#mcpserverconfig) más una variante de solo salida `claudeai-proxy` para servidores proxificados a través de claude.ai.1580La configuración de un servidor MCP tal como la informa [`get_mcp_status()`](#methods). Es la unión de todas las variantes de transporte de [`McpServerConfig`](#mcpserverconfig) más una variante `claudeai-proxy` de solo salida para servidores que pasan por proxy a través de claude.ai.
1581 1581
1582```python theme={null}1582```python theme={null}
1583McpServerStatusConfig = (1583McpServerStatusConfig = (
1589)1589)
1590```1590```
1591 1591
1592`McpSdkServerConfigStatus` es la forma serializable de [`McpSdkServerConfig`](#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`).1592`McpSdkServerConfigStatus` es la forma serializable de [`McpSdkServerConfig`](#mcpsdkserverconfig) con solo los campos `type` (`"sdk"`) y `name` (`str`); se omite la `instance` en proceso. `McpClaudeAIProxyServerConfig` tiene los campos `type` (`"claudeai-proxy"`), `url` (`str`) e `id` (`str`).
1593 1593
1594<h3 id="mcpstatusresponse">1594<h3 id="mcpstatusresponse">
1595 `McpStatusResponse`1595 `McpStatusResponse`
1596</h3>1596</h3>
1597 1597
1598Respuesta de [`ClaudeSDKClient.get_mcp_status()`](#methods). Envuelve la lista de estados del servidor bajo la clave `mcpServers`.1598Respuesta de [`ClaudeSDKClient.get_mcp_status()`](#methods). Envuelve la lista de estados de servidores bajo la clave `mcpServers`.
1599 1599
1600```python theme={null}1600```python theme={null}
1601class McpStatusResponse(TypedDict):1601class McpStatusResponse(TypedDict):
1622| Campo | Tipo | Descripción |1622| Campo | Tipo | Descripción |
1623| :- | :- | :- |1623| :- | :- | :- |
1624| `name` | `str` | Nombre del servidor |1624| `name` | `str` | Nombre del servidor |
1625| `status` | `str` | Uno de `"connected"`, `"failed"`, `"needs-auth"`, `"pending"`, o `"disabled"` |1625| `status` | `str` | Uno de `"connected"`, `"failed"`, `"needs-auth"`, `"pending"` o `"disabled"` |
1626| `serverInfo` | `dict` (opcional) | Nombre y versión del servidor (`{"name": str, "version": str}`) |1626| `serverInfo` | `dict` (opcional) | Nombre y versión del servidor (`{"name": str, "version": str}`) |
1627| `error` | `str` (opcional) | Mensaje de error si el servidor no se conectó |1627| `error` | `str` (opcional) | Mensaje de error si el servidor no pudo conectarse |
1628| `config` | [`McpServerStatusConfig`](#mcpserverstatusconfig) (opcional) | Configuración del servidor. Misma forma que [`McpServerConfig`](#mcpserverconfig) (stdio, SSE, HTTP, o SDK), más una variante `claudeai-proxy` para servidores conectados a través de claude.ai |1628| `config` | [`McpServerStatusConfig`](#mcpserverstatusconfig) (opcional) | Configuración del servidor. Misma forma que [`McpServerConfig`](#mcpserverconfig) (stdio, SSE, HTTP o SDK), más una variante `claudeai-proxy` para servidores conectados a través de claude.ai |
1629| `scope` | `str` (opcional) | Alcance de configuración |1629| `scope` | `str` (opcional) | Alcance de la configuración |
1630| `tools` | `list` (opcional) | Herramientas proporcionadas por este servidor, cada una con campos `name`, `description`, y `annotations` |1630| `tools` | `list` (opcional) | Herramientas proporcionadas por este servidor, cada una con los campos `name`, `description` y `annotations` |
1631 1631
1632<h3 id="contextusageresponse">1632<h3 id="contextusageresponse">
1633 `ContextUsageResponse`1633 `ContextUsageResponse`
1634</h3>1634</h3>
1635 1635
1636Respuesta de [`ClaudeSDKClient.get_context_usage()`](#methods). Este es el mismo payload que Claude Code renderiza para el comando `/context` en una sesión interactiva, por lo que junto con los conteos de tokens lleva campos de visualización como `color` y `gridRows` que Claude Code utiliza para dibujar la cuadrícula de uso de `/context`.1636Respuesta de [`ClaudeSDKClient.get_context_usage()`](#methods). Es el mismo payload que Claude Code renderiza para el comando `/context` en una sesión interactiva, por lo que, junto con los recuentos de tokens, incluye campos de visualización como `color` y `gridRows` que Claude Code usa para dibujar la cuadrícula de uso de `/context`.
1637 1637
1638Claude Code construye este payload enviando varias solicitudes a la API de [conteo de tokens](https://platform.claude.com/docs/en/build-with-claude/token-counting). Estas solicitudes no aparecen en el flujo de mensajes, por lo que el seguimiento de costos que lee el flujo no las verá. En la API de Anthropic, el conteo de tokens no se factura.1638Claude Code construye este payload enviando varias solicitudes a la API de [conteo de tokens](https://platform.claude.com/docs/en/build-with-claude/token-counting). Estas solicitudes no aparecen en el stream de mensajes, por lo que el seguimiento de costos que lee el stream no las verá. En la API de Anthropic, el conteo de tokens no se factura.
1639 1639
1640```python theme={null}1640```python theme={null}
1641class ContextUsageResponse(TypedDict):1641class ContextUsageResponse(TypedDict):
1660 apiUsage: NotRequired[dict[str, Any] | None]1660 apiUsage: NotRequired[dict[str, Any] | None]
1661```1661```
1662 1662
1663Cada entrada `ContextUsageCategory` lleva `name`, `tokens`, `color`, y una bandera `isDeferred` opcional. `totalTokens` es el uso de contexto actual de la sesión, y `maxTokens` es la ventana contra la que se mide el uso. Esa ventana es la ventana de contexto del modelo, o la ventana de compactación automática más baja cuando se aplica una, y `rawMaxTokens` lleva el mismo valor que `maxTokens`. `apiUsage` contiene el uso de la respuesta de API más reciente, no un total acumulado para la sesión. Claude Code deja sin establecer las claves opcionales `deferredBuiltinTools`, `systemTools` y `systemPromptSections`, por lo que espere que estén ausentes incluso aunque el tipo las declare.1663Cada entrada de `ContextUsageCategory` incluye `name`, `tokens`, `color` y un flag opcional `isDeferred`. `totalTokens` es el uso de contexto actual de la sesión, y `maxTokens` es la ventana con la que se mide ese uso. Esa ventana es la ventana de contexto del modelo, o la ventana de compactación automática más baja cuando corresponde, y `rawMaxTokens` contiene el mismo valor que `maxTokens`. `apiUsage` contiene el uso de la respuesta de API más reciente, no un total acumulado de la sesión. Claude Code deja sin establecer las claves opcionales `deferredBuiltinTools`, `systemTools` y `systemPromptSections`, así que espera que estén ausentes aunque el tipo las declare.
1664 1664
1665<h3 id="sdkpluginconfig">1665<h3 id="sdkpluginconfig">
1666 `SdkPluginConfig`1666 `SdkPluginConfig`
1688]1688]
1689```1689```
1690 1690
1691Para información completa sobre cómo crear y usar plugins, consulte [Plugins](/docs/es/agent-sdk/plugins).1691Para obtener información completa sobre cómo crear y usar plugins, consulta [Plugins](/docs/es/agent-sdk/plugins).
1692 1692
1693<h2 id="message-types">1693<h2 id="message-types">
1694 Tipos de mensaje1694 Tipos de mensaje
1736| `tool_use_result` | `dict[str, Any] \| None` | Datos de resultado de herramienta si es aplicable |1736| `tool_use_result` | `dict[str, Any] \| None` | Datos de resultado de herramienta si es aplicable |
1737| `origin` | `MessageOrigin \| None` | Procedencia de este mensaje, rellenado en turnos inyectados como notificaciones de tareas y mensajes de pares. `None` cuando la CLI no lo atribuyó. Requiere Python Agent SDK 0.2.137 o posterior |1737| `origin` | `MessageOrigin \| None` | Procedencia de este mensaje, rellenado en turnos inyectados como notificaciones de tareas y mensajes de pares. `None` cuando la CLI no lo atribuyó. Requiere Python Agent SDK 0.2.137 o posterior |
1738 1738
1739El 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`](/docs/es/agent-sdk/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.1739El 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`](/docs/es/agent-sdk/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, lee `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.
1740 1740
1741La 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()`](#tool) nunca produce la clave, porque el SDK aplana sus bloques `resource_link` a texto antes de que la CLI vea el resultado.1741La 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 defines en proceso con [`tool()`](#tool) nunca produce la clave, porque el SDK aplana sus bloques `resource_link` a texto antes de que la CLI vea el resultado.
1742 1742
1743<h3 id="assistantmessage">1743<h3 id="assistantmessage">
1744 `AssistantMessage`1744 `AssistantMessage`
1789]1789]
1790```1790```
1791 1791
1792El 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`](/docs/es/agent-sdk/typescript#sdkassistantmessage) enumera el conjunto completo de valores que la CLI puede emitir.1792El 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 trata las cadenas fuera de esta lista de la misma manera en que tratas `unknown`. El tipo TypeScript [`SDKAssistantMessageError`](/docs/es/agent-sdk/typescript#sdkassistantmessage) enumera el conjunto completo de valores que la CLI puede emitir.
1793 1793
1794<h3 id="systemmessage">1794<h3 id="systemmessage">
1795 `SystemMessage`1795 `SystemMessage`
1842 1842
1843* `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.1843* `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.
1844* `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"`.1844* `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"`.
1845* `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.1845* `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 verifica `api_error_status` y el contenido anterior de `AssistantMessage` para obtener detalles.
1846* `errors`: cadenas de error a nivel de bucle como el mensaje de máx-turnos. Se rellena solo en los subtipos `error_*`.1846* `errors`: cadenas de error a nivel de bucle como el mensaje de máx-turnos. Se rellena solo en los subtipos `error_*`.
1847* `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()`](#claudesdkclient) y una devolución de llamada de permiso que devuelve [`PermissionResultDeny`](#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`](/docs/es/agent-sdk/typescript#sdkresultmessage) del SDK de TypeScript, que enumera el conjunto completo de valores.1847* `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()`](#claudesdkclient) y una devolución de llamada de permiso que devuelve [`PermissionResultDeny`](#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`](/docs/es/agent-sdk/typescript#sdkresultmessage) del SDK de TypeScript, que enumera el conjunto completo de valores.
1848* `origin`: origen del mensaje del usuario que activó este turno. En [modo de entrada de streaming](/docs/es/agent-sdk/streaming-vs-single-mode), 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.1848* `origin`: origen del mensaje del usuario que activó este turno. En [modo de entrada de streaming](/docs/es/agent-sdk/streaming-vs-single-mode), verifica esto para distinguir el resultado de tu propio prompt, donde `origin` es `None` o `{"kind": "human"}`, del resultado de un turno inyectado como una notificación de tarea en segundo plano. Requiere Python Agent SDK 0.2.137 o posterior.
1849 1849
1850El 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](/docs/es/agent-sdk/streaming-vs-single-mode), los valores son por turno. Prefiera `model_usage` para contabilidad de token y costo. El dict `usage` contiene las siguientes claves cuando está presente:1850El 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](/docs/es/agent-sdk/streaming-vs-single-mode), los valores son por turno. Prefiere `model_usage` para contabilidad de token y costo. El dict `usage` contiene las siguientes claves cuando está presente:
1851 1851
1852| Clave | Tipo | Descripción |1852| Clave | Tipo | Descripción |
1853| - | - | - |1853| - | - | - |
1854| `input_tokens` | `int` | Tokens de entrada consumidos por el bucle del agente de nivel superior. [Los tokens de subagentes no se incluyen](/docs/es/agent-sdk/cost-tracking#get-the-total-cost-of-a-query); use `model_usage` para contabilidad de árbol completo. |1854| `input_tokens` | `int` | Tokens de entrada consumidos por el bucle del agente de nivel superior. [Los tokens de subagentes no se incluyen](/docs/es/agent-sdk/cost-tracking#get-the-total-cost-of-a-query); usa `model_usage` para contabilidad de árbol completo. |
1855| `output_tokens` | `int` | Tokens de salida generados por el bucle del agente de nivel superior. Los tokens de subagentes no se incluyen. |1855| `output_tokens` | `int` | Tokens de salida generados por el bucle del agente de nivel superior. Los tokens de subagentes no se incluyen. |
1856| `cache_creation_input_tokens` | `int` | Tokens usados para crear nuevas entradas de caché. |1856| `cache_creation_input_tokens` | `int` | Tokens usados para crear nuevas entradas de caché. |
1857| `cache_read_input_tokens` | `int` | Tokens leídos de entradas de caché existentes. |1857| `cache_read_input_tokens` | `int` | Tokens leídos de entradas de caché existentes. |
1858 1858
1859El 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.1859El 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`. Trata `model_usage` como una estimación, no como un estado de facturación.
1860 1860
1861En [modo de entrada de streaming](/docs/es/agent-sdk/streaming-vs-single-mode), `model_usage` y `total_cost_usd` son acumulativos entre turnos, así que lea el resultado más reciente en lugar de sumar entre resultados. Una llamada que reanuda una sesión también cuenta los [totales restaurados de las llamadas anteriores de la sesión](/docs/es/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls). Vea [Rastrear costos en modo de entrada de streaming](/docs/es/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode) para reiniciaciones y [Recuperar totales después de un bloqueo de sesión](/docs/es/agent-sdk/cost-tracking#recover-totals-after-a-session-crash) para resultados puestos a cero.1861En [modo de entrada de streaming](/docs/es/agent-sdk/streaming-vs-single-mode), `model_usage` y `total_cost_usd` son acumulativos entre turnos, así que lee el resultado más reciente en lugar de sumar entre resultados. Una llamada que reanuda una sesión también cuenta los [totales restaurados de las llamadas anteriores de la sesión](/docs/es/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls). Consulta [Rastrear costos en modo de entrada de streaming](/docs/es/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode) para reiniciaciones y [Recuperar totales después de un bloqueo de sesión](/docs/es/agent-sdk/cost-tracking#recover-totals-after-a-session-crash) para resultados puestos a cero.
1862 1862
1863Cada 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`](/docs/es/agent-sdk/typescript#modelusage):1863Cada 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`](/docs/es/agent-sdk/typescript#modelusage):
1864 1864
1869| `cacheReadInputTokens` | `int` | Tokens de lectura de caché para este modelo. |1869| `cacheReadInputTokens` | `int` | Tokens de lectura de caché para este modelo. |
1870| `cacheCreationInputTokens` | `int` | Tokens de creación de caché para este modelo. |1870| `cacheCreationInputTokens` | `int` | Tokens de creación de caché para este modelo. |
1871| `webSearchRequests` | `int` | Solicitudes de búsqueda web realizadas por este modelo. |1871| `webSearchRequests` | `int` | Solicitudes de búsqueda web realizadas por este modelo. |
1872| `thinkingTokens` | `int` | Tokens de pensamiento generados por este modelo, ya contados en `outputTokens`. Ausente hasta que un turno se ejecute en una versión de Claude Code que lo registre, y no declarado en el TypedDict, así que léalo con `.get()`. Requiere Python Agent SDK 0.2.150 o posterior, cuya CLI incluida lo registra. |1872| `thinkingTokens` | `int` | Tokens de pensamiento generados por este modelo, ya contados en `outputTokens`. Ausente hasta que un turno se ejecute en una versión de Claude Code que lo registre, y no declarado en el TypedDict, así que léelo con `.get()`. Requiere Python Agent SDK 0.2.150 o posterior, cuya CLI incluida lo registra. |
1873| `costUSD` | `float` | Costo estimado en USD para este modelo, calculado del lado del cliente. Vea [Rastrear costo y uso](/docs/es/agent-sdk/cost-tracking) para advertencias de facturación. |1873| `costUSD` | `float` | Costo estimado en USD para este modelo, calculado del lado del cliente. Consulta [Rastrear costo y uso](/docs/es/agent-sdk/cost-tracking) para advertencias de facturación. |
1874| `contextWindow` | `int` | Tamaño de ventana de contexto para este modelo. |1874| `contextWindow` | `int` | Tamaño de ventana de contexto para este modelo. |
1875| `maxOutputTokens` | `int` | Límite de token de salida máximo para este modelo. |1875| `maxOutputTokens` | `int` | Límite de token de salida máximo para este modelo. |
1876| `canonicalModel` | `str` | ID de modelo canónico utilizado para la búsqueda de precios. Puede diferir de la cadena de modelo sin procesar por la que se indexa la entrada, como un ID específico del proveedor o un alias. No siempre presente. |1876| `canonicalModel` | `str` | ID de modelo canónico utilizado para la búsqueda de precios. Puede diferir de la cadena de modelo sin procesar por la que se indexa la entrada, como un ID específico del proveedor o un alias. No siempre presente. |
1877| `provider` | `str` | Proveedor de API que sirvió este modelo, como `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle`, o `gateway`. No siempre presente. |1877| `provider` | `str` | Proveedor de API que sirvió este modelo, como `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle`, o `gateway`. No siempre presente. |
1878| `costBasis` | `str` | Tabla de precios con la que se calculó el precio de la solicitud más reciente de este modelo: `list` para el precio de lista, `managed` para una tabla [`modelPricing`](/docs/es/settings-reference#modelpricing), o `unknown` cuando ninguna coincidió con el ID del modelo. No siempre presente, y no declarado en el TypedDict, así que léelo con `.get()`. Requiere Claude Code v2.1.246 o posterior. |
1878 1879
1879<h3 id="streamevent">1880<h3 id="streamevent">
1880 `StreamEvent`1881 `StreamEvent`
1881</h3>1882</h3>
1882 1883
1883Evento 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`.1884Evento de streaming 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`.
1884 1885
1885```python theme={null}1886```python theme={null}
1886@dataclass1887@dataclass
1895| :- | :- | :- |1896| :- | :- | :- |
1896| `uuid` | `str` | Identificador único para este evento |1897| `uuid` | `str` | Identificador único para este evento |
1897| `session_id` | `str` | Identificador de sesión |1898| `session_id` | `str` | Identificador de sesión |
1898| `event` | `dict[str, Any]` | Los datos del evento de flujo de API de Claude sin procesar |1899| `event` | `dict[str, Any]` | Los datos del evento de streaming de API de Claude sin procesar |
1899| `parent_tool_use_id` | `str \| None` | Siempre `None`. Los eventos de flujo se emiten solo para la sesión principal. Para la atribución de subagentes, use mensajes completos como [`AssistantMessage`](#assistantmessage) |1900| `parent_tool_use_id` | `str \| None` | Siempre `None`. Los eventos de streaming se emiten solo para la sesión principal. Para la atribución de subagentes, usa mensajes completos como [`AssistantMessage`](#assistantmessage) |
1900 1901
1901<h3 id="ratelimitevent">1902<h3 id="ratelimitevent">
1902 `RateLimitEvent`1903 `RateLimitEvent`
1903</h3>1904</h3>
1904 1905
1905Emitido 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"`.1906Emitido cuando el estado del rate limit cambia (por ejemplo, de `"allowed"` a `"allowed_warning"`). Usa esto para advertir a los usuarios antes de que alcancen un límite duro, o para retroceder cuando el estado es `"rejected"`.
1906 1907
1907```python theme={null}1908```python theme={null}
1908@dataclass1909@dataclass
1914 1915
1915| Campo | Tipo | Descripción |1916| Campo | Tipo | Descripción |
1916| :- | :- | :- |1917| :- | :- | :- |
1917| `rate_limit_info` | [`RateLimitInfo`](#ratelimitinfo) | Estado actual del límite de velocidad |1918| `rate_limit_info` | [`RateLimitInfo`](#ratelimitinfo) | Estado actual del rate limit |
1918| `uuid` | `str` | Identificador único del evento |1919| `uuid` | `str` | Identificador único del evento |
1919| `session_id` | `str` | Identificador de sesión |1920| `session_id` | `str` | Identificador de sesión |
1920 1921
1922 `RateLimitInfo`1923 `RateLimitInfo`
1923</h3>1924</h3>
1924 1925
1925Estado del límite de velocidad llevado por [`RateLimitEvent`](#ratelimitevent).1926Estado del rate limit llevado por [`RateLimitEvent`](#ratelimitevent).
1926 1927
1927```python theme={null}1928```python theme={null}
1928RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]1929RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]
1945 1946
1946| Campo | Tipo | Descripción |1947| Campo | Tipo | Descripción |
1947| :- | :- | :- |1948| :- | :- | :- |
1948| `status` | `RateLimitStatus` | Estado actual. `"allowed_warning"` significa acercarse al límite; `"rejected"` significa que se alcanzó el límite |1949| `status` | `RateLimitStatus` | Estado actual, uno de `"allowed"`, `"allowed_warning"` o `"rejected"`. `"allowed_warning"` significa acercarse al límite; `"rejected"` significa que se alcanzó el límite |
1949| `resets_at` | `int \| None` | Marca de tiempo Unix cuando se reinicia la ventana del límite de velocidad |1950| `resets_at` | `int \| None` | Marca de tiempo Unix cuando se reinicia la ventana del rate limit |
1950| `rate_limit_type` | `RateLimitType \| None` | Qué ventana de límite de velocidad se aplica |1951| `rate_limit_type` | `RateLimitType \| None` | Qué ventana de rate limit se aplica |
1951| `utilization` | `float \| None` | Fracción del límite de velocidad consumido (0.0 a 1.0) |1952| `utilization` | `float \| None` | Fracción del rate limit consumida (0.0 a 1.0) |
1952| `overage_status` | `RateLimitStatus \| None` | Estado del uso de exceso de pago por uso, si es aplicable |1953| `overage_status` | `RateLimitStatus \| None` | Estado del uso de exceso de pago por uso, si es aplicable |
1953| `overage_resets_at` | `int \| None` | Marca de tiempo Unix cuando se reinicia la ventana de exceso |1954| `overage_resets_at` | `int \| None` | Marca de tiempo Unix cuando se reinicia la ventana de exceso |
1954| `overage_disabled_reason` | `str \| None` | Por qué el exceso no está disponible, si el estado es `"rejected"` |1955| `overage_disabled_reason` | `str \| None` | Por qué el exceso no está disponible, si el estado es `"rejected"` |
1955| `raw` | `dict[str, Any]` | Dict sin procesar completo del CLI, incluyendo campos no modelados arriba |1956| `raw` | `dict[str, Any]` | Dict sin procesar completo de la CLI, incluyendo campos no modelados arriba |
1956 1957
1957<h3 id="conversationresetmessage">1958<h3 id="conversationresetmessage">
1958 `ConversationResetMessage`1959 `ConversationResetMessage`
1959</h3>1960</h3>
1960 1961
1961Emitido 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](/docs/es/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode) para cómo un reinicio afecta los totales en ejecución en objetos `ResultMessage` posteriores. Requiere Python Agent SDK 0.2.137 o posterior.1962Emitido cuando la conversación se reemplaza sin terminar la conexión, como después de `/clear`. Consulta [Rastrear costos en modo de entrada de streaming](/docs/es/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode) para ver cómo un reinicio afecta los totales en ejecución en objetos `ResultMessage` posteriores. Requiere Python Agent SDK 0.2.137 o posterior.
1962 1963
1963```python theme={null}1964```python theme={null}
1964@dataclass1965@dataclass
1970 1971
1971| Campo | Tipo | Descripción |1972| Campo | Tipo | Descripción |
1972| :- | :- | :- |1973| :- | :- | :- |
1973| `new_conversation_id` | `str` | Identificador opaco para la conversación nueva. No es el `session_id` de mensajes posteriores; lea eso del siguiente mensaje |1974| `new_conversation_id` | `str` | Identificador opaco para la conversación nueva. No es el `session_id` de mensajes posteriores; léelo del siguiente mensaje |
1974| `uuid` | `str` | Identificador único del mensaje |1975| `uuid` | `str` | Identificador único del mensaje |
1975| `session_id` | `str` | ID de la sesión que fue reiniciada. Los mensajes después del reinicio llevan un nuevo `session_id` |1976| `session_id` | `str` | ID de la sesión que fue reiniciada. Los mensajes después del reinicio llevan un nuevo `session_id` |
1976 1977
1978 `TaskStartedMessage`1979 `TaskStartedMessage`
1979</h3>1980</h3>
1980 1981
1981Emitido 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](#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`.1982Emitido cuando comienza una tarea en segundo plano. Una tarea en segundo plano es cualquier cosa rastreada fuera del turno principal: un comando Bash en segundo plano, una vigilancia de [Monitor](#monitor), un subagente generado a través de la herramienta Agent, o un agente remoto. El campo `task_type` te indica cuál. Este nombre no está relacionado con el cambio de nombre de herramienta `Task`-a-`Agent`.
1982 1983
1983```python theme={null}1984```python theme={null}
1984@dataclass1985@dataclass
1998| `uuid` | `str` | Identificador único del mensaje |1999| `uuid` | `str` | Identificador único del mensaje |
1999| `session_id` | `str` | Identificador de sesión |2000| `session_id` | `str` | Identificador de sesión |
2000| `tool_use_id` | `str \| None` | ID de uso de herramienta asociado |2001| `tool_use_id` | `str \| None` | ID de uso de herramienta asociado |
2001| `task_type` | `str \| None` | Qué tipo de tarea de fondo: `"local_bash"` para Bash de fondo y relojes de Monitor, `"local_agent"`, o `"remote_agent"` |2002| `task_type` | `str \| None` | Qué tipo de tarea en segundo plano: `"local_bash"` para Bash en segundo plano y vigilancias de Monitor, `"local_agent"`, o `"remote_agent"` |
2002 2003
2003<h3 id="taskusage">2004<h3 id="taskusage">
2004 `TaskUsage`2005 `TaskUsage`
2005</h3>2006</h3>
2006 2007
2007Datos de token y tiempo para una tarea de fondo.2008Datos de token y tiempo para una tarea en segundo plano.
2008 2009
2009```python theme={null}2010```python theme={null}
2010class TaskUsage(TypedDict):2011class TaskUsage(TypedDict):
2017 `TaskProgressMessage`2018 `TaskProgressMessage`
2018</h3>2019</h3>
2019 2020
2020Emitido periódicamente con actualizaciones de progreso para una tarea de fondo en ejecución.2021Emitido periódicamente con actualizaciones de progreso para una tarea en segundo plano en ejecución.
2021 2022
2022```python theme={null}2023```python theme={null}
2023@dataclass2024@dataclass
2045 `TaskNotificationMessage`2046 `TaskNotificationMessage`
2046</h3>2047</h3>
2047 2048
2048Emitido 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.2049Emitido cuando una tarea en segundo plano se completa, falla o se detiene. Las tareas en segundo plano incluyen comandos Bash `run_in_background`, vigilancias de Monitor y subagentes en segundo plano.
2049 2050
2050```python theme={null}2051```python theme={null}
2051@dataclass2052@dataclass
2071| `tool_use_id` | `str \| None` | ID de uso de herramienta asociado |2072| `tool_use_id` | `str \| None` | ID de uso de herramienta asociado |
2072| `usage` | `TaskUsage \| None` | Uso de token final para la tarea |2073| `usage` | `TaskUsage \| None` | Uso de token final para la tarea |
2073 2074
2074Cuando la CLI [mueve una llamada de herramienta MCP larga al fondo](/docs/es/mcp#automatic-backgrounding-of-long-tool-calls), 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`](#usermessage). 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.2075Cuando la CLI [mueve una llamada a herramienta MCP larga a segundo plano](/docs/es/mcp#automatic-backgrounding-of-long-tool-calls), 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`](#usermessage). 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.
2075 2076
2076La clase de datos no tiene campo para `resource_links`. Léalo del dict `data` que el mensaje hereda de [`SystemMessage`](#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.2077La clase de datos no tiene campo para `resource_links`. Léelo del dict `data` que el mensaje hereda de [`SystemMessage`](#systemmessage): `message.data.get("resource_links")`. Haz 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 a herramientas MCP.
2077 2078
2078<h2 id="content-block-types">2079<h2 id="content-block-types">
2079 Tipos de bloque de contenido2080 Tipos de bloque de contenido
2153 Tipos de error2154 Tipos de error
2154</h2>2155</h2>
2155 2156
2156Los 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](/docs/es/agent-sdk/troubleshooting).2157Los tipos a continuación definen lo que tu 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, consulta [Solución de problemas](/docs/es/agent-sdk/troubleshooting).
2157 2158
2158<h3 id="claudesdkerror">2159<h3 id="claudesdkerror">
2159 `ClaudeSDKError`2160 `ClaudeSDKError`
2166 """Base error for Claude SDK."""2167 """Base error for Claude SDK."""
2167```2168```
2168 2169
2169Cuando 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`](#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`.2170Cuando 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`](#resulterror).
2170 2171
2171<h3 id="clinotfounderror">2172<h3 id="clinotfounderror">
2172 `CLINotFoundError`2173 `CLINotFoundError`
2216 `ResultError`2217 `ResultError`
2217</h3>2218</h3>
2218 2219
2219Se genera después del [`ResultMessage`](#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.2220Se genera cuando el proceso de Claude Code se cierra porque la ejecución terminó con un [mensaje de resultado](#resultmessage) 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 puedes actuar según por qué falló la ejecución sin analizar el texto del mensaje. Requiere Python Agent SDK 0.2.140 o posterior.
2220 2221
2221```python theme={null}2222```python theme={null}
2222class ResultError(ProcessError):2223class ResultError(ProcessError):
2229 data: dict[str, Any] # the raw result message payload2230 data: dict[str, Any] # the raw result message payload
2230```2231```
2231 2232
2232Para 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_*`.2233Para distinguir los fallos, comprueba `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 estableces termina la ejecución, como `max_turns` o `max_budget_usd`, informa un subtipo `error_*`.
2233 2234
2234<h3 id="clijsondecodeerror">2235<h3 id="clijsondecodeerror">
2235 `CLIJSONDecodeError`2236 `CLIJSONDecodeError`
2370| `session_id` | `str` | Identificador de sesión actual |2371| `session_id` | `str` | Identificador de sesión actual |
2371| `transcript_path` | `str` | Ruta al archivo de transcripción de sesión |2372| `transcript_path` | `str` | Ruta al archivo de transcripción de sesión |
2372| `cwd` | `str` | Directorio de trabajo actual |2373| `cwd` | `str` | Directorio de trabajo actual |
2373| `permission_mode` | `str` (opcional) | Modo de permiso actual |2374| `permission_mode` | `str` (opcional) | Modo de permisos actual |
2374 2375
2375<h3 id="pretoolusehookinput">2376<h3 id="pretoolusehookinput">
2376 `PreToolUseHookInput`2377 `PreToolUseHookInput`
2627```2628```
2628 2629
2629<Note>2630<Note>
2630 Use `continue_` (con guion bajo) en código Python. Se convierte automáticamente a `continue` cuando se envía al CLI.2631 Usa `continue_` (con guion bajo) en código Python. Se convierte automáticamente a `continue` cuando se envía al CLI.
2631</Note>2632</Note>
2632 2633
2633<h4 id="hookspecificoutput">2634<h4 id="hookspecificoutput">
2634 `HookSpecificOutput`2635 `HookSpecificOutput`
2635</h4>2636</h4>
2636 2637
2637Una 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](/docs/es/agent-sdk/hooks#outputs).2638Una 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 [Controlar la ejecución con hooks](/docs/es/agent-sdk/hooks#outputs).
2638 2639
2639```python theme={null}2640```python theme={null}
2640class PreToolUseHookSpecificOutput(TypedDict):2641class PreToolUseHookSpecificOutput(TypedDict):
2649 hookEventName: Literal["PostToolUse"]2650 hookEventName: Literal["PostToolUse"]
2650 additionalContext: NotRequired[str]2651 additionalContext: NotRequired[str]
2651 updatedToolOutput: NotRequired[Any]2652 updatedToolOutput: NotRequired[Any]
2652 updatedMCPToolOutput: NotRequired[Any] # Deprecated: use updatedToolOutput, which works for all tools2653 updatedMCPToolOutput: NotRequired[Any] # MCP tools only. Prefer updatedToolOutput, which works for all tools
2653 2654
2654 2655
2655class PostToolUseFailureHookSpecificOutput(TypedDict):2656class PostToolUseFailureHookSpecificOutput(TypedDict):
2701```2702```
2702 2703
2703<Note>2704<Note>
2704 Use `async_` (con guion bajo) en código Python. Se convierte automáticamente a `async` cuando se envía al CLI.2705 Usa `async_` (con guion bajo) en código Python. Se convierte automáticamente a `async` cuando se envía al CLI.
2705</Note>2706</Note>
2706 2707
2707<h3 id="hook-usage-example">2708<h3 id="hook-usage-example">
2708 Ejemplo de uso de hook2709 Ejemplo de uso de hook
2709</h3>2710</h3>
2710 2711
2711Este 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.2712Este 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.
2712 2713
2713```python theme={null}2714```python theme={null}
2714import asyncio2715import asyncio
2767 Tipos de entrada/salida de herramienta2768 Tipos de entrada/salida de herramienta
2768</h2>2769</h2>
2769 2770
2770Documentació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.2771Documentación de esquemas de entrada/salida para 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.
2771 2772
2772Cada salida mostrada es el valor que usted lee desde [`UserMessage.tool_use_result`](#usermessage) para esa herramienta. Los nombres de clave aparecen exactamente como Claude Code los emite. Una clave anotada `| None` con un comentario "presente cuando" u "opcional" se omite cuando no aplica.2773Cada salida mostrada es el valor que lees desde [`UserMessage.tool_use_result`](#usermessage) para esa herramienta. Los nombres de clave aparecen exactamente como Claude Code los emite. Una clave anotada `| None` con un comentario "presente cuando" u "opcional" se omite cuando no aplica.
2773 2774
2774<h3 id="agent">2775<h3 id="agent">
2775 Agent2776 Agent
2875 2876
2876Devuelve 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, donde `sessionUrl` enlaza a esa sesión y `taskId` la identifica. Si Claude Code [mantuvo el worktree aislado del subagente](/docs/es/worktrees#isolate-subagents-with-worktrees), `worktreePath` en la variante `completed` es donde encontrarlo, y `worktreeBranch` es su rama cuando Claude Code creó el worktree con git.2877Devuelve 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, donde `sessionUrl` enlaza a esa sesión y `taskId` la identifica. Si Claude Code [mantuvo el worktree aislado del subagente](/docs/es/worktrees#isolate-subagents-with-worktrees), `worktreePath` en la variante `completed` es donde encontrarlo, y `worktreeBranch` es su rama cuando Claude Code creó el worktree con git.
2877 2878
2878En la variante `completed`, `resolvedModel` nombra el modelo en el que comenzó el subagente, que puede diferir del `model` de entrada solicitado cuando [`availableModels`](/docs/es/model-config#restrict-model-selection) 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.2879En la variante `completed`, `resolvedModel` nombra el modelo en el que comenzó el subagente, que puede diferir del `model` de entrada solicitado cuando [`availableModels`](/docs/es/model-config#restrict-model-selection) u otra sobrescritura 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.
2879 2880
2880Claude 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. La clave `fallback_credit` requiere Python SDK v0.2.162 o posterior, que incluye Claude Code v2.1.285.2881Claude 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. La clave `fallback_credit` requiere Python SDK v0.2.162 o posterior, que incluye Claude Code v2.1.285.
2881 2882
2885 2886
2886**Nombre de herramienta:** `AskUserQuestion`2887**Nombre de herramienta:** `AskUserQuestion`
2887 2888
2888Hace preguntas aclaratorias al usuario durante la ejecución. Ver [Manejar aprobaciones e entrada del usuario](/docs/es/agent-sdk/user-input#handle-clarifying-questions) para detalles de uso.2889Hace preguntas aclaratorias al usuario durante la ejecución. Consulta [Manejar aprobaciones y entrada del usuario](/docs/es/agent-sdk/user-input#handle-clarifying-questions) para detalles de uso.
2889 2890
2890**Entrada:**2891**Entrada:**
2891 2892
2945 2946
2946**Nombre de herramienta:** `Bash`2947**Nombre de herramienta:** `Bash`
2947 2948
2948Para lo que establece el límite de primer plano, ver [Límites de tiempo de espera y salida](/docs/es/tools-reference#timeout-and-output-limits). Para el límite de tiempo en segundo plano, ver [Límite de tiempo para comandos en segundo plano](/docs/es/tools-reference#time-limit-for-background-commands).2949Para lo que establece el límite de primer plano, consulta [Límites de tiempo de espera y salida](/docs/es/tools-reference#timeout-and-output-limits). Para el límite de tiempo en segundo plano, consulta [Límite de tiempo para comandos en segundo plano](/docs/es/tools-reference#time-limit-for-background-commands).
2949 2950
2950**Entrada:**2951**Entrada:**
2951 2952
2976 2977
2977**Nombre de herramienta:** `Monitor`2978**Nombre de herramienta:** `Monitor`
2978 2979
2979Ejecuta 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`.2980Ejecuta una fuente en segundo plano 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. Proporciona exactamente uno de `command` o `ws`.
2980 2981
2981Cuando 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](/docs/es/tools-reference#monitor-tool) para comportamiento y disponibilidad de proveedor.2982Cuando Monitor ejecuta un comando, sigue las mismas reglas de permisos que Bash; una vigilancia de WebSocket solicita aprobación por separado. La fuente `ws` requiere Claude Code v2.1.195 o posterior. Consulta la [referencia de la herramienta Monitor](/docs/es/tools-reference#monitor-tool) para comportamiento y disponibilidad de proveedor.
2982 2983
2983**Entrada:**2984**Entrada:**
2984 2985
3065}3066}
3066```3067```
3067 3068
3068La salida toma una de las siguientes formas dependiendo de lo que Claude leyó. Verifique la clave `type` para distinguirlas.3069La salida toma una de las siguientes formas dependiendo de lo que Claude leyó. Verifica la clave `type` para distinguirlas.
3069 3070
3070**Salida (tipo: `"text"`):**3071**Salida (tipo: `"text"`):**
3071 3072
3386 3387
3387 Este conjunto predeterminado se aplica en Claude Code v2.1.268 y posterior, que el TypeScript Agent SDK agrupa desde v0.3.268.3388 Este conjunto predeterminado se aplica en Claude Code v2.1.268 y posterior, que el TypeScript Agent SDK agrupa desde v0.3.268.
3388 3389
3389 Ver [Disponibilidad de modelos](/docs/es/agent-sdk/todo-tracking#model-availability) para optar por participar.3390 Consulta [Disponibilidad de modelos](/docs/es/agent-sdk/todo-tracking#model-availability) para optar por participar.
3390</Note>3391</Note>
3391 3392
3392**Entrada:**3393**Entrada:**
3544 TaskOutput3545 TaskOutput
3545</h3>3546</h3>
3546 3547
3547Eliminado en Claude Code v2.1.277. Anteriormente recuperaba salida de una tarea en ejecución o completada, con `BashOutput` aceptado como alias; Claude lee el archivo de salida de una tarea en segundo plano con `Read` en su lugar.3548Eliminado en Claude Code v2.1.277. Anteriormente recuperaba la salida de una tarea en segundo plano en ejecución o completada, con `BashOutput` aceptado como alias; Claude lee el archivo de salida de una tarea en segundo plano con `Read` en su lugar.
3548 3549
3549Una entrada `disallowed_tools` o una regla de denegación que aún nombre cualquiera de estos nombres se ignora sin una advertencia.3550Una entrada `disallowed_tools` o una regla de denegación que aún nombre cualquiera de estos nombres se ignora sin una advertencia.
3550 3551
