Agent SDK: lleva las capacidades de Claude Code a tus propios programas

📚 Navegación de la serie: El artículo anterior 44 GitHub Actions te enseñó cómo integrar a Claude en tu flujo de CI para que trabaje de forma autónoma en PRs y pipelines. Este artículo va un paso más allá: no solo lo integraremos en pipelines, sino que trataremos a Claude Code como una biblioteca para incrustarlo en tus propios programas y servicios. El Agent SDK es la vía oficial que te permite "invocar un agente de Claude mediante código".

Hoy hablaremos de algo que te permitirá pasar de ser un "usuario de herramientas" a ser un "creador de herramientas".

Durante los artículos anteriores has sido un usuario de Claude Code: abres una terminal, escribes claude e interactúas con él para que modifique código. Esa es su "interfaz frontal". Pero hay una "interfaz trasera" que probablemente no has explorado: su núcleo (ese ciclo de agente que lee archivos, ejecuta comandos y reflexiona antes de actuar) puede ser invocado directamente por tu propio código.

Esto es el Agent SDK (un conjunto de bibliotecas de desarrollo que te permiten llamar al núcleo de Claude Code en Python o TypeScript). En pocas palabras, convierte a Claude Code de una herramienta de línea de comandos en una función dentro de tu programa. Con unas pocas líneas de código, puedes ejecutar un agente de IA en tu aplicación que lea código de forma autónoma, modifique archivos e investigue en la web.

El valor de esto se entiende mejor cuando intentas crear, por ejemplo, un bot para revisar PRs de forma automática. Si intentas interactuar con la API básica del modelo desde cero, solo para lograr que el modelo lea un archivo tienes que escribir mucho código: adjuntar el contenido del archivo en la solicitud, procesar la respuesta del modelo que dice "quiero leer el archivo X", realizar la lectura real en el sistema y devolver el resultado al modelo... un flujo repetitivo y complejo. Con el Agent SDK, ese trabajo de pegamento desaparece; en tres líneas de código, Claude lee el archivo y corrige el bug por sí mismo. Hoy simplificaremos este camino.

Al terminar este artículo, obtendrás:

• Una explicación simple de qué es el Agent SDK y qué parte de Claude Code "se extrae para que la uses".
• La diferencia entre el SDK y la CLI que usas a diario: un mismo núcleo con dos puntos de acceso diferentes.
• La diferencia fundamental entre el SDK y la "API básica" (si no entiendes esto, sentirás que estás reinventando la rueda).
• Cómo elegir entre las versiones de TypeScript y Python, qué paquetes instalar y los requisitos previos.
• Un código de agente mínimo paso a paso que identifica y corrige un bug por sí mismo.
• Una guía de decisión para saber si esta herramienta es adecuada para tus necesidades actuales.

---

01 Concepto: qué parte de Claude Code extrae el Agent SDK

Para empezar, la conclusión: el Agent SDK convierte el núcleo de Claude Code en una biblioteca para que puedas iniciar, mediante código (Python o TypeScript), un agente de Claude equivalente al de la CLI.

Recuerda el "ciclo del agente" que explicamos en el artículo 03: el flujo de trabajo de Claude es "pensar → actuar → observar" de forma iterativa. Decide el siguiente paso, ejecuta una herramienta (leer archivos, ejecutar comandos) y analiza el resultado para planificar el siguiente movimiento. Al usar claude en la terminal, te beneficias de este ciclo y de sus herramientas integradas (Read, Edit, Bash, etc., vistas en el artículo 03).

Punto clave: este ciclo y sus herramientas no son exclusivos de la CLI, sino que pueden ser invocados directamente desde tu código. La documentación oficial lo describe con claridad:

El Agent SDK le proporciona las mismas herramientas, ciclo del agente y gestión del contexto que Claude Code, programables en Python y TypeScript.

