Claude Agent SDK en Python: crea agentes autónomos paso a paso (tutorial agosto 2026)

El Claude Agent SDK de Anthropic es hoy la vía más rápida para pasar de un script suelto a un agente autónomo real: file editing, ejecución bash, búsqueda web, subagentes delegados, sesiones persistentes y cliente MCP vienen de fábrica. En este tutorial montamos, paso a paso y con código Python real, un agente completo con Claude Opus 5 en menos de 200 líneas, usando la última versión del paquete claude-agent-sdk disponible en agosto de 2026.

Por qué el Agent SDK y no la API directa

Quien haya montado un agente contra la Claude API a mano sabe el ritual: bucle de tool use, gestión del historial, permisos manuales, retries con backoff, contabilidad de coste, cancelación limpia y logging estructurado. El Claude Agent SDK es la librería oficial que Anthropic renombró desde "Claude Code SDK" el 29 de septiembre de 2025, y encapsula exactamente esa infraestructura: la misma que hace funcionar Claude Code en el terminal, expuesta como librería que puedes apuntar a cualquier problema. El propio Anthropic reconoció que el rename responde a que la SDK ha crecido mucho más allá de tareas de código: hay equipos construyendo asistentes legales, advisors financieros, bots de SRE y revisores de seguridad sobre las mismas primitivas.

La diferencia práctica frente al enfoque manual es enorme. Antes escribías cientos de líneas para dar al modelo acceso a bash o al sistema de archivos, gestionar el bucle de tool use, controlar los permisos por acción y mantener el historial dentro del límite de contexto. Ahora el SDK trae esas herramientas activadas, con permisos granulares, checkpoints humanos, subagentes delegados, sesiones persistentes y cliente MCP nativo. Si te interesa el enfoque "manual" para entender qué pasa por debajo tenemos ya un tutorial de agente Claude con MCP a pelo, pero para producción real hoy el atajo correcto es este SDK.

El motor bajo el capó es Claude Opus 5, lanzado el 24 de julio de 2026 con precio de $5 por millón de tokens de entrada y $25 por millón de salida, ventana de contexto de 1 millón de tokens, hasta 128.000 tokens de salida y "adaptive thinking" activo por defecto. El Agent SDK lo usa como cerebro del bucle, aunque puedes cambiar a Sonnet 4.5 (más barato para tareas de tool use rutinarias) o Haiku 4.5 (ideal para subagentes de bajo coste) simplemente cambiando el parámetro model. La flexibilidad de mezclar modelos por rol es una de las claves para que un agente serio no cueste una fortuna.

Requisitos previos

Necesitas Python 3.10 o superior, un gestor moderno como uv (recomendado por Anthropic en la documentación oficial), y una ANTHROPIC_API_KEY o una suscripción activa Pro/Max con créditos SDK ($20/$100/$200 desde el 15 de junio de 2026, ver seccion dedicada más abajo).

Del lado hardware no hay milagros: cualquier laptop moderna sirve, pero para trabajo largo con agentes autónomos (compilaciones, pruebas, generación de documentación) conviene una máquina rápida y una workstation cómoda. Estas son las piezas que uso a diario en mi flujo con Claude Agent SDK:

• MacBook Pro 14" con chip M4 Pro (24 GB, 1 TB) — el cliente ideal para agentes locales con Node/Python.
• Mini PC Beelink SER8 (Ryzen 7 8845HS, 32 GB, 1 TB) — servidor barato y silencioso para dejar el agente corriendo 24/7.
• Monitor LG UltraGear 32GS95UE OLED 4K 240 Hz — 32 pulgadas para tener a la vez chat, código y logs del agente.
• Teclado mecánico Keychron K8 Pro (layout ES) — programable QMK/VIA para bindings del terminal.
• Ratón ergonómico Logitech MX Master 3S — 8K DPI, casi silencioso, imprescindible en sesiones largas.
• Auriculares Sony WH-1000XM5 con cancelación de ruido — para pensar en paz mientras el agente compila.
• Silla ergonómica Secretlab TITAN Evo — obligatoria si programas más de cuatro horas al día.

