Claude Agent SDK: cómo crear agentes nativos de Anthropic

El Claude Agent SDK es el framework oficial de Anthropic para crear agentes de IA listos para producción directamente sobre los modelos Claude. En lugar de programar a mano el bucle de herramientas de un agente, el SDK ofrece un harness de agente completo: bucles de herramientas automáticos, integración nativa de MCP, subagentes, gestión de sesiones y de contexto, y un sistema integrado de permisos y sandbox. Surgió el 29 de septiembre de 2025 del Claude Code SDK y utiliza el mismo conjunto de herramientas que hay detrás de Claude Code.

Tres respuestas rápidas

• Qué es: un SDK nativo de Anthropic (Python y TypeScript) que proporciona a Claude bucles de herramientas gestionados, sesiones, sandboxing y subagentes, es decir, todo lo que de otro modo habría que construir a mano alrededor de una llamada en bruto a la API de un LLM.
• Cuándo encaja: agentes de programación, agentes de investigación y tareas largas de varios pasos en un stack que apuesta deliberadamente por los modelos Claude.
• Qué hay que tener en cuenta: dependencia del proveedor Claude, API todavía en v0.x con breaking changes (en 2026), SDK de Python con licencia MIT, SDK de TypeScript propietario y uso de ambos bajo los Anthropic Commercial Terms.

Del Claude Code SDK al Claude Agent SDK

El framework se llamaba originalmente Claude Code SDK y era la base técnica del agente de programación Claude Code. Con el cambio de nombre del 29 de septiembre de 2025, Anthropic lo posiciona deliberadamente de forma más amplia: como harness general para agentes con uso de herramientas, en el que la programación es solo un caso de uso más. La idea central sigue siendo el llamado «dogfooding»: los desarrolladores reciben exactamente el mismo conjunto de herramientas y la misma mecánica de bucle que Anthropic usa internamente para Claude Code, entre ellas Read, Write, Edit, Bash, Glob, Grep, WebFetch y WebSearch.

Esa es la diferencia decisiva frente al simple Anthropic Client SDK. Con el Client SDK, el bucle del agente lo escribes tú: llamar al modelo, recibir la llamada a la herramienta, ejecutar la herramienta, devolver el resultado y volver a llamar. El Agent SDK asume precisamente esta orquestación y la complementa con piezas pensadas para producción. La propia Anthropic recomienda en «Building Effective Agents» (diciembre de 2024) trabajar primero directamente con la API del LLM, porque muchos patrones se implementan en pocas líneas de código. Si usas un framework, deberías entender el código que hay debajo. El principio detrás: primero la solución más sencilla y más complejidad solo cuando haga falta. Si solo necesitas una única llamada a la API, no necesitas un framework; un harness como el Agent SDK solo compensa con cadenas de herramientas largas y de varios pasos.

Los componentes clave

Uso de herramientas y el conjunto de herramientas de Claude Code. El SDK incluye las herramientas probadas Read, Write, Edit, Bash, Glob, Grep, WebFetch y WebSearch. Con ellas, un agente puede leer y escribir archivos, ejecutar comandos de shell y obtener contenido web sin que tengas que definir y asegurar esas herramientas por tu cuenta.

Integración nativa de MCP. El Model Context Protocol (MCP) está anclado de forma nativa en el Claude Agent SDK; los servidores MCP pueden incluso ejecutarse in-process. MCP estandariza el acceso a herramientas externas, fuentes de datos y API. Desde su traspaso a la Agentic AI Foundation (AAIF) de la Linux Foundation el 9 de diciembre de 2025, el protocolo es neutral respecto al proveedor; según Anthropic, en abril de 2026 superó los 110 millones de descargas mensuales del SDK y los 10.000 servidores activos. Para las agencias, esto significa que las integraciones construidas una vez como servidor MCP también se pueden reutilizar fuera del ecosistema de Anthropic.

Subagentes y sesiones. En lugar de un modelo de grafo clásico (como en LangGraph), el SDK apuesta por subagentes y sesiones para flujos de varios pasos y con reparto de tareas. Un agente principal puede lanzar subagentes especializados para subtareas; las sesiones mantienen el contexto a lo largo de varios pasos. Oficialmente no existe soporte nativo para A2A (protocolo Agent-to-Agent), lo que distingue al SDK de Microsoft Agent Framework, CrewAI o Pydantic AI.

Gestión de contexto y permisos, más sandbox. El SDK gestiona el contexto a través de la sesión e incluye un sistema de permisos integrado y sandboxing. Los permisos controlan qué acciones puede ejecutar un agente, por ejemplo qué archivos puede escribir o qué comandos puede ejecutar, una palanca importante para los requisitos de human-in-the-loop y de auditoría.

Observabilidad mediante hooks. A diferencia de LangGraph (LangSmith) o Pydantic AI (Logfire), el SDK no tiene una plataforma de observabilidad propia madura. Funciona con hooks y se integra con la Anthropic Console. Si operas el SDK en self-hosting puro, tienes que añadir tu propio logging estructurado para la trazabilidad y para las evidencias relevantes de cara al Reglamento de IA de la UE.

