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.
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.
Cómo Usar Esta Lista
- Las opciones se agrupan por lo que controlan: modelo/identidad, acceso a herramientas, permisos y comportamiento de sesión/subagente.
- Los ejemplos de Python usan
AgentOptions(...); los ejemplos de TypeScript usan el objeto de opciones equivalente pasado aquery(). - Los nombres de los campos son consistentes en ambos lenguajes; el casing sigue la convención de cada lenguaje (
snake_caseen Python,camelCaseen TypeScript). - Consulta las páginas enlazadas a continuación para conocer el razonamiento detrás de cada opción, no solo su estructura.
Opciones de Modelo e Identidad
| 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 |
Opciones de Acceso a Herramientas
| 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 |
Opciones de Permisos
| 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 |
Opciones de Sesión
| 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) |
Modos de Permiso de un Vistazo
| 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 |
Elección del Alcance de la Lista de Herramientas Permitidas
| 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 |
Preguntas Frecuentes
¿Son idénticos los nombres de las opciones de Python y TypeScript?
Los campos se mapean uno a uno, pero la convención de nombres difiere: Python usa snake_case (allowed_tools), TypeScript usa camelCase (allowedTools).
¿Cuál es la diferencia entre allowed_tools y permission_mode?
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.
¿Es max_turns lo mismo que un límite de sesión?
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.
¿Los subagentes heredan el allowed_tools del padre?
No, cada configuración de subagente lleva su propio allowed_tools y tool_config, independientemente de los del padre.
¿Qué sucede si no configuro permission_mode?
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.
¿Puedo registrar más de un servidor MCP?
Sí, mcp_servers acepta una lista y puede mezclar registros de servidores stdio (locales) y HTTP (remotos) en la misma ejecución.
¿Qué restaura realmente resume?
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.
¿Es cwd obligatorio para cada ejecución?
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.
¿Cuál es el AgentOptions válido más simple?
from claude_agent_sdk import AgentOptions
options = AgentOptions() # todos los valores predeterminados: modelo predeterminado, conjunto de herramientas predeterminado, sin reanudación de sesión¿Qué opción controla si el bucle puede navegar por la web?
Incluye 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.
¿Tienen que usarse juntos checkpoint_tools y checkpoint_hook?
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.
Relacionado
- El Modelo Mental del Claude Agent SDK - los conceptos detrás de estas opciones
- Habilitar Herramientas de Edición de Archivos, Bash y Web en el Agent SDK - opciones de acceso a herramientas en profundidad
- Añadir Puntos de Control Human-in-the-Loop a un Flujo de Trabajo del Agent SDK - opciones de modo de permiso y punto de control en profundidad
- Persistir Sesiones Entre Ejecuciones con el Claude Agent SDK - opciones de sesión en profundidad
- Delegar Trabajo a Subagentes en el Claude Agent SDK - configuración de subagentes en profundidad
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.