Agents

Agents sind die Governance-Einheit in Palveron. Jeder API-Aufruf wird einem Agent zugeordnet, und jeder Agent durchläuft einen strikten, von der Gateway durchgesetzten Lebenszyklus.

Agent registrieren

POST /api/v1/agents

{
  "name": "Customer Support Bot",
  "description": "Beantwortet Tier-1-Support-E-Mails mit GPT-4o.",
  "agent_type": "chatbot",
  "risk_classification": "LIMITED",
  "purpose_description": "Tier-1-Kundensupport-Triage",
  "requires_human_oversight": true,
  "responsible_person_id": "ckuser...",
  "technical_lead_id": "cklead..."
}

Feld	Erforderlich	Beschreibung
`name`	✅	Agent-Name
`description`	—	Was der Agent tut
`agent_type`	—	z. B. `chatbot`
`model`	—	Bezeichner des zugrunde liegenden Modells
`risk_classification`	—	Risikoklasse der EU-KI-Verordnung, z. B. `MINIMAL`, `LIMITED`, `HIGH`
`purpose_description` / `intended_purpose`	—	Deklarierter Zweck (PBEG)
`intended_users` / `known_limitations`	—	Onboarding-Dokumentation nach EU-KI-Verordnung
`requires_human_oversight`	—	Art.-14-Oversight-Flag
`annex_iii_domain` / `prohibited_screen_result` / `provider_or_deployer`	—	Screening-Metadaten
`responsible_person_id` / `technical_lead_id` / `approval_authority_id`	—	Verantwortungskette
`tags` / `permissions` / `infrastructure_permissions`	—	Klassifikations- und Capability-Eingaben
`framework`	—	Deklariertes Integrations-Framework (z. B. `langchain`)
`protection_profile`	—	`safe` / `balanced` / `full_access` — mappt auf das Capability-Modell (weggelassen = fail-closed Default)

Ein neu registrierter Agent startet in PENDING_APPROVAL. Die Response liefert keinen Agent-API-Key: Anfragen authentifizieren sich mit dem Projekt-Key (siehe Authentifizierung), Traces ordnen den Agent über seine nackte ID zu.

Lebenszyklus-Übergänge

Endpoint	Übergang
`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 und revoke erfordern alle die Admin-Rolle. Das Sperren eines Agenten weist jede Anfrage ab, die ihn nennt, und ändert seinen API-Schlüssel nicht; der frühere projektweite Agenten-Stopp entfällt zugunsten der Notabschaltung des Projekts weiter unten.

Agent-Lifecycle-Events werden von den Attestierungsregeln immer erfasst (EU-KI-Verordnung Art. 12); die Verankerung folgt der Projekt-Attestierung.

Notabschaltung des Projekts

Die Notabschaltung des Projekts ersetzt den früheren projektweiten Agenten-Stopp. Solange sie aktiv ist, wird jede Anfrage mit dem Projektschlüssel auf jedem Weg abgewiesen, offene Freigaben werden beendet, das Dashboard bleibt zum Lesen, Untersuchen und Aufheben erreichbar, und bereits laufende Antworten laufen zu Ende. Sie ändert keinen Status von Agenten, Servern oder Werkzeugregeln; nach dem Aufheben behalten sie ihren Zustand, und Freigaben, die beim Setzen beendet wurden, bleiben beendet.

Endpoint	Rolle	Zweck
`POST /api/v1/project/emergency-stop`	Admin	Notabschaltung aktivieren (optional `{ "reason": string }`).
`GET /api/v1/project/emergency-stop`	Viewer	Lesen, ob eine Notabschaltung aktiv ist.
`POST /api/v1/project/emergency-stop/lift`	Admin	Notabschaltung aufheben (optional `{ "reason": string }`).

Fehlercodes: project_emergency_stopped (403, die Anmeldung weist ab, solange eine Notabschaltung aktiv ist), project_emergency_stop_already_active (409, Aktivieren bei bereits aktiver Notabschaltung) und project_emergency_stop_not_active (409, Aufheben ohne aktive Notabschaltung).

Read-Endpoints

GET /api/v1/agents

Liefert die Agent-Liste des Projekts mit Status, Risikoklassifizierung und Aktivitäts-Metadaten.

Governance-Metadaten aktualisieren

PATCH /api/v1/agents/{id}

Aktualisierbare Felder u. a.: 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.

Die Feldnamen lauten risk_classification und technical_lead_id — es gibt kein risk_level, kein technical_maintainer_id und kein data_protection_level. Unbekannte Felder werden still ignoriert; ein Tippfehler macht das Update für dieses Feld zum No-op.

Fehler

Fehler liefern ein strukturiertes error-Objekt (code, message, request_id) mit passendem HTTP-Status (400 Validierung, 403 Autorisierung, 404 unbekannter Agent). Verzweigen Sie auf error.code.