Agents
Register, govern, and transition AI agents through their lifecycle.
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) |
POST /agents/emergency-stop | Project-wide emergency stop (no {id} — stops agents across the project) |
Agent-lifecycle events are always captured by the attestation rules (EU AI Act Art. 12); anchoring follows the project's attestation setting.
Read endpoints
GET /api/v1/agentsReturns 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_classificationandtechnical_lead_id— there is norisk_level,technical_maintainer_id, ordata_protection_levelfield. Unknown fields are silently ignored, so a typo here means the update is a no-op for that field.
Errors
Errors return a plain {"error": "<message>"} body (localized) with the appropriate HTTP status (400 validation, 403 authorization/entitlement, 404 unknown agent).