Analogía: llevar la cafetera automática de la cafetería a la cocina de tu casa. Vas a la cafetería todos los días a pedir café (usar la CLI). Pero un día decides ofrecer el mismo café en tu propio negocio de desayunos; no puedes enviar a tus clientes a la cafetería original. Así que instalas la misma máquina en tu local: tiene el mismo núcleo para moler granos, extraer y espumar leche, pero ahora está integrado en tu flujo de trabajo y decides cuándo prepararlo, a quién entregarlo y con qué menú acompañarlo a través de tus procesos. El Agent SDK es esa máquina que puedes trasladar: el mismo núcleo integrado en tu programa.

¿Qué elementos del agente incluye el SDK? La documentación oficial confirma que incluye todos los componentes que hacen potente a la CLI:

• Herramientas integradas: Read, Write, Edit, Bash, Glob, Grep y WebSearch listos para usar, sin que tengas que programar su lógica de ejecución.
• Ciclo del agente: la coordinación del ciclo de pensar, actuar y observar integrada de forma automática.
• Gestión de contexto: realiza el seguimiento de los archivos leídos y del historial de la conversación.
• Extensiones avanzadas: llamadas a ganchos (Hooks), subagentes, MCP, control de permisos y restauración de sesiones programables a través del SDK.

¿En qué escenarios es útil? Considera estas tres necesidades comunes:

• "Quiero crear un bot de Slack que reciba un log de error, ubique el fallo en el código base y proponga la corrección": requiere integrar al agente en tu servicio de Slack.
• "Quiero programar una tarea que analice el código base todas las noches en busca de comentarios TODO y genere un reporte": requiere iniciar el agente mediante código y procesar sus respuestas.
• "Quiero añadir un asistente de IA a mi producto que actúe sobre los archivos locales de los usuarios de forma directa": requiere necesariamente el uso del SDK.

Estas tareas son complejas de realizar mediante la CLI, la cual está diseñada para la interacción humana en la terminal; estas necesidades requieren una activación automatizada y procesamiento de resultados programático. Ese es el terreno del SDK.

💡 Resumen rápido: el Agent SDK empaqueta el núcleo de Claude Code (herramientas, ciclo y contexto) en una biblioteca para que puedas iniciar por código un agente equivalente al de la CLI, integrándolo en tus propios programas y servicios.

---

02 SDK vs. CLI: un mismo núcleo, dos puntos de acceso

Este es un concepto fundamental que conviene aclarar: el Agent SDK y la CLI que ejecutas en tu terminal comparten el mismo núcleo subyacente; la diferencia es el punto de acceso (uno para interacción humana, otro para automatización programática).

La documentación oficial lo define con precisión:

Mismas capacidades, diferentes interfaces.

Analogía: la misma cafetera operada por el barista vs. integrada en una máquina de autoservicio. La cafetera (el núcleo) es la misma. Detrás de la barra, el barista atiende al cliente y puede preguntar sobre la marcha si desea azúcar (uso de la CLI, ideal para la presencia humana y ajustes interactivos). La misma cafetera integrada en una máquina expendedora opera con monedas y botones, preparando el café de forma automática y desatendida (uso del SDK, ideal para automatizaciones activadas por código y procesamiento por lotes). La máquina no cambia; lo que cambia es quién presiona el botón.

La documentación oficial proporciona una tabla comparativa para elegir el enfoque adecuado:

Escenario de uso	Opción recomendada
Desarrollo interactivo (escribir y depurar código en la terminal)	CLI
Tareas puntuales (pedirle que resuelva algo en el momento)	CLI
Integración en flujos de CI/CD (automatización en pipelines)	SDK
Aplicaciones personalizadas (añadir IA a tu producto)	SDK
Automatización en producción (ejecución programada y desatendida)	SDK

Para elegir, pregúntate: "¿Esta tarea la supervisará un humano en tiempo real o se ejecutará de forma automática mediante un programa?". Si requiere supervisión e interacción directa, usa la CLI; si es una ejecución automatizada que procesa resultados, usa el SDK.

La documentación destaca un detalle clave para facilitar la transición:

