Mejores Prácticas del Claude Agent SDK

Reglas prácticas para llevar un agente del Claude Agent SDK de un prototipo funcional a algo seguro para ejecutar en producción, cubriendo el alcance de herramientas, puntos de control, subagentes y sesiones.

Cómo Usar Esta Lista

• Trabaja a través de cada grupo con letras antes de desplegar un agente que toque datos reales, sistemas reales o usuarios reales.
• Los grupos están ordenados aproximadamente por la etapa del ciclo de vida de un agente en la que son importantes: primero el alcance y las herramientas, luego las puertas de seguridad, y finalmente la delegación y la continuidad.
• Trata esto como una lista de verificación de revisión, no como un tutorial; cada elemento enlaza de vuelta a la página que explica el razonamiento en profundidad.

A - Alcance de Herramientas

• Habilita solo las familias de herramientas que una tarea realmente necesita. Un agente que solo escribe archivos no necesita bash, web_search o web_fetch; cada herramienta habilitada es un área de superficie adicional sobre la que el bucle puede actuar sin supervisión.
• Limita bash a una lista explícita de comandos permitidos en lugar de otorgar un shell abierto. El acceso irrestricto a bash convierte una herramienta en una capacidad de ejecución de código arbitrario; una lista de comandos permitidos la mantiene en las operaciones específicas que requiere la tarea.
• Restringe file_edit a las rutas que una tarea realmente debe tocar. Las restricciones de ruta o glob evitan que un agente que abarca todo el monorepo edite archivos fuera del paquete o directorio en el que se le pidió trabajar.
• Prefiere web_fetch sobre web_search cuando la URL ya se conoce. web_search es una capacidad más amplia y menos predecible; resérvala para tareas de investigación genuinamente abiertas.
• Revisa el alcance de las herramientas cada vez que el prompt de una tarea cambie significativamente. Las decisiones de alcance tomadas para una versión de una tarea pueden volverse silenciosamente demasiado amplias o demasiado estrechas a medida que el comportamiento real de la tarea evoluciona.

B - Puntos de Control con Intervención Humana

• Punto de control de acciones destructivas o irreversibles, no de cada llamada a herramienta. La supervisión de lecturas inofensivas junto con riesgos genuinos entrena a los revisores para aprobar sin leer.
• Asigna a cada hook de punto de control un tiempo de espera explícito con un valor predeterminado seguro. Un hook que puede bloquearse para siempre esperando una decisión humana puede colgar una ejecución en producción; por defecto, rechaza cuando la ventana expira.
• Crea un canal de aprobación real antes de desplegar en un entorno alojado. Un prompt de terminal bloqueante no tiene terminal desde el cual leer una vez que un agente se ejecuta sin supervisión en un servidor; enruta las aprobaciones a través de una cola, un panel o un webhook en su lugar.
• Registra cada decisión de punto de control junto con la llamada a la que se aplicó. Sin un rastro de auditoría de lo que fue aprobado o rechazado y por quién, los puntos de control pierden la responsabilidad que se supone que deben proporcionar.
• Superpón puntos de control sobre el alcance de herramientas, nunca como un sustituto. El alcance cierra clases enteras de acciones; los puntos de control solo capturan las llamadas específicas que recordaste marcar.

C - Subagentes

• Delega solo tareas que son genuinamente independientes. Dividir una tarea con dependencias reales entre subagentes te obliga a secuenciar y pasar resultados manualmente, lo que anula el beneficio de delegar en primer lugar.
• Escribe las descripciones de los subagentes tan específicamente como las descripciones de las herramientas. Una descripción vaga no le da al modelo padre ninguna señal confiable para saber cuándo invocar ese subagente.
• Define el alcance de las herramientas de cada subagente de forma independiente, no copiando el alcance del padre. Un subagente no hereda nada automáticamente; otórgale solo lo que su trabajo específico requiere.
• No dividas una tarea simple en un subagente solo para sentirte exhaustivo. La sobrecarga de un nuevo contexto y un bucle interno completo no vale la pena para un paso que una sola llamada a herramienta manejaría igual de bien.
• Ejecuta subagentes independientes concurrentemente cuando la tarea lo permita. El despacho secuencial de subagentes no relacionados desperdicia el paralelismo que el aislamiento se suponía que habilitaría.

D - Sesiones y Continuidad

• Persiste los IDs de sesión en un almacenamiento que sobreviva al proceso. El SDK te proporciona el mecanismo para reanudar; si el ID no se almacena de forma duradera, se pierde una vez que el proceso sale.
• Clasifica las sesiones por un identificador de tarea estable, no por un valor aleatorio nuevo en cada llamada. Una nueva clave en cada invocación significa que en realidad nunca reanudas nada.
• Maneja un ID de sesión faltante o caducado como un caso de fallo explícito. Reanudar con un ID obsoleto debería fallar predeciblemente y volver a un nuevo inicio, no producir silenciosamente una sesión vacía.
• Establece una política de retención para los datos de sesión almacenados. El historial de sesiones puede contener resultados de herramientas confidenciales; mantenerlo para siempre sin limpieza es un riesgo, no una conveniencia.
• No confíes en resume para reproducir efectos secundarios. Reanudar restaura el registro de lo que ya sucedió; no vuelve a ejecutar comandos bash ni vuelve a obtener URLs de la sesión anterior.

E - Despliegue y Operaciones

• Ajusta la forma de despliegue a si hay un humano presente. Las ejecuciones de binarios CLI locales se adaptan a flujos de trabajo interactivos de un solo operador; la ejecución alojada se adapta a cargas de trabajo desatendidas, programadas o multi-inquilino.
• Reconstruye el enrutamiento de puntos de control explícitamente al pasar de local a alojado. Un flujo de aprobación basado en terminal que funcionó localmente se convierte en un bloqueo silencioso o en un no-op una vez que el agente se ejecuta sin una terminal adjunta.
• Mueve los secretos de los archivos locales antes de desplegar en un entorno alojado. Lee las credenciales del administrador de secretos de la plataforma, no de los archivos de entorno locales que no existirán en ese entorno.
• Agrega registro estructurado una vez que ningún operador esté observando una terminal en vivo. Las ejecuciones alojadas necesitan observabilidad incorporada, ya que no hay nadie presente para notar un problema a medida que ocurre.

Preguntas Frecuentes

Relacionado

• El Modelo Mental del Claude Agent SDK - los conceptos en los que se basan estas prácticas
• Habilitar Herramientas de Edición de Archivos, Bash y Web en el Agent SDK - alcance de herramientas en profundidad
• Añadir Puntos de Control con Intervención Humana a un Flujo de Trabajo del Agent SDK - mecánica de puntos de control en profundidad
• Delegar Trabajo a Subagentes en el Claude Agent SDK - delegación de subagentes en profundidad
• Persistir Sesiones Entre Ejecuciones con el Claude Agent SDK - persistencia de sesiones en profundidad
• Referencia de Patrones de Despliegue del Claude Agent SDK - ventajas y desventajas del despliegue local vs. alojado

Versiones de la Pila: 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.