Claude Code SDK (Claude Agent SDK): Guía de Python y TypeScript

El SDK de Claude Code, renombrado como Claude Agent SDK en la versión de SDK de agentes de Anthropic, es una biblioteca de Python y TypeScript para ejecutar agentes de codificación autónomos dentro de tu aplicación. Maneja lecturas de archivos, comandos, ediciones de código, llamadas a herramientas e iteraciones de varios pasos sin necesidad de un bucle de herramientas construido manualmente. Con el endpoint compatible con Anthropic de Novita AI, el mismo SDK también puede ejecutar modelos de peso abierto compatibles, brindando a los equipos una ruta de elección de modelo y control de costos más allá del backend predeterminado de Anthropic.

Esta guía cubre todo lo que los desarrolladores necesitan para comenzar: instalación, la API central query(), herramientas integradas, hooks, sesiones, subagentes, integración MCP y cómo usar la API LLM de Novita AI como backend de modelo.

Puntos clave

• El SDK de Claude Code ahora se llama Claude Agent SDK (claude-agent-sdk para Python, @anthropic-ai/claude-agent-sdk para TypeScript).
• Una única función query() reemplaza el bucle manual de ejecución de herramientas que necesitarías con el SDK de Cliente de Anthropic.
• Las herramientas integradas cubren lectura de archivos, edición, ejecución de bash, búsqueda web y más, sin necesidad de implementación.
• Las sesiones permiten que los agentes reanuden el trabajo a través de múltiples llamadas con todo el contexto intacto.
• Los hooks te permiten validar, registrar o bloquear llamadas a herramientas en puntos específicos del ciclo de vida.
• El endpoint compatible con Anthropic de Novita AI (https://api.novita.ai/anthropic) te permite usar modelos de peso abierto de alta calidad con el mismo código del SDK.

¿Qué es el SDK de Claude Code?

El SDK de Claude Code es una interfaz programática para las capacidades de agente de Claude Code. Expone las mismas herramientas, bucle de razonamiento y gestión de contexto que la CLI de Claude Code utiliza interactivamente, pero como una biblioteca que importas y llamas desde tu propio código.

Anthropic lo renombró a Claude Agent SDK a partir de la generación 4.6, pero el término de búsqueda original “claude code sdk” sigue describiendo con precisión lo que es: la capa de SDK que se sitúa sobre Claude Code y te permite automatizar tareas de agente en software.

Para qué es bueno:

• Revisión de código automatizada, refactorización o generación de pruebas en CI/CD
• Agentes que leen y modifican archivos, ejecutan scripts o buscan en la web en tu nombre
• Pipelines multiagente donde un coordinador delega subtareas a trabajadores especializados
• Cualquier flujo de trabajo donde quieras que Claude tome medidas autónomas de varios pasos, no solo responder a un prompt

Para qué no sirve: Si necesitas control directo sobre cada mensaje, salida estructurada de una sola llamada o respuestas en streaming para una interfaz de chat, el SDK de Cliente de Anthropic es más apropiado.

SDK de Claude Code vs. SDK de Cliente de Anthropic: cuándo usar cada uno

Ambos SDK se basan en Claude, pero resuelven problemas diferentes.

	Claude Agent SDK	SDK de Cliente de Anthropic
Ejecución de herramientas	Gestionada autónomamente por Claude	Tú implementas el bucle de herramientas
Interfaz	query() devuelve un iterador asíncrono	client.messages.create() devuelve un objeto de respuesta
Herramientas integradas	Leer, Escribir, Editar, Bash, Grep, Glob, WebSearch y más	Ninguna: tú defines y ejecutas todas las herramientas
Sesiones	Integradas: reanuda con un ID de sesión	Manual: gestiona el historial de la conversación tú mismo
Mejor para	Pipelines de agentes, CI/CD, operaciones con archivos	Aplicaciones de chat, salida estructurada, control detallado

Si quieres que Claude descubra qué archivos leer y los edite autónomamente: Agent SDK. Si quieres que Claude responda a un prompt específico y devuelva un valor que tú proceses: Client SDK.

Instalar el Claude Agent SDK

Python (requiere Python 3.10+):

pip install claude-agent-sdk

TypeScript / Node.js:

npm install @anthropic-ai/claude-agent-sdk

El paquete TypeScript incluye un binario nativo de Claude Code para tu plataforma como dependencia opcional. No necesitas instalar Claude Code por separado.

Para verificar tu versión de Python antes de instalar:

python3 --version  # macOS/Linux
py --version       # Windows

Si pip reporta No matching distribution found for claude-agent-sdk, tu intérprete de Python es anterior a 3.10.

Paso 1: Configurar la autenticación

Establece tu clave de API de Anthropic como variable de entorno:

export ANTHROPIC_API_KEY=tu-clave-api

El SDK también admite Amazon Bedrock, Google Vertex AI y Azure AI Foundry para equipos que enrutan a través de proveedores en la nube:

# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
# más credenciales estándar de AWS

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
# más GOOGLE_CLOUD_PROJECT y credenciales de gcloud

# Microsoft Azure AI Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
# más credenciales de Azure

Paso 2: Ejecutar tu primera consulta de agente

Toda la superficie del SDK se basa en una única función: query(). Acepta un prompt y opciones, y devuelve un iterador asíncrono de eventos de mensaje.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Lista todos los archivos Python en este directorio",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Lista todos los archivos Python en este directorio",
  options: { allowedTools: ["Bash", "Glob"] }
})) {
  if ("result" in message) console.log(message.result);
}