Muchos equipos utilizan ambos: la CLI para el desarrollo diario y el SDK para producción. Los flujos de trabajo se traducen directamente entre ambos.

Esta es una práctica común: realizas tu desarrollo diario apoyándote en la terminal con claude (CLI); cuando notas que repites el mismo flujo manual por quinta vez, escribes un script con el SDK para automatizar la tarea. Los conceptos de instrucciones (prompts), herramientas disponibles y control de permisos son idénticos; todo el aprendizaje que acumulas con la CLI se aplica directamente en el SDK.

Considera a la CLI y al SDK como dos interfaces para la misma herramienta, como ilustra el siguiente esquema:

Este diagrama muestra cómo el acceso manual de la CLI y el programático del SDK convergen en el mismo núcleo de Claude Code, ejecutando las mismas funciones en el sistema.

💡 Resumen rápido: La CLI y el SDK comparten el mismo núcleo pero ofrecen diferentes puntos de acceso. La CLI está diseñada para la interacción en tiempo real y el SDK para la automatización mediante código. Tu experiencia con la CLI es completamente transferible al SDK.

---

03 Agent SDK vs. API básica: la gestión del ciclo de herramientas

Esta es la distinción más valiosa de este artículo. Si no la comprendes, podrías terminar programando manualmente características que el SDK ya resuelve de forma nativa.

Es probable que conozcas las API de Anthropic o su Client SDK (las bibliotecas cliente para interactuar directamente con los modelos de lenguaje). Aunque comparten nombres similares y ambos se comunican con Claude, su propósito es diferente:

El Client SDK te proporciona un "modelo conversacional" y te corresponde a ti programar el ciclo de herramientas; el Agent SDK te proporciona un "agente activo" que gestiona y ejecuta las herramientas de forma autónoma.

La documentación oficial lo aclara:

El Client SDK de Anthropic le proporciona acceso directo a la API: usted envía las instrucciones e implementa la ejecución de herramientas de forma manual. El Agent SDK le proporciona un Claude con ejecución de herramientas integrada.

Analogía: comprar granos de café enteros vs. usar una cafetera de autoservicio. El Client SDK es como comprar granos de café: el insumo es excelente (el modelo es potente), pero para obtener la taza de café debes realizar tú mismo el tostado, la molienda, el calentamiento del agua, la extracción y la espuma de leche. El Agent SDK es la cafetera de autoservicio: presionas "café con leche" y la máquina se encarga de la molienda, la extracción y la mezcla, entregándote la taza lista. El insumo es el mismo, pero el trabajo intermedio lo realiza la máquina.

En el código de desarrollo, la diferencia en la complejidad es evidente. Compara estos fragmentos de código en Python:

# Client SDK: el ciclo de herramientas debe ser implementado manualmente por ti
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.tool_use)   # Ejecutas la herramienta en tu código
    response = client.messages.create(tool_result=result, **params)  # Devuelves el resultado al modelo

# Agent SDK: Claude ejecuta las herramientas de forma automática
async for message in query(prompt="Corrige el bug en auth.py"):
    print(message)

En el caso del Client SDK, debes programar el ciclo while para gestionar la llamada a herramientas: recibir la indicación del modelo de que desea leer auth.py, realizar la lectura física del archivo en tu sistema, empaquetar el contenido y enviarlo de regreso al modelo en una nueva solicitud.

El Agent SDK integra este ciclo dentro del método query(). Le das la instrucción "Corrige el bug en auth.py" y él decide qué archivos leer, realiza la lectura, aplica la edición y valida los cambios de forma autónoma, mientras tú recibes las actualizaciones del flujo.

Esta es la razón de las dificultades al crear automatizaciones: intentar gestionar el ciclo while de llamadas a herramientas manualmente (como leer archivos o ejecutar comandos bash) suele introducir errores de lógica. Dejar que el Agent SDK se encargue de este flujo te permite reducir el código de pegamento a una sola llamada de query().

