Claude Agent SDK: Claude Code, pero llamado desde tu código

TL;DR pip install claude-agent-sdk (o npm install @anthropic-ai/claude-agent-sdk), importas query, pasas un prompt y la lista de tools permitidas, y obtienes el mismo agente que corre en tu terminal — programable. CI/CD, cron, API, lo que quieras. Por dentro: el agent loop, las built-in tools (Read, Write, Edit, Bash, Glob, Grep, WebSearch...), las skills de ~/.claude/, los hooks, los subagents, MCP, sessions con resume/fork. No es el Client SDK (donde implementas tú el tool loop). Es el agente completo corriendo en tu proceso. La nota importante: a partir del 15 de junio de 2026, el uso del SDK en planes de suscripción consume un crédito mensual de Agent SDK separado de tus límites interactivos.

Si llevas tiempo con Claude Code en la terminal, lo que sigue te ahorra el rato de confusión: Claude Agent SDK y Claude Code SDK son el mismo SDK. Anthropic lo renombró durante 2026 — la PAA de Google sigue llena de gente preguntando "What is the difference between Claude Code and Claude Agent SDK?". La diferencia real es la interfaz: en tu terminal lo llamas claude, en tu código lo llamas con la librería.

Bajo el capó es el mismo agent loop que corre cuando escribes claude en tu terminal: lee archivos, ejecuta comandos, edita código, gestiona contexto. La librería expone los primitivos que ya conoces (skills, hooks, subagents, MCP, permisos) como argumentos de la función query.

Hello world

Python, leer + editar + bash permitidos:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Encuentra y arregla el bug en auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)  # Claude lee el archivo, encuentra el bug, lo edita

asyncio.run(main())

TypeScript equivalente:

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

for await (const message of query({
  prompt: "Encuentra y arregla el bug en auth.ts",
  options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
  console.log(message);
}

Eso es todo. No implementas el tool loop. No serializas tool_use ni tool_result. Claude lo gestiona dentro de la librería.

Setup

1. Instala el SDK.

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

El SDK de TypeScript trae el binario nativo de Claude Code empaquetado, así que no necesitas instalar Claude Code aparte.

2. Configura tu API key.

export ANTHROPIC_API_KEY=tu-api-key

Otras vías de auth soportadas: Amazon Bedrock (CLAUDE_CODE_USE_BEDROCK=1), Google Vertex AI (CLAUDE_CODE_USE_VERTEX=1), Azure AI Foundry (CLAUDE_CODE_USE_FOUNDRY=1), Claude Platform on AWS (CLAUDE_CODE_USE_ANTHROPIC_AWS=1).

Claude Code (CLI) vs Agent SDK: cuándo cada uno

Mismas capacidades, distinta superficie. La tabla oficial:

"Many teams use both: CLI for daily development, SDK for production." — docs.

Lo que enchufas como en local

Las skills, slash commands y CLAUDE.md se cargan por defecto desde .claude/ y ~/.claude/. Si quieres restringir orígenes, pasa setting_sources en las opciones.

El SDK ≠ Client SDK

La trampa típica. El Anthropic Client SDK te da acceso directo a la API: tú envías prompts y tú implementas el tool loop. El Agent SDK ya lo trae:

# Client SDK — tú escribes el loop
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.tool_use)
    response = client.messages.create(tool_result=result, **params)

# Agent SDK — Claude gestiona las tools
async for message in query(prompt="Fix the bug in auth.py"):
    print(message)

Si te encuentras escribiendo un while response.stop_reason == "tool_use", estás en el SDK equivocado.

Coste a partir del 15 de junio de 2026

Anthropic introduce un crédito mensual de Agent SDK en los planes de suscripción, separado del uso interactivo de Claude Code. El uso del SDK (y de claude -p, modo headless) cuenta contra ese crédito, no contra tus límites interactivos. Detalle oficial en el aviso de pricing.

Antes del 15 de junio, todo el uso del SDK cuenta como API normal (tokens facturados a tu cuenta).

Combina con

• GitHub Actions — la action de @claude que revisa PRs corre encima del Agent SDK. Saber esto te permite extenderla.
• Subagents — el patrón que ya usabas en local, vía agents={}.
• Plugins — cargables programáticamente via la opción plugins.
• Cheat sheet de slash commands — todo lo que invocas con / también es invocable desde el SDK.

Documentación oficial: Agent SDK overview · Python SDK · TypeScript SDK