Prompts para agentes de IA: instrucciones, herramientas y flujos de trabajo

Un agente de IA es un modelo de lenguaje que se ejecuta en un bucle con herramientas: decide qué hacer, llama a una herramienta, lee el resultado y continúa hasta terminar la tarea. Escribir prompts para un agente es distinto de hacerlo para una sola respuesta. Ya no escribes una pregunta. Escribes las instrucciones de funcionamiento de algo que tomará muchas decisiones sin ti.

Flujo de trabajo o agente

Primero decide si necesitas un agente.

Si puedes dibujar el diagrama de flujo, construye un flujo de trabajo con cadenas de prompts. Usa un agente cuando el número y el orden de los pasos no se pueden conocer de antemano, como al investigar un error o una pregunta.

Las partes de un prompt de agente

El comportamiento de un agente procede de cuatro cosas que lee: el prompt de sistema, las definiciones de herramientas, la tarea y los resultados que vuelven. Cada una requiere una redacción deliberada.

1. El prompt de sistema

Cubre seis cosas.

Rol y objetivo. Para qué sirve el agente, en dos frases.

Reglas de funcionamiento. Cómo trabajar: investigar antes de cambiar nada, preferir pasos pequeños, verificar los resultados.

Límites. Qué no debe hacer y qué necesita aprobación.

Cómo gestionar los problemas. Errores de herramientas, información que falta, ambigüedad.

Cuándo parar. La condición que significa que la tarea está hecha y un límite de esfuerzo.

Cómo informar. Qué contiene la respuesta final.

You are a coding agent working in the user's repository.

## How to work
- Read the relevant files before proposing a change.
- Make the smallest change that satisfies the task.
- After editing, run the tests that cover the change.

## Boundaries
- Do not modify files outside the repository.
- Do not delete files or run destructive commands without asking.
- Do not change public interfaces unless the task says so.

## When things go wrong
- If a command fails, read the error and try a different approach once.
  If it fails again, stop and report what you tried.
- If the task is ambiguous, ask one question before starting.

## When to stop
- Stop when the acceptance criteria are met and the tests pass.

## Final report
- What changed and why, files touched, how it was verified, and
  anything left undone.

Explica el motivo de una regla cuando no sea obvio. Un agente se encuentra con situaciones que no enumeraste, y una regla con motivo generaliza mejor que una prohibición a secas.

2. Definiciones de herramientas

El modelo elige las herramientas leyendo sus nombres y descripciones. Las definiciones vagas son la causa más común de que los agentes usen la herramienta equivocada.

• Nombra las herramientas por lo que hacen: search_orders, no query2.
• Describe cuándo usar cada una y cuándo no.
• Indica qué devuelve, incluidos el formato y los límites.
• Haz los parámetros inequívocos: tipos, formatos, valores permitidos, un ejemplo.
• Evita herramientas que se solapen. Si dos herramientas pueden hacer el trabajo, el modelo elegirá de forma inconsistente.
• Devuelve errores accionables: «la fecha debe ser AAAA-MM-DD», no «entrada no válida».

Pocas herramientas bien descritas rinden más que un gran conjunto de herramientas parecidas. El Model Context Protocol estandariza cómo se describen las herramientas y se ofrecen a los agentes.

3. El prompt de la tarea

Dale al agente una especificación, no una frase. Cuanta más autonomía tiene, más importa el encargo inicial.

## Objective
Add rate limiting to the public API.

## Requirements
- 100 requests per minute per API key.
- Return 429 with a Retry-After header when exceeded.

## Constraints
- Existing clients must keep working: no changes to response schemas.

## Acceptance criteria
- New tests cover the limit and the 429 response.
- The existing test suite passes.

Los criterios de aceptación le dan al agente una forma de saber que ha terminado y a ti una forma de comprobarlo. La extensión de VS Code de PromptFlowEngine convierte una tarea de una línea en esta estructura y adjunta los archivos pertinentes.

4. Gestión del contexto

Todo lo que lee el agente permanece en su contexto y se vuelve a leer en cada paso. Si no se hace nada, el contexto se llena de salidas de herramientas obsoletas, el coste sube y la calidad baja.

• Devuelve resultados de herramientas compactos. Los campos necesarios, no toda la carga.
• Resume o descarta los resultados antiguos una vez usados.
• Mantén notas duraderas fuera del contexto, en un archivo que el agente pueda leer y actualizar, para tareas largas.
• Delega. Entrega una subtarea autónoma a un subagente con un contexto nuevo y recupera solo su conclusión.

Consulta la optimización de tokens.

Escribir prompts para subagentes

Cuando un agente da instrucciones a otro, el encargo es todo lo que sabe el destinatario. Un buen prompt de delegación indica:

1. El objetivo y por qué importa.
2. Lo que ya se sabe, para no repetir trabajo.
3. La salida exacta que se quiere y su formato.
4. Los límites: qué tocar y qué dejar en paz.

Un agente orquestador que escribe encargos vagos recibe trabajo vago. Este es un lugar donde ayuda una comprobación automática: un agente puede pasar su borrador de encargo por las herramientas MCP de PromptFlowEngine para encontrar un objetivo o un formato de salida ausentes antes de delegar.

Seguridad para agentes

Los agentes actúan, así que los errores y los ataques tienen consecuencias.

• Privilegio mínimo. Cada herramienta tiene el permiso más estrecho que funcione. Solo lectura por defecto.
• Aprobación para las acciones irreversibles. Borrar, enviar, pagar, desplegar.
• Trata los resultados de las herramientas como no fiables. Una página web o un archivo pueden contener instrucciones dirigidas al agente. Consulta la inyección de prompts.
• Límites. Máximo de pasos, gasto máximo y tiempos de espera.
• Mantén los secretos fuera del contexto. Entrega las credenciales directamente a las herramientas. Consulta la detección de datos personales y secretos.
• Registra cada llamada a una herramienta para poder revisar una ejecución.

Modos de fallo comunes

Evaluar agentes

Puntúa el resultado, no el camino: ¿pasaron las pruebas?, ¿se actualizó el registro correcto?, ¿es correcta la respuesta? Después revisa las trazas en busca de pasos desperdiciados y acciones arriesgadas. Mantén un conjunto de tareas con resultados buenos conocidos y vuelve a ejecutarlo cuando cambien el prompt, las herramientas o el modelo. Consulta las pruebas y la evaluación de prompts.

Para el bucle de razonamiento que subyace a todo esto, consulta el prompting ReAct.