Característica	Client SDK (API básica)	Agent SDK
Componente entregado	Modelo conversacional	Agente activo
Ejecución de herramientas	Programada manualmente por ti	Gestionada automáticamente por Claude
Ciclo de llamadas (while)	Requiere implementación manual	Gestionado de forma interna por el SDK
Herramientas del sistema (lectura/bash)	No incluidas, debes crearlas	Integradas y listas para usar
Ideal para	Casos que no requieran interactuar con el sistema de archivos	Agentes que deben modificar código y ejecutar comandos

Regla de decisión: si necesitas que Claude interactúe con el sistema de archivos, modifique código o ejecute comandos, usa el Agent SDK. Reserva el Client SDK para flujos puramente conversacionales que no requieran interactuar con el sistema operativo y donde necesites un control estricto sobre cada mensaje enviado.

💡 Resumen rápido: El Agent SDK se diferencia de la API básica en que esta última te entrega el modelo y tú programas la ejecución de herramientas; el Agent SDK te entrega al agente con las herramientas y su ciclo de ejecución ya resueltos. Prefiere el Agent SDK para tareas que requieran interactuar con el sistema de archivos.

---

04 Soporte de lenguajes: TypeScript y Python

El Agent SDK cuenta con soporte oficial para dos lenguajes: TypeScript y Python. Ambas versiones ofrecen las mismas capacidades y la documentación incluye ejemplos para ambos, por lo que puedes elegir el lenguaje que mejor se adapte a tu proyecto actual.

Criterio de elección: utiliza la versión del SDK del lenguaje en el que esté escrito tu proyecto. Si usas Node.js o JavaScript, elige TypeScript; si desarrollas herramientas de datos, scripts o ingeniería de IA, elige Python.

Comandos de instalación y requisitos

Detallamos los comandos y requisitos de entorno para cada versión (según la especificación oficial):

Lenguaje	Comando de instalación	Versión requerida	¿Requiere Claude Code instalado?
TypeScript	npm install @anthropic-ai/claude-agent-sdk	Node.js 18+	No (incluye el binario de ejecución)
Python	pip install claude-agent-sdk	Python 3.10+	Requiere entorno compatible

Para la versión de TypeScript, la documentación oficial señala un beneficio práctico:

El SDK de TypeScript incluye un binario local de Claude Code como dependencia opcional para tu plataforma, por lo que no requieres instalar Claude Code por separado.

En el caso de Python, ten en cuenta que requiere Python 3.10 o superior. Si al ejecutar pip obtienes un error del tipo No matching distribution found for claude-agent-sdk, valida la versión instalada en tu sistema:

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

Si es inferior a 3.10, deberás actualizar tu entorno de Python antes de proceder con la instalación.

Credenciales de API

Ambas versiones requieren una clave de API de Anthropic para realizar las llamadas al modelo. Se recomienda guardarla en un archivo .env en la raíz del proyecto:

ANTHROPIC_API_KEY=tu-clave-de-api

Obtén la clave desde la consola de Anthropic (console.anthropic.com). Este es un dato confidencial; agrégalo al archivo .gitignore para evitar subirlo a git. (Visto en el artículo 04).

Nota de facturación importante incluida en la documentación oficial:

A partir del 15 de junio de 2026, el uso de Agent SDK y claude -p bajo planes de suscripción se deducirá de una cuota mensual independiente de Agent SDK, separada de tu límite de consumo interactivo.

Es decir, el consumo del SDK y el uso de la terminal interactiva se facturan de forma separada. Ten esto en cuenta al planificar ejecuciones automatizadas del SDK.

💡 Resumen rápido: Las versiones del SDK para TypeScript y Python tienen las mismas capacidades. TS requiere Node.js 18+ (instalable con npm install @anthropic-ai/claude-agent-sdk y con binario integrado); Python requiere Python 3.10+ (instalable con pip install claude-agent-sdk). Ambos requieren ANTHROPIC_API_KEY y tienen una facturación de cuota independiente.

---

05 Código de ejemplo: la función query() como punto de partida

Para entender su funcionamiento, analicemos el punto de partida del SDK: la función query(). Es el componente principal para iniciar al agente.

