¿Qué es Claude Agent SDK? Guía completa para crear agentes de IA

"¿No sería genial darle una instrucción a la IA y que ella piense y trabaje por su cuenta?" Exactamente eso es lo que hacen los agentes de IA. Claude Agent SDK de Anthropic es una biblioteca que te permite crear agentes de IA potenciados por Claude usando Python o TypeScript. Pone en tus propios programas las mismas herramientas, el mismo bucle de agente y la misma gestión de contexto que hacen funcionar Claude Code, el agente de programación oficial de Anthropic.

En este artículo te explicamos Claude Agent SDK de forma integral: desde los conceptos fundamentales hasta la implementación y los casos de uso prácticos.

¿Qué es un agente de IA?

Los agentes de IA son fundamentalmente distintos a la IA tradicional de "pregunta y respuesta". Su característica principal es la capacidad de descomponer tareas de forma autónoma, usar herramientas, evaluar resultados y decidir el siguiente paso.

Por ejemplo, si le pides a un agente que "corrija el bug en auth.py", seguirá estos pasos:

1. Leer el archivo para comprender el código
2. Buscar archivos relacionados para entender el contexto general
3. Identificar la causa raíz del bug
4. Aplicar la corrección
5. Ejecutar las pruebas para verificar la solución
6. Informar los resultados

El agente gestiona todo este flujo por su cuenta, sin intervención humana en cada paso. Esa es la verdadera potencia de los agentes.

Descripción general de Claude Agent SDK

Claude Agent SDK es la biblioteca oficial de Anthropic para crear agentes. La documentación oficial la describe como una biblioteca que ejecuta el binario de Claude Code. Es decir, la dirección es el SDK pone en marcha Claude Code, y no al revés. Los SDK de Python y TypeScript incluyen ese binario, así que en la mayoría de los entornos no hace falta instalar Claude Code por separado.

Sus características principales son:

El Agent SDK sirve para llevar el agente que funciona en Code (Claude Code) de Claude a tus propias aplicaciones y scripts, fuera de esa interfaz.

Cómo funciona el bucle del agente

El corazón del Agent SDK es el bucle del agente: un ciclo automático en el que Claude piensa, usa herramientas, revisa los resultados y vuelve a pensar.

El flujo paso a paso es el siguiente:

1. Recibir el prompt: la instrucción del usuario se envía a Claude
2. Claude razona: analiza la instrucción y determina las acciones necesarias
3. Ejecutar herramientas: se invocan herramientas como Bash, Edit y Read para realizar el trabajo
4. Procesar resultados: la salida de las herramientas se devuelve a Claude
5. Continuar o finalizar: si queda trabajo pendiente, vuelve al paso 2. De lo contrario, devuelve una respuesta de texto

El punto clave es que el bucle termina cuando no hay más llamadas a herramientas. Cuando Claude determina que ya no necesita usar ninguna herramienta, devuelve la respuesta final en texto.

Primeros pasos: instalación y código básico

Instalación

El SDK está disponible para Python y TypeScript.

# Python
pip install claude-agent-sdk

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

Necesitas Node.js 18 o superior, o Python 3.10 o superior (guía de inicio rápido oficial).

Autenticación: usa una clave de API (no el inicio de sesión de claude.ai)

El SDK funciona con la clave de API de la variable de entorno ANTHROPIC_API_KEY. Si prefieres pasar por Amazon Bedrock, Google Cloud (la versión operada por Google) o Microsoft Foundry, define CLAUDE_CODE_USE_BEDROCK=1, CLAUDE_CODE_USE_VERTEX=1 o CLAUDE_CODE_USE_FOUNDRY=1 y configura las credenciales de esa nube. El SDK no carga archivos .env automáticamente, así que define la variable en la shell donde se ejecuta el agente. La configuración y los precios de Claude en Google Cloud se explican en Claude en Vertex AI.

Ojo con el inicio de sesión de claude.ai (suscripciones Pro, Max y similares). Salvo aprobación previa, la documentación oficial no permite que desarrolladores externos ofrezcan en sus productos el inicio de sesión o los límites de uso de claude.ai, incluidos los agentes creados con el Agent SDK. Las aplicaciones que construyas con el SDK deben autenticarse con una clave de API.

Agente mínimo (Python)

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    async for message in query(
        prompt="Find and fix the bug in src/auth.py",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash", "Grep"],
            max_turns=30,
        ),
    ):
        if isinstance(message, ResultMessage):
            if message.subtype == "success":
                print(message.result)
            if message.total_cost_usd is not None:
                print(f"Cost: ${message.total_cost_usd:.4f}")

