Claude Agent SDK: Qué hace y cómo evaluarlo

El Claude Agent SDK es una interfaz de desarrollo para crear aplicaciones que permiten a Claude ejecutar flujos de trabajo delimitados que utilizan herramientas. El SDK puede administrar sesiones, invocar herramientas y coordinar el trabajo, pero no elimina la necesidad de permisos de aplicación, control de versiones, evaluación o aprobación humana. Considérenlo un componente de tiempo de ejecución del agente, no un sistema de producción completo.

Para los equipos que necesitan finalizar el trabajo basado en código fuente sin poseer un entorno de ejecución de agente, Ottermind proporciona la ruta de espacio de trabajo administrado: mantenga conectados los archivos, el contexto de la investigación, las decisiones y los entregables mientras una persona revisa el resultado. El SDK y un espacio de trabajo administrado resuelven diferentes problemas operativos.

Investigación y divulgación: Esta guía se basa en Repositorio Claude Agent SDK, Documentación de uso de la herramienta Anthropic y Documentación de AWS AgentCore y Claude Agent SDK., revisadas el 3 de septiembre de 2026. Las API y los límites están en constante evolución; verifique la versión actual antes de la implementación.

Los componentes básicos

Componente básico	Responsabilidad	Control de la aplicación
Sesión	Mantiene una ejecución y su estado de conversación.	Caducidad, aislamiento y registro de auditoría
Modelo	Interpreta el contexto y propone pasos	Versión del modelo, presupuesto y contrato de salida
Herramienta	Realiza una operación limitada	Esquema, tiempo de espera, permisos e idempotencia
Subagente	Gestiona un rol independiente	Alcance, presupuesto y reglas de escalamiento
Modo de permisos	Controla a qué puede acceder o modificar el agente.	Lista de permisos y confirmación humana.
Resultado.	Devuelve texto, datos estructurados o artefactos.	Validación y entrega al revisor.

Comienza con una tarea reversible.

Crea un prototipo de flujo de trabajo con gran cantidad de lectura, como convertir archivos de repositorio aprobados en un informe de cambios. Captura el conjunto de entrada, la solicitud, la versión del modelo, las llamadas a herramientas, la salida, las correcciones del revisor y la decisión final. Agrega acceso de escritura solo después de que el rastreo sea comprensible y los fallos sean recuperables.

Contrato de tarea mínimo

Prompt

Objetivo: elaborar un informe de implementación basado en el código fuente.
Fuentes permitidas: solo los archivos del repositorio adjunto.
Herramientas permitidas: listar y leer archivos; no se permiten escrituras ni llamadas de red.
Resultados: hallazgos, cambios propuestos, evidencia, riesgos y preguntas abiertas.
Detenerse cuando: falte una fuente requerida o los permisos no estén claros.

Sesiones y subagentes

Utilice una sesión cuando el flujo de trabajo requiera continuidad en varios pasos. Utilice un subagente solo cuando el rol, las herramientas o los criterios de evaluación difieran realmente. Un mayor número de agentes aumenta la coordinación, la latencia y las posibilidades de fallo. Proporciona el contexto mínimo que necesita cada rol y devuelve resultados estructurados con estado y evidencia.

Una arquitectura práctica

Mantén el SDK dentro de un límite de aplicación con cinco responsabilidades:

Gestor de solicitudes: autentica al usuario, selecciona el proyecto permitido y establece un presupuesto.
Cargador de contexto: recupera solo los archivos permitidos y registra sus identificadores y fechas.
Ejecutor de agentes: inicia la sesión, proporciona herramientas y guarda cada solicitud y resultado de herramienta.
Capa de políticas: valida los argumentos, bloquea las acciones no permitidas y solicita confirmación.
Adaptador de resultados: valida la forma devuelta y entrega un borrador al revisor o al siguiente sistema.

Esta separación es importante porque el SDK puede ayudar al modelo a solicitar una herramienta, pero su aplicación decide si se permite dicha solicitud. No coloque lógica de autorización en una solicitud ni asuma que un modelo conservará los límites de inquilino por sí solo.

Sesiones, reanudación y fallos

Asigne a cada ejecución un identificador explícito y un estado terminal, como completed, needs_review, blocked o failed. Conserve la versión del modelo y del SDK, la revisión de la solicitud, las fuentes de entrada, las llamadas a herramientas y la decisión del revisor. Si se produce un error de red después de una escritura, utilice una clave de idempotencia y consulte el sistema de registro antes de reintentar. Si una sesión se reanuda tras una edición humana, incluya el archivo editado y el motivo del cambio, en lugar de reproducir una conversación poco clara.

Ejemplos de diseño de herramientas

Prefiera una función como create_draft_task(title, owner, due_date) a una herramienta de shell de propósito general. Esta función específica permite aplicar formatos de fecha, definir propietarios permitidos, el alcance del proyecto y establecer un estado de solo borrador. Una herramienta de búsqueda de archivos debe devolver identificadores y extractos de archivos, en lugar de exponer silenciosamente toda la unidad. Una herramienta de navegador debe usar una lista de permitidos y detenerse antes de la autenticación o el pago.