Veamos la estructura del código mínimo en Python provisto por la documentación:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    # El flujo query() devuelve un generador asíncrono que emite los mensajes del agente
    async for message in query(
        prompt="Find and fix the bug in auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)  # Imprime la reflexión del agente, el uso de herramientas y los resultados

asyncio.run(main())

Y su equivalencia en TypeScript:

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

for await (const message of query({
  prompt: "Find and fix the bug in auth.ts",
  options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
  console.log(message);
}

Analicemos los tres parámetros clave de este código (según la especificación oficial):

1. query(): es el método de inicio del agente. Devuelve un iterador asíncrono (async iterator) que te permite recibir los mensajes en tiempo real utilizando un ciclo async for (o for await en TS), mostrando su análisis, las herramientas invocadas y el resultado final.

2. prompt: la instrucción en lenguaje natural con la tarea que deseas encomendarle. Es equivalente a lo que escribirías en la terminal.

3. options: objeto de configuración del agente. La opción principal es allowed_tools (o allowedTools en TS), que define qué herramientas tiene autorización de usar. En el ejemplo, habilitamos Read, Edit y Bash.

El ciclo async for se mantiene activo hasta que el agente completa la tarea o se produce un error. El SDK gestiona de forma interna la ejecución de las herramientas, la memoria y la lógica de reintentos:

El SDK gestiona la orquestación (ejecución de herramientas, gestión del contexto y reintentos), permitiéndote enfocarte en procesar el flujo de mensajes.

Esta es la ventaja frente a la API directa: no tienes que implementar la lógica de lectura o escritura de archivos, ya que el método query() la resuelve de forma nativa.

La selección de herramientas actúa también como control de seguridad (relacionado con el artículo 20): las herramientas que declares limitan lo que el agente puede hacer en tu sistema.

Herramientas asignadas	Alcance del agente
Read, Glob, Grep	Modo consulta (puede leer archivos pero no modificarlos)
Read, Edit, Glob	Modo edición (puede leer y modificar archivos de código)
Read, Edit, Bash, Glob, Grep	Modo automatización (puede leer, editar y ejecutar comandos)

Si deseas crear un agente seguro de solo análisis, limítate a autorizar Read, Glob y Grep. Al no tener asignada la herramienta Edit, el agente no tendrá capacidad técnica de modificar tus archivos.

Nota para Python: Además del método query(), el SDK de Python incluye la clase ClaudeSDKClient, que facilita mantener una sesión conversacional persistente entre múltiples consultas, útil para crear interfaces de chat o herramientas interactivas. Para ejecuciones de una sola tarea, query() es la opción adecuada.

💡 Resumen rápido: El Agent SDK se inicia con query(), pasándole la tarea en prompt y la lista de herramientas en allowed_tools (dentro de options). El método devuelve un flujo de mensajes asíncrono y gestiona internamente la ejecución del código sin que tengas que estructurar el ciclo de herramientas manual.

---

06 Ejercicio práctico: crear un agente que resuelva un bug de forma autónoma

Crearemos un agente mínimo en tu entorno local para experimentar el flujo: un script que identifique y corrija un fallo de código en un archivo de forma autónoma.

Requisitos: Node.js 18+ o Python 3.10+, y una clave de API de Anthropic. El proceso requiere conexión a internet para descargar las dependencias y comunicarse con el modelo.

Paso 1: Crear un directorio de trabajo

Abre una terminal y crea una carpeta para este proyecto:

mkdir mi-agente-sdk && cd mi-agente-sdk

Paso 2: Instalar el SDK y configurar las credenciales

En Python (creando un entorno virtual):

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

En TypeScript usa: npm install @anthropic-ai/claude-agent-sdk.

Crea un archivo .env en la carpeta mi-agente-sdk con tu clave de API:

ANTHROPIC_API_KEY=tu-clave-de-api-real

Resultado esperado: La instalación de claude-agent-sdk debe finalizar con éxito. Si obtienes errores de distribución, valida que tu versión de Python sea 3.10 o superior.

Paso 3: Crear el archivo de código con fallos

Crea un archivo llamado utils.py en la carpeta e introduce este código (basado en el ejemplo oficial que incluye dos errores de lógica comunes):

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)


def get_user_name(user):
    return user["name"].upper()

Los fallos de este código son: calculate_average([]) causará una división por cero si recibe una lista vacía; y get_user_name(None) arrojará un TypeError si el parámetro es nulo.

Paso 4: Escribir el script del agente

Crea el archivo agent.py con el siguiente código (que utiliza la configuración rápida del SDK y muestra los mensajes del flujo):

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


async def main():
    # Iniciamos el agente para que analice utils.py y corrija los fallos detectados
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # Herramientas autorizadas
            permission_mode="acceptEdits",            # Autorización automática de ediciones
        ),
    ):
        # Procesamos y mostramos la comunicación en tiempo real
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
                elif hasattr(block, "name"):
                    print(f"Herramienta invocada: {block.name}")
        elif isinstance(message, ResultMessage):
            print(f"Flujo terminado: {message.subtype}")


