Claude Agent SDK: Orquestación Multi-Agente para Producción Real
Build production Claude Agent SDK systems with multi-agent orchestration, structured outputs, prompt caching, and real error handling patterns that work.
La Mayoría de los "Agentes" No Son Agentes. Son Prompts Glorificados
Un agente real toma decisiones. Usa herramientas. Coordina con otros agentes. Persiste estado entre llamadas.
Lo que la mayoría llama "agente" es un prompt largo con una función de Python alrededor.
*La diferencia no es semántica. Es arquitectural.*
El real problema con Claude Agent SDK no es aprenderlo. Es entender cuándo necesitas orquestación multi-agente versus cuándo un solo LLM call basta.
Esta guía te da la arquitectura correcta para cada caso.
---
Por Qué Multi-Agente Importa en 2026
Los sistemas de agente único tienen un límite duro: el context window.
Cuando tu pipeline necesita procesar 50 fuentes de noticias, generar artículos, publicar en 6 plataformas y auditar cada paso — todo en paralelo — un solo agente se rompe.
El patrón que funciona en producción es orquestación jerárquica:
→ Un agente orquestador que decide qué hacer
↳ Agentes especializados que ejecutan tareas concretas
↳ Cada agente tiene herramientas específicas y contexto limitado
Esto no es teoría. Es la arquitectura que usamos en el sistema autónomo de contenido que corre todos los días sin intervención humana: 5 pipelines, 14 agentes, un solo modelo.
---
Arquitectura Real: Orquestador + Agentes Especializados
Antes de escribir código, decide tu topología.
❌ Lo que hace la mayoría:
```typescript
// Un agente que intenta hacer todo
const response = await claude.messages.create({
model: 'claude-haiku-4-5-20251001',
messages: [{
role: 'user',
content: 'Busca noticias, analiza tendencias, escribe artículo, publícalo en Twitter y LinkedIn'
}]
});
```
Este enfoque falla en producción por tres razones:
→ El contexto se satura con información irrelevante
→ No puedes reintentar pasos individuales cuando fallan
→ Imposible paralelizar
✅ La arquitectura correcta:
```typescript
// Orquestador: decide qué agentes lanzar
async function orchestrator(topic: string) {
// Paso 1: Agente de investigación (paralelo)
const [sources, trends] = await Promise.all([
researchAgent(topic),
trendAnalysisAgent(topic)
]);
// Paso 2: Agente de escritura (secuencial, necesita output anterior)
const article = await writingAgent({ topic, sources, trends });
// Paso 3: Agentes de publicación (paralelo)
await Promise.all([
publishToTwitter(article),
publishToLinkedIn(article),
saveToDatabase(article)
]);
}
```
Cada agente tiene una responsabilidad. Cada uno puede fallar y reintentarse de forma independiente.
---
Structured Outputs: La Feature Más Infrautilizada
El 90% de los desarrolladores parsean JSON con regex o con `.includes('{')`. Eso es frágil, lento y produce bugs en producción.
Claude Agent SDK tiene `jsonSchemaOutput` — Claude retorna JSON válido garantizado por el modelo.
```typescript
import Anthropic from '@anthropic-ai/sdk';
import { zodToJsonSchema } from 'zod-to-json-schema';
import { z } from 'zod';
// Define el schema con Zod (validación runtime)
const ArticleSchema = z.object({
title: z.string().min(10).max(100),
summary: z.string().min(50).max(300),
content: z.string().min(500),
tags: z.array(z.string()).max(5),
seoScore: z.number().min(0).max(100)
});
type Article = z.infer<typeof ArticleSchema>;
async function writingAgent(
context: { topic: string; sources: string[]; trends: string[] }
): Promise<Article> {
const client = new Anthropic();
const response = await client.messages.create({
model: 'claude-haiku-4-5-20251001',
max_tokens: 4096,
system: {
type: 'text',
text: `Eres un experto en creación de contenido SEO.
Genera artículos estructurados basados en el contexto proporcionado.
Responde SIEMPRE con JSON válido que coincida con el schema.`,
// Prompt caching: ahorra tokens en llamadas repetidas
cache_control: { type: 'ephemeral' }
},
messages: [{
role: 'user',
content: `Crea un artículo sobre: ${context.topic}
Fuentes: ${context.sources.join('\n')}
Tendencias: ${context.trends.join('\n')}`
}],
// Structured output: JSON garantizado
output_config: {
type: 'json_schema',
json_schema: {
name: 'article_output',
schema: zodToJsonSchema(ArticleSchema)
}
}
});
const raw = JSON.parse(response.content[0].text);
// Validación runtime con Zod
return ArticleSchema.parse(raw);
}
```
Por qué esto importa en producción:
→ Elimina el parsing frágil de JSON
→ Zod valida que el output tiene la forma correcta
→ Los errores se detectan en el agente, no en el consumidor
---
Prompt Caching: El Multiplicador de Eficiencia
Si tu sistema llama al mismo agente cientos de veces por día, el prompt caching es obligatorio.
El `cache_control: { type: 'ephemeral' }` en el system prompt le dice a Claude que reutilice el contexto cacheado. El requisito mínimo es 4.096 tokens para Haiku.
```typescript
// Sistema centralizado de configuración
// src/utils/constants.ts
export const CLAUDE_CONFIG = {
model: 'claude-haiku-4-5-20251001',
maxTokens: 4096,
systemPromptCaching: true
} as const;
// Cliente compartido como singleton
// src/lib/anthropic.ts
import Anthropic from '@anthropic-ai/sdk';
let client: Anthropic | null = null;
export function getAnthropicClient(): Anthropic {
if (!client) {
client = new Anthropic({
apiKey: process.env.ANTHROPIC_API_KEY!
});
}
return client;
}
```
El patrón de singleton evita crear un cliente nuevo en cada llamada. En sistemas con alta frecuencia, eso consume recursos innecesariamente.
---
Manejo de Errores en Pipelines Multi-Agente
La mayoría aprende esto a golpes en producción.
*El error más común: fire-and-forget en Vercel.*
```typescript
// ❌ INCORRECTO: Vercel mata las promesas pendientes al timeout
async function pipeline(topic: Topic) {
await processArticle(topic);
// Este log puede perderse si Vercel termina la función
logAudit(topic.id, 'completed').catch(() => {});
}
```
```typescript
// ✅ CORRECTO: El audit log completa antes de resolver la promesa
async function pipeline(topic: Topic) {
try {
const result = await processArticle(topic);
await logAudit(topic.id, 'completed', result);
return result;
} catch (error) {
await logAudit(topic.id, 'failed', { error: error.message });
throw error;
}
}
```
Vercel Fluid Compute termina funciones al límite de timeout (300 segundos). Cualquier promesa pendiente muere — incluso las que parecen seguras en un `.catch()`.
Tres reglas para pipelines robustos:
Regla 1: Awaita siempre los audit logs dentro de la misma promesa que el trabajo que rastrean.
Regla 2: Usa SHA-256 para deduplicación de fuentes, no timestamps. Los timestamps tienen colisiones en pipelines paralelos.
Regla 3: Diseña cada agente para ser idempotente. Si el pipeline se reintenta, no debe duplicar trabajo.
---
Coordinación de Agentes en Equipo: El Patrón Real
Cuando construyes Claude Code Agent Teams — agentes que se coordinan para tareas complejas — la clave es la separación de responsabilidades.
```typescript
// Cada agente tiene un rol exacto y herramientas específicas
interface AgentConfig {
role: 'researcher' | 'writer' | 'publisher' | 'auditor';
tools: string[];
maxContextTokens: number;
outputSchema: ZodSchema;
}
const AGENT_CONFIGS: Record<string, AgentConfig> = {
researcher: {
role: 'researcher',
tools: ['web_search', 'rss_fetch', 'content_extract'],
maxContextTokens: 2048,
outputSchema: ResearchOutputSchema
},
writer: {
role: 'writer',
tools: ['seo_check', 'readability_score'],
maxContextTokens: 8192, // Necesita más contexto
outputSchema: ArticleSchema
},
publisher: {
role: 'publisher',
tools: ['twitter_post', 'linkedin_post', 'database_save'],
maxContextTokens: 1024, // Solo necesita el artículo final
outputSchema: PublishResultSchema
}
};
```
El `maxContextTokens` limitado por agente es crítico. Un agente de publicación no necesita las 50 fuentes que procesó el investigador. Pasarle contexto innecesario aumenta latencia y reduce precisión.
---
De Prototipo a Producción: El Checklist
Antes de declarar tu sistema "en producción", verifica esto:
→ Structured outputs con Zod en todos los agentes — sin parsing manual de JSON
→ Prompt caching en system prompts que superen 4.096 tokens
→ Singleton client de Anthropic — no instancies el cliente en cada llamada
→ Audit logs awaited — nunca fire-and-forget en entornos serverless
→ Deduplicación con hash — SHA-256 sobre contenido normalizado, no timestamps
→ Idempotencia — cada agente puede reejecutarse sin duplicar efectos
→ Separación de contexto — cada agente recibe solo la información que necesita
El sistema autónomo que describimos en la arquitectura maneja 14 agentes con estas reglas. Corre todos los días. No requiere intervención humana.
---
Takeaways
La orquestación multi-agente no es complejidad por complejidad. Es la única forma de construir pipelines que escalen sin romperse.
→ Un agente hace una cosa bien. Un sistema de agentes hace cosas imposibles.
→ Structured outputs con Zod eliminan la categoría entera de bugs de parsing.
→ Prompt caching es obligatorio en sistemas de alta frecuencia.
→ Fire-and-forget en serverless es un bug silencioso que descubres en producción.
→ El context window limitado por agente mejora precisión, no la reduce.
*Los agentes que funcionan en producción no son más inteligentes. Son más disciplinados.*
La próxima vez que diseñes un sistema de agentes, empieza por la topología — no por el prompt.
Lee el artículo completo en brianmenagomez.com