Con eso listo, arrancamos.

Paso 1: Instalación con uv

La versión disponible del SDK a fecha 4 de agosto de 2026 es la más reciente publicada por Anthropic en PyPI. Instala en un proyecto nuevo con uv (o pip, indistinto):

uv init mi-agente
cd mi-agente
uv add claude-agent-sdk python-dotenv

El paquete trae el binario de Claude Code embebido como dependencia opcional. No necesitas instalarlo por separado: el SDK lo lanza sobre stdio cuando arrancas un agente. Requisito: Python 3.10, 3.11, 3.12 o 3.13.

Ahora el fichero .env:

ANTHROPIC_API_KEY=sk-ant-...
CLAUDE_AGENT_MODEL=claude-opus-5

Gotcha: si vienes del antiguo Claude Code SDK, el tipo ClaudeCodeOptions ha sido renombrado a ClaudeAgentOptions. Migrar es sustituir el import, punto.

Paso 2: Primera invocación de AgentClient

El SDK expone dos modos: query() para un intercambio único y ClaudeSDKClient para conversaciones persistentes. Empezamos por el más sencillo.

import anyio
from dotenv import load_dotenv
from claude_agent_sdk import query, ClaudeAgentOptions

load_dotenv()

async def main():
    options = ClaudeAgentOptions(
        model="claude-opus-5",
        system_prompt="Eres un ingeniero Python sénior. Respondes conciso y en español.",
        max_turns=1,
    )
    async for message in query(
        prompt="Explica en 3 lineas que es un context manager.",
        options=options,
    ):
        print(message)

anyio.run(main)

Resultado esperado: unos mensajes de sistema seguidos de un AssistantMessage con el texto pedido y, al final, un ResultMessage con el coste en tokens y USD.

Trampa común: query() es asíncrono. Envuélvelo con anyio.run() o asyncio.run(). Si lo llamas directamente desde el REPL sin bucle de eventos, no verás nada.

Para conversaciones multi-turn con estado (chat interactivo, TUI, plugin de IDE) existe también ClaudeSDKClient. Se instancia como context manager, mantiene el proceso hijo del CLI vivo entre mensajes y expone un método send_message para enviar turnos adicionales sin reabrir stdio. La regla general: query() para tareas one-shot en scripts y jobs; ClaudeSDKClient cuando el mismo agente responde a muchos mensajes seguidos.

Paso 3: Tool use built-in (bash y file editing)

Aquí empieza la magia: pedimos al agente algo que requiere acción, no solo texto. El SDK tiene las herramientas Read, Write, Edit, Bash, Glob, Grep y varias más ya definidas.

import anyio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        model="claude-opus-5",
        system_prompt="Eres un agente de desarrollo. Escribes codigo Python limpio.",
        permission_mode="acceptEdits",
        max_turns=6,
    )
    prompt = (
        "Crea un archivo hello.py que imprima Hola desde el Agent SDK, "
        "ejecutalo con python3 y muestrame la salida."
    )
    async for message in query(prompt=prompt, options=options):
        print(message)

anyio.run(main)

El agente hará tres tool calls: Write con el contenido del fichero, Bash para ejecutarlo y una respuesta final con la salida capturada.

Trampa común: en permission_mode="default" el SDK te pedirá permiso por cada edit y cada bash. Para automatización usa acceptEdits (auto-aprueba escrituras) o el whitelist del paso 5.

Paso 4: PermissionMode (los cuatro modos)

Es el corazón de la seguridad. Los cuatro modos que necesitas conocer:

• default: pregunta al usuario antes de cada acción destructiva. Ideal en desarrollo local.
• acceptEdits: auto-aprueba las ediciones de archivo, pero sigue pidiendo confirmación en bash y web. Buen equilibrio para tareas de refactor.
• plan: modo lectura. El agente puede explorar (Read, Glob, Grep) pero no escribir ni ejecutar. Sirve para auditorías de seguridad y planificación.
• bypassPermissions: cero fricción, cero pregunta. Solo para entornos aislados (contenedor, sandbox, CI). En producción sin sandbox es un tiro al pie.

