Claude Agent SDK: integra Claude Code en apps con seguridad

Si quieres pasar de usar Claude Code como asistente interactivo en la terminal a integrarlo en herramientas internas, CI, revisión de PR, QA de contenido o paneles de soporte, el punto de partida actual es Claude Agent SDK.

Muchos ejemplos antiguos todavía hablan de @anthropic-ai/claude-code, claude-code-sdk o “Claude Code SDK”. En junio de 2026, la documentación oficial recomienda @anthropic-ai/claude-agent-sdk para TypeScript y claude-agent-sdk para Python. Antes de copiar código de un artículo viejo, confirma la API en Agent SDK overview y en la Migration Guide.

Este artículo no construye otro chatbot. El objetivo es un agente que pueda leer archivos, buscar en el repositorio, llamar herramientas MCP, hacer una corrección pequeña con permisos limitados, ejecutar una prueba concreta y devolver evidencia revisable.

Qué cambió y cómo pensarlo

Claude Agent SDK permite usar desde tu aplicación el agent loop que impulsa Claude Code. Un agent loop es el ciclo en el que Claude decide qué herramienta usar, lee el resultado y continúa hasta completar la tarea o detenerse. No es una llamada API de una sola respuesta.

Tema	Recomendación actual
Paquete TypeScript	@anthropic-ai/claude-agent-sdk
Paquete Python	claude-agent-sdk
CLI vs SDK	CLI para interacción humana; SDK para apps y automatización
Client SDK vs Agent SDK	Client SDK exige implementar el loop; Agent SDK usa el loop de Claude Code
Riesgo principal	Más permisos significan más potencia y más superficie de error

El SDK de TypeScript normalmente incluye un binario nativo de Claude Code como dependencia opcional, así que no siempre necesitas instalar la CLI aparte. Si tu gestor de paquetes omite optional dependencies, puede aparecer un error de binario nativo no encontrado. En ese caso corrige la instalación o pasa una ruta explícita con pathToClaudeCodeExecutable.

Setup mínimo copiable

Usaremos TypeScript con tsx para ejecutar sin pipeline de build.

mkdir claude-agent-sdk-demo
cd claude-agent-sdk-demo
npm init -y
npm install @anthropic-ai/claude-agent-sdk zod
npm install -D typescript tsx @types/node

Deja package.json así:

{
  "type": "module",
  "scripts": {
    "audit": "tsx src/read-only-audit.ts",
    "runbook": "tsx src/runbook-agent.ts",
    "fix": "tsx src/safe-fix.ts"
  },
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "latest",
    "zod": "latest"
  },
  "devDependencies": {
    "@types/node": "latest",
    "tsx": "latest",
    "typescript": "latest"
  }
}

Configura la clave por variable de entorno. No la escribas en el repositorio, en la documentación ni en logs de CI.

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

En Windows PowerShell:

$env:ANTHROPIC_API_KEY = "sk-ant-..."

Primero crea src/read-only-audit.ts. Este agente solo lee y busca; no edita y no ejecuta comandos.

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

const prompt = [
  "Inspecciona este repositorio en modo solo lectura.",
  "Encuentra comentarios TODO, dependencias antiguas y zonas con tests débiles.",
  "Devuelve una lista priorizada con referencias de archivo concretas.",
].join("\n");

