Claude Agent SDK

Llegados aquí dominas Claude Code como herramienta. Pero Claude Code es solo una de las aplicaciones posibles de un motor más general: el Claude Agent SDK. El SDK te permite construir tus propios agentes — bots de soporte, copilotos internos, workflows automáticos — usando exactamente los mismos primitivos: tool use, prompt caching, sub-agentes, MCP, hooks.

Objetivos

• Distinguir API de Anthropic, Agent SDK y Claude Code.
• Hacer tu primera llamada con tool use.
• Activar prompt caching para reducir costes hasta un 90%.
• Configurar streaming para feedback en tiempo real.
• Pensar en costes: input/output, caching, modelos.

9.1 Las tres capas

Anthropic ofrece tres niveles de abstracción para usar Claude:

Si tu proyecto es "asistente de programación", usa Claude Code. Si es "asistente de soporte para clientes con acceso a nuestro CRM", construye con el SDK. Si es algo de muy bajo nivel y no encaja en SDK, vete a la API directa.

9.2 Primera llamada API

Instalación del SDK oficial:

npm install @anthropic-ai/sdk
# o
pip install anthropic

TypeScript

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "Resume en 3 frases qué es FUNDAE." }
  ]
});

console.log(response.content[0].text);

Python

from anthropic import Anthropic

client = Anthropic()  # lee ANTHROPIC_API_KEY del entorno

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Resume en 3 frases qué es FUNDAE."}
    ]
)

print(response.content[0].text)

Esto es solo "pregunta-respuesta". Para tener un agente real, necesitas tool use.

9.3 Tool use

Tool use es el mecanismo por el cual el modelo decide invocar una función externa. El flujo es:

1. Tú declaras una lista de tools con su schema.
2. Mandas el mensaje del usuario.
3. El modelo responde con: o un mensaje normal, o una solicitud de tool use.
4. Si es tool use: tú ejecutas la tool, devuelves el resultado.
5. El modelo continúa con el resultado en contexto.
6. Repite hasta que el modelo responda al usuario.

Ejemplo: agente que valida NIFs

const tools = [
  {
    name: "validate_nif",
    description: "Valida si un NIF/CIF español es correcto. Devuelve { valid, type }",
    input_schema: {
      type: "object",
      properties: { nif: { type: "string", description: "NIF a validar" } },
      required: ["nif"]
    }
  }
];

async function runAgent(userMessage: string) {
  const messages = [{ role: "user", content: userMessage }];

  while (true) {
    const response = await client.messages.create({
      model: "claude-sonnet-4-6",
      max_tokens: 1024,
      tools,
      messages
    });

    if (response.stop_reason === "end_turn") {
      return response.content[0].type === "text" ? response.content[0].text : "";
    }

    if (response.stop_reason === "tool_use") {
      const toolUse = response.content.find(c => c.type === "tool_use");

      // Añade respuesta del modelo al historial
      messages.push({ role: "assistant", content: response.content });

      // Ejecuta la tool
      const result = await executeToolLocally(toolUse);

      // Mete el resultado y continúa
      messages.push({
        role: "user",
        content: [{
          type: "tool_result",
          tool_use_id: toolUse.id,
          content: JSON.stringify(result)
        }]
      });
    }
  }
}

Eso es todo. Esa función runAgent es esencialmente lo que Claude Code hace por debajo, multiplicado por muchas tools.

9.4 Prompt caching

El cuello de botella económico de los agentes es el contexto repetido. Cada turno re-envía el system prompt, el historial, los tool results. En agentes con muchas vueltas, el coste por mensaje crece linealmente.

Prompt caching resuelve esto. Marcas un trozo del prompt como cacheable, y los siguientes 5 minutos las vueltas que reusen ese trozo lo leen del caché a 1/10 del coste.

Cómo se usa

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: "Eres un asistente de soporte de Qlcube. Sigues estas reglas...",
      cache_control: { type: "ephemeral" }      // ← marca cacheable
    }
  ],
  tools: [...],
  messages
});