from claude_agent_sdk import ClaudeAgentOptions

# Auditoria de seguridad: solo lectura
auditor = ClaudeAgentOptions(
    model="claude-opus-5",
    permission_mode="plan",
    system_prompt="Auditor de seguridad. Nunca modifiques nada.",
)

# Refactor automatico
refactor = ClaudeAgentOptions(
    model="claude-opus-5",
    permission_mode="acceptEdits",
    max_turns=20,
)

# CI aislado
ci_runner = ClaudeAgentOptions(
    model="claude-sonnet-4-5",
    permission_mode="bypassPermissions",
)

Gotcha: bypassPermissions deshabilita también los hooks PreToolUse. Si dependes de ellos para logging o billing, no lo uses.

En la práctica, mi patrón es: plan para la fase de exploración (el agente entiende el repo sin tocar nada), luego acceptEdits para el refactor propuesto y, si algo sale mal, revierto con git. El modo default lo reservo para dev local cuando estoy debuggeando el prompt del sistema y quiero ver cada acción antes de aprobarla. El modo bypassPermissions solo en contenedores Docker efímeros con acceso restringido al filesystem del host.

Paso 5: AllowedTools (whitelist para producción)

En producción no basta con un permission_mode: quieres decir exactamente qué herramientas puede tocar el agente y bloquear el resto. La whitelist es explícita:

from claude_agent_sdk import query, ClaudeAgentOptions

readonly_analyst = ClaudeAgentOptions(
    model="claude-opus-5",
    allowed_tools=["Read", "Glob", "Grep"],
    permission_mode="acceptEdits",
    system_prompt="Analizas repos, nunca los modificas.",
)

code_editor = ClaudeAgentOptions(
    model="claude-opus-5",
    allowed_tools=["Read", "Write", "Edit", "Grep", "Glob"],
    disallowed_tools=["Bash", "WebFetch"],
)

Las tools listadas en allowed_tools se auto-aprueban. Las que no aparecen caen al permission_mode (típicamente denegadas). Si quieres bloquear una tool concreta explícitamente, usa disallowed_tools: gana sobre allowed.

Trampa común: si defines allowed_tools=[] el agente queda mudo, no bloqueado. Para bloquear todo pon un disallowed_tools exhaustivo.

Paso 6: Sessions persistentes

Cada query() arranca de cero. Para mantener contexto entre ejecuciones (por ejemplo, un asistente que retoma la conversación al día siguiente) usa el session_id:

import anyio
from claude_agent_sdk import query, ClaudeAgentOptions

async def primera_llamada():
    session_id = None
    options = ClaudeAgentOptions(model="claude-opus-5")
    async for message in query(prompt="Me llamo Chester y trabajo en Arkaia.", options=options):
        if hasattr(message, "session_id"):
            session_id = message.session_id
        print(message)
    return session_id

async def retomar(session_id: str):
    options = ClaudeAgentOptions(
        model="claude-opus-5",
        resume=session_id,
    )
    async for message in query(prompt="Como me llamo?", options=options):
        print(message)

async def main():
    sid = await primera_llamada()
    await retomar(sid)

anyio.run(main)

La segunda llamada responde con "Chester" porque el historial se rehidrata. Los transcripts se comprimen automáticamente con resumen cuando el contexto se acerca al límite de tokens, así puedes tener sesiones de miles de turnos sin desbordar. El session_id es un UUID que puedes persistir en tu base de datos junto al identificador del usuario o del ticket, lo que abre casos de uso como "retomar la conversación de ayer" o "pasar la sesión de nivel 1 al agente de nivel 2" en soporte técnico.

Paso 7: Subagents delegados

Un subagente es una instancia hija con su propio contexto y sus propios permisos. El agente padre delega tareas concretas y recibe solo el resultado final. Ideal para paralelizar y aislar dominios.

from claude_agent_sdk import ClaudeAgentOptions, AgentDefinition

