El modelo mental del SDK de Claude Agent
El SDK de Claude Agent es la biblioteca de Anthropic para crear agentes de IA de producción en Python o TypeScript.
Fue renombrado de "Claude Code SDK" en 2025, y ese cambio de nombre es la forma más rápida de entender qué es realmente.
Claude Code, el agente de codificación de línea de comandos, se basa en los mismos primitivos que este SDK te expone: un bucle de uso de herramientas, un conjunto de herramientas integradas, subagentes, sesiones y soporte para clientes MCP.
Aprender este SDK es aprender cómo funciona Claude Code internamente, y luego poder dirigir esa misma maquinaria hacia el problema que estés resolviendo en lugar de solo la ingeniería de software.
Esta página construye el modelo mental que el resto de la sección asume: qué hace el bucle en cada turno, cómo encajan las herramientas integradas y los subagentes en él, y dónde se adjuntan las sesiones y los servidores MCP.
Resumen
- Idea Central: El SDK envuelve una llamada al modelo en un bucle de uso de herramientas, le entrega a ese bucle un conjunto limitado de herramientas (integradas, de subagente o MCP) y permite que el bucle se ejecute hasta que el agente produzca una respuesta final o alcance una condición de parada.
- Por qué es importante: Una única llamada de pregunta-respuesta no puede leer un archivo, ejecutar un comando o delegar una subtarea; el bucle es lo que convierte un modelo de lenguaje en algo que realmente puede actuar sobre una base de código o un sistema.
- Conceptos Clave: bucle de uso de herramientas, herramientas integradas, subagentes, sesiones, puntos de control de intervención humana, cliente MCP.
- Cuándo usarlo: Cualquier tarea que requiera que el modelo lea/escriba archivos, ejecute comandos, navegue por la web o coordine múltiples flujos de trabajo independientes, no solo generar texto.
- Limitaciones / Compensaciones: Más capacidad significa más superficie de ataque para asegurar; cada herramienta que habilitas es algo que el bucle ahora puede hacer sin que un humano observe cada paso, a menos que agregues puntos de control.
- Temas Relacionados: conceptos básicos de query(), alcance de herramientas, delegación de subagentes, persistencia de sesiones, servidores MCP.
Fundamentos
En su forma más simple, llamar a un modelo de lenguaje es una solicitud y una respuesta.
Envías un prompt, el modelo devuelve texto y nada en el mundo cambia como resultado.
El SDK de Claude Agent existe porque la mayor parte del trabajo real no tiene esa forma.
El trabajo real generalmente significa "mira este archivo, decide qué cambiar, haz el cambio, comprueba que funcionó", una secuencia de acciones, no una única suposición.
La respuesta del SDK a esa brecha es el bucle de uso de herramientas: lo inicias con una llamada de estilo query(), y en lugar de devolver después de una respuesta, el bucle sigue ejecutándose mientras el modelo siga decidiendo que necesita llamar a una herramienta.
En cada turno, el modelo produce una respuesta final o solicita invocar una herramienta, el SDK ejecuta esa herramienta y devuelve el resultado, y el modelo tiene otro turno con esa nueva información disponible.
Una analogía simple es un contratista trabajando a partir de un plano frente a uno que solo describe la casa por teléfono.
Una llamada de modelo sin procesar es la descripción telefónica: detallada, pero nada se construye.
El bucle de uso de herramientas es el contratista que realmente toma las herramientas, las usa y verifica el resultado antes de decidir qué hacer a continuación.
El SDK envía varias categorías de capacidad que se conectan a este bucle, y comprender para qué sirve cada categoría es la mayor parte de lo que necesitas antes de escribir tu primer agente.
Las herramientas integradas cubren la edición de archivos, la ejecución de bash, la búsqueda web y la obtención web, listas para usar, sin necesidad de cableado de terceros.
Los subagentes son agentes hijos con su propia ventana de contexto aislada a los que un agente padre puede delegar trabajo, útil cuando una tarea se divide en piezas independientes.
Las sesiones permiten que el historial de conversación y llamadas a herramientas de un agente persista entre ejecuciones de procesos, de modo que una segunda invocación pueda reanudarse en lugar de comenzar desde cero.
El soporte para clientes MCP permite que el bucle llame a herramientas que viven fuera del SDK por completo, en un proceso local o un servidor remoto, a través del Protocolo de Contexto del Modelo.
Mecánica e Interacciones
La forma básica del bucle es siempre la misma: decidir, actuar, observar, repetir.
El paso de "decidir" es el modelo eligiendo, basándose en la conversación y los resultados previos de las herramientas hasta el momento, si llamar a una herramienta o producir una respuesta final.
El paso de "actuar" es el SDK ejecutando lo que el modelo solicitó, ya sea una herramienta integrada, una invocación de subagente o una llamada a herramienta MCP.
El paso de "observar" devuelve el resultado de esa acción a la conversación como nuevo contexto, que es lo que hace que el siguiente paso de "decidir" esté mejor informado que el anterior.
Este es exactamente el bucle que ejecuta Claude Code cuando edita un archivo por ti en la terminal: leer, decidir, editar, verificar la diferencia, decidir de nuevo.
Donde las categorías interactúan es en cómo cada una cambia lo que "actuar" puede hacer.
Las herramientas integradas son las manos predeterminadas del bucle: la edición de archivos le da la capacidad de cambiar lo que está en el disco, bash le da una shell, la búsqueda web y la obtención web le dan una forma de obtener información más allá de sus datos de entrenamiento.
Ninguna de estas es obligatoria; un agente de producción típicamente habilita solo el subconjunto que la tarea realmente necesita, porque cada herramienta habilitada es algo que el bucle puede invocar sin preguntar primero, a menos que agregues un punto de control.
from claude_agent_sdk import query, AgentOptions
options = AgentOptions(
allowed_tools=["file_edit", "bash"], # con alcance limitado, no "todo activado"
permission_mode="default", # el bucle se pausa antes de acciones arriesgadas
)
result = query("Arregla la prueba fallida en tests/test_orders.py", options=options)Los subagentes cambian la forma de "actuar" de "ejecutar una herramienta" a "entregar esta subtarea completa a un agente separado y esperar su resultado".
Cada subagente obtiene su propia ventana de contexto y su propio acceso a herramientas, lo que significa que un agente padre que trabaja en una tarea grande puede distribuir el trabajo a varios subagentes que no contaminan el contexto entre sí ni se pisan el razonamiento intermedio.
Ese aislamiento es también la razón principal para recurrir a un subagente en lugar de simplemente agregar otra llamada a herramienta: los flujos de trabajo independientes se mantienen independientes y puedes ejecutarlos en paralelo.
Los puntos de control de intervención humana se adjuntan específicamente al paso "actuar", no a todo el bucle.
Un punto de control pausa la ejecución justo antes de que se realice una llamada a una herramienta específica, típicamente una marcada como destructiva o irreversible (eliminar archivos, enviar a un remoto, gastar dinero), y espera la aprobación antes de permitir que "actuar" continúe.
Las sesiones operan entre invocaciones de bucle en lugar de dentro de una sola.
Un ID de sesión captura el historial de conversación y resultados de herramientas en el punto en que finaliza una ejecución, y pasar ese ID a una llamada query() posterior reanuda el bucle desde allí en lugar de comenzar desde cero, lo que es importante para tareas de agente de larga duración o de varios pasos que no caben en una sola vida útil del proceso.
El soporte para clientes MCP amplía lo que "actuar" puede alcanzar sin que tú mismo escribas código de herramienta personalizado.
Un servidor MCP, ya sea un proceso stdio local o un punto final HTTP remoto, expone herramientas con la misma forma que las herramientas integradas, por lo que una vez que registras una, el bucle puede llamarla exactamente como llama a la edición de archivos o bash.
Consideraciones y Aplicaciones Avanzadas
El modelo mental anterior se mantiene bien hasta que comienzas a componer piezas, y ahí es donde realmente viven la mayoría de las decisiones de diseño de producción.
Un agente padre con subagentes sigue siendo un único bucle de uso de herramientas en la parte superior: cada invocación de subagente es solo otra llamada a herramienta desde la perspectiva del padre, y el subagente ejecuta su propio bucle interno debajo, con su propio ciclo de decidir-actuar-observar y su propio alcance de herramientas.
Esa anidación es la razón por la que los subagentes se componen limpiamente con puntos de control y sesiones: un punto de control en el padre no se aplica automáticamente dentro de un subagente, y un subagente típicamente no hereda la sesión del padre a menos que lo configures explícitamente.
El alcance de las herramientas interactúa con los puntos de control de una manera que es fácil de confundir: el alcance decide de qué es capaz el bucle de llamar, mientras que los puntos de control deciden cuáles de esas llamadas permitidas aún necesitan que un humano diga que sí.
Un agente con un alcance limitado y sin puntos de control puede ser más seguro que un agente con un alcance amplio y con puntos de control solo en las acciones destructivas obvias, porque el alcance cierra clases enteras de acciones en lugar de depender de atrapar cada una arriesgada en el momento de la aprobación.
La forma de implementación cambia lo que las sesiones y los puntos de control significan en la práctica.
Ejecutar el binario CLI empaquetado localmente mantiene todo, incluidas las aprobaciones de puntos de control, en una sola máquina con un humano al teclado; un modelo de ejecución alojado generalmente necesita que las aprobaciones de puntos de control se enruten a través de algún otro canal (una cola, un webhook, un panel) ya que no hay una terminal para solicitarla.
| Enfoque | Fortaleza | Debilidad | Mejor Ajuste |
|---|---|---|---|
| Agente único, solo herramientas integradas | Simple de razonar y depurar | Sin paralelismo, una ventana de contexto para todo | Tareas pequeñas y autocontenidas |
| Agente único + servidores MCP | Amplía el alcance sin código de herramienta personalizado | Agrega una dependencia externa y sus propios modos de falla | Tareas que necesitan sistemas que el SDK no cubre de forma nativa |
| Padre + subagentes | Paraleliza el trabajo independiente, aísla el contexto | Más partes móviles, más difícil de rastrear de extremo a extremo | Tareas grandes que se dividen en piezas independientes claras |
| Cualquiera de los anteriores + puntos de control | Agrega un veto humano antes de acciones irreversibles | Agrega latencia y una dependencia operativa de un revisor | Cualquier cosa que toque datos de producción, dinero o eliminación |
Conceptos erróneos comunes
- "query() solo envía un prompt y recibe una respuesta." Inicia un bucle; la respuesta que recibes es el resultado después de que el modelo haya llamado potencialmente a herramientas, observado los resultados y decidido de nuevo, posiblemente muchas veces.
- "Habilitar una herramienta integrada significa que el agente puede hacer cualquier cosa con ella." El acceso a las herramientas se puede limitar a herramientas y rutas específicas permitidas; habilitar "edición de archivos" no tiene por qué significar acceso irrestricto al sistema de archivos.
- "Los subagentes son solo una forma de ahorrar tokens." El aislamiento del contexto es el beneficio principal; la capacidad de ejecutar subagentes independientes en paralelo y evitar que su razonamiento intermedio sature el contexto del padre importa tanto como cualquier ahorro de tokens.
- "Las sesiones y los puntos de control son el mismo mecanismo de seguridad." Las sesiones se refieren a la continuidad del contexto entre ejecuciones; los puntos de control se refieren a pausar para aprobación antes de una acción específica. Ninguno sustituye al otro.
- "MCP es solo para conectarse a APIs remotas." Los servidores MCP pueden ejecutarse localmente sobre stdio tan fácilmente como sobre HTTP; al protocolo no le importa si la herramienta vive en tu máquina o a través de la red.
Preguntas Frecuentes
¿Es el SDK de Claude Agent lo mismo que Claude Code?
- No, pero comparten los mismos primitivos subyacentes.
- Claude Code es un producto CLI específico construido sobre estos primitivos, dirigido a la ingeniería de software.
- El SDK de Agent expone esos primitivos directamente para que puedas construir un agente para cualquier dominio, no solo para codificación.
¿Qué sucede realmente cuando llamo a query()?
Inicia un bucle de uso de herramientas: el modelo razona sobre tu solicitud, opcionalmente llama a una o más herramientas, observa cada resultado y repite hasta que produce una respuesta final o se alcanza una condición de parada (como un límite de pasos).
¿Tengo que habilitar las herramientas de edición de archivos, bash y web cada vez?
No. El acceso a las herramientas es opcional y con alcance limitado; eliges qué herramientas integradas puede usar un agente para una tarea determinada, hasta operaciones específicas permitidas, en lugar de otorgar todo por defecto.
¿Cuándo debería usar un subagente en lugar de simplemente agregar otra herramienta?
- Cuando una subtarea es genuinamente independiente y de lo contrario saturaría el contexto del padre con pasos intermedios irrelevantes.
- Cuando quieras paralelizar múltiples flujos de trabajo independientes.
- No para cada pequeña acción de ayuda; una única llamada a herramienta con alcance limitado suele ser más simple.
¿Qué es mecánicamente un punto de control de intervención humana?
Es una pausa que el SDK inserta justo antes de que se ejecute una llamada a una herramienta específica, típicamente una marcada como destructiva o irreversible, que se bloquea hasta que un humano la aprueba o rechaza antes de que el paso "actuar" del bucle continúe.
¿Las sesiones persisten para siempre?
Las sesiones persisten durante el tiempo que elijas almacenar el identificador de sesión y su historial asociado; el SDK te proporciona el mecanismo para reanudar, pero la retención y el almacenamiento son responsabilidad de tu aplicación.
¿Cómo se diferencia MCP de una herramienta integrada?
Las herramientas integradas (edición de archivos, bash, web) se envían con el propio SDK. Las herramientas MCP residen en un servidor separado, local o remoto, que registras; una vez registrado, el bucle las llama de la misma manera que llama a las herramientas integradas.
¿Puede un subagente usar herramientas diferentes a las de su padre?
Sí. Cada subagente tiene su propio alcance de herramientas, que es una de las razones principales para usar uno: puedes entregarle a un subagente solo lo que necesita para su parte específica de la tarea.
¿Qué detiene el bucle de uso de herramientas de ejecutarse para siempre?
El bucle termina cuando el modelo produce una respuesta final en lugar de otra llamada a herramienta, o cuando se alcanza una condición de parada configurada (como un número máximo de turnos).
¿Agregar más herramientas hace que un agente sea más inteligente?
No directamente. Más herramientas amplían sobre qué puede actuar el agente, pero el modelo aún tiene que decidir correctamente cuándo se aplica cada herramienta; el acceso excesivo y sin alcance a herramientas principalmente amplía el radio de explosión de una decisión incorrecta.
¿Es Python o TypeScript el SDK "real"?
Ambos son paquetes de primera clase para el mismo SDK subyacente. Esta sección se basa en Python para sus ejemplos, pero los mismos conceptos, bucle, herramientas, subagentes y sesiones, se aplican en TypeScript.
Relacionado
- Conceptos básicos del SDK de Claude Agent - instala el paquete y ejecuta tu primera query()
- Habilitar herramientas de edición de archivos, bash y web en el SDK de Agent - alcance de las herramientas integradas en la práctica
- Delegar trabajo a subagentes en el SDK de Claude Agent - el modelo de aislamiento con más detalle
- Agregar puntos de control de intervención humana a un flujo de trabajo del SDK de Agent - pausar el bucle antes de acciones irreversibles
- Persistir sesiones entre ejecuciones con el SDK de Claude Agent - reanudar el contexto entre ejecuciones de procesos
- Conectar el SDK de Claude Agent a servidores MCP - ampliar el alcance del bucle con herramientas externas
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 SDK de Claude Agent (ú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.