Claude Agent SDK: Cómo crear agentes (2026)

TL;DR

• Claude Agent SDK es la biblioteca de Anthropic para crear agentes de IA en tu propio código: el mismo motor de agentes que impulsa Claude Code, expuesto como claude-agent-sdk para Python (3.10+) y @anthropic-ai/claude-agent-sdk para TypeScript.
• Fue renombrado desde `claude-code-sdk` a finales de 2025; si un tutorial dice ClaudeCodeOptions, está desactualizado: la clase ahora es ClaudeAgentOptions.
• Obtienes el bucle completo del agente gratis: herramientas de archivos, Bash, búsqueda web, herramientas personalizadas mediante @tool, servidores MCP (así es como conectas Jira o Shopify), subagentes, hooks y permisos. Solo pagas por los tokens de la API de Claude.
• Se comunica con la Anthropic Messages API, así que puedes apuntarlo a una pasarela con ANTHROPIC_BASE_URL: lo probamos contra el endpoint /v1/messages de Velokey y funciona con una sola clave y facturación por crédito.

Todo el mundo está creando agentes ahora mismo, y la mayoría de las guías se quedan en el quickstart de diez líneas. Esta cubre lo que viene después: cómo instalarlo sin la trampa común de Node, cómo conectar herramientas reales como Jira y Shopify, cuánto cuesta realmente ejecutarlo y cómo enrutarlo a través de una pasarela. Vamos a ello.

¿Qué es Claude Agent SDK?

Claude Agent SDK es una biblioteca que le da a tu propia aplicación el mismo bucle de agente autónomo que se ejecuta dentro de Claude Code: leer y escribir archivos, ejecutar comandos, buscar en la web y llamar a herramientas, sin que tengas que escribir a mano el bucle de llamadas a herramientas. Anthropic lo distribuye para Python y TypeScript, y según la documentación oficial, es la forma admitida de crear agentes de producción en Claude.

El contexto importante que la mayoría pasa por alto: antes se llamaba Claude Code SDK. Anthropic lo renombró como Claude Agent SDK a finales de 2025 para indicar que sirve para crear *cualquier* agente, no solo herramientas de programación. El paquete, las importaciones y una clase principal cambiaron: claude-code-sdk pasó a ser claude-agent-sdk, y ClaudeCodeOptions pasó a ser ClaudeAgentOptions. Muchas publicaciones de blog y respuestas de Stack Overflow todavía hacen referencia a los nombres antiguos, así que si tu importación falla, normalmente esa es la razón.

Bajo el capó, el SDK envuelve la CLI de Claude Code como un subproceso. Tu código Python o TypeScript habla con el SDK; el SDK controla la CLI incluida; la CLI habla con Claude. Esa arquitectura importa por dos razones a las que volveremos: la CLI es un binario de Node (así que necesitas tener Node instalado incluso para el SDK de Python), y la CLI hace un almacenamiento en caché de prompts agresivo en su prompt del sistema (lo que cambia tus cálculos de costes).

¿Cómo instalo y uso el Claude Agent SDK?

Instala el Claude Agent SDK desde PyPI (o npm), configura tu clave de API y llama a query() — un agente funcional son unas diez líneas. Python necesita 3.10 o una versión más reciente:

pip install claude-agent-sdk
export ANTHROPIC_API_KEY="sk-ant-..."

Aquí está el agente mínimo de una sola ejecución. query() devuelve un iterador asíncrono de mensajes:

import anyio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="List the Python files in this repo and summarize each."):
        print(message)

anyio.run(main)

Para cualquier cosa interactiva o de varios turnos, usa ClaudeSDKClient y configúralo con ClaudeAgentOptions:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