research_subagent = AgentDefinition(
    description="Investigador. Busca en la web y sintetiza en 200 palabras.",
    prompt="Eres un analista rapido. Devuelve solo la sintesis, nunca el proceso.",
    tools=["WebSearch", "WebFetch", "Read"],
    model="claude-sonnet-4-5",
)

tester_subagent = AgentDefinition(
    description="Ejecuta pytest y devuelve el output.",
    prompt="Corre los tests, no modifiques codigo.",
    tools=["Bash", "Read"],
    model="claude-haiku-4-5",
)

orchestrator = ClaudeAgentOptions(
    model="claude-opus-5",
    agents={
        "researcher": research_subagent,
        "tester": tester_subagent,
    },
    system_prompt=(
        "Eres el orquestador. Delega investigacion a 'researcher' "
        "y ejecucion de tests a 'tester'. Nunca hagas su trabajo tu mismo."
    ),
)

El padre invoca al hijo con la tool Task pasando subagent_type="researcher". El hijo corre en su propio proceso, con su historial separado, y solo el resultado (no el ruido intermedio) llega al padre. Contexto limpio y coste controlado.

Los subagentes también pueden lanzarse en paralelo: si el padre delega dos investigaciones independientes, el SDK las corre a la vez y sincroniza al terminar la más lenta. Esto acelera brutalmente flujos como "lee estos cinco directorios y resume cada uno", donde el padre gasta segundos en lugar de minutos. Los transcripts de cada subagente se persisten dentro de su propia sesión: puedes reanudar un subagente concreto tras reiniciar simplemente resumiendo la misma sesión. Es una feature crítica para procesos largos que no toleran empezar desde cero.

Paso 8: Cliente MCP (conecta tu servidor FastMCP)

El SDK es un cliente MCP nativo. Puedes enchufar cualquier servidor que hayas construido con FastMCP en Python o con TypeScript y sus herramientas aparecen automáticamente en el bucle del agente.

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-opus-5",
    mcp_servers={
        "arkaia-db": {
            "type": "stdio",
            "command": "uv",
            "args": ["run", "servidor_arkaia.py"],
            "env": {"MONGO_URI": "mongodb://..."},
        },
        "weather": {
            "type": "http",
            "url": "https://mcp.example.com/weather",
            "headers": {"Authorization": "Bearer xxx"},
        },
    },
    allowed_tools=[
        "mcp__arkaia-db__count_articulos",
        "mcp__weather__forecast",
        "Read", "Write",
    ],
)

Los nombres de tool MCP siguen el patrón mcp__{servidor}__{tool}. Añádelos al allowed_tools igual que las built-in.

Trampa común: si el proceso stdio del servidor MCP tarda en arrancar (por ejemplo, carga un modelo), aumenta el startup_timeout. Por defecto son 30 segundos.

Paso 9: Streaming token a token

Para interfaces interactivas (chat en vivo, TUI, IDE plugin) no quieres esperar el mensaje completo. Activa el streaming de mensajes parciales:

import anyio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        model="claude-opus-5",
        include_partial_messages=True,
    )
    async for msg in query(prompt="Explica que es MCP en 200 palabras.", options=options):
        # msg puede ser AssistantMessage, PartialAssistantMessage o ResultMessage
        if hasattr(msg, "delta") and msg.delta:
            print(msg.delta, end="", flush=True)

anyio.run(main)

Con include_partial_messages=True el SDK emite deltas del texto según llegan del modelo. Combínalo con un WebSocket para transmitirlos al frontend en tiempo real. Un detalle importante: el streaming solo aplica al texto final del asistente; los tool_use y sus resultados llegan como mensajes atómicos, no fragmentados. Si tu UI necesita indicar "el agente está ejecutando bash..." tendrás que renderizarlo cuando llegue el ToolUseBlock y limpiarlo cuando llegue el ToolResultBlock.

Paso 10: Producción (errores, retries, logging, coste)

Un agente real necesita más que un print. Este es el patrón mínimo que uso en Arkaia:

