# 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.