asyncio.run(main())

Nota sobre la configuración: usamos permission_mode="acceptEdits", que autoriza automáticamente las ediciones de archivos, evitando que el script se detenga a solicitar confirmación del usuario para estas operaciones. La documentación oficial detalla los modos de permisos disponibles:

Modo de permiso	Comportamiento	Uso recomendado
acceptEdits	Autoriza de forma automática la edición de archivos y comandos comunes; solicita confirmación para operaciones críticas	Flujos de desarrollo automatizados locales (usado en esta práctica)
bypassPermissions	Ejecuta todas las herramientas sin solicitar confirmaciones	Entornos de pruebas aislados o contenedores dedicados
default	Requiere definir una función de callback para procesar cada confirmación	Integraciones donde desees personalizar la aprobación
dontAsk	Rechaza automáticamente cualquier herramienta que no esté pre-aprobada	Entornos de CI estrictos o scripts desatendidos
plan	Solo permite herramientas de lectura para generar un plan de acción sin modificar archivos	Fase de diseño o auditorías previas

Paso 5: Ejecutar el agente

python agent.py

En TypeScript usa: npx tsx agent.ts.

Resultado esperado: Verás el proceso del agente impreso en la terminal: su análisis indicando que leerá utils.py, el registro de las herramientas Read y Edit siendo invocadas, y finalmente el mensaje Flujo terminado: success.

Paso 6: Validar los cambios aplicados en utils.py

Abre el archivo utils.py en tu editor.

Resultado esperado: Verás que Claude ha modificado el archivo agregando validaciones para controlar listas vacías en calculate_average y prevenir nulos en get_user_name, corrigiendo los fallos.

El agente ha completado la tarea de forma autónoma: leyendo el archivo, analizando la lógica, determinando los fallos, editando el código y guardando los cambios, sin que hayas tenido que escribir lógica de pegamento para las herramientas.

💡 Resumen rápido: La práctica consta de seis pasos: crear carpeta → instalar SDK y configurar secretos → crear el archivo utils.py con fallos → escribir el script agent.py → ejecutarlo → verificar que el código haya sido corregido.

---

07 Cuándo utilizar el SDK

El Agent SDK no es una herramienta indispensable para todos los usuarios de Claude Code, pero es el recurso clave si buscas construir integraciones y automatizaciones.

Si tu objetivo es agilizar tu programación diaria escribiendo código y resolviendo bugs en la terminal, la CLI es suficiente; no necesitas el SDK. El SDK añade una capa de complejidad orientada al desarrollo de software.

Te resultará útil el SDK si te identificas con alguna de estas situaciones:

Situación	Recomendación
"Uso la terminal para programar y corregir fallos cotidianos"	❌ La CLI es adecuada, no requieres el SDK
"He repetido el mismo flujo de comandos en la terminal varias veces y quiero automatizarlo"	✅ Diseña un script con el SDK para automatizar la tarea
"Quiero integrar capacidades de agente en mi producto o aplicación de software"	✅ El SDK es el componente adecuado para esta integración
"Quiero crear bots, integraciones de mensajería o flujos desatendidos"	✅ El SDK permite estructurar estas tareas de forma programática