import anyio, logging, json
from datetime import datetime
from claude_agent_sdk import (
    query, ClaudeAgentOptions,
    ClaudeSDKError, CLINotFoundError, ProcessError,
)

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("agente")

async def run_with_retry(prompt: str, options: ClaudeAgentOptions, retries: int = 3):
    attempt, backoff = 0, 2.0
    while attempt < retries:
        try:
            cost_usd = 0.0
            tokens_in = tokens_out = 0
            async for msg in query(prompt=prompt, options=options):
                if hasattr(msg, "usage"):
                    tokens_in += msg.usage.input_tokens
                    tokens_out += msg.usage.output_tokens
                if hasattr(msg, "total_cost_usd"):
                    cost_usd = msg.total_cost_usd
                log.info(json.dumps({
                    "ts": datetime.utcnow().isoformat(),
                    "type": type(msg).__name__,
                }))
            log.info(f"OK tokens_in={tokens_in} tokens_out={tokens_out} cost=${cost_usd:.4f}")
            return
        except (ProcessError, ClaudeSDKError) as e:
            attempt += 1
            log.warning(f"fallo intento {attempt}: {e}. Reintentando en {backoff}s")
            await anyio.sleep(backoff)
            backoff *= 2
        except CLINotFoundError:
            log.error("El binario de Claude Code no esta instalado. Reinstala el SDK.")
            raise
    log.error("agotados los reintentos")

anyio.run(run_with_retry, "Refactoriza main.py", ClaudeAgentOptions(model="claude-opus-5"))

Cubre lo esencial: retries con backoff exponencial, logging estructurado en JSON, contabilidad de tokens y coste por invocación. En producción añade además métricas Prometheus o traces OpenTelemetry con las hooks PreToolUse/PostToolUse, que se disparan síncronamente antes y después de cada llamada a herramienta y te permiten emitir eventos sin depender del razonamiento del modelo.

Dos consejos adicionales de producción que han evitado facturas sorpresa en Arkaia: primero, poner siempre un max_turns generoso pero acotado (30 a 60 según tarea) para cortar bucles infinitos donde el agente insiste en reintentar lo mismo; segundo, guardar el session_id junto con el cost_usd acumulado en Redis o MongoDB, de forma que puedas trazar exactamente qué sesión (y qué usuario) gastó cada dólar. Con esos dos hábitos la operación de un agente 24/7 pasa de "terror" a "rutina".

Créditos SDK y planes (junio 2026)

El 15 de junio de 2026 Anthropic cambió el modelo económico del SDK. La suscripción Claude Pro/Max ahora incluye un bolsillo separado de créditos SDK cada mes:

El crédito SDK se consume primero. Al agotarlo, si tienes "usage credits" activados, el agente sigue funcionando a tarifas API estándar. No se acumula mes a mes: si no lo gastas, se pierde. Las cuentas Platform con API key no reciben crédito: siguen con pay-as-you-go desde el balance de consola, exactamente igual que antes. Hay que activar el crédito manualmente una vez desde la configuración de la cuenta después del 15 de junio de 2026: si no lo activas, tu SDK sigue tirando del balance API por defecto y el crédito se queda intacto (y se pierde a fin de mes).

En números: con Opus 5 a $5/$25 por millón de tokens, $20 de Pro te dan aproximadamente 2 millones de tokens de entrada o 800.000 tokens de salida al mes en el escenario más caro. Con una mezcla realista (mucho tool use, respuestas cortas) suelen ser 5-10 sesiones agentic al día. Max 20x ($200) escala a equipos pequeños con agentes ejecutándose continuamente, y por debajo de eso el pay-as-you-go directo puede seguir siendo más barato.

Comparativa: Agent SDK vs API bare vs Claude Code CLI

