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 |
budget_daily_requests / budget_daily_tokens / budget_daily_cost_eur / budget_monthly_cost_eur | — | Per-agent budgets |
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 returns an ag_ agent API key — store it immediately, it is only shown once. Note: this key is not yet accepted for API authentication (see Authentication); requests keep authenticating with the project key, 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 belong to the mandatory Flare attestation set (EU AI Act Art. 12).
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, the four budget_* fields, 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).