El iterador produce varios tipos de mensajes. Los dos más útiles:

• ResultMessage (o mensajes con un campo result) — la respuesta final del agente
• SystemMessage con subtype === "init" — lleva el session_id para reanudar más tarde

Paso 3: Controlar permisos con allowedTools

El SDK incluye herramientas preimplementadas. Tú declaras cuáles puede usar el agente; Claude maneja la ejecución.

Herramienta	Qué hace
Read	Leer cualquier archivo en el directorio de trabajo
Write	Crear nuevos archivos
Edit	Hacer ediciones específicas en archivos existentes
Bash	Ejecutar comandos de shell, scripts, operaciones de git
Glob	Encontrar archivos por patrón (**/*.ts, src/**/*.py)
Grep	Buscar contenido de archivos con regex
WebSearch	Buscar en la web información actual
WebFetch	Obtener y analizar contenido de páginas web
Monitor	Observar un script en segundo plano y reaccionar a líneas de salida
AskUserQuestion	Preguntar al usuario preguntas aclaratorias durante la tarea
Agent	Invocar un subagente definido

La combinación de Bash + Read + Edit es suficiente para la mayoría de las tareas automatizadas de código. Añade WebSearch o WebFetch cuando el agente necesite datos externos.

allowed_tools (Python) / allowedTools (TypeScript) preaprueba herramientas específicas sin solicitar confirmación. Restringir el conjunto de herramientas también limita lo que el agente puede hacer involuntariamente, una salvaguarda útil para pipelines automatizados.

Agente de revisión de código de solo lectura:

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Revisa este código en busca de problemas de seguridad y mal olor",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
    ),
):
    if hasattr(message, "result"):
        print(message.result)

Agente de edición completa (preaprueba escrituras de archivos):

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Edit", "Bash"],
    permission_mode="acceptEdits",
)

permission_mode="acceptEdits" autoaprueba las ediciones de archivos sin un prompt interactivo, lo cual es necesario cuando se ejecuta en CI.

Paso 4: Usar hooks para control del ciclo de vida

Los hooks te permiten ejecutar código personalizado en puntos definidos de la ejecución del agente. Puedes registrar acciones, validar entradas, bloquear operaciones peligrosas o actualizar estado externo.

Eventos de hook disponibles: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStop, SubagentStart, PreCompact, Notification, PermissionRequest

Este ejemplo escribe un registro de auditoría cada vez que el agente edita o crea un archivo:

import asyncio
from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher

async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now().isoformat()}: modified {file_path}\n")
    return {}

