Claude Code SDK: Tutorial Completo
Guía práctica de 20 capítulos para construir agentes de IA autónomos usando el SDK oficial de Anthropic. Cada capítulo incluye ejemplos completos en Python y TypeScript.
Arquitectura del SDK
flowchart TB
subgraph TuApp["Tu Aplicación"]
Python["Python\nclaude-code-sdk"]
TS["TypeScript\n@anthropic-ai/claude-code-sdk"]
end
subgraph SDK["Claude Code SDK"]
QueryFn["query()"]
Client["ClaudeSDKClient"]
Options["ClaudeCodeOptions"]
end
subgraph CLI["Claude Code CLI (subproceso)"]
AgentLoop["Agent Loop"]
Tools["Herramientas integradas\nRead, Edit, Write, Bash..."]
MCPServers["MCP Servers"]
Hooks["Hooks\nPreTool, PostTool, Stop"]
end
subgraph External["Servicios Externos"]
AnthAPI["Anthropic API\n(LLM)"]
FS["Sistema de\nArchivos"]
Terminal["Terminal\n(Bash)"]
MCP["Servidores\nMCP"]
end
Python --> QueryFn
TS --> QueryFn
QueryFn --> Client
Client --> |"spawn subprocess\nJSON Lines stdio"| AgentLoop
AgentLoop --> Tools
AgentLoop --> MCPServers
AgentLoop --> Hooks
AgentLoop --> AnthAPI
Tools --> FS
Tools --> Terminal
MCPServers --> MCP
Tabla de Contenidos
Bloque 1: Fundamentos
| Cap | Título | Descripción |
|---|
| 01 | Introducción | Qué es el SDK, casos de uso, comparación con otras herramientas |
| 02 | Instalación y Configuración | Setup de Python/TS, API key, primera ejecución |
| 03 | Query Básico | La función query(), opciones, iteración de mensajes |
| 04 | Herramientas Integradas | Read, Edit, Write, Bash, Glob, Grep y cuándo usarlas |
| 05 | Model Context Protocol | Integrar servidores MCP para extender capacidades |
Bloque 2: Core Features
| Cap | Título | Descripción |
|---|
| 06 | Sistema de Hooks | PreToolUse, PostToolUse, Stop — interceptar y controlar |
| 07 | Subagentes | Patrones de orquestación y delegación de tareas |
| 08 | Manejo de Sesiones | Reanudar sesiones, session_id, estado persistente |
| 09 | Casos de Uso Prácticos | Code review, migración de código, análisis de repositorios |
| 10 | Mejores Prácticas | Seguridad, performance, mantenibilidad, testing |
Bloque 3: Funcionalidades Avanzadas
| Cap | Título | Descripción |
|---|
| 11 | Streaming y Eventos en Tiempo Real | SSE, WebSockets, terminal output, cancelación |
| 12 | Testing de Agentes | Unit, integration, e2e, evals, LLM-as-judge, CI/CD |
| 13 | Manejo de Errores y Resiliencia | Retry, circuit breaker, rollback, human-in-the-loop |
| 14 | Seguridad y Permisos Avanzados | Threat model, sandboxing, RBAC, secrets management |
| 15 | Performance y Optimización | Prompt caching, paralelismo, model routing, costos |
| 16 | Integración con Frameworks | FastAPI, Express, Hono, Next.js, queues |
Bloque 4: Producción y Escala
| Cap | Título | Descripción |
|---|
| 17 | Deployment en Producción | Docker, Kubernetes, serverless, CI/CD, Railway, Render |
| 18 | Monitoreo y Observabilidad | Logs estructurados, Prometheus, OpenTelemetry, Grafana |
| 19 | Patrones Multi-Agente Avanzados | Reflection, Debate, Ensemble, Verificación cruzada |
| 20 | SDK Internals y Extensiones | Cómo funciona el SDK, extensiones, interoperabilidad |
| 21 | Referencia Rápida y Cookbook | Cheat sheets, recetas listas, troubleshooting guide |
Paquetes Oficiales
| Lenguaje | Paquete | Instalación | Importación |
|---|
| Python | claude-code-sdk | pip install claude-code-sdk | from claude_code_sdk import query, ClaudeCodeOptions |
| TypeScript | @anthropic-ai/claude-code-sdk | npm install @anthropic-ai/claude-code-sdk | import { query, ClaudeCodeOptions } from "@anthropic-ai/claude-code-sdk" |
Nota importante: El paquete Python se instala como claude-code-sdk pero se importa como claude_code_sdk (guiones → guiones bajos). El paquete TypeScript usa el scope @anthropic-ai.
Ejemplo Rápido: Hello World
Python
import asyncio
from claude_code_sdk import query, ClaudeCodeOptions
async def main():
async for message in query(
prompt="¿Cuántos archivos .py hay en el directorio actual?",
options=ClaudeCodeOptions(
allowed_tools=["Bash"],
max_turns=5
)
):
if hasattr(message, 'content') and message.content:
print(message.content)
asyncio.run(main())
TypeScript
import { query, ClaudeCodeOptions } from "@anthropic-ai/claude-code-sdk";
async function main(): Promise<void> {
for await (const message of query(
"¿Cuántos archivos .ts hay en el directorio actual?",
{
allowedTools: ["Bash"],
maxTurns: 5,
} as ClaudeCodeOptions
)) {
if ("content" in message && message.content) {
console.log(message.content);
}
}
}
main();
Ejemplo más completo: Agente de análisis de código
import asyncio
from claude_code_sdk import query, ClaudeCodeOptions
async def code_analyzer(file_path: str) -> dict:
"""Analiza un archivo de código y retorna hallazgos."""
results = []
session_id = None
total_cost = 0.0
async for message in query(
prompt=f"""
Analiza el archivo {file_path}:
1. Lista los bugs potenciales
2. Sugiere mejoras de rendimiento
3. Verifica el manejo de errores
""",
options=ClaudeCodeOptions(
allowed_tools=["Read", "Bash"],
max_turns=20
)
):
if hasattr(message, 'session_id') and message.session_id:
session_id = message.session_id
if hasattr(message, 'cost_usd') and message.cost_usd:
total_cost += float(message.cost_usd)
if hasattr(message, 'content') and message.content:
results.append(str(message.content))
return {
"analysis": "\n".join(results),
"session_id": session_id,
"cost_usd": round(total_cost, 6)
}
async def main():
result = await code_analyzer("src/main.py")
print(f"Análisis completado (costo: ${result['cost_usd']})")
print(result["analysis"])
asyncio.run(main())
Requisitos Previos
Obligatorios
- Python 3.10+ o Node.js 18+
- Claude Code CLI instalado:
npm install -g @anthropic-ai/claude-code
- API Key de Anthropic: Obtener en console.anthropic.com
- Variable de entorno:
export ANTHROPIC_API_KEY="sk-ant-..."
Conocimientos necesarios
- Python o TypeScript (nivel intermedio)
async/await (fundamental — el SDK es completamente asíncrono)- Conceptos básicos de línea de comandos
Verificar instalación
# Verificar Claude Code CLI
claude --version
# Verificar variable de entorno
echo $ANTHROPIC_API_KEY
# Test rápido desde Python
python3 -c "
import asyncio
from claude_code_sdk import query, ClaudeCodeOptions
async def test():
async for msg in query('Hola', options=ClaudeCodeOptions(allowed_tools=[], max_turns=1)):
print('SDK funcionando:', type(msg).__name__)
asyncio.run(test())
"
Diagrama de Flujo de un Query
sequenceDiagram
participant Code as Tu código
participant SDK as Claude Code SDK
participant CLI as claude -p (CLI)
participant API as Anthropic API
participant Tools as Herramientas
Code->>SDK: query(prompt, options)
SDK->>CLI: spawn subprocess
CLI->>API: POST /messages (LLM call 1)
API-->>CLI: AssistantMessage (puede incluir tool_use)
CLI-->>SDK: JSON line: AssistantMessage
SDK-->>Code: yield AssistantMessage
CLI->>Tools: Ejecutar herramienta (ej: Read file)
Tools-->>CLI: Resultado de herramienta
CLI-->>SDK: JSON line: ToolResultMessage
SDK-->>Code: yield ToolResultMessage
CLI->>API: POST /messages (LLM call 2, con tool result)
API-->>CLI: AssistantMessage final
CLI-->>SDK: JSON line: ResultMessage
SDK-->>Code: yield ResultMessage (con cost_usd)
CLI->>CLI: exit
SDK->>SDK: cerrar proceso
Links a Documentación Oficial