¿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 un framework que te permite crear agentes de IA potenciados por Claude usando Python o TypeScript. Es la misma tecnología que impulsa Claude Code, la CLI 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 el framework oficial de desarrollo de agentes de Anthropic. Te da acceso programático al mismo motor que impulsa Claude Code.

Sus características principales son:

De los tres modos de Claude — Chat, Cowork y Code, el Agent SDK es la tecnología detrás de Claude Code (el modo Code).

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

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)
            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.

Herramientas integradas

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

Solo necesitas especificar las herramientas a habilitar con allowed_tools y estarán listas. No hace falta escribir el código de manejo de herramientas por tu cuenta.

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 conectan al agente. Cuando ocurren errores, devuelve isError: true en vez de lanzar una excepción. Así el bucle del agente sigue funcionando y Claude puede reintentar o probar un enfoque diferente.

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.

Agent SDK vs Client SDK vs Claude Code

Claude ofrece tres interfaces para desarrolladores. Cada una tiene fortalezas distintas, así que elige según tus necesidades.

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

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/max)
)

2. Usa solo las herramientas necesarias

Habilitar herramientas innecesarias desperdicia espacio en la ventana de contexto. Concede solo las herramientas que la tarea realmente necesita a través de allowed_tools.

3. Usa isError para el manejo de errores

Si una herramienta personalizada lanza una excepción, el bucle completo del agente se detiene. Devuelve isError: true en su lugar, y Claude intentará 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.

Para más información sobre los conceptos básicos de Claude, consulta también Comparación de las tres pestañas de Claude: Chat, Cowork y Code.