Se puede cachear:

• El system prompt.
• La declaración de tools.
• Mensajes de la conversación (con un breakpoint en el último cacheable).

Estructura recomendada

1. System prompt grande con instrucciones (cacheable).
2. Tools (cacheable).
3. Mensajes históricos antiguos (cacheable hasta cierto punto).
4. Últimos mensajes (no cacheables — cambian).

9.5 Streaming

Para experiencias de chat, mejor ir entregando el texto a medida que se genera, no esperar al final. Streaming activa esto:

const stream = await client.messages.stream({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages
});

for await (const event of stream) {
  if (event.type === "content_block_delta" &&
      event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}

const final = await stream.finalMessage();

El usuario ve la respuesta materializarse en tiempo real, igual que en Claude Code o ChatGPT. Reduce la sensación de latencia incluso si el coste total es el mismo.

9.6 Diseñar tu agente

Reglas que aplican a cualquier agente que construyas con el SDK:

1. System prompt extenso, claro, cacheado

El system prompt es donde defines la personalidad, las reglas duras, los formatos. Mejor 3000 palabras claras que 200 ambiguas. Cachéalo.

2. Tools con schemas estrictos y descripciones para el modelo

El description de cada tool es lo que el modelo lee para decidir cuándo usarla. Es prompt, no documentación de developer. Escribe orientado al modelo: "Use this tool when…", "Returns…", "Do NOT use when…".

3. Loop de tool use con guardas

Limita el máximo de iteraciones (ej. 25). Si el modelo entra en bucle infinito, mata el loop con un mensaje de error.

4. Errores en tool results, no en respuestas

Si una tool falla, devuelve el error como tool_result con is_error: true. El modelo lo interpreta y replanifica. Si lanzas excepción, pierdes el contexto.

5. Métricas desde el día 1

Loguea: latencia, tokens input, tokens output, tokens cache_hit, tokens cache_creation, número de tools por conversación. Sin métricas no puedes optimizar coste.

9.7 Costes — el resumen práctico

Tarifas oficiales (octubre 2026, sujetas a cambios):

Reglas de oro para no quemar dinero:

• Activa caching. Es el mayor ahorro disponible.
• Usa Haiku en sub-agentes mecánicos. Reservar Opus para razonamiento.
• Limita max_tokens. Un output de 8K tokens cuesta ~8 veces más que uno de 1K.
• No mandes contexto irrelevante. Cada token mandado se paga.
• Mide por conversación, no por request. Una conversación de 20 turnos puede costar 0,30 € (con caching) o 3 € (sin).

9.8 Cuándo NO usar el SDK

El SDK es potente pero no siempre es la respuesta:

• Tu caso es asistencia de programación. Usa Claude Code, no escribas un wrapper.
• Tu caso es chat sin tools. La API directa es suficiente. El SDK aporta poco.
• Quieres un copiloto en tu IDE. Hay extensiones oficiales (VS Code, JetBrains).
• Tu equipo no tiene capacidad para mantener un agente custom. Considera Claude Projects, Claude Apps o un partner que gestione.

Donde el SDK sí brilla:

• Bot de atención al cliente con acceso a vuestro CRM y catálogo.
• Asistente interno con conocimiento de vuestros procesos (RGPD, FUNDAE, finance).
• Workflow automático con triggers (PR abierto → análisis → comentario).
• Procesamiento batch de documentos con razonamiento (clasificar 5000 facturas, extraer datos, validarlos).

Práctica

Test de comprensión

Resumen

• Tres capas: API directa < Agent SDK < Claude Code (apps).
• Tool use: declarar tools, ejecutar las que el modelo invoca, devolver resultados.
• Prompt caching reduce coste hasta 90% en hits — siempre actívalo.
• Streaming para sensación de inmediatez en interfaces de chat.
• Costes: medir, limitar max_tokens, escoger modelo por tarea.

Último módulo: buenas prácticas de seguridad, RGPD y compliance al desplegar Claude Code en una organización.