Básicos del Claude Agent SDK

9 ejemplos para empezar a usar el Claude Agent SDK: 6 básicos y 3 intermedios.

Prerrequisitos

Instala el paquete de Python: pip install claude-agent-sdk (TypeScript: npm install @anthropic-ai/claude-agent-sdk).
Configura una clave API en tu entorno: export ANTHROPIC_API_KEY=sk-ant-....
El SDK incluye su propio binario CLI internamente; no necesitas instalar Claude Code por separado para usarlo.
Los ejemplos a continuación usan asyncio ya que query() del SDK de Python es un generador asíncrono.

Ejemplos Básicos

1. Tu primer `query()`

La estructura mínima: un prompt, herramientas predeterminadas, respuesta transmitida.

import asyncio
from claude_agent_sdk import query
 
async def main():
    async for message in query(prompt="¿Cuánto es 17 * 34?"):
        print(message)
 
asyncio.run(main())

query() devuelve un iterador asíncrono de mensajes, no una cadena única.
Sin pasar options, el agente se ejecuta con el conjunto de herramientas predeterminado del SDK.
Cada mensaje emitido representa un paso del bucle subyacente de uso de herramientas, incluida la respuesta final.

Relacionado: El Modelo Mental del Claude Agent SDK - qué sucede detrás de esta llamada

2. Selección de un Modelo

Elige un modelo específico en lugar del predeterminado del SDK.

from claude_agent_sdk import query, AgentOptions
 
options = AgentOptions(model="claude-sonnet-5")
 
async for message in query(prompt="Resume este changelog.", options=options):
    print(message)

AgentOptions es donde reside la mayor parte de la configuración por llamada.
claude-sonnet-5 es el predeterminado equilibrado actual; claude-haiku-4-5 intercambia calidad por velocidad y costo.
La elección del modelo no cambia la mecánica del bucle, solo qué modelo toma cada decisión.

3. Ámbito del Acceso a Herramientas

Restringe qué herramientas integradas puede llamar el agente.

from claude_agent_sdk import query, AgentOptions
 
options = AgentOptions(allowed_tools=["file_edit"])
 
async for message in query(
    prompt="Corrige la errata en README.md",
    options=options,
):
    print(message)

allowed_tools es una lista explícita de permitidos; todo lo que no esté listado no estará disponible para el bucle.
Limitar solo a file_edit significa que este agente no puede ejecutar comandos bash ni buscar en la web, incluso si quisiera.
Empieza de forma restrictiva y amplía solo cuando una tarea realmente necesite más.

Relacionado: Habilitar Herramientas de Edición de Archivos, Bash y Web en el Agent SDK - guía completa sobre el ámbito de las herramientas

4. Lectura del Directorio de Trabajo

Apunta el agente a la raíz de un proyecto específico.

from claude_agent_sdk import query, AgentOptions
 
options = AgentOptions(
    cwd="/ruta/al/proyecto",
    allowed_tools=["file_edit", "bash"],
)
 
async for message in query(prompt="Lista las pruebas fallidas.", options=options):
    print(message)

cwd limita las operaciones de archivos y bash a un árbol de directorios específico.
Establecer cwd explícitamente evita sorpresas cuando el SDK se ejecuta desde un directorio de trabajo de proceso diferente.
Combina con allowed_tools para que el agente pueda inspeccionar y actuar sobre ese proyecto.

5. Transmitir Texto a Medida que Llega

Imprime solo el contenido de texto del asistente en lugar de cada tipo de mensaje.

from claude_agent_sdk import query
 
async for message in query(prompt="Explica qué hace este repositorio."):
    if message.get("type") == "text":
        print(message["text"], end="", flush=True)

El flujo de mensajes mezcla eventos de llamada a herramientas, resultados de herramientas y texto; filtrar por type te da solo el texto.
La transmisión te permite mostrar el progreso en una CLI o UI en lugar de esperar a que termine todo el bucle.
Las formas exactas de los mensajes se documentan en la referencia del SDK; trata type como el discriminador principal.

6. Un Ayudante Sincrónico de un Solo Disparo

