El Secreto de los Agentes en Producción Que Nadie Menciona
Todos hablan de construir agentes con Claude. Nadie habla de desplegarlos.
La semana pasada actualicé un agente en producción. Dos horas después, estaba procesando solicitudes de usuarios que no deberían tener acceso y generando respuestas que violaban las reglas del negocio.
El agente funcionaba perfectamente en mi máquina.
En producción era un caos.
Lo que aprendí: la diferencia entre un agente que funciona en desarrollo y uno que sobrevive en producción no está en el modelo. Está en tres patrones que implementé después de ese desastre.
El Problema Real: Agentes en Desarrollo vs Agentes en Producción
Cuando pruebas localmente, tú eres el único usuario. Controlas el input. Sabes qué esperar.
En producción:
→ Múltiples usuarios simultáneos con diferentes permisos → Inputs que nunca imaginaste → Llamadas API que fallan en el peor momento posible → Costes que escalan sin control si algo sale mal
El claude-agent-sdk te da las herramientas para construir el agente. Pero los patrones de producción tienes que implementarlos tú.
Patrón 1: Autenticación Con Contexto de Usuario
Este fue mi primer error: tratar la autenticación como un simple API key check.
El error común:
```typescript // ❌ Esto funciona en dev, falla en producción const agent = new ClaudeAgent({ apiKey: process.env.ANTHROPIC_API_KEY, model: 'claude-3-5-sonnet-20241022' });
await agent.chat(userMessage); ```
El problema: todos los usuarios comparten el mismo contexto. No hay aislamiento entre sesiones.
El patrón que funciona:
```typescript // ✅ Contexto de usuario en cada llamada const agent = new ClaudeAgent({ apiKey: process.env.ANTHROPIC_API_KEY, model: 'claude-3-5-sonnet-20241022' });
// Inyectar contexto de usuario en system prompt const systemPrompt = ` User Context:
- User ID: ${user.id}
- Role: ${user.role}
- Permissions: ${user.permissions.join(', ')}
- Organization: ${user.orgId}
You may only access data belonging to this user's organization. If a request exceeds user permissions, respond: "No tienes permisos para esta operación." `;
await agent.chat(userMessage, { systemPrompt, metadata: { userId: user.id, orgId: user.orgId } }); ```
La clave: el contexto de usuario no es solo para logging. Es para que el agente sepa qué puede y qué no puede hacer.
Patrón 2: System Prompts Como Guardrails
Los system prompts no son solo para personalidad. Son tus reglas de negocio ejecutables.
Después del incidente, reescribí mis prompts de sistema como guardrails explícitos:
```typescript const guardrails = ` OPERATIONAL BOUNDARIES: 1. Data Access: Only query resources where orgId = "${user.orgId}" 2. Rate Limits: Maximum 10 API calls per user request 3. Sensitive Operations: NEVER delete, update, or modify data without explicit confirmation 4. External Calls: Only call approved APIs: [${APPROVED_APIS.join(', ')}]
IF ANY RULE IS VIOLATED:
- Stop processing immediately
- Log the violation with context
- Return error message to user
- DO NOT attempt to continue or "work around" the rule
ERROR RESPONSES: For auth errors: "No tienes permisos para esta operación." For rate limit: "Has alcanzado el límite de consultas. Intenta de nuevo en unos minutos." For unsafe operations: "Esta operación requiere confirmación explícita." `;
const agent = new ClaudeAgent({ systemPrompt: guardrails, // ... resto de config }); ```
Por qué funciona:
Los LLMs son buenos siguiendo instrucciones explícitas. Si defines tus reglas de negocio como instrucciones del sistema, el modelo las respeta en la mayoría de casos.
No es perfecto (ningún sistema lo es), pero es mejor que confiar en validaciones post-hoc.
Patrón 3: Error Handling Con Fallbacks Graduales
Este es el que más me costó aprender.
La primera versión de mi agente tenía un try-catch genérico. Si algo fallaba, el usuario veía "Error procesando tu solicitud".
Útil, ¿verdad?
El patrón de fallbacks graduales:
```typescript async function executeAgentWithFallbacks( agent: ClaudeAgent, userMessage: string, context: UserContext ) { // Nivel 1: Intentar respuesta completa try { return await agent.chat(userMessage, { systemPrompt: buildSystemPrompt(context), maxTokens: 4096 }); } catch (error) { // Nivel 2: Intentar respuesta reducida if (error.type === 'rate_limit_error') { await delay(1000); try { return await agent.chat(userMessage, { systemPrompt: buildSystemPrompt(context), maxTokens: 1024 // Reducir tokens }); } catch (retryError) { // Nivel 3: Respuesta fallback return { content: `Tu consulta está en cola. Te notificaremos cuando esté lista.`, queued: true, queueId: await queueRequest(userMessage, context) }; } }
// Nivel 4: Error específico según tipo if (error.type === 'invalid_request_error') { logError('Invalid request', { error, userMessage, context }); return { content: `No pude procesar esa solicitud. ¿Puedes reformularla?`, suggestion: await getSuggestion(userMessage) }; }
// Nivel 5: Error genérico con contexto útil logError('Agent execution failed', { error, userMessage, context }); return { content: `Algo salió mal. Ya estamos investigando. Mientras tanto, puedes: [opciones alternativas]`, supportId: generateSupportId() }; } } ```
La filosofía:
Cada nivel de fallback intenta dar al usuario la mejor experiencia posible dadas las circunstancias.
No es solo "devolver un error". Es degradar gracefully.
Lo Que Realmente Cambió
Después de implementar estos tres patrones:
→ Cero incidentes de seguridad relacionados con acceso indebido a datos → Errores visibles cayeron porque los fallbacks manejan la mayoría de casos edge → Costes predecibles porque los guardrails limitan llamadas excesivas → Usuarios más contentos porque los errores incluyen contexto útil
El Verdadero Aprendizaje
Lo que nadie te dice sobre agentes en producción:
No es suficiente que funcione. Tiene que funcionar cuando:
- El usuario hace algo inesperado
- La API de Claude tiene un rate limit
- Dos usuarios acceden simultáneamente al mismo recurso
- Alguien intenta explotar el agente
Los patrones de producción no son sobre hacer que el código sea "mejor". Son sobre hacer que el código sea robusto ante la realidad del mundo real.
Tu Checklist Antes de Desplegar
Antes de subir tu próximo agente a producción, pregúntate:
1. Autenticación: ¿Cada solicitud tiene contexto de usuario? ¿Los permisos están validados? 2. Guardrails: ¿Tus reglas de negocio están en el system prompt? ¿Son explícitas? 3. Error Handling: ¿Tienes fallbacks para cada tipo de error común? ¿Los errores son útiles para el usuario?
Si la respuesta a cualquiera es "no", no despliegues todavía.
Aprende de mis errores. Implementa estos patrones desde el día uno.
Tu yo futuro (y tus usuarios) te lo agradecerán.
