Introducción al Claude Code Agent SDK — Construye agentes autónomos rápidamente

¿Qué es el Agent SDK?

Claude Code Agent SDK es un framework para construir agentes autónomos impulsados por modelos Claude. A diferencia de simples llamadas a API, un agente recibe un objetivo, selecciona herramientas por sí mismo, evalúa resultados y ejecuta un bucle de razonamiento multi-paso para alcanzar una solución.

Los chatbots tradicionales funcionan en un solo ciclo de solicitud-respuesta. Con el Agent SDK, puedes completar flujos de trabajo complejos — leer archivos, identificar problemas, aplicar correcciones, ejecutar pruebas y reportar resultados — todo desde una sola instrucción.

Configuración

Inicializa tu proyecto e instala el SDK.

mkdir my-agent && cd my-agent
npm init -y
npm install @anthropic-ai/claude-code --save

Para desarrollo con TypeScript, añade también las definiciones de tipos.

npm install typescript @types/node --save-dev
npx tsc --init

Configura la variable de entorno ANTHROPIC_API_KEY y estarás listo.

export ANTHROPIC_API_KEY="sk-ant-..."

Un agente mínimo

Aquí tienes un agente simple que puede interactuar con el sistema de archivos.

import { Claude } from "@anthropic-ai/claude-code";

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  maxTurns: 10,
});

async function main() {
  const result = await agent.run(
    "Lista todos los comentarios TODO en el directorio src y ordénalos por prioridad"
  );
  console.log(result.text);
}

main();

El parámetro maxTurns limita el número máximo de pasos que el agente puede ejecutar. Configúralo siempre como protección contra bucles infinitos.

Definición de herramientas personalizadas

El verdadero poder del Agent SDK reside en las herramientas personalizadas. Al dar al agente acceso a APIs externas o bases de datos, desbloqueas una automatización mucho más práctica.

import { Claude, Tool } from "@anthropic-ai/claude-code";

const fetchIssueTool: Tool = {
  name: "fetch_github_issue",
  description: "Obtener un issue de GitHub",
  parameters: {
    type: "object",
    properties: {
      owner: { type: "string", description: "Propietario del repositorio" },
      repo: { type: "string", description: "Nombre del repositorio" },
      number: { type: "number", description: "Número del issue" },
    },
    required: ["owner", "repo", "number"],
  },
  async execute({ owner, repo, number }) {
    const res = await fetch(
      `https://api.github.com/repos/${owner}/${repo}/issues/${number}`,
      { headers: { Authorization: `token ${process.env.GITHUB_TOKEN}` } }
    );
    return await res.json();
  },
};

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  tools: [fetchIssueTool],
  maxTurns: 15,
});

Con esta definición, el agente llama a fetch_github_issue cuando lo necesita y decide su siguiente acción basándose en la información obtenida.

Cómo funciona la ejecución multi-paso

Internamente, el Agent SDK ejecuta el siguiente bucle:

1. Planificación — Descomponer la instrucción del usuario en pasos necesarios
2. Selección de herramienta — Elegir la herramienta óptima entre las disponibles
3. Ejecución — Ejecutar la herramienta y capturar resultados
4. Evaluación — Verificar si se ha alcanzado el objetivo
5. Repetir o completar — Volver al paso 1 si no ha terminado, o generar la respuesta final

Este bucle elimina la necesidad de codificar cada procedimiento de antemano, permitiendo un procesamiento flexible que se adapta a la situación.

Ejemplo práctico: Agente de revisión automática de PRs

Construyamos un caso de uso real — un agente de revisión automática de Pull Requests.

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  tools: [fetchIssueTool, readFileTool, postCommentTool],
  maxTurns: 20,
  systemPrompt: `Eres un experto en revisión de código.
Lee el diff del PR y revísalo considerando:
- Posibles bugs
- Riesgos de seguridad
- Problemas de rendimiento
- Sugerencias de mejora`,
});

const result = await agent.run(
  "Revisa el PR #42 y deja comentarios si hay algún problema"
);

Al especificar el rol del agente y los criterios de evaluación en systemPrompt, obtienes revisiones consistentes y confiables.

Manejo de errores y reintentos

El manejo robusto de errores es esencial en entornos de producción.

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  maxTurns: 10,
  onError: (error, context) => {
    console.error(`Error en el paso ${context.turn}:`, error.message);
    if (context.turn >= 3) {
      return "abort"; // Abortar tras 3 fallos
    }
    return "retry"; // Reintentar en caso contrario
  },
});

Resumen y próximos pasos

Con el Agent SDK, puedes automatizar tareas complejas de múltiples pasos en lugar de depender de respuestas de IA de un solo disparo. Comienza con tareas pequeñas como organización de archivos o análisis de logs, y gradualmente añade herramientas para expandir las capacidades de tu agente.

Para los fundamentos de Claude Code, consulta la Guía de inicio. Para desarrollo con APIs, revisa la Guía de desarrollo de APIs. Para integración con CLI, consulta Desarrollo de herramientas CLI.

Para más detalles, visita la documentación oficial de Anthropic y el repositorio de GitHub de Claude Code.