Ir al contenido
Agentes a juicio

ADR: ¿agente, flujo fijo o persona?

Usala cuando alguien propone un agente para una tarea, antes de construir nada. Un ADR (registro de decisión de arquitectura) guarda una decisión y sus razones. El resultado puede ser un flujo fijo o una persona.

La plantilla te pide cinco cosas:

  • Responder seis preguntas sobre la tarea.
  • Marcar la trifecta: contenido no confiable, datos sensibles y acciones hacia afuera en una misma sesión.
  • Revisar qué se puede deshacer.
  • Anotar cómo vas a evaluar.
  • Anotar cuánto va a costar.

Copiá el bloque con el botón de la esquina, o abrí el archivo en GitHub.

templates/es/adr-agente-o-no.md
# ADR-[número]: [tarea] ¿agente, flujo fijo o persona?


<!--
Cómo usar esta plantilla:
- Un ADR (registro de decisión de arquitectura) guarda una decisión y sus razones.
- Escribilo antes de construir. Guardalo en el repositorio, por ejemplo en docs/adr/.
- Completá cada campo entre corchetes. Borrá estos comentarios al terminar.
- Formato: MADR (Markdown Architectural Decision Records), adaptado a agentes.
-->


- Estado: [propuesta | aceptada | reemplazada por ADR-___]
- Fecha: [AAAA-MM-DD]
- Decide: [nombre y rol de la persona responsable]
- Consultados: [seguridad, datos personales, el equipo que hace la tarea hoy]


## Contexto


<!-- Describí la tarea como la hace hoy una persona. Un problema concreto, no una "plataforma de agentes". -->


- Tarea: [qué entra, qué sale]
- Quién la hace hoy y cuánto tarda: [rol, minutos por caso]
- Volumen: [casos por mes]
- Costo de un error hoy: [qué pasa y cuánto cuesta]


## Las preguntas que deciden


| Pregunta | Respuesta | Qué indica |
|---|---|---|
| ¿Podés escribir los pasos y las ramas de antemano? | [sí / no] | Si es sí, alcanza un flujo fijo. |
| ¿Las entradas son ambiguas (texto libre, documentos variados)? | [sí / no] | Si no lo son, no hace falta un modelo. |
| Si se equivoca, ¿el error es barato y reversible, caro pero reversible, o irreversible? | [...] | Lo irreversible queda con una persona o detrás de una aprobación. |
| ¿Cuántos pasos encadenados tiene la tarea? | [n] | Con 95 % de acierto por paso, 10 pasos aciertan el 60 % de las veces. |
| ¿Tenés al menos 20 casos reales para evaluar? | [sí / no] | Sin casos reales, todavía no podés decidir. |
| ¿Quién revisa y con cuánto tiempo? | [rol, minutos por caso] | Sin un revisor con tiempo, la aprobación es un sello. |


## Trifecta (regla de dos)


<!--
La trifecta son tres condiciones que juntas permiten robar datos.
Marcá cada condición que se cumple en una misma sesión del agente.
Si marcás las tres, el agente no puede correr solo. Cortá una de las tres,
o poné una aprobación humana atada a la acción exacta. Detalle en mapa-de-amenazas.md.
Cualquier pedido a una URL cuenta como salida hacia afuera, igual que un mensaje.
Por ejemplo: una búsqueda, un fetch, una imagen en markdown, un link que se previsualiza
o una traza que va a una herramienta de terceros.
-->


- [ ] Lee contenido no confiable (correos, páginas web, tickets, archivos de clientes, descripciones de herramientas de terceros).
- [ ] Accede a datos sensibles o personales.
- [ ] Actúa hacia afuera o cambia estado (manda mensajes, pide una URL, paga, publica, borra, modifica datos).


Condición que cortamos y cómo: [...]
Acciones con aprobación humana: [...]


## Reversibilidad


<!-- Una fila por cada acción que el agente puede tomar. Lo que no se puede deshacer queda con una persona o detrás de una aprobación. -->


| Acción | Si sale mal, ¿se puede deshacer? | Cómo se deshace y cuánto tarda | Nivel en la política |
|---|---|---|---|
| [ej.: crear un reembolso] | [no, la plata ya salió] | [pedir la devolución al cliente, días] | [confirmar] |
| [...] | [...] | [...] | [...] |


## Opciones consideradas


1. Flujo fijo: código determinista (hace siempre lo mismo con la misma entrada). Si hace falta, un modelo resuelve un solo paso acotado.
2. Agente acotado: una tarea, pocas herramientas, mínimo privilegio (solo los permisos que la tarea necesita), presupuesto con corte.
3. Agente con aprobación humana en las acciones de riesgo.
4. Persona, con o sin ayuda de IA.


## Decisión


Elegimos [opción] porque [razón ligada a las preguntas de arriba].


## Evaluación antes de salir


<!-- pass^k: la probabilidad de que k intentos de la misma tarea salgan todos bien. -->


- Plan de evaluación: [link a plan-de-evaluacion.md]
- Criterio de salida: pass^[k] de al menos [__] % en [n] tareas.
- Criterio de vuelta atrás: [métrica, umbral, quién decide].


## Costo


- Costo por tarea exitosa estimado: [__] (ver ficha-de-costo.md).
- Costo de la tarea hoy (persona o flujo fijo): [__].
- Presupuesto por día con corte automático: [__].


## Consecuencias


- A favor: [...]
- En contra, y riesgos que aceptamos: [...]
- Fecha en que revisamos esta decisión: [AAAA-MM-DD]


## Por qué está esto acá


- Si podés escribir los pasos de antemano, escribilos en código y no en el prompt: *Agents need control flow, not more prompts* (Hacker News, 2026).
- Sumá complejidad solo si mejora un resultado medible. Un arnés (el código que coordina a los agentes) de tres agentes hizo mejores aplicaciones que un agente solo, pero costó más de 20 veces: *Harness design for long-running application development* (Anthropic, 2026).
- Con contenido no confiable, datos sensibles y acciones hacia afuera en la misma sesión, el agente necesita supervisión humana: *Agents Rule of Two* (Meta, 2025) y *New prompt injection papers: Agents Rule of Two and The Attacker Moves Second* (Simon Willison, 2025). Una inyección de instrucciones (texto que da órdenes escondidas al agente) sacó archivos de la víctima por un dominio permitido, sin ninguna aprobación del usuario: *Claude Cowork Exfiltrates Files* (PromptArmor, 2026).
- pass^k mide si el agente acierta todas las veces y no solo una: *Demystifying evals for AI agents* (Anthropic, 2026). Acertar en todos los intentos es mucho más difícil que acertar en uno: *τ-Knowledge* (Shi y otros, 2026).
- Medí costo y acierto juntos: *Holistic Agent Leaderboard* (Kapoor y otros, 2025).