Instrucciones de uso de Claude Agent SDK

El Claude Agent SDK te permite construir agentes de IA que pueden leer archivos, ejecutar comandos, buscar en la web, editar código, etc., de forma autónoma.

El Claude Agent SDK expone las herramientas, el bucle de agente y las capacidades de gestión de contexto que impulsan a Claude Code como bibliotecas programables de Python y TypeScript.

En pocas palabras, es un SDK que utiliza Claude Code como una biblioteca. Puedes integrarlo en tus propias aplicaciones, canalizaciones de CI o scripts de automatización para construir agentes de IA que completen tareas complejas de forma autónoma.

Capacidades principales

El SDK incluye herramientas integradas para leer archivos, ejecutar comandos y editar código. Tu agente no necesita implementar la lógica de ejecución de herramientas por sí mismo, puede empezar a trabajar de inmediato. Las capacidades principales incluyen:

Capacidad Descripción
Herramientas integradas Lectura/escritura de archivos, comandos de terminal, edición de código, búsqueda web, etc.
Hooks Ejecutar lógica personalizada antes y después de las llamadas a herramientas
Subagentes (Subagents) Dividir tareas grandes y asignarlas en paralelo a subagentes independientes para su ejecución.
Servidores MCP Conectar bases de datos, navegadores, API externas, etc.
Control de permisos Controlar con precisión qué puede hacer el agente y cuándo requiere aprobación del usuario.
Gestión de sesiones (Sessions) Construir agentes conversacionales de múltiples turnos que mantienen el contexto.

Requisitos previos

  • Node.js 18+(TypeScript) oPython 3.10+
  • unacuenta de Anthropic, y obtener una clave de API (regístrate aquí）

Paso 1: Instalar el SDK

TypeScript

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

El SDK de TypeScript incluye el binario de Claude Code para tu plataforma actual como una dependencia opcional, por lo que no necesitas instalar Claude Code por separado.

Python

# 使用 pip
pip install claude-agent-sdk

# 或使用 uv（推荐）
uv add claude-agent-sdk

Nota: ¡La CLI de Claude Code se instalará automáticamente con el paquete, no es necesario instalarla por separado! El SDK utiliza la CLI incluida de forma predeterminada.

Si prefieres usar una instalación a nivel de sistema o especificar una versión, puedes hacerlo medianteClaudeAgentOptions(cli_path="/path/to/claude")especificar la ruta.

Paso 2: Configurar la clave de API

desdeClaude ConsoleObtén una clave de API y luego crea en el directorio del proyecto el archivo.envarchivo:

ANTHROPIC_API_KEY=your-api-key-here

O establécelo directamente como variable de entorno:

export ANTHROPIC_API_KEY=your-api-key-here

Plataformas en la nube de terceros compatibles

El SDK también admite autenticación a través de proveedores de API de terceros: Amazon Bedrock (configurando la variable de entornoCLAUDE_CODE_USE_BEDROCK=1variable de entorno y configurando las credenciales de AWS), Google Vertex AI (configurandoCLAUDE_CODE_USE_VERTEX=1) y Microsoft Azure (configurandoCLAUDE_CODE_USE_FOUNDRY=1）。

⚠️ Importante: A menos que obtengan la aprobación previa de Anthropic, los desarrolladores de terceros no pueden ofrecer inicio de sesión de claude.ai ni limitación de velocidad en productos construidos con Claude Agent SDK. Utiliza el método de autenticación con clave de API descrito en la documentación.

Paso 3: Ejecuta tu primer agente

El siguiente ejemplo crea un agente que lista los archivos del directorio actual:

Python

Ejemplo

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="What files are in this directory?",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

TypeScript

Ejemplo

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

async function main() {
  for await (const message of query({
    prompt: "What files are in this directory?",
    options: { allowedTools: ["Bash", "Glob"] },
  })) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

Tutorial práctico: Construir un agente que corrige errores automáticamente

A continuación, mediante un ejemplo completo, se demuestra el uso principal del Agent SDK.

Preparar un archivo con errores

Creautils.py, que contiene dos errores intencionales:

Ejemplo

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)   # Bug: división por 0 cuando la lista está vacía

def get_user_name(user):
    return user["name"].upper()   # Bug: se produce TypeError cuando user es None

Escribir el agente

Creaagent.py：

Ejemplo

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

async def main():
    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 permitidas
            permission_mode="acceptEdits",            # Aprobar automáticamente la edición de archivos
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)          # El proceso de razonamiento de Claude
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}") # La herramienta que se está llamando
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")  # Resultado final

asyncio.run(main())

Ejecutar

python agent.py