asyncio.run(main())

Agente mínimo (TypeScript)

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

for await (const message of query({
  prompt: "Find and fix the bug in src/auth.py",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Grep"],
    maxTurns: 30,
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Con solo este código, ya tienes un agente que lee archivos, busca bugs, aplica correcciones y reporta los resultados de forma completamente autónoma. Eso sí: allowed_tools no es la lista de herramientas que Claude puede usar, sino la lista de herramientas que se aprueban automáticamente sin preguntar. Como este ejemplo incluye Bash, los comandos de shell que elija Claude se ejecutan sin confirmación (salvo unas pocas acciones, como ciertos borrados, que ningún ajuste aprueba automáticamente). Como este ejemplo no fija permission_mode, el modo sale de permissions.defaultMode en tus archivos de configuración o, si no lo hay, del valor predeterminado integrado, que desde la v2.1.285 era auto en las sesiones que no obtienen feature flags, como con un proveedor externo (Bedrock, Google Cloud, Microsoft Foundry) o con la telemetría desactivada (documentación oficial). Sin embargo, desde la v2.1.302 (16 de octubre de 2026) cambió: las sesiones del Agent SDK y de claude -p que no fijan un modo de permisos empiezan en default, incluso a través de proveedores externos. Para usar auto hay que indicarlo explícitamente (en la CLI, --permission-mode auto; historial de cambios, consultado el 18 de octubre de 2026). El modo auto descarta reglas de permiso amplias como Bash, así que, si dependes del comportamiento anterior, pasa permission_mode="default" (TS: permissionMode: "default") de forma explícita (documentación oficial). Pruébalo en un directorio de trabajo que no te importe romper. En la siguiente sección verás cómo limitar de verdad las herramientas.

Herramientas integradas

El Agent SDK incluye un amplio conjunto de herramientas listas para usar sin necesidad de escribir código adicional.

No necesitas escribir código de manejo de herramientas para usar las integradas. Lo importante es que "qué herramientas ve Claude" y "qué herramientas se ejecutan sin preguntar" son ajustes distintos. Así lo explica la documentación oficial:

Por ejemplo, si combinas allowed_tools=["Read"] con permission_mode="bypassPermissions", se aprueba todo, incluidas Bash, Write y Edit, que no están en la lista (la documentación oficial advierte expresamente sobre esta combinación). Para dejar una herramienta fuera de alcance, quítala con tools o disallowed_tools. Para trabajar solo con un conjunto fijo, combina allowed_tools con permission_mode="dontAsk", que deniega todo lo que de otro modo pediría confirmación.

Un detalle más: en macOS, Linux y WSL, Glob y Grep no forman parte de las herramientas por defecto (en Windows sí). Allí Claude busca con find y grep a través de Bash. Si nombras cualquiera de las dos en tools o allowed_tools, vuelven a estar disponibles (referencia oficial de herramientas).

Cómo crear herramientas personalizadas

Cuando las herramientas integradas no son suficientes, puedes crear las tuyas propias. Veamos cómo construir una herramienta que se conecte a una API de clima.

Python

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool(
    "get_weather",
    "Get the current weather for a given city",
    {"city": str}
)
async def get_weather(args: dict) -> dict:
    city = args["city"]
    # In practice, call an actual API
    weather_data = await fetch_weather_api(city)
    return {
        "content": [
            {"type": "text", "text": f"Weather in {city}: {weather_data}"}
        ]
    }

weather_server = create_sdk_mcp_server(
    name="weather",
    version="1.0.0",
    tools=[get_weather]
)

TypeScript

import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const getWeather = tool(
  "get_weather",
  "Get the current weather for a given city",
  { city: z.string().describe("City name") },
  async (args) => {
    const data = await fetchWeatherApi(args.city);
    return {
      content: [{ type: "text", text: `Weather in ${args.city}: ${data}` }]
    };
  }
);

Las herramientas personalizadas se crean como servidores MCP y se pasan al agente con mcp_servers (TS: mcpServers). El nombre completo de cada herramienta pasa a ser mcp__nombre-del-servidor__nombre-de-la-herramienta, así que, para que se ejecute sin preguntar, añade ese nombre a allowed_tools:

options=ClaudeAgentOptions(
    mcp_servers={"weather": weather_server},
    allowed_tools=["mcp__weather__get_weather"],
)

Si tu herramienta lanza una excepción, el bucle del agente no se detiene. El servidor MCP del SDK la captura y entrega a Claude el mensaje de la excepción tal cual, como resultado de error. Si capturas el error tú mismo y devuelves "is_error": True (TypeScript: isError: true), puedes redactar el mensaje que lee Claude: qué petición falló y qué probar en su lugar. En ambos casos Claude puede reintentar, probar otra herramienta o explicar el fallo (documentación oficial: herramientas personalizadas).

Procesamiento paralelo con subagentes

Para tareas grandes, dividir el trabajo entre subagentes y ejecutarlos en paralelo es mucho más eficiente. Los subagentes se encargan de tareas especializadas sin contaminar el contexto (memoria) del agente principal.

Cuándo usar subagentes

• Suites de pruebas extensas: aunque los logs de prueba sean enormes, no afectan el contexto del agente principal
• Investigación paralela: analizar varios módulos simultáneamente y recopilar los resultados
• Separar trabajos especializados: asignar "revisión de código" y "ejecución de pruebas" a agentes distintos

Subagentes personalizados en Claude Code

En Claude Code (CLI), puedes definir subagentes personalizados simplemente colocando archivos Markdown en el directorio .claude/agents/.

# .claude/agents/reviewer.md
---
name: code-reviewer
description: A sub-agent specialized in code review
tools: Read, Glob, Grep
model: sonnet
---

You are a senior code reviewer.
Review code for quality, security,
and best practices.

Al limitar el acceso a herramientas (en este ejemplo, solo de lectura), evitas que el revisor modifique el código accidentalmente.

Permisos, hooks y sesiones

Estos tres elementos son los que más pesan cuando un agente pasa a producción. La documentación oficial los incluye entre las capacidades de Claude Code disponibles en el SDK.

Permisos: cada llamada se evalúa en un orden fijo

Cuando Claude solicita una herramienta, el SDK evalúa hooks → reglas de denegación → reglas de consulta → modo de permisos → reglas de permiso → el callback can_use_tool, en ese orden. Una llamada que coincide con una regla de denegación (de disallowed_tools, por ejemplo) se bloquea incluso en modo bypassPermissions. Una excepción: un mod (un plugin cuyos hooks son funciones) también se ejecuta en las sesiones del Agent SDK que lo cargan (documentación oficial), y un mod que responde a tool.check puede aprobar una llamada que una regla de denegación rechazó, salvo en equipos con configuración gestionada o con sesión iniciada en un plan Team o Enterprise (documentación oficial). Instala solo mods de autores en los que confíes; más detalles en Mods de Claude Code. El modo se elige con permission_mode (según la documentación oficial a septiembre de 2026):

Hooks: ejecuta tu propio código en momentos clave

Los hooks son callbacks que se disparan con eventos como antes de ejecutar una herramienta (PreToolUse), después (PostToolUse) o al detenerse la ejecución (Stop). Se ejecutan antes de la evaluación de permisos, así que una acción que quieras bloquear en cualquier modo va aquí. Este ejemplo, recortado de la documentación oficial, bloquea la escritura en archivos .env:

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher

async def protect_env_files(input_data, tool_use_id, context):
    file_path = input_data["tool_input"].get("file_path", "")
    if file_path.split("/")[-1] == ".env":
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Cannot modify .env files",
            }
        }
    return {}

options = ClaudeAgentOptions(
    hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]}
)

