Referencia de Opciones de Configuración del Claude Agent SDK
Una referencia detallada para las opciones que pasas a una ejecución del Claude Agent SDK, en Python y TypeScript.
//
Busca en todas las páginas de la documentación
Una referencia detallada para las opciones que pasas a una ejecución del Claude Agent SDK, en Python y TypeScript.
Usa esta página para buscar el nombre, tipo y valor predeterminado de una opción específica en lugar de releer las páginas conceptuales cada vez.
AgentOptions(...); los ejemplos de TypeScript usan el objeto de opciones equivalente pasado a query().snake_case en Python, camelCase en TypeScript).| Opción (Python) | Opción (TypeScript) | Tipo | Descripción |
|---|---|---|---|
model | model | str | Qué modelo de Claude ejecuta el paso decide del bucle, p. ej., "claude-sonnet-5" |
cwd | cwd | str | Directorio raíz de trabajo para file_edit y bash |
system_prompt | systemPrompt | str | Instrucciones adicionales a nivel de sistema que se superponen a los valores predeterminados del SDK |
max_turns | maxTurns | int | Límite estricto de iteraciones del bucle de uso de herramientas antes de que se detenga |
| Opción (Python) | Opción (TypeScript) | Tipo | Descripción |
|---|---|---|---|
allowed_tools | allowedTools | list[str] | Lista de permitidos de nombres de herramientas integradas que el bucle puede llamar |
tool_config | toolConfig | dict | Alcance por herramienta (comandos permitidos, rutas, dominios) |
mcp_servers | mcpServers | list | Servidores MCP stdio o HTTP registrados en los que el bucle puede llamar herramientas |
subagents | subagents | list | Configuraciones de agentes hijos con nombre, cada uno con su propio alcance de herramientas |
| Opción (Python) | Opción (TypeScript) | Tipo | Descripción |
|---|---|---|---|
permission_mode | permissionMode | str | Si las llamadas a herramientas permitidas aún requieren aprobación humana, p. ej., "default", "bypass" |
checkpoint_hook | checkpointHook | callable | Función invocada antes de una llamada a herramienta marcada, para aprobarla/rechazarla/modificarla |
checkpoint_tools | checkpointTools | list[str] | Qué nombres de herramientas activan una pausa de punto de control |
| Opción (Python) | Opción (TypeScript) | Tipo | Descripción |
|---|---|---|---|
resume | resume | str | Un ID de sesión anterior para reanudar la conversación y el historial de resultados de herramientas |
session_store | sessionStore | object | Dónde se persiste el estado de la sesión (en memoria, archivo o un backend personalizado) |
| Modo | Comportamiento | Uso Típico |
|---|---|---|
default | Pausa antes de llamadas a herramientas destructivas/marcadas para aprobación | La mayoría de los agentes de producción |
bypass | Sin puerta de aprobación; cada llamada a herramienta permitida se ejecuta inmediatamente | Automatizaciones de alcance limitado y bajo riesgo |
Personalizado (a través de checkpoint_hook) | Tu propia lógica decide aprobar/rechazar/modificar por llamada | Reglas de aprobación detalladas o condicionales |
| Forma del Alcance | Cuándo Usar |
|---|---|
Familia de herramientas única (p. ej., ["file_edit"]) | La tarea es de un solo tipo de acción |
Múltiples familias, sin restricción de tool_config | Entorno de confianza, tarea bien entendida |
Múltiples familias con restricciones de tool_config | Agentes de producción que tocan datos o sistemas reales |
| Lista vacía | Generación de texto puro, sin necesidad de actuar sobre nada |
Los campos se mapean uno a uno, pero la convención de nombres difiere: Python usa snake_case (allowed_tools), TypeScript usa camelCase (allowedTools).
allowed_tools decide a qué puede acceder el bucle en absoluto. permission_mode decide si una llamada permitida y alcanzable aún necesita que un humano la apruebe antes de que se ejecute.
No. max_turns limita las iteraciones internas de una sola llamada query(). Las sesiones abarcan múltiples llamadas query() separadas a lo largo del tiempo.
No, cada configuración de subagente lleva su propio allowed_tools y tool_config, independientemente de los del padre.
El comportamiento recurre al modo predeterminado del SDK, que generalmente aún controla las acciones destructivas; consulta las notas de la versión actual del SDK para conocer el valor predeterminado exacto, ya que los valores predeterminados seguros pueden refinarse entre versiones.
Sí, mcp_servers acepta una lista y puede mezclar registros de servidores stdio (locales) y HTTP (remotos) en la misma ejecución.
El historial de la conversación y el historial de resultados de herramientas capturados bajo ese ID de sesión, para que el bucle continúe con ese contexto ya presente en lugar de comenzar en blanco.
No estrictamente, pero omitirlo significa que file_edit y bash recurren al directorio de trabajo ambiental del proceso, lo cual es frágil entre entornos. Establécelo explícitamente para cualquier cosa más allá de una prueba local rápida.
from claude_agent_sdk import AgentOptions
options = AgentOptions() # todos los valores predeterminados: modelo predeterminado, conjunto de herramientas predeterminado, sin reanudación de sesiónIncluye web_search y/o web_fetch en allowed_tools; son entradas separadas ya que la búsqueda y la obtención de URL única tienen diferentes perfiles de riesgo.
checkpoint_tools nombra qué llamadas a herramientas activan una pausa; checkpoint_hook es la función que se ejecuta durante esa pausa para decidir el resultado. Usar uno sin el otro generalmente recurre a un comportamiento de confirmación predeterminado en lugar de lógica personalizada.
Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y el Claude Agent SDK (última versión, Python y TypeScript). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.
Revisado por Chris St. John·Última actualización: 16 jul 2026