Envuelve query() para los llamadores que no quieren lidiar con la iteración asíncrona.

import asyncio
from claude_agent_sdk import query
 
def ask(prompt: str) -> str:
    async def _run():
        chunks = []
        async for message in query(prompt=prompt):
            if message.get("type") == "text":
                chunks.append(message["text"])
        return "".join(chunks)
    return asyncio.run(_run())
 
print(ask("Dame un resumen de una frase de asyncio."))

Útil para scripts o notebooks que solo quieren una cadena final.
Este patrón descarta los eventos intermedios de llamada a herramientas; usa el flujo crudo cuando necesites mostrarlos o registrarlos.
El código de producción generalmente mantiene la forma asíncrona para poder ejecutarse dentro de un bucle de eventos existente.

Ejemplos Intermedios

7. Combinar Herramientas con un Modo de Permiso

Habilita múltiples herramientas integradas mientras requiere aprobación para las riesgosas.

from claude_agent_sdk import query, AgentOptions
 
options = AgentOptions(
    allowed_tools=["file_edit", "bash", "web_search"],
    permission_mode="default",  # pausa antes de acciones destructivas
)
 
async for message in query(
    prompt="Investiga la ejecución fallida de CI y propone una solución.",
    options=options,
):
    print(message)

permission_mode="default" mantiene intactas las decisiones de uso de herramientas del bucle, pero inserta una puerta de aprobación antes de las llamadas destructivas.
Aquí se habilitan tres herramientas juntas porque la tarea abarca genuinamente la lectura (bash), la corrección (file_edit) y la investigación (web_search).
Esta es la forma que toman la mayoría de los agentes de "investigar y corregir".

Relacionado: Añadir Puntos de Control de Humano en el Bucle a un Flujo de Trabajo del Agent SDK - puertas de aprobación en profundidad

8. Reanudar una Sesión

Continúa una ejecución anterior en lugar de empezar con un contexto vacío.

from claude_agent_sdk import query, AgentOptions
 
first = query(prompt="Empieza a revisar src/orders/", options=AgentOptions())
session_id = None
async for message in first:
    if message.get("type") == "session_start":
        session_id = message["session_id"]
 
# más tarde, posiblemente en un proceso nuevo
resume_options = AgentOptions(resume=session_id)
async for message in query(prompt="Continúa donde lo dejaste.", options=resume_options):
    print(message)

El identificador de sesión captura el historial de conversación y resultados de herramientas de la primera ejecución.
Pasarlo a través de resume en una llamada posterior continúa el bucle con ese historial ya en contexto.
Esto es lo que hace que las tareas de agente de larga duración y multi-paso sean prácticas a través de invocaciones de procesos separadas.

Relacionado: Persistir Sesiones Entre Ejecuciones con el Claude Agent SDK - patrones de almacenamiento y reanudación

9. Delegar una Parte del Trabajo a un Subagente

Crear un agente hijo aislado para una parte de una tarea más grande.

from claude_agent_sdk import query, AgentOptions, SubagentConfig
 
options = AgentOptions(
    allowed_tools=["file_edit", "bash"],
    subagents=[
        SubagentConfig(
            name="test-runner",
            allowed_tools=["bash"],
            description="Ejecuta la suite de pruebas e informa solo los fallos.",
        )
    ],
)
 
async for message in query(
    prompt="Usa el subagente test-runner para comprobar si la suite pasa, luego corrige cualquier fallo.",
    options=options,
):
    print(message)

El subagente obtiene su propio ámbito de herramientas (bash solamente) y su propio contexto aislado, separado del del padre.
El agente padre decide cuándo invocar al subagente, de la misma manera que decide llamar a cualquier otra herramienta.
Usa esto cuando el razonamiento intermedio de una subtarea podría saturar el contexto del padre.

Relacionado: Delegar Trabajo a Subagentes en el Claude Agent SDK - paralelización de flujos de trabajo independientes

Versiones de la Pila: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y el Claude Agent SDK (última versión, Python y TypeScript). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.

Básicos del Claude Agent SDK

