Dokumentation

So funktioniert PROMIVO

Die Konzepte, die Sie brauchen, um einen Agenten einzusetzen, einen Workflow zu bauen und die Plattform aus Ihren eigenen Systemen aufzurufen.

Agenten und Versionen

Ein Agent ist ein Katalogeintrag plus eine oder mehrere unveränderliche Versionen. Eine Version trägt den System-Prompt, die Modellkonfiguration, die Werkzeuge, die sie aufrufen darf, ihre Ein- und Ausgabeschemata, Ausführungsgrenzen und ihre automatische Risikoobergrenze.

Eine Aktualisierung zu veröffentlichen erzeugt eine neue Version und verschiebt den aktuellen Zeiger. Eine bestehende Version wird nie verändert, ein bereits laufender Durchgang behält also das Verhalten, mit dem er begonnen hat.

Berechtigungen und Risiko

Jedes Werkzeug deklariert eine Risikostufe. Eine Agentenversion deklariert die höchste Stufe, die sie ohne Menschen ausführen darf.

READAbrufen, suchen, zusammenfassen. Ändert nichts.
WRITEEine E-Mail senden, ein Update posten, einen Datensatz anlegen oder ändern.
DESTRUCTIVEDaten löschen oder Geld ausgeben.

Ein Werkzeugaufruf über der Obergrenze wird abgelehnt, als genehmigungspflichtige Aufgabe erfasst und dem Modell als nicht ausgeführt zurückgemeldet. Der Lauf geht weiter; die Nebenwirkung tritt nicht ein.

Workflow-Knoten

Knoten	Was er tut
`TRIGGER`	Einstiegspunkt. Manuell, Webhook, Zeitplan oder Ereignis.
`AI`	Führt einen Agenten mit einer eingesetzten Eingabevorlage aus.
`HTTP`	Ruft einen öffentlichen HTTP-Endpunkt auf. Private Bereiche sind gesperrt.
`CONDITION`	Verzweigt anhand eines Werts im Laufkontext.
`TRANSFORM`	Formt Daten in ein neues Objekt um.
`EMAIL`	Sendet eine E-Mail über den konfigurierten Anbieter.
`WEBHOOK`	Sendet eine signierte JSON-Nutzlast nach außen.
`DELAY`	Wartet bis zu 300 Sekunden innerhalb eines Laufs.
`DATABASE`	Erfasst eine Notiz oder liest die letzten Ausführungen.
`OUTPUT`	Definiert das Endergebnis des Ablaufs.

Vorlagen

Die Knotenkonfiguration setzt Werte aus dem Laufkontext ein. Es gibt keine Ausdrucksauswertung, eine Vorlage kann also niemals Code ausführen.

{{trigger.email}}                  → the trigger payload
{{steps.qualify.output.score}}     → an earlier node result
{{workflow.name}}                  → workflow metadata

Öffentliche API

Erstellen Sie einen kapazitätsbegrenzten Schlüssel auf der Seite für API-Schlüssel. Das Geheimnis wird einmal angezeigt; gespeichert wird nur sein Hash.

POST /api/agents/run
Authorization: Bearer pmv_live_…
Content-Type: application/json

{ "agentId": "<uuid>", "input": { "topic": "Q4 planning" } }

Jede Antwort nutzt denselben Umschlag:

{ "ok": true,  "data": { … } }
{ "ok": false, "error": { "code": "…", "message": "…" } }

Endpunkte

GET /api/agents
POST /api/agents/run
GET /api/workflows
POST /api/workflows
POST /api/workflows/:id/run
GET /api/executions
GET /api/executions/:id
GET /api/usage

Webhook-Auslöser

Ein Webhook-Workflow erhält ein öffentliches Token und ein Signaturgeheimnis, das bei der Erstellung einmal angezeigt wird. Signieren Sie den Rohtext damit.

POST /api/webhooks/workflow/<token>
x-promivo-secret:    <signing secret>
x-promivo-signature: <hex HMAC-SHA256 of the raw body>
x-idempotency-key:   <optional; makes redelivery safe>

{ "email": "lead@example.com", "message": "…" }