Agents and their lifecycle
An agent is anything Bairav governs: an AI agent, an MCP server, a local model runtime, an IDE assistant or an application that calls a model. Each agent is in exactly one lifecycle state.
discovered ──> under_review ──approve──> approved / active ──suspend──> suspended
│ reject │ block │ reactivate
v v v
rejected <──────────────── blocked back to active
└─────── ─ re-review (a fresh intake decision) ───────────┘
| State | Where it lives | Meaning |
|---|---|---|
under_review | Intake queue | Discovered, waiting for a decision |
approved / active | Registry | Governed and allowed to act |
suspended | Quarantine | Held. Reversible with Reactivate. |
blocked | Quarantine | Held. Not reversible with Reactivate; it needs a fresh intake decision (Re-review). |
rejected | Quarantine | Refused at intake. Can be re-reviewed. |
Suspended, blocked and rejected agents cannot act: the gateway refuses their calls and the sensor stops them on the host. They are excluded from coverage figures.
Transitions
| Action | From | Reason | Endpoint |
|---|---|---|---|
| Approve | under_review | An accountable owner is required | POST /api/intake/{id}/approve |
| Reject | under_review | Required (tenant setting, on by default) | POST /api/intake/{id}/reject |
| Suspend | approved or active | Optional | POST /api/agents/{id}/suspend |
| Block | approved, active or suspended | Required | POST /api/agents/{id}/block |
| Reactivate | suspended only | None | POST /api/agents/{id}/reactivate |
| Re-review | rejected or blocked | None | POST /api/agents/{id}/rereview |
Approve, reject and the other decisions need the admin or reviewer role. Every transition writes one entry to the Audit ledger with who did it, why and when.
Agent ID
Every agent gets a permanent ID of the form AGT-######. It is assigned once, at the first decision (approve or reject), never at discovery, and is never reused. Until then screens say "Agent ID pending intake decision".
How agents are discovered
| Source | What happens |
|---|---|
| Sensor | Reports agents, MCP servers, models and IDEs found on a host |
| AI Gateway | The first call from a new X-Bairav-Agent name creates an Intake queue entry and a notification |
| Salesforce Agentforce | Agents in a connected org appear in the Intake queue |
| Shadow-agent discovery | Unregistered agents inferred from events become candidates to triage |
Ownership
Approving an agent requires an accountable owner (name and department); the server enforces this with a 422, not just the console. Owners can decide access requests for their agents in the Agent catalog. Nobody can decide their own request.