Private betaRequest early access →

Sign in

Registering an AI agent

An AI agent in Perihelium is a principal of its own: it has an identity, a credential of its own, a risk profile that sets how much oversight it attracts, delegated and expiring authority, a journal of what it did, and a switch that stops it. This page walks the whole lifecycle in order. Everything here is available through the console under AI Agents and through the API under /api/v1/agents; the API reference has every field.

Registering and managing an agent is a human act: an AI agent or an API key is refused 403 on register, update, rotate and retire, whatever permissions it holds, because a principal that could rewrite the record it is governed by would not be governed.

1. Register the agent

Register an agent in your organization with a name and a risk level. The risk level derives the agent's governance band, and the band is a ceiling:

risk_levelMaximum max_risk_score for an agent under human oversightNotes
minimal20an AUTONOMOUS agent is capped at 10
limited12an AUTONOMOUS agent is capped at 10
high8locks oversight_mode to HUMAN_APPROVE

oversight_mode is AUTONOMOUS, HUMAN_IN_LOOP or HUMAN_APPROVE. Any field you leave out defaults from the band, and a value weaker than the band is refused (422). You can tighten an agent at any time; loosening takes a second person: widening the band answers 202 Accepted with an approval_id, a different person holding agents:manage decides it, and you then repeat the original call.

HTTP
POST /api/v1/agents
{ "name": "release-notes-writer", "risk_level": "limited" }

The response carries the agent's credential once; store it then, because it cannot be read again. A name already in use in your organization answers 409.

An agent can also take part in onboarding: it proposes an IAM manifest, a person reviews it, and nothing applies until that person approves one content hash (Agent-driven onboarding).

2. Its credential

The agent authenticates with a credential of its own, never a person's. Two shapes:

  • a client credential, the secret returned at registration, which the agent presents to obtain tokens;
  • a federated identity: the agent proves who it is with a token from your own workload identity provider and never holds a long-lived secret (Federated workload identity).

Tokens issued to an agent are sender-constrained when the agent presents a proof of possession (DPoP). The software requires the proof unless a deployment explicitly allows bearer tokens; where it is required, a stolen token is useless without the agent's key.

To rotate a client credential, POST /api/v1/agents/{id}/rotate-credential. The old credential stops working when the new one is issued, and rotation needs a second person to approve it, as widening a band does. An operator can set a maximum credential age (security.agent_max_credential_age_days; 0, the default, disables it); an agent whose credential is older than the limit raises a detection that names the agent.

3. Bound what it may do

An agent's authority is a delegation: permissions drawn from what the person delegating holds, with an expiry, tightened and never widened. Three mechanisms compose:

  • Scopes: the permissions the delegation names. A request outside them is refused, and the reason is recorded.
  • Budgets: a per-window budget of mutations and a per-window budget of refusals. Tripping either engages the agent's kill switch automatically, and the reason names which budget tripped.
  • Approvals: actions the delegation marks as obligations wait for a person (Human-in-the-loop agent approvals). The agent is told the approval is pending and retries after it is granted.

The band and the delegation each govern the agent, and the stricter of the two applies.

4. Give it tools

Two doors, both governed per call:

  • The MCP tool gateway puts the platform between the agent and every MCP server it calls: an allowlist of servers, the delegation's scope, the caps, the kill switch and a pending approval are all evaluated on each tools/call, and every decision is logged (MCP tool gateway). The gateway speaks standard MCP, so an off-the-shelf client connects to it directly.
  • The platform's own MCP server lets the agent operate Perihelium itself, read-only by default with human approval for writes (Operating Zynth over MCP).

5. Watch what it does

  • The journal: every action the agent took, with the delegation and approval it acted under, readable from the agent's detail view and GET /api/v1/recovery/agents/{id}/journal.
  • Containment: GET /api/v1/agents/{id}/containment returns the kill switch (engaged, by whom and why) and what is left of the mutation and refusal budgets in the current window.
  • Liveness: every agent read says whether a credential the agent holds would still be accepted (live, idle or never).
  • Detections in the agents family: repeated failed authentication, a token throttle storm, a breached task scope, an exhausted budget, a tripped blast-radius limit, a burst of refused tool calls and a stale credential, each naming the agent (Security monitoring).
  • Lifecycle events for your own systems: agents.registered, agents.updated, agents.credential_rotated, agents.kill_switch_engaged, agents.kill_switch_released, agents.deleted, authz.delegation_created and authz.delegation_revoked, delivered by webhook.

6. Stop it

The kill switch refuses the agent at authentication on every surface (the API, both MCP doors and token refresh) from the moment it is engaged, and refuses every token the agent already holds:

HTTP
POST /api/v1/agents/{id}/kill-switch   { "engaged": true, "reason": "…" }

Engaging is open to any principal holding agents:kill, including an API key, so a pager or a SIEM can stop an agent without a person signing in. Releasing is human-only, because it restores a stopped principal's authority. Who engaged the switch and why survive a release, so the question "who stopped this" always has an answer. Every engagement and release is audited and notified.

When an agent's writes have to be undone, a person can replay its journal in reverse for a window of their choosing: POST /api/v1/recovery/agents/{id}/rollback, with optional since and until bounds. The report has three buckets: what was restored, what was skipped and what was irreversible.

7. Retire it

DELETE /api/v1/agents/{id} retires the agent immediately: its credential is destroyed, any token it already holds is refused on its next request, and every delegation it handed onward is revoked, so nobody keeps acting on authority from a source that has ended. The agent leaves the list and every later call for it answers 404. Its record stays, because its audit entries, approval decisions and detections refer to it: what is destroyed is the agent's authority, not its history. There is no un-retire. To pause an agent you may want back, set its status to suspended.

Where to go next