System prompts para agentes en producción: el formato que sobrevivió 3 rediseños

La solución correcta para hacer que un agente haga menos es escribirle más en el system prompt. Sé que suena raro. Dejame explicar.

El primer instinto cuando un agente se pasa de rosca es recortarle permisos en la lógica de la aplicación. Validaciones, guardrails, filtros sobre la respuesta. Pero el problema suele estar antes: el modelo no tiene un contrato claro de qué se espera de él. Y sin contrato, optimiza para parecer útil. No para ser correcto.

Mi tesis es esta: un system prompt bien estructurado no es documentación para el modelo, es un contrato. Las secciones más importantes no son las que describen el rol —esas las escribe cualquiera— sino las que definen límites explícitos y el formato de salida esperado. Sin esas dos, el agente llena los huecos con lo que cree que querés escuchar.

Esto no es una conclusión universal. Es el patrón que encontré después de rediseñar el mismo formato varias veces, respaldado por la guía oficial de Anthropic sobre prompt engineering.

El problema concreto que genera este formato

Hay un patrón común en equipos que empiezan a usar agentes: el system prompt es un párrafo en prosa que describe el personaje del modelo. "Sos un asistente experto en X. Respondé de forma clara y concisa."

Eso funciona para demos. En producción, ese prompt enfrenta casos que el autor no imaginó al escribirlo. El modelo no tiene instrucciones sobre qué hacer cuando la pregunta está fuera de scope, cuando le faltan datos para responder correctamente, o cuando el formato esperado por el sistema que consume la respuesta es específico.

El resultado típico es uno de dos extremos: el agente inventa información para parecer completo, o da respuestas tan genéricas que no sirven. Ambos son el mismo error de diseño: el prompt no tiene contratos de borde.

La guía de Anthropic es explícita en este punto: separar el system prompt del turno humano tiene propósito arquitectónico. El system prompt establece identidad, capacidades y restricciones. No es un lugar para instrucciones mezcladas con contexto dinámico sin estructura.

Las cuatro secciones que quedaron después de tres rediseños

El formato actual que uso tiene secciones fijas, marcadas con encabezados en mayúsculas para que el modelo las identifique sin ambigüedad. La estructura quedó así:

// Construcción del system prompt con secciones fijas
// El contexto dinámico se inyecta solo en CONTEXT, no mezcla con ROL o LIMITS

function buildSystemPrompt(ctx: AgentContext): string {
  return `
ROL
Sos un agente de procesamiento de documentos. Analizás texto estructurado y extraés entidades definidas en el esquema.

LÍMITES
- No inferís información que no esté en el documento fuente.
- Si un campo requerido no aparece en el texto, devolvés null para ese campo. No inventes un valor plausible.
- No respondés preguntas fuera del scope de extracción de entidades.
- Si el documento está en un idioma no soportado, devolvés un error estructurado, no intentás traducir.

CONTEXT
Fecha de procesamiento: ${ctx.processingDate}
Esquema de entidades esperado: ${JSON.stringify(ctx.schema, null, 2)}
Idiomas soportados: ${ctx.supportedLanguages.join(', ')}

FORMATO DE SALIDA
Devolvé exclusivamente JSON válido con esta estructura. Sin texto adicional, sin markdown, sin explicaciones:
{
  "entities": [...],
  "confidence": number,  // entre 0 y 1
  "errors": string[]     // vacío si no hay errores
}
`.trim();
}

ROL — describe qué hace el agente, no cómo es su personalidad. La diferencia importa: el rol es funcional, no estético.

LÍMITES — esta es la sección que más veces reescribí. El primer diseño no la tenía. El segundo la tenía mezclada con el rol. El tercero la separó pero usaba lenguaje vago ("no exageres", "sé conservador"). La versión actual usa condiciones específicas y acciones específicas. Si X, entonces Y. Sin margen de interpretación.

CONTEXT — la única sección dinámica. Todo lo que cambia por request, por usuario o por estado del sistema va acá. La regla que me costó aprender: si algo cambia entre llamadas, no va en ROL ni en LÍMITES. Mezclarlo en las secciones fijas rompe la consistencia semántica del prompt entre requests.

FORMATO DE SALIDA — la sección que más trabajo ahorra en el código que consume la respuesta. Cuanto más específico, menos parsing defensivo necesitás después.

