Registry

The Registry screen lets you list the agents of the tenant, register an agent with a manifest, open an agent to start a run and read its runs, versions and manifest, and suspend, resume, kill, edit or delete it. Portal path: /agents/registry (detail page: /agents/registry/<agent-id>); the page title reads Agents registry. Developers and application owners register and edit agents, tenant administrators and security officers control their lifecycle. The screen is drawn by portal/src/screens/agents.tsx.

What the screen shows

The list page has two blocks:

• Agents table, read with GET /v1/agents (50 rows per call, the next rows load when you page forward). Columns: Name, Version, Owner, Risk, Status, Updated.
• Filter Status (Active, Suspended, Killed, or all) and the Filter button.
• When no agent exists: No agent registered, with the hint Apply an Agent manifest below to register an agent.
• A click on a row, or the row menu View details, opens the detail page of the agent.
• Apply a manifest panel: an editor prefilled with an Agent manifest sample (portal/src/samples/agent-manifest.json), the buttons Reset example and Apply, and a result area. The result area shows Manifest applied with the API answer, the list of validation errors returned by the API, or Cannot parse the document when the text is neither YAML nor JSON.

The detail page shows:

• Back, the agent name, its status badge and its current version (record read with GET /v1/agents/{agent_id}).
• The buttons Start run, Suspend (or Resume when the agent is suspended) and Kill. Start run is disabled when the agent is suspended or killed; Suspend and Kill are disabled when it is killed.
• Three tabs:
  • Runs: the runs of this agent, same columns and actions as the Runs screen (GET /v1/runs with agent=<agent-id>).
  • Versions: columns Version, Status, Created by, Created (GET /v1/agents/{agent_id}/versions); No version recorded when the list is empty.
  • Manifest: the exported manifest of the agent in JSON (GET /v1/manifests/{kind}/{name} with the kind Agent).

Actions

Button or action	What it does	API call	Roles
Refresh (icon)	Reloads the list.	GET /v1/agents	Any tenant member
Filter	Applies the Status filter.	GET /v1/agents with status	Any tenant member
Row click or row menu View details	Opens the detail page.	GET /v1/agents/{agent_id}	Relation viewer on the agent
Row menu Suspend (agent neither suspended nor killed)	Suspends the agent at once: its active runs are suspended and new runs are refused.	POST /v1/agents/{agent_id}/suspend	tenant_admin, security_officer
Row menu Resume (suspended agent)	Opens a promotion approval; the agent becomes active, and the runs it suspended resume, only when another person approves it.	POST /v1/agents/{agent_id}/resume	tenant_admin, security_officer
Row menu Edit	Form Description, Owner, Risk (minimal, limited, high), Labels (JSON), submitted with Edit.	PATCH /v1/agents/{agent_id}	tenant_admin, developer, application_owner and relation editor
Row menu Delete	Opens Confirm a destructive action (impacted dependent resources, risks, required permissions); type the agent name, then Confirm.	GET /v1/lineage/graph, then DELETE /v1/agents/{agent_id}	tenant_admin and relation owner
Reset example	Puts the sample manifest back in the editor.	None	Everyone
Apply	Validates the manifest against its contract, checks it with the policy and stores it in the agent registry.	POST /v1/manifests/apply	tenant_admin, developer
Back (detail)	Returns to the list.	None	Everyone
Start run (detail)	Opens a side panel: Objective (required), Input (JSON), Session id, Max cost (EUR); the Start run button sends it with a new Idempotency-Key. On success the toast Run started shows and the run page opens.	POST /v1/agents/{agent_id}/runs	tenant_admin, developer, agent, scope agents:run and relation can_invoke
Suspend / Resume (detail)	Same as the row actions.	POST /v1/agents/{agent_id}/suspend / POST /v1/agents/{agent_id}/resume	tenant_admin, security_officer
Kill (detail)	Asks Kill this agent? Running executions are stopped and the agent cannot be resumed., then cancels every active run and marks the agent killed for good.	POST /v1/agents/{agent_id}/kill	tenant_admin, security_officer
Tabs Runs, Versions, Manifest	Show the runs, the versions and the exported manifest.	GET /v1/runs, GET /v1/agents/{agent_id}/versions, GET /v1/manifests/{kind}/{name}	Any tenant member (relation viewer for the versions)
Retry (error state)	Sends the failed read again.	Same call	Same roles

The Start run form sends this body (built by portal/src/lib/request-bodies.ts); session_id and budgets are only sent when filled:

{
  "task": {"objective": "Check the supplier invoices received today", "input": {}},
  "session_id": "<session-id>",
  "budgets": {"max_cost": {"amount": "5.00", "currency": "EUR"}}
}

<session-id>: identifier of an existing session from the Sessions screen.

warning

