El Agent SDK es un arnés, no un permiso

El problema

Un equipo configura un agente con el Claude Agent SDK e incluye en el system prompt la siguiente instrucción: "ejecuta siempre el linter después de editar un archivo". La mayor parte del tiempo funciona. Sin embargo, en ingeniería de producción, "la mayor parte del tiempo" no es una garantía — una instrucción en lenguaje natural puede olvidarse, reinterpretarse o ignorarse cuando el modelo está resolviendo razonamientos complejos. Cuando un comportamiento debe garantizarse de forma determinista y no meramente probabilística, la solución no es redactar la instrucción con mayor énfasis. Es sacarla del prompt e implementarla en código: un hook.

El Agent SDK existe precisamente para separar dos dominios: lo que el modelo decide (juicio, resolución de ambigüedades, síntesis) y lo que el arnés de ejecución garantiza (determinismo, control, límites). Confundir ambos conceptos es la causa principal de sistemas agénticos que deslumbran en demostraciones pero fallan en producción.

El Agent SDK es un arnés, no un permiso

Un error de interpretación habitual: "el Agent SDK otorga permisos al agente para hacer más cosas". En realidad es lo contrario — el SDK es la capa que restringe y estructura lo que el agente puede hacer, transformando comportamientos probabilísticos en ejecuciones controladas. La gestión de sesiones, los hooks de ciclo de vida, los subagentes y la lista de herramientas permitidas (allowedTools) son mecanismos de control defensivo, no de expansión indiscriminada.

Hooks: control determinista donde un prompt no basta

Un hook ejecuta código de aplicación determinista en puntos específicos del ciclo de vida de una sesión — como inmediatamente antes o después de la ejecución de una herramienta —, aplicando reglas de negocio sin depender de la interpretación del modelo. Casos de uso arquitectónico válidos:

• Ejecutar un linter o formateador automáticamente tras cada edición de archivo, sin depender de que el modelo recuerde invocarlo.
• Interceptar y bloquear comandos de shell peligrosos (como git push --force o rm -rf) antes de su ejecución, independientemente del juicio del modelo.
• Normalizar y validar la estructura de retorno de una herramienta antes de devolverla a la ventana de contexto.

La regla de decisión entre "instrucción en el prompt" y "código en un hook" es directa: si un incumplimiento ocasional es admisible, basta con una instrucción en el prompt. Si la regla debe cumplirse el 100% de las veces, corresponde a un hook.

allowedTools y aislamiento de contexto por subagente

Al delegar tareas a subagentes, dos decisiones de diseño restringen su radio de impacto:

• allowedTools: delimita el conjunto exacto de herramientas que un subagente específico puede invocar. Un subagente cuyo propósito es exclusivamente leer y resumir un archivo no debe tener acceso a herramientas Bash o Write — no porque sea malintencionado, sino porque el principio de menor privilegio mitiga los daños de cualquier alucinación en el razonamiento.
• Aislamiento de contexto: los subagentes deben operar con ventanas de contexto acotadas y específicas, sin heredar indiscriminadamente todo el historial de la sesión principal. Esto evita que información irrelevante o sensible se filtre a tareas secundarias y mantiene al subagente enfocado en su tarea asignada.

Descomposición secuencial vs. adaptativa

Los flujos de trabajo complejos pueden dividirse según dos topologías:

• Descomposición secuencial: las etapas se conocen de antemano y se ejecutan en un orden lineal fijo. Resulta óptima cuando los parámetros del problema son deterministas y bien conocidos.
• Descomposición adaptativa: cada etapa se determina dinámicamente en función de los hallazgos empíricos del paso anterior (por ejemplo, en investigaciones de incidentes donde los diagnósticos posteriores dependen de lo observado en tiempo de ejecución).

Forzar canalizaciones secuenciales en tareas que requieren descubrimiento dinámico produce sistemas rígidos que fallan ante cualquier imprevisto. Por el contrario, introducir bucles adaptativos en tareas lineales bien definidas agrega no determinismo y dificulta las pruebas automatizadas. Alinea la topología de descomposición con el grado de certeza del problema.

Ponlo en práctica

En el laboratorio de esta lección implementarás un registro de hooks de ciclo de vida en Python: interceptará llamadas a herramientas simuladas antes y después de su ejecución, bloqueará acciones peligrosas de forma determinista y comprobará que las salvaguardas permanezcan infranqueables incluso cuando la lógica del modelo intente eludir la restricción.