Dónde se equivoca la gente: el costo oculto del contexto dinámico sin estructura

El error más común que veo en prompts compartidos en repos públicos es inyectar contexto dinámico directamente en el cuerpo del rol, sin separación. Algo así:

// ❌ Patrón problemático: contexto mezclado con instrucciones fijas
const systemPrompt = `
Sos un asistente de soporte. Hoy es ${new Date().toISOString()}.
El usuario se llama ${user.name} y tiene plan ${user.plan}.
Ayudalo con sus preguntas. Sé amable y conciso.
El esquema de respuesta es: { message: string }.
`;

El problema no es que incluya contexto dinámico —eso está bien. El problema es que mezcla fecha, datos del usuario, instrucciones de comportamiento y formato de salida en el mismo bloque sin estructura. Cuando el modelo recibe eso, no tiene señales claras de qué es un límite, qué es contexto y qué es instrucción de formato.

En la práctica, esto se manifiesta de dos formas: el modelo ignora el formato de salida cuando el contexto del usuario es inusual, o aplica restricciones que eran para un contexto específico a todos los contextos. Ambos casos terminan en bugs difíciles de reproducir porque dependen del contenido dinámico del request.

La guía de Anthropic recomienda usar etiquetas XML para separar secciones cuando el contenido puede ser ambiguo. El encabezado en mayúsculas es una variante del mismo principio: darle al modelo señales inequívocas de estructura.

Cuándo el contexto dinámico ayuda y cuándo confunde

Esta es la distinción que más me costó llegar a articular con precisión:

Contexto dinámico que ayuda: datos factuales que el modelo necesita para operar correctamente en ese request específico. Fecha actual, esquema de datos, configuración del entorno, estado relevante del sistema. Información que no puede venir de ningún otro lado.

Contexto dinámico que confunde: instrucciones de comportamiento que cambian por usuario o por sesión. Si los límites del agente varían según el tipo de usuario, no los inyectes en el prompt como texto libre. Modelalos como secciones condicionales con lógica explícita, o considerá agentes separados.

// ✓ Contexto dinámico factual: correcto
const context = `
CONTEXT
Fecha: ${processingDate}
Esquema activo: ${JSON.stringify(schema)}
`;

// ❌ Instrucciones que cambian por usuario: problemático
const context = `
CONTEXT
${user.isPremium ? 'Podés responder preguntas avanzadas.' : 'Solo respondés preguntas básicas.'}
`;

// ✓ Alternativa para comportamiento variable: sección explícita y condicional
const limits = user.isPremium
  ? 'LÍMITES\nScope: análisis avanzado. Sin restricción de longitud.'
  : 'LÍMITES\nScope: preguntas básicas únicamente. Máximo 3 pasos de razonamiento.';

El modelo maneja bien el contexto factual dinámico. Maneja peor las instrucciones condicionales escritas en prosa, especialmente cuando se acumulan a lo largo de múltiples versiones del prompt.

Checklist antes de deployar un system prompt

Antes de poner un system prompt en producción, pasalo por estas preguntas. No son exhaustivas, pero cubren los problemas más comunes:

• ¿Hay una sección explícita de límites separada del rol? Si los límites están mezclados con la descripción del rol, separarlos.
• ¿El formato de salida está especificado con un ejemplo concreto? Describirlo en prosa no es suficiente si el formato es estructurado (JSON, XML, lista con formato específico).
• ¿Todo el contenido dinámico está en la sección CONTEXT? Si hay ${variables} fuera de esa sección, revisar si deben estar ahí.
• ¿Los límites usan condiciones específicas? "No inventes datos" es vago. "Si el campo no aparece en el texto fuente, devolvés null" es un contrato.
• ¿Sabés qué debe hacer el agente cuando la pregunta está fuera de scope? Si no hay instrucción explícita para ese caso, el modelo va a inventar una respuesta razonable.
• ¿El prompt tiene más de 800 tokens? No es automáticamente malo, pero es señal de revisar si hay redundancia entre secciones o contexto innecesario.

Este checklist no reemplaza probar el prompt con casos de borde. Pero reduce los problemas obvios antes de llegar a esa etapa.

Los límites de este enfoque

Acá es donde tengo que ser honesto sobre lo que este formato resuelve y lo que no.