Su lugar en el ecosistema de Anthropic

La fortaleza del SDK está en su estrecho acoplamiento con los modelos Claude y con MCP. En el modelo de capas de los frameworks, se sitúa junto al OpenAI Agents SDK en el nivel de agent runtime/harness, es decir, una capa por encima de los SDK puros de los proveedores y con un carácter distinto al de la capa de frameworks (LangGraph, CrewAI, Pydantic AI). Esta cercanía es a la vez ventaja y limitación: la optimización y el conjunto de herramientas están hechos a medida para Claude, pero a cambio no es posible cambiar de modelo a GPT, Gemini o modelos locales.

Sobre la adopción: según las estadísticas de npm, el paquete de TypeScript alcanzó unos 12,1 millones de descargas en la semana del 5 al 11 de octubre de 2026; en la semana del 1 al 7 de febrero de 2026 eran solo unos 1,85 millones. Con Apple Xcode 26.3, un fabricante destacado ha integrado el SDK de forma nativa.

Perspectiva europea: soberanía y licencia

Para los responsables de decisiones B2B en Europa, hay dos puntos clave. El primero, la residencia de datos: el endpoint directo de Anthropic está en EE. UU. Para requisitos estrictos de la UE o del RGPD, el camino pasa por AWS Bedrock (región de la UE), Google Vertex o Azure AI Foundry. El código del SDK de Python tiene licencia MIT, pero el paquete incluye la CLI propietaria de Claude Code. El SDK de TypeScript es propietario en su totalidad. Ambos se ejecutan en local; el endpoint del modelo, no. De ahí la clasificación de «soberanía media» frente a frameworks totalmente autoalojables como n8n (proveedor alemán), LangGraph o Pydantic AI.

El segundo, la licencia: el código del SDK de Python tiene licencia MIT. Sin embargo, según el README, el paquete incluye la CLI de Claude Code, y según su archivo de licencia esta es propietaria (All rights reserved). El SDK de TypeScript es propietario en su totalidad. El uso de ambos SDK se rige por los Anthropic Commercial Terms of Service, también si con ellos ofreces productos a tus propios clientes. Esta distinción debe figurar con claridad en cualquier evaluación de proveedores y revisión de compras.

Ejemplo concreto

Supongamos que una agencia crea un agente de investigación que, para cada consulta, busca en documentos Markdown internos, elabora una ficha de un competidor y guarda el resultado como archivo. Con el Client SDK, el equipo tendría que escribir por su cuenta todo el bucle de herramientas, la gestión de errores y la gestión del contexto; según análisis de terceros sobre agentes ReAct comparables, entre 40 y más de 100 líneas de código de orquestación. Con el Claude Agent SDK, todo se reduce a una configuración y una llamada (ejemplo simplificado en Python, a octubre de 2026, API v0.x):

```python
import asyncio
from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient

options = ClaudeAgentOptions(
model="claude-...", # ligado a los modelos Claude
allowed_tools=["Read", "Glob", "Grep", "WebFetch", "WebSearch", "Agent"],
permission_mode="default", # Write no está autorizado de antemano
can_use_tool=comprobar_permiso, # pide confirmación antes de escribir (human-in-the-loop)
mcp_servers={"crm": crm_mcp_server}, # conexión MCP nativa, p. ej., CRM
agents={"investigador": investigador}, # subagente solo para la investigación
setting_sources=["project"], # cargar solo la configuración del proyecto y CLAUDE.md
)

async def main():
async with ClaudeSDKClient(options=options) as client:
await client.query("Elabora una ficha de competidor sobre la empresa X.")
async for message in client.receive_response():
print(message)

asyncio.run(main())
```

Importante al migrar desde el nombre antiguo: ClaudeCodeOptions ahora se llama ClaudeAgentOptions. setting_sources define qué archivos de configuración (user, project, local) se cargan. Si no se indica, según la referencia de Python el SDK carga los tres; si estableces el valor de forma explícita, tienes que incluir "project" para que se apliquen las reglas del proyecto y CLAUDE.md. Los bucles de herramientas, el lanzamiento del subagente de investigación, la gestión del contexto de la sesión y la solicitud de permiso antes de escribir el archivo corren a cargo del SDK.

Para agencias y B2B

El Claude Agent SDK es la opción adecuada cuando la decisión estratégica de modelo ya recae en Claude y el foco está en agentes de programación, de investigación o de larga duración. Reduce considerablemente el time-to-production gracias a un harness probado y a la conexión nativa con MCP. En cambio, si necesitas independencia del modelo, comunicación multiagente nativa con A2A, una observabilidad propia madura o plena soberanía europea sin proveedor estadounidense, deberías valorar LangGraph, Pydantic AI o n8n. Blck Alpaca evalúa de forma conjunta para clientes en Europa el framework, la vía de hosting (Bedrock/Vertex/Azure UE) y las implicaciones de licencia, para que el prototipo se convierta en una operación en producción conforme al RGPD. Todos los datos de versiones, precios y adopción corresponden a 2026 y deben volver a verificarse antes de iniciar un proyecto.