Prompt engineering para agentes: cómo escribir prompts que funcionen

En un chatbot, el prompt es una instrucción. En un agente, el prompt es código: define qué herramientas usa, cómo decide llamarlas, qué formato entrega y qué le está prohibido hacer. Un prompt de agente mal escrito no produce respuestas graciosas, produce llamadas a herramientas equivocadas, datos inventados y costos duplicados. Esta guía cubre la diferencia entre system y user prompt, las técnicas que funcionan (roles, formato de salida, límites), ejemplos antes y después, y cómo iterar con evals en lugar de probar a ciegas.

System prompt vs user prompt

El system prompt es la especificación permanente del agente: quién es, qué hace, qué herramientas tiene, cómo debe comportarse y qué no debe hacer nunca. Se mantiene fijo entre conversaciones y es el lugar donde vive el 80% de la calidad del agente. El user prompt es el mensaje variable: la petición de cada usuario, el ticket, la tarea del día.

La regla de oro: todo lo que no cambia va al system prompt, todo lo que cambia va al user prompt. Si mezclas instrucciones permanentes dentro del mensaje del usuario, el modelo pierde la distinción entre "la regla" y "la petición", y el usuario puede romperla sin querer. Además, el system prompt es el bloque que la caché de contexto deja barato: cuanto más estable, mejor para tu factura.

Contexto y herramientas: el prompt como contrato

En un agente, el prompt también declara las herramientas disponibles: nombre, descripción y schema de argumentos. La descripción de la herramienta es un mini-prompt: el modelo decide si llamarla leyendo esa descripción. Dos errores típicos:

• Descripciones vagas ("consulta la base de datos"): el modelo la usa cuando no debe o no la usa cuando debe.
• Argumentos sin validar ("sku": cualquier cosa): el modelo inventa valores que la función rechaza.

La descripción debe decir qué hace, cuándo usarla y qué devuelve: "Consulta el stock disponible de un producto por SKU. Úsala siempre que el usuario pregunte por disponibilidad. Devuelve un objeto con sku y stock". La guía de function calling para agentes confiables cubre el diseño de herramientas y sus errores más caros en detalle.

Técnicas que funcionan

Roles. Declarar el rol le da al modelo un marco de comportamiento: "Eres un agente de soporte técnico de una empresa de software. Tu tono es claro y directo. Nunca inventas información técnica". El rol no es decoración: define qué información debe pedir, qué tono usar y qué líneas no cruzar.

Formato de salida explícito. Para agentes, la salida debe ser parseable: JSON con campos definidos, tabla, lista numerada o texto con secciones fijas. Cuanto más estricto el formato, más fácil validarla y más barato procesarla. Ejemplo: "Devuelve solo un objeto JSON con los campos: resumen (string), prioridad (alta|media|baja), accion (responder|escalar|archivar). No agregues texto fuera del JSON".

Límites explícitos. Un buen prompt dice lo que el agente NO debe hacer: "No respondas preguntas sobre precios no publicados. No ejecutes acciones sobre la cuenta sin aprobación. Si no tienes la información, dilo y ofrece escalar". Los límites son la diferencia entre un agente útil y un agente peligroso: el modelo no sabe qué es "sentido común" de tu negocio.

Antes y después

Antes: "Responde los correos de los clientes."

El resultado: respuestas genéricas, sin estructura, inventando datos de pedidos y con tono inconsistente.

Después:

System: Eres el agente de soporte de la tienda. Respondes en español,
con tono amable y directo. Solo respondes con información verificada
por tus herramientas (consulta_pedido, consulta_stock). Si una pregunta
requiere un reembolso o una cancelación, escalas el ticket con un
resumen. Nunca inventas datos de pedidos ni plazos de entrega.
Devuelves la respuesta en el formato: saludo breve, respuesta al
problema, siguiente paso sugerido.

El cambio no es de estilo: es de contrato. El modelo sabe qué consultar, qué no responder, cuándo escalar y en qué formato entregar. Los documentos oficiales de prompt engineering de Claude y de OpenAI tienen las técnicas completas con ejemplos por tarea.

Cómo iterar: con evals, no con impresiones

El error más caro del prompt engineering es iterar por sensación: cambiar una frase, probar dos casos, "se ve mejor", publicar. Un prompt de agente afecta cientos de decisiones por día; la iteración correcta es con evals:

1. Dataset de casos reales: 20-50 entradas representativas con la respuesta esperada o los criterios de una buena respuesta.
2. Corre la suite antes y después de cada cambio de prompt: la métrica sube, baja o queda igual, sin discusión.
3. Cambia una variable por vez: prompt, modelo o herramientas, nunca las tres juntas.
4. Convierte cada error real en un caso nuevo: el dataset crece con la operación.

Con eso, un cambio de prompt deja de ser una opinión y se vuelve una medición. La guía de evals prácticos para agentes explica cómo armar la suite completa y los límites de iterar sin métricas.

Errores comunes

• Prompt gigante: un system prompt de 3.000 palabras diluye las instrucciones clave; prioriza y separa (lo esencial arriba, los detalles después).
• Instrucciones contradictorias: "sé breve" junto a "explica cada paso en detalle" produce respuestas impredecibles; audita el prompt buscando contradicciones.
• Sin límites: el modelo inventa lo que no se le prohibió; los límites explícitos son parte del prompt, no un extra.
• Formato libre: salidas sin estructura obligan a parsear con regex frágiles y fallan en producción; exige formato desde el prompt.
• Iterar sin evals: el prompt "que se ve mejor" en dos ejemplos empeora en el 30% de los casos reales sin que lo notes.

Verificación de tu prompt

1. Lo permanente está en el system prompt; lo variable, en el user prompt.
2. Cada herramienta tiene descripción con cuándo usarla y qué devuelve.
3. La salida tiene formato explícito y validable.
4. Los límites están escritos (qué no hacer, cuándo escalar).
5. Cada cambio de prompt corre la suite de evals antes de publicarse.

El prompt de un agente es el archivo más importante de tu proyecto: es donde vive la calidad, el costo y el riesgo. Escríbelo como contrato, itéralo con evals y verás la diferencia en cada métrica. Para el resto del camino de construcción, el hub de guías de construcción de agentes reúne arquitectura, herramientas y buenas prácticas, y el curso gratuito de instalación te deja un agente corriendo para que empieces a iterar tu primer prompt con datos reales.