Kill cannot be undone: the agent stays killed, every later Resume, Suspend or Kill answers agent_killed. Use Suspend to stop an agent for a while.

Roles

The portal hides no button on this screen: the Control Plane is the authority and answers forbidden (403) with the required_roles it expects. The role groups come from services/control-plane/src/eai/domains/agents/kit.py:

• WRITE_ROLES (tenant_admin, developer, application_owner): edit an agent.
• OPS_ROLES (tenant_admin, developer, agent): start a run.
• SECURITY_ROLES (tenant_admin, security_officer): suspend, resume and kill.
• Delete: tenant_admin only. Apply a manifest: tenant_admin or developer (services/control-plane/src/eai/domains/contracts/__init__.py).

The routes of services/control-plane/src/eai/domains/agents/routes.py also check a relation on the agent (viewer, editor, owner, can_invoke), see Permissions (ReBAC). platform_admin passes every role check. Reading the list only needs a tenant.

Typical tasks

Register an agent from a manifest

1. Prepare the manifest. The registry is filled from an Agent manifest, never from a free form. In Apply a manifest, paste your manifest in YAML or JSON, or adapt the sample (metadata.name, metadata.tenant, spec). Expected result: the editor holds your document. If it fails: click Reset example to start again from the sample.
2. Apply it. The Control Plane validates the contract and the policy before it stores the agent. Click Apply. Expected result: Manifest applied and the API answer; after Refresh the agent is in the Agents table. If it fails: read the errors listed under the editor (invalid_manifest) and fix the fields they name.
3. Check the version. Each applied version is kept. Open the agent, then the Versions tab. Expected result: the version of metadata.version is listed. If it fails: version_immutable means this version already exists with another content; raise the version number.

Start a run and follow it

1. Open the agent. A run always starts from an active agent. Click its row in the table. Expected result: the detail page with the status Active. If it fails: when Start run is disabled, the agent is suspended or killed.
2. Fill the form. The objective is what the agent must do. Click Start run, type the Objective, add an Input in JSON and a Max cost (EUR) if needed, then click Start run. Expected result: the toast Run started, then the run page opens. If it fails: the error shows at the top of the panel (insufficient_scope, agent_not_active, forbidden).
3. Follow the run. The run page updates itself while the run is active. Read its timeline on the Runs screen. Expected result: the state moves to Succeeded or Failed. If it fails: a state Waiting approval needs a decision in the Approvals inbox.

Suspend an agent, then bring it back

1. Suspend it. Suspension blocks new runs and suspends the active ones at once. Click Suspend on the detail page or in the row menu. Expected result: the toast Done and the status Suspended. If it fails: forbidden means you are neither tenant_admin nor security_officer.
2. Ask for the resumption. Going back to active is a promotion that needs a second person. Click Resume. Expected result: the toast Done; the agent stays Suspended and a request with the action promotion appears in the Approvals inbox. If it fails: kill_switch_active means a SOC kill switch holds the agent; lift it with the recovery workflow of the Kill Switch screen.
3. Have it approved. Separation of duties forbids you to approve your own request. Ask another approver to click Approve in the inbox. Expected result: the agent becomes Active and the runs it suspended resume. If it fails: the promotion may be refused by the risk check or by a blocking evaluation suite, see Quality gates.

Troubleshooting

Symptom	Cause	Fix
forbidden (403) with required_roles	Your roles are not in the required_roles of the error, or the relation on the agent is missing.	Ask a tenant administrator for the role, or for the relation on the agent.
insufficient_scope (403) on Start run	The credential lacks the scope agents:run.	Use a key or a session that carries agents:run.
agent_not_active (409): "Agent ... is suspended: new runs are blocked."	The agent is suspended or killed.	Resume it (approval required), or use another agent.
agent_killed (409)	The agent was killed; it cannot be changed any more.	Register the agent again under a new name with a manifest.
kill_switch_active (409) on Resume	A security kill switch holds the agent.	Ask the security team to run the four eyes recovery (POST /v1/soc/recoveries).
agent_has_active_runs (409) on Delete	The agent still has active runs.	Cancel the runs or wait for their end, then delete.
invalid_manifest (422) under the editor	The document does not match the Agent contract.	Fix each field listed in the errors.
tenant_mismatch (403) on Apply	metadata.tenant names another tenant.	Set the slug of your tenant or remove the field.
Cannot parse the document	The text is neither valid YAML nor valid JSON.	Fix the syntax (indentation, quotes, commas).
Resume shows Done but the agent stays suspended	Resumption is a promotion waiting for approval.	Have the request approved in the Approvals inbox.

Related pages

• Runs
• Approvals inbox
• Schedules
• Triggers
• Sessions
• Applications
• Kill Switch
• Agent development guide
• Agent runtime brick
• Agent kill switch brick