Regla de dedo: si tu producto envuelve a Claude, usa Agent SDK. Si eres tú frente al terminal, Claude Code CLI. Si haces algo muy raro y controlas cada byte del prompt, API bare. Y si dudas entre los tres, empieza por Agent SDK: puedes bajar a Messages API cuando encuentres una limitación real, pero rara vez pasa. Los ejemplos oficiales del repositorio en GitHub cubren skip-permissions, human-in-the-loop, subagentes y hooks, y son una excelente forma de arrancar con código probado en vez de plantillas genéricas.

Casos de uso reales

Estos son los tres patrones que veo funcionar en producción hoy con Agent SDK:

• Code review automático en PRs: hook de GitHub Actions lanza un agente con permission_mode="plan" y allowed_tools=["Read", "Glob", "Grep", "Bash"] que comenta el diff. Coste típico: $0.10 por PR con Opus 5.
• Tickets de soporte con contexto: subagente "kb" consulta la base de conocimiento vía MCP, subagente "crm" abre el ticket. Padre Opus 5, hijos Sonnet o Haiku para bajar coste.
• Generación de documentación: agente escanea el repo, escribe README, docstrings y changelog. Ejecución nocturna en el mini PC, sesión persistente para continuar donde lo dejó.
• Migración de código legado: subagente auditor (plan mode) audita el módulo, subagente migrador (acceptEdits) aplica los cambios, subagente tester (bash only) valida con pytest. Sale por menos de un dólar en repos medianos.
• Data scientist asistido: MCP client conectado a un servidor con tools run_query, plot_chart y export_pdf. El agente entiende la pregunta en lenguaje natural y encadena las tools sin que el analista escriba SQL a mano.

El denominador común: en todos separas responsabilidades entre padre orquestador (Opus 5) y subagentes especializados (Sonnet o Haiku), y cierras la superficie de ataque con allowed_tools más un permission_mode mínimo. Ese patrón, más un buen sistema de logging con coste por sesión, es lo que separa un demo bonito de un producto operado en serio.

Recursos y libros recomendados

Para profundizar en Python idiomático, arquitectura de sistemas y LLMs en producción, estos son los libros de mi mesa (los cuatro imprescindibles para trabajar con agentes en serio):

• "Fluent Python" de Luciano Ramalho (2ª edición) — la biblia del Python moderno, incluyendo asyncio, type hints y descriptors.
• "Architecture Patterns with Python" de Percival y Gregory — TDD, DDD y microservicios event-driven. Aplica directamente a los subagentes.
• "Designing Machine Learning Systems" de Chip Huyen — cómo pensar producción, monitorización y iteración en sistemas de ML.
• "Building LLMs for Production" de Bouchard y Peters — prompting, fine-tuning y RAG, con casos reales.

Complementos oficiales: la documentación de Anthropic y el repositorio en GitHub con ejemplos oficiales de skip-permissions, human-in-the-loop y orquestación.

Preguntas frecuentes (FAQ)

Conclusión

El Claude Agent SDK convierte lo que hace un año era un proyecto de dos semanas en un fichero de 100 líneas. File editing, bash, sesiones, subagentes y MCP salen de fábrica, con permisos granulares y coste medible por invocación. Con Claude Opus 5 detrás y créditos incluidos en las suscripciones Pro y Max, el coste de arrancar es casi cero. Si aún estás enganchado a montar el bucle de tool use a mano, este es el momento de migrar.

El siguiente paso natural, cuando ya tengas tu primer agente funcionando, es construir tus propias tools con MCP y enchufarlas. Ahí es donde el SDK realmente brilla: pasas de un asistente genérico a un agente con acceso a tu CRM, tu base de datos, tu wiki interna y tus scripts internos, sin escribir ni una sola línea de glue code. Los subagentes te permiten además dividir dominios sin ensuciar contexto, y las sesiones persistentes hacen que la experiencia de usuario deje de ser "cada mensaje empieza de cero". Si vienes de agentes montados a mano contra la Messages API, la reducción de código y de bugs es literalmente de un orden de magnitud, y el coste operativo (con la mezcla adecuada de Opus, Sonnet y Haiku) baja al mismo tiempo. Es raro ver a la vez menos código y menos factura, pero en 2026 el Agent SDK lo consigue.