Después de ejecutar, revisautils.py, verás que el agente completó de forma autónoma las siguientes acciones:

  1. Leeryautils.pyel archivo
  2. Analizóla lógica del código, identificando casos límite que podrían causar fallos.
  3. Editóel archivo, añadiendo un manejo de errores sólido.

Análisis de conceptos clave

Función: entrada al bucle del agente

queryEs el punto de entrada principal para crear el bucle del agente y devuelve un iterador asíncrono, por lo que usasasync forpara obtener en tiempo real, mediante streaming, los mensajes generados mientras Claude trabaja. El bucle finaliza cuando Claude completa la tarea o encuentra un error. El SDK se encarga de la orquestación (ejecución de herramientas, gestión de contexto, reintentos); solo tienes que consumir este flujo de mensajes.

Cada iteración produce un mensaje, que puede ser:

  • El proceso de razonamiento de Claude
  • Una llamada a herramienta
  • El resultado de una llamada a herramienta
  • El resultado final

Herramientas (Tools): controlar lo que el agente puede hacer

Combinación de herramientas Capacidad del agente
Read, Glob, Grep Análisis de solo lectura
Read, Edit, Glob Analizar y modificar código
Read, Edit, Bash, Glob, Grep Automatización completa
AñadiendoWebSearch Añadir capacidad de búsqueda web

Modos de permiso (Permission Modes): controlar el nivel de supervisión humana

Modo Comportamiento Casos de uso
acceptEdits Aprueba automáticamente la edición de archivos; otras operaciones aún requieren confirmación. Flujo de trabajo de desarrollo de confianza
dontAsk RechazarallowedToolstodas las operaciones excepto Agente desatendido bloqueado
auto(solo TypeScript) El clasificador de modelos aprueba/rechaza automáticamente cada llamada a herramienta. Agente autónomo con salvaguardas de seguridad
bypassPermissions Ejecuta todas las herramientas directamente sin pedir confirmación. Entornos de CI en sandbox
default Requiere proporcionarcanUseToolun callback para manejar la aprobación. Flujo de aprobación personalizado

Personalizar el comportamiento del agente

Añadir búsqueda web

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"],
    permission_mode="acceptEdits"
)

Añadir indicaciones de sistema personalizadas

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)

Permitir ejecutar comandos de terminal

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"],
    permission_mode="acceptEdits"
)
# 可以尝试：
# prompt="Write unit tests for utils.py, run them, and fix any failures"

Cargar configuración del proyecto (CLAUDE.md, etc.)

El SDK está construido sobre la misma base que Claude Code; los agentes del SDK pueden acceder a las mismas funciones basadas en el sistema de archivos: instrucciones del proyecto (CLAUDE.md y rules), habilidades, hooks, etc. De forma predeterminada, el SDK no carga ninguna configuración del sistema de archivos.

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit"],
    # "user" 从 ~/.claude/ 加载，"project" 从 ./.claude/ 加载
    setting_sources=["user", "project"],
)

Manejo de errores

from claude_agent_sdk import (
    ClaudeSDKError,      # 基础错误
    CLINotFoundError,    # Claude Code 未安装
    CLIConnectionError,  # 连接问题
    ProcessError,        # 进程失败
    CLIJSONDecodeError,  # JSON 解析失败
)

try:
    async for message in query(prompt="Hello"):
        pass
except CLINotFoundError:
    print("请先安装 Claude Code")
except ProcessError as e:
    print(f"进程失败，退出码：{e.exit_code}")
except CLIJSONDecodeError as e:
    print(f"响应解析失败：{e}")

Agent SDK vs. otras herramientas de Claude

Agent SDK Client SDK（Messages API） Claude Code CLI
Forma de uso Biblioteca Python/TypeScript Llamadas HTTP API Herramienta CLI de terminal
Ejecución de herramientas Integrada, ejecución automática Requiere implementación manual Integrada, interactiva
Casos de uso Construcción de agentes autónomos, integración de aplicaciones Llamadas generales a LLM Asistencia directa de codificación
Gestión de estado Con estado, admite sesiones Sin estado Con estado, interactivo

Tabla comparativa de funciones del SDK

El SDK también admite la configuración basada en el sistema de archivos de Claude Code. Para usar estas funciones, debe configurarlas en las opcionessetting_sources=["project"](Python) osettingSources: ['project']（TypeScript）。

Función Descripción Ubicación
Skills (habilidades) Capacidades especializadas definidas con Markdown .claude/skills/*/SKILL.md
Slash Commands Comandos personalizados para tareas comunes .claude/commands/*.md
Memory (memoria) Contexto e instrucciones del proyecto CLAUDE.md
Plugins (complementos) A través depluginsExtensión de opciones Configuración mediante código
Otras extensiones