Agents

Agents are the unit of governance in Palveron. Every API call is attributed to an agent, and every agent moves through a strict lifecycle that's enforced by the gateway.

Register an agent

POST /api/v1/agents

{
  "name": "Customer Support Bot",
  "description": "Answers tier-1 support emails using GPT-4o.",
  "agent_type": "chatbot",
  "risk_classification": "LIMITED",
  "purpose_description": "Tier-1 customer support triage",
  "requires_human_oversight": true,
  "responsible_person_id": "ckuser...",
  "technical_lead_id": "cklead..."
}

Field	Required	Description
`name`	✅	Agent name
`description`	—	What the agent does
`agent_type`	—	e.g. `chatbot`
`model`	—	Underlying model identifier
`risk_classification`	—	EU AI Act risk class, e.g. `MINIMAL`, `LIMITED`, `HIGH`
`purpose_description` / `intended_purpose`	—	Declared purpose (PBEG)
`intended_users` / `known_limitations`	—	EU AI Act onboarding documentation
`requires_human_oversight`	—	Art. 14 oversight flag
`annex_iii_domain` / `prohibited_screen_result` / `provider_or_deployer`	—	Screening metadata
`responsible_person_id` / `technical_lead_id` / `approval_authority_id`	—	Responsibility chain
`tags` / `permissions` / `infrastructure_permissions`	—	Classification and capability inputs
`framework`	—	Declared integration framework (e.g. `langchain`)
`protection_profile`	—	`safe` / `balanced` / `full_access` — maps to the capability model (omitted = fail-closed default)

A newly registered agent starts in PENDING_APPROVAL. The response does not return an agent API key: requests authenticate with the project key (see Authentication), and traces attribute the agent via its plain id.

Lifecycle transitions

Endpoint	Transition
`POST /agents/{id}/approve`	`PENDING_APPROVAL → ACTIVE`
`POST /agents/{id}/reject`	`PENDING_APPROVAL → REJECTED`
`POST /agents/{id}/pause`	`ACTIVE → PAUSED`
`POST /agents/{id}/resume`	`PAUSED → ACTIVE`
`POST /agents/{id}/suspend`	`ACTIVE → SUSPENDED`
`POST /agents/{id}/reactivate`	`SUSPENDED → ACTIVE`
`POST /agents/{id}/revoke`	`* → REVOKED` (terminal)

suspend, reactivate, pause, resume, approve, reject, and revoke all require the Admin role. Suspending an agent refuses every request that names it and does not change its API key; the former project-wide agent stop has been removed in favour of the project emergency stop below.

Agent-lifecycle events are always captured by the attestation rules (EU AI Act Art. 12); anchoring follows the project's attestation setting.

Project emergency stop

The project emergency stop replaces the former project-wide agent stop. While it is active, every request that uses the project key is refused on every path, open approvals end, the dashboard stays available for reading, investigating and lifting, and answers already running finish. It changes no agent, server, or tool-rule status; after lifting they keep their state, and approvals that ended when it was set stay ended.

Endpoint	Role	Purpose
`POST /api/v1/project/emergency-stop`	Admin	Activate the emergency stop (optional `{ "reason": string }`).
`GET /api/v1/project/emergency-stop`	Viewer	Read whether an emergency stop is active.
`POST /api/v1/project/emergency-stop/lift`	Admin	Lift the emergency stop (optional `{ "reason": string }`).

Error codes: project_emergency_stopped (403, the gate refuses while an emergency stop is active), project_emergency_stop_already_active (409, activating when one is already active), and project_emergency_stop_not_active (409, lifting when none is active).

Read endpoints

GET /api/v1/agents

Returns the project's agent list with status, risk classification, and activity metadata.

Update governance metadata

PATCH /api/v1/agents/{id}

Updatable fields include: name, description, status, suspended_reason, risk_classification, requires_human_oversight, permitted_tools, fria_assessment, transparency_disclosure, responsible_person_id, technical_lead_id, approval_authority_id, infrastructure_permissions, capability_model, framework.

The field names are risk_classification and technical_lead_id — there is no risk_level, technical_maintainer_id, or data_protection_level field. Unknown fields are silently ignored, so a typo here means the update is a no-op for that field.

Errors

Errors return a structured error object (code, message, request_id) with the appropriate HTTP status (400 validation, 403 authorization, 404 unknown agent). Branch on error.code.