9 ejemplos para empezar a usar el Claude Agent SDK: 6 básicos y 3 intermedios.

Prerrequisitos

Instala el paquete de Python: pip install claude-agent-sdk (TypeScript: npm install @anthropic-ai/claude-agent-sdk).
Configura una clave API en tu entorno: export ANTHROPIC_API_KEY=sk-ant-....
El SDK incluye su propio binario CLI internamente; no necesitas instalar Claude Code por separado para usarlo.
Los ejemplos a continuación usan asyncio ya que query() del SDK de Python es un generador asíncrono.

Ejemplos Básicos

1. Tu primer `query()`

La estructura mínima: un prompt, herramientas predeterminadas, respuesta transmitida.

import asyncio
from claude_agent_sdk import query
 
async def main():
    async for message in query(prompt="¿Cuánto es 17 * 34?"):
        print(message)
 
asyncio.run(main())

query() devuelve un iterador asíncrono de mensajes, no una cadena única.
Sin pasar options, el agente se ejecuta con el conjunto de herramientas predeterminado del SDK.
Cada mensaje emitido representa un paso del bucle subyacente de uso de herramientas, incluida la respuesta final.

Relacionado: El Modelo Mental del Claude Agent SDK - qué sucede detrás de esta llamada

2. Selección de un Modelo

Elige un modelo específico en lugar del predeterminado del SDK.

from claude_agent_sdk import query, AgentOptions
 
options = AgentOptions(model="claude-sonnet-5")
 
async for message in query(prompt="Resume este changelog.", options=options):
    print(message)

AgentOptions es donde reside la mayor parte de la configuración por llamada.
claude-sonnet-5 es el predeterminado equilibrado actual; claude-haiku-4-5 intercambia calidad por velocidad y costo.
La elección del modelo no cambia la mecánica del bucle, solo qué modelo toma cada decisión.

3. Ámbito del Acceso a Herramientas

Restringe qué herramientas integradas puede llamar el agente.

from claude_agent_sdk import query, AgentOptions
 
options = AgentOptions(allowed_tools=["file_edit"])
 
async for message in query(
    prompt="Corrige la errata en README.md",
    options=options,
):
    print(message)

allowed_tools es una lista explícita de permitidos; todo lo que no esté listado no estará disponible para el bucle.
Limitar solo a file_edit significa que este agente no puede ejecutar comandos bash ni buscar en la web, incluso si quisiera.
Empieza de forma restrictiva y amplía solo cuando una tarea realmente necesite más.

Relacionado: Habilitar Herramientas de Edición de Archivos, Bash y Web en el Agent SDK - guía completa sobre el ámbito de las herramientas

4. Lectura del Directorio de Trabajo

Apunta el agente a la raíz de un proyecto específico.

from claude_agent_sdk import query, AgentOptions
 
options = AgentOptions(
    cwd="/ruta/al/proyecto",
    allowed_tools=["file_edit", "bash"],
)
 
async for message in query(prompt="Lista las pruebas fallidas.", options=options):
    print(message)

cwd limita las operaciones de archivos y bash a un árbol de directorios específico.
Establecer cwd explícitamente evita sorpresas cuando el SDK se ejecuta desde un directorio de trabajo de proceso diferente.
Combina con allowed_tools para que el agente pueda inspeccionar y actuar sobre ese proyecto.

5. Transmitir Texto a Medida que Llega

Imprime solo el contenido de texto del asistente en lugar de cada tipo de mensaje.

from claude_agent_sdk import query
 
async for message in query(prompt="Explica qué hace este repositorio."):
    if message.get("type") == "text":
        print(message["text"], end="", flush=True)

El flujo de mensajes mezcla eventos de llamada a herramientas, resultados de herramientas y texto; filtrar por type te da solo el texto.
La transmisión te permite mostrar el progreso en una CLI o UI en lugar de esperar a que termine todo el bucle.
Las formas exactas de los mensajes se documentan en la referencia del SDK; trata type como el discriminador principal.

6. Un Ayudante Sincrónico de un Solo Disparo

