Agents
KI-Agenten registrieren, verwalten und durch ihren Lebenszyklus steuern.
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 |
budget_daily_requests / budget_daily_tokens / budget_daily_cost_eur / budget_monthly_cost_eur | — | Per-Agent-Budgets |
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 einen ag_-Agent-API-Key — sofort speichern, er wird nur einmal angezeigt. Hinweis: Dieser Key wird noch von keinem API-Auth-Pfad akzeptiert (siehe Authentifizierung); Anfragen authentifizieren sich weiterhin mit dem Projekt-Key, 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) |
POST /agents/emergency-stop | Projektweiter Not-Aus (ohne {id} — stoppt Agents projektweit) |
Agent-Lifecycle-Events gehören zu den verpflichtenden Flare-Attestierungs-Events (EU-KI-Verordnung Art. 12).
Read-Endpoints
GET /api/v1/agentsLiefert 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, die vier budget_*-Felder, permitted_tools, fria_assessment, transparency_disclosure, responsible_person_id, technical_lead_id, approval_authority_id, infrastructure_permissions, capability_model, framework.
Die Feldnamen lauten
risk_classificationundtechnical_lead_id— es gibt keinrisk_level, keintechnical_maintainer_idund keindata_protection_level. Unbekannte Felder werden still ignoriert; ein Tippfehler macht das Update für dieses Feld zum No-op.
Fehler
Fehler liefern einen einfachen {"error": "<Meldung>"}-Body (lokalisiert) mit passendem HTTP-Status (400 Validierung, 403 Autorisierung/Entitlement, 404 unbekannter Agent).