Costos y latencia

Establezca presupuestos antes de que comience la ejecución: número máximo de iteraciones del modelo, llamadas a herramientas, tokens, tiempo transcurrido y número de subagentes. Dirija la extracción a un modelo más pequeño cuando la calidad lo permita y reserve el razonamiento complejo para pasos ambiguos. Registre el uso real junto con el resultado para que una demostración exitosa no oculte un flujo de trabajo ineficiente. Las tareas largas deben ser asíncronas, cancelables y visibles para el usuario.

SDK frente a un espacio de trabajo gestionado

Desarrolle con el SDK cuando su equipo necesite herramientas específicas para la aplicación, control de la implementación o un entorno de ejecución personalizado, y pueda gestionar la seguridad, la observabilidad y el mantenimiento. Un espacio de trabajo gestionado es un mejor punto de partida cuando el requisito principal es conectar archivos, investigaciones, decisiones y entregables para su revisión humana. La elección radica en la responsabilidad operativa, no en qué etiqueta suena más autónoma.

Ejemplo: un agente de investigación a informe

Imagina un equipo que necesita un informe semanal sobre la competencia. El gestor de solicitudes verifica la identidad del analista y selecciona el proyecto aprobado. El cargador de contexto recupera la lista de fuentes y registra la fecha de recuperación. La sesión del agente solo puede llamar a search_approved_sources y draft_brief. La capa de políticas rechaza las solicitudes de URL arbitrarias, publicaciones externas o archivos ajenos al proyecto. El adaptador de resultados requiere secciones para hallazgos, citas, incertidumbre y preguntas abiertas antes de presentar el borrador a un revisor.

El artefacto útil no es solo el texto final. Es el registro: qué fuentes estaban disponibles, qué herramientas se utilizaron, qué se bloqueó, qué modificó el revisor y si el informe fue aceptado. Este registro permite la depuración, el análisis de costes y un conjunto de evaluación repetible cuando cambia el modelo o el SDK.

Control de versiones y actualizaciones

Fije las versiones del SDK y del modelo en cada entorno. Consulte las notas de la versión para conocer los cambios en los modos de permisos, los esquemas de herramientas, el comportamiento de la sesión y los modelos compatibles. Ejecute pruebas de regresión antes de actualizar, incluyendo una prueba que confirme que las herramientas prohibidas siguen prohibidas. Mantenga una versión de reversión disponible y evite actualizar en medio de un flujo de trabajo prolongado sin un plan de migración.

Lista de verificación para la preparación de producción

La autenticación y las comprobaciones de inquilinos se realizan antes de la recuperación del contexto.
Cada herramienta tiene un esquema limitado, un tiempo de espera y una verificación de autorización.
Las sesiones tienen presupuestos, cancelación, expiración y estados de finalización.
Los resultados se validan antes de que lleguen a un sistema de registro.
Las acciones sensibles requieren una aprobación humana explícita.
Los registros contienen suficiente información de procedencia para reproducir un fallo sin almacenar secretos.
Los casos de evaluación abarcan calidad, seguridad, coste y latencia.

Permisos y límites de seguridad.

Validar los argumentos de la herramienta en el código de la aplicación. Mantenga las credenciales fuera de las solicitudes, limite el acceso al sistema de archivos y a la red, establezca tiempos de espera y requiera confirmación para enviar, eliminar, comprar o cambiar el acceso. Registre cada llamada a la herramienta con la identidad del usuario y la decisión de aprobación.

Evalúe el flujo de trabajo, no la demostración.

Cree un conjunto de pruebas con casos normales, incompletos, contradictorios, adversarios y con permisos sensibles. Mida la finalización correcta, la escalada segura, los errores de la herramienta, la latencia, el costo y las correcciones del revisor. Fije las versiones del modelo y del SDK para cada ejecución de evaluación.

Preguntas frecuentes

¿Es Claude Agent SDK lo mismo que el uso de la herramienta API de Claude?

No. El uso de herramientas es un patrón de interacción de modelo. El SDK proporciona más componentes básicos a nivel de aplicación para sesiones de agente y flujos de trabajo, mientras que su aplicación sigue siendo responsable de las políticas, el almacenamiento, los permisos y la evaluación.

¿Necesito varios agentes?

Normalmente no al principio. Un agente con herramientas específicas y puntos de control explícitos es más fácil de probar y operar.

¿Puede el SDK editar archivos o ejecutar comandos de forma segura?

Puede conectarse a dichas herramientas, pero la seguridad depende de su entorno aislado, listas de permisos, validación, revisión y diseño de reversión. Nunca considere un comando generado como preaprobado.

Para obtener información sobre los límites del sistema, consulte Arquitectura del agente de IA y Seguridad del agente de IA.