options = ClaudeAgentOptions(
    system_prompt="You are a careful code-review assistant.",
    allowed_tools=["Read", "Grep", "Glob"],
    permission_mode="acceptEdits",
    max_turns=10,
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Review auth.py for security issues.")
    async for msg in client.receive_response():
        print(msg)

Dos problemas de instalación que suelen hacer tropezar a la gente, ninguno de los cuales está en la guía rápida de diez líneas:

¿Qué puedes crear con Claude Agent SDK?

Puedes crear cualquier agente que necesite acceso a archivos, ejecución de comandos o uso de herramientas — desde un revisor de código hasta un clasificador de soporte al cliente o un operador de pipelines de datos. El SDK te da cinco bloques de construcción, y todo el diseño trata sobre controlar qué se le permite hacer al agente:

Las herramientas personalizadas son la parte más limpia. Decora una función y el agente puede llamarla directamente — sin proceso separado, sin salto de red:

from claude_agent_sdk import tool

@tool("get_order", "Look up an order by ID", {"order_id": str})
async def get_order(args):
    order = db.fetch(args["order_id"])
    return {"content": [{"type": "text", "text": str(order)}]}

Los hooks y los permisos son lo que convierten una demo en algo que ejecutarías sin supervisión. Un hook PreToolUse puede bloquear un comando Bash que coincida con un patrón peligroso; permission_mode decide si el agente se detiene para pedir aprobación o acepta ediciones automáticamente. En producción, la mayoría de los equipos empiezan con una lista allowed_tools estricta y la amplían a medida que confían en el agente — lo opuesto al quickstart completamente abierto.

El sexto bloque, y aquel al que la gente recurre cuando un solo agente se vuelve lento, son los subagentes. El SDK puede lanzar un subagente nuevo con su propio contexto para manejar una subtarea acotada y luego devolver el resultado — Claude Code usa esto para distribuir el trabajo entre archivos. Es la respuesta integrada a "puede trabajar en varias cosas en paralelo" y "cómo evito que el contexto principal se llene": delega el trabajo ruidoso (leer diez archivos, ejecutar una matriz de pruebas) a subagentes para que el agente principal se mantenga enfocado. La bifurcación de sesiones es el truco relacionado para ramificar una conversación en curso.

¿Cómo integro Jira o Shopify con Claude Agent SDK?

Integras Jira, Shopify o cualquier sistema externo añadiendo su servidor MCP a mcp_servers en ClaudeAgentOptions: el SDK no tiene código específico para Jira, habla el Model Context Protocol abierto, y tanto Atlassian como Shopify proporcionan servidores MCP. Esta es la respuesta a las preguntas de integración más frecuentes ("cómo conectar Jira/Shopify con Claude Agent SDK"): no hay un conector especial, registras un servidor MCP y permites sus herramientas.

El patrón es el mismo para ambos. Apunta el SDK al servidor MCP (un comando local o una URL remota) y luego permite las herramientas que expone:

options = ClaudeAgentOptions(
    mcp_servers={
        "jira": {
            "command": "npx",
            "args": ["-y", "@atlassian/mcp-server-jira"],
            "env": {"JIRA_API_TOKEN": os.environ["JIRA_API_TOKEN"]},
        }
    },
    allowed_tools=["mcp__jira__search_issues", "mcp__jira__create_issue"],
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Find open bugs assigned to me and summarize them.")
    async for msg in client.receive_response():
        print(msg)

Cambia el bloque del servidor por @shopify/mcp-server (con tu token de Shopify) y el mismo agente puede leer pedidos o actualizar productos. Dos cosas que debes hacer bien: los nombres de las herramientas siguen la convención mcp__<server>__<tool>, así que tus entradas de allowed_tools deben coincidir exactamente, y cada servidor MCP necesita su propia credencial en env. Si el agente dice que una herramienta no está disponible, casi siempre se trata de una discrepancia de nombres o de un token faltante, no de un bug del SDK.

Si el proveedor aloja un servidor MCP remoto en lugar de un comando local, regístralo por URL en vez de command/args: {"jira": {"url": "https://mcp.atlassian.com/v1/sse"}}; y el SDK se conecta por la red. Los servidores locales (stdio) son más sencillos para el desarrollo y mantienen el token en tu máquina; los servidores remotos (URL) te evitan instalar nada. En cualquier caso, las reglas de allowed_tools y credenciales por servidor son las mismas.

¿Cómo ejecuto el Claude Agent SDK a través de una gateway?

Configura ANTHROPIC_BASE_URL con la raíz de tu gateway, y el SDK enviará cada solicitud allí en lugar de a api.anthropic.com, sin cambiar el código. El SDK respeta las variables de entorno estándar de Anthropic, por lo que cualquier backend que exponga la Anthropic Messages API (/v1/messages) funciona: un proxy corporativo, un puente regional o una gateway unificada.

Probamos esto con [Velokey](https://api.velokey.ai), que expone un endpoint compatible con Anthropic /v1/messages. Una solicitud en vivo devolvió una respuesta estándar de Messages (stop_reason: end_turn, uso con formato de Anthropic), que es exactamente lo que espera el SDK:

export ANTHROPIC_BASE_URL="https://api.velokey.ai"
export ANTHROPIC_API_KEY="sk-your-velokey-key"
# then run your agent as usual — set the model to one Velokey serves:

options = ClaudeAgentOptions(
    model="claude-sonnet-5",      # or claude-opus-4-8
    allowed_tools=["Read", "Grep"],
    max_turns=8,
)

¿Por qué enrutar un agente a través de una gateway? Una sola clave en lugar de una cuenta de Anthropic separada, un nivel y una configuración de retención de 30 días; facturación basada en créditos que puedes limitar; y la misma clave llega a [Claude Opus 4.8](/model/claude-opus-4-8), [Claude Sonnet 5](/model/claude-sonnet-5) y otros modelos que podrías usar en otros lugares. Si tu proxy quiere un token bearer en lugar del encabezado x-api-key, configura ANTHROPIC_AUTH_TOKEN en lugar de ANTHROPIC_API_KEY. Es la misma idea plug-and-play que apuntar una herramienta compatible con OpenAI a una gateway; consulta nuestra guía de Qwen CLI para el equivalente en formato OpenAI.

¿Cuánto cuesta el Claude Agent SDK?

El SDK en sí es gratuito y open-source: pagas por los tokens de la API de Claude que consume el agente, y los agentes consumen muchos. Cada turno vuelve a enviar la conversación en crecimiento, cada resultado de herramienta vuelve al contexto, y una sola tarea de "corrige este bug" puede ejecutar más de diez turnos. Esa es la sorpresa del costo: el código son diez líneas, pero la factura de tokens escala según cuánto explore el agente.

Tres palancas lo mantienen bajo control, y el SDK incorpora la más importante por ti:

Esa última fila es real, no teórica: en nuestra solicitud de prueba, la respuesta informó decenas de miles de cache_read_input_tokens, lo que significa que el gran prompt de sistema se sirvió desde caché a aproximadamente una décima parte del precio de entrada, en lugar de volver a facturarse en cada turno. Es la razón principal por la que los costos de los agentes no son tan brutales como sugiere el número de turnos. Para ver el cálculo completo de tokens por modelo, consulta nuestra guía de precios de la API de Claude; si quieres una llamada única funcional a un modelo de Claude antes de conectar un agente, cómo llamar a Claude con una clave de API cubre los conceptos básicos.

Preguntas frecuentes

¿Qué es el Claude Agent SDK?

Es la biblioteca oficial de Anthropic para crear agentes de IA en Python o TypeScript, usando el mismo bucle de agente autónomo que impulsa Claude Code. Gestiona por ti el bucle de llamadas a herramientas, las operaciones de archivos, la ejecución de comandos y las integraciones MCP, para que escribas el objetivo y las herramientas, no la orquestación. Solo pagas por los tokens de la API de Claude.

¿El Claude Agent SDK es lo mismo que el Claude Code SDK?

Sí — es la versión renombrada. Anthropic renombró claude-code-sdk a claude-agent-sdk a finales de 2025, y ClaudeCodeOptions pasó a ser ClaudeAgentOptions. La funcionalidad se mantuvo; solo cambiaron los nombres del paquete y de la clase. Si un tutorial importa los nombres antiguos, es anterior al cambio de nombre y las importaciones fallarán con el paquete actual.

¿Cómo instalo el Claude Agent SDK?

Ejecuta pip install claude-agent-sdk (Python 3.10+) o npm install @anthropic-ai/claude-agent-sdk para TypeScript, y luego configura ANTHROPIC_API_KEY. Como el SDK controla la CLI de Claude Code incluida como un subproceso, también necesitas tener Node.js instalado, incluso para el paquete de Python — la falta de Node es el fallo de instalación más común.

¿Cómo conecto Jira o Shopify a un agente de Claude Agent SDK?

Añade el servidor MCP del proveedor a mcp_servers en ClaudeAgentOptions y permite sus herramientas. Tanto Atlassian (Jira) como Shopify publican servidores MCP, así que no hay que escribir un conector personalizado — registras el servidor con su token de API y enumeras sus herramientas (nombradas mcp__<server>__<tool>) en allowed_tools.

¿Funciona el Claude Agent SDK con una pasarela o proxy?

Sí. Respeta la variable de entorno ANTHROPIC_BASE_URL, por lo que enruta a cualquier backend que exponga la API Anthropic Messages (/v1/messages) sin cambiar el código. Verificamos una solicitud en vivo contra el endpoint compatible con Anthropic de Velokey. Usa ANTHROPIC_API_KEY para proxies x-api-key o ANTHROPIC_AUTH_TOKEN para los que usan token bearer.

¿Qué modelos usa el Claude Agent SDK?

Usa modelos Claude a través de cualquier endpoint al que lo apuntes — por defecto, el más reciente de Anthropic, y puedes establecer uno específico mediante la opción model (por ejemplo claude-sonnet-5 o claude-opus-4-8). A través de una pasarela, puedes seleccionar cualquier modelo Claude que esa pasarela ofrezca, lo cual es útil para usar un modelo más económico en ejecuciones rutinarias de agentes.

¿El Claude Agent SDK es gratis?

El SDK es gratuito y de código abierto, pero ejecutar un agente cuesta tokens de la API de Claude, y los bucles de agente de varios turnos los consumen rápidamente. Controla el gasto eligiendo un modelo más económico para el trabajo rutinario, configurando max_turns y limitando el acceso a herramientas — y aprovecha el almacenamiento en caché de prompts integrado, que sirve el prompt de sistema repetido a aproximadamente una décima parte del precio de entrada.