Lo que resuelve bien: claridad estructural, menos ambigüedad en comportamiento de borde, mejor consistencia en formato de salida. Esos beneficios son observables sin métricas sofisticadas.

Lo que no resuelve: un modelo mal elegido para la tarea, contexto insuficiente para responder correctamente, o instrucciones contradictorias que requieren razonamiento complejo. Estructurar mejor el prompt no compensa esos problemas.

Lo que no puedo afirmar sin experimento: que este formato mejora métricas de accuracy en un porcentaje específico, que funciona igual con todos los modelos, o que la separación en cuatro secciones es superior a otras estructuras en casos no contemplados. Para eso necesitás logs, evaluaciones con casos de prueba definidos y un criterio de medición previo.

La guía de Anthropic es el mejor punto de partida para validar estructura. Lo que yo agrego es el criterio de cuándo separar contexto dinámico y la insistencia en límites con condiciones específicas, no prosa vaga.

FAQ

¿Cuántas secciones debe tener un system prompt para agentes? No hay un número mágico. El formato de cuatro secciones (ROL, LÍMITES, CONTEXT, FORMATO DE SALIDA) es el mínimo que encontré útil para agentes con comportamiento no trivial. Agentes simples pueden funcionar con menos. Lo que no conviene recortar son los LÍMITES y el FORMATO DE SALIDA: esas dos secciones son las que más impacto tienen en consistencia.

¿Dónde va la información del usuario en un system prompt? En la sección CONTEXT, como dato factual. No en ROL ni en LÍMITES. Si la información del usuario cambia el comportamiento del agente (no solo el contexto), considerá si eso debería ser una sección condicional explícita o un agente diferente con su propio system prompt.

¿Tiene sentido usar XML en lugar de encabezados en mayúsculas? Sí, especialmente si el contenido de alguna sección puede contener caracteres que confundan el parsing. Anthropic lo recomienda para contenido ambiguo. Los encabezados en mayúsculas son más legibles para revisión humana. Elegí el que sea más consistente con el resto de la codebase.

¿Cómo testeo que el system prompt funciona correctamente? Con casos de borde definidos antes de escribir el prompt, no después. Los más importantes: pregunta fuera de scope, dato requerido ausente en el input, formato de input inusual. Si el agente no tiene instrucciones explícitas para esos casos, va a inventar una respuesta. La Anthropic Prompt Engineering Guide tiene ejemplos de evaluación estructurada.

¿El system prompt puede cambiar en runtime? Técnicamente sí, pero es una fuente de bugs difíciles de depurar. Lo que cambia en runtime es la sección CONTEXT. El ROL y los LÍMITES deben ser estables entre requests del mismo agente. Si necesitás comportamiento radicalmente diferente, es señal de que necesitás dos agentes, no un prompt condicional complejo.

¿Qué hago si el modelo ignora el formato de salida especificado? Primero, verificá que el ejemplo de formato está en la sección correcta y es inequívoco. Segundo, probá con un prefill de respuesta (en modelos que lo soportan) para anclar el inicio del output. Tercero, si el problema persiste, revisá si el contexto dinámico está introduciendo ambigüedad que sobrescribe las instrucciones de formato.

Cierre: un contrato que se puede revisar

Lo que me cambió la forma de pensar sobre system prompts no fue leer sobre prompt engineering sino enfrentar comportamiento inesperado de un agente y no tener forma de razonar sobre qué instrucción lo causó, porque todo estaba en un bloque de prosa sin estructura.

Estructurar el prompt en secciones no es burocracia. Es lo que te permite decir "el modelo se comportó distinto porque cambió el contexto dinámico" en lugar de "no sé, el modelo es impredecible". La diferencia entre esas dos frases es la diferencia entre un sistema debuggeable y uno que opera por intuición.

Mi recomendación práctica: si tenés un agente en producción con un system prompt en prosa, no lo reescribas de cero. Empezá por separar los límites en su propia sección y mover todo el contenido dinámico a una sección CONTEXT explícita. Esos dos cambios solos ya reducen la superficie de ambigüedad.

El próximo paso concreto: tomá el prompt actual, pegalo en un doc, y preguntate: ¿cuál es el límite más importante de este agente y dónde está escrito explícitamente? Si no podés señalar una oración específica, ahí está el primer hueco.

Fuente original:

• Anthropic Prompt Engineering Guide: https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview