Conceptos
Agente
Un trabajador digital con oficio, instrucciones y herramientas. Tiene versiones: editarlo crea una versión nueva en dev; lo que corre en staging y prod es la versión que se promovió. Cada corrida anota con qué versión, qué memoria y qué documentos trabajó.
Tarea
Lo que se le pide. Nace con un presupuesto duro en USD y un máximo de turnos, sin excepción. Tiene una traza en árbol: cada tramo con su costo, cada herramienta con su intento, cada freno con su motivo. El estado se lee por API (GET /api/v1/tickets/{id}), por MCP (estado_de_tarea, ver_traza) o llega por webhook.
Verificación
El claim del agente nunca es la verdad. Cuando un agente declara que terminó, un verificador independiente relee el sistema del cliente —la herramienta de lectura o la entidad de Datos que el agente declaró en como_se_verifica— y decide. La discrepancia (el agente dijo que sí, la verificación dijo que no) es la métrica central y dispara el evento discrepancia.detectada.
Aprobación (Human in the Loop)
Lo irreversible espera a una persona. Cada agente tiene un dial: hitl dice cuándo frenar (por defecto sólo lo irreversible) y tope_sin_firma_usd cuánto puede gastar en efectos sin que alguien firme. La aprobación se hace en el portal: aprobar sólo devuelve un enlace de un solo uso (15 minutos) que la persona del token abre con su sesión. La única excepción es la segunda firma de una promoción a producción (aprobar_promocion), que da OTRA persona que la que la pidió, con su propio token. Producción exige dos firmas (cuatro ojos), o una con constancia cuando la organización tiene un solo publicador.
Bóveda y puente
Las credenciales del cliente se guardan selladas y sólo el worker las abre, fuera del entorno donde corre el modelo. El modelo pide una herramienta por MCP; el puente aplica los permisos, resuelve la credencial, hace el HTTP y registra el intento. El secreto nunca entra al prompt ni al contenedor.
Ambientes
dev, staging, prod. Las conexiones tienen credencial por ambiente, y una conexión puede estar simulada en dev (respuesta grabada, sin efecto). El default de toda API y herramienta es dev: la primera prueba de una integración no le pega al sistema real.
Token y persona
Un token MCP o de API actúa en nombre de una persona con su rol de hoy. Los alcances son lectura, escritura, auditoria, topes: lectura ve, escritura además crea trabajo (o sea gasta), auditoría sólo lee la bitácora, y topes sólo fija el tope de gasto de un agente (PUT /api/v1/agentes/{id}/tope): no lee nada más ni pide tareas, es el de una aplicación conectada. No hay jerarquía: cada ruta nombra el alcance que pide. Si la persona pierde la membresía, el token muere con ella.
Organización (tenant)
Todo dato de dominio lleva la organización y la base lo aplica con Row-Level Security. Un token de una organización no puede ver la otra ni por error nuestro.