for await (const message of query({
  prompt,
  options: {
    cwd: process.cwd(),
    allowedTools: ["Read", "Glob", "Grep"],
    maxTurns: 4,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Ejecuta:

npm run audit

Empezar en solo lectura no es exceso de prudencia. Te da una línea base antes de permitir Edit, Write o Bash.

Casos de uso realmente útiles

Claude Agent SDK encaja cuando la tarea requiere observar, usar herramientas y decidir. En flujos de Masa para desarrollo y contenido, estos casos son los más prácticos:

Caso	Herramientas	Salida	Límite necesario
Auditoría previa de PR	Read, Glob, Grep	Riesgos, tests faltantes, foco de review	El comentario final lo publica una persona
Corrección pequeña	Read, Edit, Bash(npm test)	Diff mínimo y resultado de tests	Prohibir push, deploy y borrados
Triage de incidente	MCP runbook y búsqueda de logs	Hipótesis y siguientes checks	Herramientas de producción solo lectura
QA de artículos multilingües	Read, Grep	Mojibake, CTA ausente, links viejos	Revisión humana del lenguaje

Para ampliar dentro de ClaudeCodeLab, combina esto con la guía de permisos, la guía de MCP server y los consejos de productividad con Claude Code.

Añadir una herramienta Runbook con MCP

MCP significa Model Context Protocol. Es una forma estándar de exponer herramientas y fuentes de datos a un agente. La guía oficial de MCP muestra cómo conectar servidores MCP desde Agent SDK. También puedes crear un servidor MCP dentro del mismo proceso.

Este ejemplo da a Claude una herramienta de runbook de solo lectura. En producción podría leer una wiki interna o una base de incidentes; aquí usamos un objeto local para que sea copiable.

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

const runbooks: Record<string, string> = {
  billing: "Revisar pagos fallidos, webhooks de Stripe y último deploy.",
  search: "Revisar hora de indexación, task status de Algolia y límites API.",
  content: "Revisar sincronización CMS, slugs por locale e imagen hero.",
};

const lookupRunbook = tool(
  "lookup_runbook",
  "Devuelve un runbook operativo de solo lectura para un servicio",
  { service: z.string().min(1) },
  async ({ service }) => {
    const text = runbooks[service] ?? "No hay runbook para ese servicio.";
    return { content: [{ type: "text", text }] };
  },
  { annotations: { readOnlyHint: true, openWorldHint: false } },
);

const runbookServer = createSdkMcpServer({
  name: "runbook",
  version: "1.0.0",
  tools: [lookupRunbook],
});

for await (const message of query({
  prompt: "Sugiere los primeros checks ante un incidente de publicación.",
  options: {
    mcpServers: { runbook: runbookServer },
    allowedTools: ["mcp__runbook__lookup_runbook"],
    maxTurns: 3,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

El error típico es permitir el nombre incorrecto. Las herramientas MCP se aprueban como mcp__nombreServidor__nombreHerramienta; lookup_runbook solo no basta.

Permitir edición sin regalar el repositorio

Cuando la auditoría solo lectura funciona, puedes permitir cambios pequeños. Hazlo con límites claros. Lee la guía oficial de permissions antes de poner en producción un agente con escritura o comandos.

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

const prompt = [
  "Corrige un único error pequeño de TypeScript bajo src.",
  "Después ejecuta npm test y reporta el resumen del diff.",
  "No hagas refactors amplios ni añadas dependencias.",
].join("\n");

for await (const message of query({
  prompt,
  options: {
    cwd: process.cwd(),
    allowedTools: [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Bash(npm test)",
    ],
    disallowedTools: [
      "Bash(git push)",
      "Bash(git commit)",
      "Bash(rm -rf *)",
    ],
    permissionMode: "default",
    maxTurns: 6,
  },
})) {
  if (message.type === "result") {
    console.log(message.subtype, message.result ?? "");
  }
}

Este patrón no da libertad total al agente. Produce un diff pequeño y evidencia de test para que una persona lo revise.

Errores y trampas comunes

La primera trampa es el nombre viejo. Si ves @anthropic-ai/claude-code o ClaudeCodeOptions, confirma si el ejemplo está desactualizado.

La segunda es abrir Bash sin restricciones. Eso puede incluir comandos de limpieza, deploy, git, instalación de paquetes o scripts con efectos secundarios. Empieza con Bash(npm test).

La tercera es no fijar cwd. Local, CI y workers pueden arrancar desde carpetas distintas. En producción, el directorio objetivo debe ser explícito.

La cuarta es tratar Agent SDK como un chat SDK normal. Un agente puede leer muchos archivos y consumir varios turnos. Revisa la guía oficial de cost tracking, registra usage y define límites.

La quinta es diseñar herramientas vagas. Nombre, descripción, schema y anotaciones deben decir cuándo usar la herramienta y si es de solo lectura.

Checklist, CTA y prueba práctica

• La API key y tokens externos no aparecen en logs.
• La primera ejecución usa solo Read, Glob, Grep.
• Los agentes con escritura tienen cwd, permisos y maxTurns definidos.
• Las herramientas MCP separan lectura de operaciones destructivas.
• Los comandos de test son concretos, no shell libre.
• Una persona revisa diff y salida de tests antes del merge.

Claude Agent SDK no se trata de automatizar todo, sino de hacer que la automatización sea revisable. Esto importa también para monetización: artículos, CTA, links de producto, eventos de analytics y formularios de consulta pueden cambiar en una sola ejecución si no hay límites.

Para empezar solo, usa la chuleta gratuita. Para prompts reutilizables y plantillas de setup, revisa productos. Para rollout de equipo, permisos, MCP, revisión en CI y automatización segura, ve a formación y consultoría Claude Code.

En esta actualización revisé las páginas oficiales de overview, TypeScript reference, MCP, permissions, migration y cost tracking. El cambio más útil fue hacer que el primer ejemplo sea solo lectura: npm run audit permite observar antes de pasar a MCP, edición y ejecución de tests. Ese orden reduce errores en repositorios reales.