La documentación oficial sugiere una ruta de adopción de menos a más:

Una ruta común es diseñar prototipos locales con el Agent SDK y luego migrar a Managed Agents para el despliegue en entornos de producción.

Los Managed Agents (agentes administrados) son la oferta hospedada de Anthropic, que provee una API REST para gestionar agentes y entornos de ejecución aislados sin que tengas que preocuparte de la infraestructura. El Agent SDK ejecuta el agente dentro de tu propio proceso de sistema. Compara sus características:

Característica	Agent SDK	Managed Agents
Entorno de ejecución	Tu propio proceso e infraestructura local	Servidores y contenedores administrados por Anthropic
Interfaz de programación	Bibliotecas nativas de Python / TypeScript	API REST estándar
Acceso a archivos	Archivos locales accesibles en tu sistema	Entornos de ejecución (sandboxes) aislados por sesión
Escenario recomendado	Prototipos, herramientas locales con acceso a tus archivos	Despliegue en producción con gestión de infraestructura delegada

Para iniciar, lo ideal es construir tus prototipos locales con el Agent SDK; una vez que valides el diseño y decidas llevarlo a producción a escala, evalúa la migración a Managed Agents.

💡 Resumen rápido: Si tu flujo es interactivo en la terminal, mantente en la CLI. Si buscas automatizar tareas o construir productos, utiliza el SDK. Diseña tus prototipos con el Agent SDK de forma local antes de evaluar Managed Agents para producción.

---

08 Resumen

En este artículo hemos analizado el Agent SDK de Claude Code, la biblioteca que te permite integrar el motor de ejecución del agente en tus propios desarrollos.

Repasemos los puntos clave:

Aspecto	Conclusión	Detalle clave
Definición del SDK	Núcleo de Claude Code en biblioteca	Expone herramientas, ciclo de agente y contexto para control de código
Relación con la CLI	Mismo motor, distinta interfaz	CLI para uso interactivo humano; SDK para automatizaciones programáticas
API básica vs. SDK	Nivel de abstracción	La API básica requiere programar el ciclo de herramientas; el SDK lo resuelve de forma nativa
Soporte de lenguajes	TypeScript y Python	TypeScript (Node 18+ con binario incorporado) y Python (3.10+)
Función de entrada	query()	Inicia el agente pasando la tarea en prompt y limitando herramientas en allowed_tools
Criterio de uso	Enfoque de integración	Úsalo si construyes herramientas, automatizaciones de scripts o productos

Ahora puedes:

• Explicar qué capacidades de Claude Code expone el SDK para su integración en código.
• Identificar la diferencia de enfoque entre la CLI y el SDK, y cómo se complementan.
• Diferenciar el nivel de abstracción del Agent SDK frente a la API básica de Anthropic.
• Instalar y configurar el SDK en tus entornos de TypeScript o Python.
• Escribir scripts utilizando query() para delegar tareas y procesar los mensajes del agente.
• Diseñar y ejecutar prototipos locales de agentes autónomos de forma segura.

El SDK te permite transformar a Claude Code de una herramienta de trabajo individual a un componente de software para construir tus propias soluciones.

---

El siguiente artículo es 46 "Configuración de desarrollo". Ahora que sabes cómo estructurar un agente con el SDK, es necesario afianzar el entorno de desarrollo: gestión de credenciales de API, separación de entornos de desarrollo y producción, y la configuración de variables para proveedores externos. Abordaremos estos aspectos en el próximo artículo para garantizar que tu entorno de desarrollo sea ordenado y seguro.

---

Lecturas recomendadas

• Tareas en paralelo: paralelizando flujos de trabajo
• Primer paso: ejecutando tu primer comando
• Atajos e interfaz: interactuando con la CLI