Sesiones: retomar donde lo dejaste o bifurcar

El SDK guarda automáticamente en disco el historial de la conversación (prompts, llamadas a herramientas, resultados y respuestas) como una sesión. Guarda el session_id del mensaje de resultado y pásalo a resume en tu siguiente query(): el agente continúa con los archivos que ya leyó y las decisiones que ya tomó. Para retomar la sesión más reciente usa continue_conversation=True (TS: continue: true); para probar otro enfoque sin tocar la original, fork_session=True (TS: forkSession: true). Las sesiones guardan solo la conversación; los cambios en archivos no se revierten (documentación oficial: sesiones).

Además, las skills, los comandos y la memoria de .claude/ en tu proyecto y de ~/.claude/ se cargan automáticamente, igual que en Claude Code. Los plugins, que agrupan skills, agentes, hooks y servidores MCP, se pueden cargar desde una ruta local.

Agent SDK vs Client SDK vs Claude Code

La comparación oficial enumera cuatro formas de construir con Claude: Agent SDK, Claude Code CLI, Client SDK y Managed Agents. Empecemos por las tres que ejecutas en tu propia máquina o servidores.

Guía rápida de decisión:

• Trabajo de desarrollo diario → Claude Code CLI
• Construir sistemas automatizados → Agent SDK
• Crear tu propia app con IA → Client SDK
• Delegar también la gestión del bucle y del sandbox → Managed Agents (un agente alojado por Anthropic que ejecuta las sesiones en un sandbox en la nube gestionado por Anthropic o en uno propio, y se usa desde el SDK de tu lenguaje, la CLI ant o la API REST)

