Guía del SDK de Agente de Claude (anteriormente SDK de Claude Code): Python y TypeScript

El SDK de Claude Code, renombrado como SDK de Agente de Claude en el lanzamiento del 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. Gestiona lectura de archivos, comandos, ediciones de código, llamadas a herramientas e iteración en varios pasos sin 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, lo que brinda a los equipos una ruta de elección de modelo y control de costos más allá del backend predeterminado de Anthropic. Para la disyuntiva entre suscripción y API, consulta Precio de la API de Claude vs planes de suscripción.

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

Puntos Clave

• El SDK de Claude Code ahora se llama SDK de Agente de Claude (claude-agent-sdk para Python, @anthropic-ai/claude-agent-sdk para TypeScript).
• Una sola 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 en múltiples llamadas con el contexto completo 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 a 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 usa de forma interactiva — pero como una biblioteca que importas y llamas desde tu propio código. Para reglas y alcance a nivel de proyecto, consulta Reglas de Claude Code y CLAUDE.md.

Anthropic lo renombró a SDK de Agente de Claude a partir de la generación 4.6, pero el término de búsqueda original “claude code sdk” todavía describe con precisión lo que es: la capa de SDK que se asienta 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 de múltiples agentes donde un coordinador delega subtareas a trabajadores especializados
• Cualquier flujo de trabajo donde quieras que Claude tome acciones autónomas de múltiples pasos, no solo responda a un prompt

Para qué no es: 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.

	SDK de Agente de Claude	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	Read, Write, Edit, Bash, Grep, Glob, WebSearch y más	Ninguna — defines y ejecutas todas las herramientas
Sesiones	Integradas — reanuda con un ID de sesión	Manuales — gestiona el historial de conversación tú mismo
Mejor para	Pipelines agénticos, CI/CD, operaciones con archivos	Aplicaciones de chat, salida estructurada, control fino

Si quieres que Claude descubra qué archivos leer y los edite de forma autónoma: SDK de Agente. Si quieres que Claude responda a un prompt específico y devuelva un valor que tú procesas: SDK de Cliente.

Instalar el SDK de Agente de Claude

Python (requiere Python 3.10+):

pip install claude-agent-sdk

TypeScript / Node.js:

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

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

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

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

Si pip informa 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-de-api

El SDK también es compatible con Amazon Bedrock, Google Vertex AI y Azure AI Foundry para equipos que enrutan a través de proveedores de 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: Ejecuta tu Primera Consulta de Agente

Toda la superficie del SDK se construye alrededor de una sola 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="List all Python files in this directory",
        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: "List all Python files in this directory",
  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: Controla los Permisos con allowedTools

El SDK incluye herramientas preimplementadas. Declaras cuáles puede usar el agente; Claude gestiona la ejecución.

Herramienta	Qué hace
Read	Lee cualquier archivo en el directorio de trabajo
Write	Crea archivos nuevos
Edit	Realiza ediciones específicas en archivos existentes
Bash	Ejecuta comandos de shell, scripts, operaciones de git
Glob	Encuentra archivos por patrón (**/*.ts, src/**/*.py)
Grep	Busca contenido de archivos con regex
WebSearch	Busca en la web información actual
WebFetch	Obtiene y analiza el contenido de páginas web
Monitor	Observa un script en segundo plano y reacciona a líneas de salida
AskUserQuestion	Pregunta al usuario preguntas aclaratorias a mitad de la tarea
Agent	Invoca un subagente definido

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

allowed_tools (Python) / allowedTools (TypeScript) preaprueba herramientas específicas sin preguntar. 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="Review this codebase for security issues and code smell",
    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" aprueba automáticamente las ediciones de archivos sin un prompt interactivo, lo cual es necesario al ejecutar en CI.

Paso 4: Usa 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="Refactor auth.py to use 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: "Refactor auth.ts to use 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: Reanuda Trabajo con Sesiones

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

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

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

async def main():
    session_id = None

    # First query: read and analyze the codebase
    async for message in query(
        prompt="Read the authentication module and identify all external dependencies",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    ):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            session_id = message.data["session_id"]

    # Second query: continue with full context from the first
    async for message in query(
        prompt="Now check if any of those dependencies have known vulnerabilities",
        options=ClaudeAgentOptions(
            resume=session_id,
            allowed_tools=["Read", "Bash", "WebSearch"],
        ),
    ):
        if isinstance(message, ResultMessage):
            print(message.result)

asyncio.run(main())

El segundo prompt usa “those dependencies” — 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: Delega 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 fluyen de vuelta al contexto principal.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Review this codebase: use the security-auditor agent for auth files and the style-checker agent for everything else",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "security-auditor": AgentDefinition(
                    description="Specialist in authentication and authorization security.",
                    prompt="Audit auth-related code for OWASP Top 10 vulnerabilities. Be specific about line numbers and risk severity.",
                    tools=["Read", "Glob", "Grep"],
                ),
                "style-checker": AgentDefinition(
                    description="Code style and maintainability reviewer.",
                    prompt="Check code for naming conventions, complexity, and documentation gaps.",
                    tools=["Read", "Glob"],
                ),
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Incluye "Agent" en allowed_tools para preaprobar invocaciones de 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: Conecta Sistemas Externos vía MCP

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

Este ejemplo agrega automatización de navegador mediante el servidor MCP de Playwright:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Open https://example.com and describe the page structure",
        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, incluidas Postgres, Puppeteer, Slack, GitHub y variantes del sistema de archivos.

Usa Novita AI como Backend de Modelo

El SDK de Agente de Claude 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 replica 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-de-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 de LLM de Novita AI para el catálogo de modelos actual y los precios.

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

SDK de Claude Code en Pipelines de CI/CD

Las restricciones de 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: Run automated code review
  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="Review all changed Python files in this PR for correctness and test coverage gaps. Output a JSON report.",
        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 en el 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. Exponla en tu shell o archivo .env antes de ejecutar.

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

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 subagentes 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 Agente de Claude (anteriormente SDK de Claude Code) te brinda un agente autónomo que gestiona la ejecución de herramientas automáticamente. El SDK de Cliente de Anthropic te brinda acceso directo a la API donde tú implementas el bucle de herramientas. Usa el SDK de Agente para pipelines agénticos; 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 Agente de Claude usar modelos que no sean los de Anthropic?

Al configurar 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 Agente de Claude Managed Agents?

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

¿El SDK de Agente de Claude admite salida en streaming?

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

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

Sí. Configura 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 Claude debería leer primero?

La documentación oficial está en code.claude.com/docs/en/agent-sdk/overview. Comienza con el inicio rápido y luego lee las guías de sesiones y hooks una vez que tengas un agente funcional.

Artículos Recomendados

• Cómo Usar Agentes de Claude Code: Configuración, Herramientas, Permisos y Flujo de Trabajo con Sandbox
• Plugins de Claude Code: Cómo las Herramientas MCP Extienden Claude Code con Capacidades Externas
• Reglas de Claude Code: Cómo Escribir CLAUDE.md y Gestionar el Contexto de Codificación Agéntico
• Documentación de la CLI de Claude Code: Configuración, Comandos Slash e Integración con API de LLM
• SDK de IA de Vercel: Guía Completa para Desarrolladores para Crear Aplicaciones de IA
• Cómo Implementar y Alojar el SDK de Agente de Claude con Novita Sandbox

---

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