Envuelve query() para los llamadores que no quieren lidiar con la iteración asíncrona.

import asyncio
from claude_agent_sdk import query
 
def ask(prompt: str) -> str:
    async def _run():
        chunks = []
        async for message in query(prompt=prompt):
            if message.get("type") == "text":
                chunks.append(message["text"])
        return "".join(chunks)
    return asyncio.run(_run())
 
print(ask("Dame un resumen de una frase de asyncio."))

Útil para scripts o notebooks que solo quieren una cadena final.
Este patrón descarta los eventos intermedios de llamada a herramientas; usa el flujo crudo cuando necesites mostrarlos o registrarlos.
El código de producción generalmente mantiene la forma asíncrona para poder ejecutarse dentro de un bucle de eventos existente.

Ejemplos Intermedios

7. Combinar Herramientas con un Modo de Permiso

Habilita múltiples herramientas integradas mientras requiere aprobación para las riesgosas.

from claude_agent_sdk import query, AgentOptions
 
options = AgentOptions(
    allowed_tools=["file_edit", "bash", "web_search"],
    permission_mode="default",  # pausa antes de acciones destructivas
)
 
async for message in query(
    prompt="Investiga la ejecución fallida de CI y propone una solución.",
    options=options,
):
    print(message)

permission_mode="default" mantiene intactas las decisiones de uso de herramientas del bucle, pero inserta una puerta de aprobación antes de las llamadas destructivas.
Aquí se habilitan tres herramientas juntas porque la tarea abarca genuinamente la lectura (bash), la corrección (file_edit) y la investigación (web_search).
Esta es la forma que toman la mayoría de los agentes de "investigar y corregir".

Relacionado: Añadir Puntos de Control de Humano en el Bucle a un Flujo de Trabajo del Agent SDK - puertas de aprobación en profundidad

8. Reanudar una Sesión

Continúa una ejecución anterior en lugar de empezar con un contexto vacío.

from claude_agent_sdk import query, AgentOptions
 
first = query(prompt="Empieza a revisar src/orders/", options=AgentOptions())
session_id = None
async for message in first:
    if message.get("type") == "session_start":
        session_id = message["session_id"]
 
# más tarde, posiblemente en un proceso nuevo
resume_options = AgentOptions(resume=session_id)
async for message in query(prompt="Continúa donde lo dejaste.", options=resume_options):
    print(message)

El identificador de sesión captura el historial de conversación y resultados de herramientas de la primera ejecución.
Pasarlo a través de resume en una llamada posterior continúa el bucle con ese historial ya en contexto.
Esto es lo que hace que las tareas de agente de larga duración y multi-paso sean prácticas a través de invocaciones de procesos separadas.

Relacionado: Persistir Sesiones Entre Ejecuciones con el Claude Agent SDK - patrones de almacenamiento y reanudación

9. Delegar una Parte del Trabajo a un Subagente

Crear un agente hijo aislado para una parte de una tarea más grande.

from claude_agent_sdk import query, AgentOptions, SubagentConfig
 
options = AgentOptions(
    allowed_tools=["file_edit", "bash"],
    subagents=[
        SubagentConfig(
            name="test-runner",
            allowed_tools=["bash"],
            description="Ejecuta la suite de pruebas e informa solo los fallos.",
        )
    ],
)
 
async for message in query(
    prompt="Usa el subagente test-runner para comprobar si la suite pasa, luego corrige cualquier fallo.",
    options=options,
):
    print(message)

El subagente obtiene su propio ámbito de herramientas (bash solamente) y su propio contexto aislado, separado del del padre.
El agente padre decide cuándo invocar al subagente, de la misma manera que decide llamar a cualquier otra herramienta.
Usa esto cuando el razonamiento intermedio de una subtarea podría saturar el contexto del padre.

Relacionado: Delegar Trabajo a Subagentes en el Claude Agent SDK - paralelización de flujos de trabajo independientes

Versiones de la Pila: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y el Claude Agent SDK (última versión, Python y TypeScript). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.

Básicos del Claude Agent SDK

Buscar en la documentación

Básicos del Claude Agent SDK