async def main():
    async for message in query(
        prompt="Refactoriza auth.py para usar dataclasses",
        options=ClaudeAgentOptions(
            permission_mode="acceptEdits",
            hooks={
                "PostToolUse": [
                    HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
                ]
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";
import { appendFile } from "fs/promises";

const logFileChange: HookCallback = async (input) => {
  const filePath = (input as any).tool_input?.file_path ?? "unknown";
  await appendFile("./audit.log", `${new Date().toISOString()}: modified ${filePath}\n`);
  return {};
};

for await (const message of query({
  prompt: "Refactoriza auth.ts para usar interfaces",
  options: {
    permissionMode: "acceptEdits",
    hooks: {
      PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }]
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

Un hook PreToolUse que devuelve { block: true } evitará la llamada a la herramienta por completo, útil para aplicar políticas como “nunca eliminar archivos” en contextos automatizados.

Paso 5: Reanudar trabajo con sesiones

Las sesiones preservan el contexto completo del agente (qué archivos leyó, qué encontró, el historial de la conversación) a través de múltiples llamadas a query(). Esto te permite dividir una tarea larga en pasos o continuar un trabajo que fue interrumpido.

Para reanudar una sesión, captura el session_id del evento de inicio de SystemMessage, luego pásalo a resume:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage

async def main():
    session_id = None

    # Primera consulta: leer y analizar el código
    async for message in query(
        prompt="Lee el módulo de autenticación e identifica todas las dependencias externas",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    ):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            session_id = message.data["session_id"]

    # Segunda consulta: continuar con el contexto completo de la primera
    async for message in query(
        prompt="Ahora verifica si alguna de esas dependencias tiene vulnerabilidades conocidas",
        options=ClaudeAgentOptions(
            resume=session_id,
            allowed_tools=["Read", "Bash", "WebSearch"],
        ),
    ):
        if isinstance(message, ResultMessage):
            print(message.result)

asyncio.run(main())

El segundo prompt usa “esas dependencias”, una referencia que solo tiene sentido porque la sesión lleva el contexto de la primera llamada. Sin resume, Claude no tendría idea de a qué te refieres.

Paso 6: Delegar tareas con subagentes

Los subagentes son agentes especializados que tu agente principal puede invocar mediante la herramienta Agent. El agente principal coordina; los subagentes hacen trabajo enfocado. Los resultados vuelven al contexto principal.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Revisa este código: usa el agente security-auditor para archivos de autenticación y el agente style-checker para todo lo demás",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "security-auditor": AgentDefinition(
                    description="Especialista en seguridad de autenticación y autorización.",
                    prompt="Audita el código relacionado con autenticación para vulnerabilidades OWASP Top 10. Sé específico sobre números de línea y gravedad del riesgo.",
                    tools=["Read", "Glob", "Grep"],
                ),
                "style-checker": AgentDefinition(
                    description="Revisor de estilo de código y mantenibilidad.",
                    prompt="Revisa el código en busca de convenciones de nombres, complejidad y brechas de documentación.",
                    tools=["Read", "Glob"],
                ),
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Incluye "Agent" en allowed_tools para preaprobar las invocaciones a subagentes. Los mensajes de un subagente incluyen un campo parent_tool_use_id para que puedas rastrear qué salida provino de qué subagente.

Paso 7: Conectar sistemas externos mediante MCP

El Protocolo de Contexto de Modelo (MCP) te permite agregar capacidades externas al agente (bases de datos, navegadores, API internas) sin escribir herramientas personalizadas. El agente trata las herramientas MCP igual que las herramientas integradas.

Este ejemplo añade automatización de navegador a través del servidor MCP de Playwright:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Abre https://example.com y describe la estructura de la página",
        options=ClaudeAgentOptions(
            mcp_servers={
                "playwright": {
                    "command": "npx",
                    "args": ["@playwright/mcp@latest"]
                }
            }
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

La opción mcp_servers acepta cualquier servidor que siga la especificación MCP. El registro comunitario de MCP en github.com/modelcontextprotocol/servers enumera cientos de integraciones que incluyen Postgres, Puppeteer, Slack, GitHub y variantes del sistema de archivos.

Usar Novita AI como backend de modelo

El SDK de Claude Agent usa por defecto la API de Anthropic, pero puedes apuntarlo al endpoint compatible con Anthropic de Novita AI para usar modelos de peso abierto rentables, sin cambios de código.

El endpoint de Novita AI refleja el formato de la API de Anthropic:

https://api.novita.ai/anthropic

Establece estas dos variables de entorno antes de ejecutar tu agente:

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_API_KEY="tu-clave-api-de-novita"

Tus llamadas existentes a query() funcionan sin modificación. El SDK lee ANTHROPIC_BASE_URL automáticamente.

Novita AI aloja una variedad de modelos, incluyendo Kimi K2.5, GLM 5.2, MiniMax M2.1 y Qwen 3.5, que son accesibles a través de este endpoint. Para equipos que construyen pipelines de agentes que ejecutan miles de tareas, la diferencia de costo por token puede ser significativa. Consulta API LLM de Novita AI para el catálogo de modelos actual y precios.

Si necesitas desplegar tu agente en infraestructura aislada en entorno sandbox (útil para ejecución de código de agente donde no quieres que el agente toque tu sistema de archivos host), Novita Agent Sandbox proporciona un entorno de ejecución compatible con E2B diseñado específicamente para agentes construidos con el SDK de Claude Agent.

SDK de Claude Code en pipelines CI/CD

Las restricciones permission_mode="acceptEdits" y allowed_tools del SDK hacen práctico ejecutar agentes sin supervisión en CI. Un patrón típico de GitHub Actions:

- name: Ejecutar revisión de código automatizada
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    python review_agent.py

Donde review_agent.py contiene algo como:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Revisa todos los archivos Python modificados en este PR en busca de corrección y brechas de cobertura de pruebas. Genera un informe JSON.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Bash"],
            permission_mode="acceptEdits",
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Para agentes que escriben de vuelta al repositorio (refactorización automatizada, generación de documentación), combina esto con un hook PostToolUse que valide los cambios antes de que lleguen a git.

Solución de problemas

No matching distribution found for claude-agent-sdk Tu versión de Python es inferior a 3.10. Ejecuta python3 --version y actualiza si es necesario.

ANTHROPIC_API_KEY is not set El SDK requiere la variable de entorno. Expórtala en tu shell o archivo .env antes de ejecutar.

El agente TypeScript termina antes de completar Asegúrate de usar await en el bucle completo del iterador. El SDK necesita procesar todos los eventos de mensaje antes de que tu proceso termine.

El agente usa herramientas inesperadas Usa allowed_tools para restringir explícitamente el conjunto de herramientas. Si no lo especificas, el agente tiene acceso a todas las herramientas integradas.

Los mensajes de subagente no aparecen en la salida Filtra los mensajes donde parent_tool_use_id esté configurado para identificar la salida del subagente por separado del agente principal.

La sesión no se reanuda correctamente Captura session_id del SystemMessage con subtype === "init" al inicio de la primera consulta, no de un mensaje de resultado.

Preguntas frecuentes

¿Cuál es la diferencia entre el SDK de Claude Code y el SDK de Anthropic?

El SDK de Claude Agent (anteriormente SDK de Claude Code) te proporciona un agente autónomo que maneja la ejecución de herramientas automáticamente. El SDK de Cliente de Anthropic te da acceso directo a la API donde tú implementas el bucle de herramientas tú mismo. Usa el SDK de Agent para pipelines de agentes; usa el SDK de Cliente para llamadas directas al modelo con control preciso.

¿Qué versión de Python se requiere para claude-agent-sdk?

Python 3.10 o posterior. El paquete no se instalará en Python 3.9 o anterior.

¿Necesito instalar la CLI de Claude Code para usar el SDK de TypeScript?

No. El paquete @anthropic-ai/claude-agent-sdk incluye su propio binario nativo de Claude Code como dependencia opcional.

¿Puede el SDK de Claude Agent usar modelos que no sean Claude de Anthropic?

Configurando ANTHROPIC_BASE_URL en un endpoint compatible con Anthropic como https://api.novita.ai/anthropic, puedes usar cualquier modelo que ese proveedor aloje, incluidos modelos de peso abierto de Kimi, GLM, MiniMax o Qwen.

¿En qué se diferencia el SDK de Agent de los Agentes Gestionados de Claude?

Los Agentes Gestionados son una API REST alojada donde Anthropic ejecuta el agente en su infraestructura. El SDK de Agent es una biblioteca que ejecuta el bucle del agente en tu propio proceso, en tu propio sistema de archivos. El SDK de Agent es mejor para desarrollo local y agentes que necesitan acceder a tus archivos o servicios privados.

¿El SDK de Claude Agent admite salida en streaming?

La función query() devuelve un iterador asíncrono que produce mensajes a medida que el agente trabaja. Esto te da un comportamiento similar al streaming: ves resultados intermedios antes de la respuesta final.

¿Puedo usar el SDK de Agent con Amazon Bedrock o Vertex AI?

Sí. Establece CLAUDE_CODE_USE_BEDROCK=1 más credenciales de AWS para Bedrock, o CLAUDE_CODE_USE_VERTEX=1 más credenciales de Google Cloud para Vertex AI.

¿Qué documentación del SDK de agente de anthropic claude debería leer primero?

Los documentos oficiales están en code.claude.com/docs/en/agent-sdk/overview. Comienza con el inicio rápido, luego lee las guías de sesiones y hooks una vez que tengas un agente funcionando.

Artículos recomendados

• Documentación de la CLI de Claude Code: configuración, comandos slash e integración con API LLM
• SDK de Vercel AI: guía completa para desarrolladores para construir aplicaciones de IA
• Cómo desplegar y alojar el SDK de Claude Agent con Novita Sandbox

---

Fuentes consultadas el 3 de julio de 2026: Documentación de Claude Agent SDK, API LLM de Novita AI