Casos de uso prácticos

Automatización del desarrollo de código

Este es el caso de uso más habitual. Dile al agente "implementa esta funcionalidad" y explorará la estructura de archivos, escribirá el código y ejecutará las pruebas.

# Automated bug fixing
async for msg in query(
    prompt="The auth module tests are failing. Investigate and fix the issue",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Bash", "Grep"],
        max_turns=20,
        max_budget_usd=2.00,  # Cost cap: $2
    ),
):
    pass

Integración en pipelines CI/CD

Integra con GitHub Actions u otras herramientas para crear flujos de trabajo que revisen automáticamente el código en cada PR o intenten correcciones automáticas cuando las pruebas fallen.

Análisis de datos e investigación

Tareas de investigación con múltiples pasos, como "analizar los patrones de error en los logs del último mes", se pueden delegar a un agente. Combínalo con la herramienta WebSearch para obtener también información actualizada.

Mejores prácticas

1. Establece siempre controles de costos

Dado que los agentes trabajan en bucle, pueden consumir más tokens de lo esperado. Configura siempre max_budget_usd y max_turns.

options=ClaudeAgentOptions(
    max_budget_usd=5.00,   # Stop at $5
    max_turns=30,           # Stop after 30 turns
    effort="medium",        # Reasoning depth (low/medium/high/xhigh/max)
)

xhigh se trata como high en los modelos que no lo admiten. Cuando un límite termina la ejecución, el mensaje de resultado final tiene subtype igual a "error_max_budget_usd" para max_budget_usd o "error_max_turns" para max_turns, y result queda vacío (None). Revisa subtype para saber por qué se detuvo el agente.

Ten en cuenta que el importe es una estimación que el SDK calcula con una tabla de precios incluida, no tu factura real. El presupuesto cuenta solo el gasto de esa llamada; lo gastado antes en una sesión que retomas con resume no cuenta. Para cifras exactas, usa la página Usage de Claude Console o la Usage and Cost API (documentación oficial: seguimiento de costos).

2. Usa solo las herramientas necesarias

Para que Claude no vea herramientas innecesarias, enumera solo las que necesitas en tools o quítalas por nombre en disallowed_tools. allowed_tools solo evita la confirmación; no reduce las herramientas disponibles. Mantén también la lista de aprobación automática al mínimo que requiera la tarea.

3. Informa los errores de herramientas con is_error

Una excepción en una herramienta personalizada no detiene el bucle del agente: el SDK pasa el mensaje de la excepción a Claude como resultado de error. Pero un mensaje de excepción en bruto no siempre basta para que Claude decida qué hacer. Captúrala tú y devuelve "is_error": True (TypeScript: isError: true) junto con qué falló y qué probar en su lugar, y a Claude le resultará más fácil recuperarse.

4. Delega las tareas pesadas a subagentes

Asigna las tareas con salidas voluminosas, como la ejecución de pruebas o el análisis de logs, a subagentes. Esto evita que el contexto del agente principal se sature.

5. Sé específico en tus prompts

En vez de "mejora el código", di "añade limitación de tasa a la función de login en auth.py y escribe pruebas para ello". Las instrucciones específicas producen resultados mucho más eficientes.

Resumen

Claude Agent SDK reduce drásticamente la barrera para crear agentes de IA. Con el mismo motor que impulsa Claude Code, te permite construir agentes autónomos que ejecutan tareas en Python o TypeScript.

Un buen enfoque es empezar usando Claude Code de forma interactiva para experimentar cómo funcionan los agentes, y luego migrar al Agent SDK cuando necesites automatización: una transición gradual y natural.

Si prefieres no gestionar tú mismo el bucle, el sandbox y el estado, la alternativa totalmente gestionada de Anthropic es Claude Managed Agents.

Para más información sobre los conceptos básicos de Claude, consulta también Las diferencias entre chat, Cowork y Code en Claude.