Documentation

Comment fonctionne PROMIVO

Les concepts nécessaires pour déployer un agent, construire un flux de travail et appeler la plateforme depuis vos propres systèmes.

Agents et versions

Un agent est une fiche de la catalogue plus une ou plusieurs versions immuables. Une version porte l’invite système, la configuration du modèle, les outils qu’elle peut appeler, ses schémas d’entrée et de sortie, ses limites d’exécution et son plafond de risque automatique.

Publier une mise à jour crée une nouvelle version et déplace le pointeur courant. Une version existante n’est jamais modifiée : une exécution déjà en cours conserve le comportement avec lequel elle a démarré.

Permissions et risque

Chaque outil déclare un niveau de risque. Une version d’agent déclare le niveau maximal qu’elle peut exécuter sans humain.

READRécupère, recherche, résume. Ne change rien.
WRITEEnvoyer un e-mail, publier une mise à jour, créer ou mettre à jour un enregistrement.
DESTRUCTIVESupprimer des données ou dépenser de l'argent.

Un appel d’outil au-dessus du plafond est refusé, enregistré comme tâche en attente d’approbation et signalé au modèle comme non effectué. L’exécution continue ; l’effet n’a pas lieu.

Nœuds de flux

Nœud	Ce qu’il fait
`TRIGGER`	Point d’entrée. Manuel, webhook, planifié ou événementiel.
`AI`	Exécute un agent avec un gabarit d’entrée interpolé.
`HTTP`	Appelle un point de terminaison HTTP public. Les plages réseau privées sont bloquées.
`CONDITION`	Se ramifie selon une valeur du contexte d’exécution.
`TRANSFORM`	Remodèle les données en un nouvel objet.
`EMAIL`	Envoie un courriel via le fournisseur configuré.
`WEBHOOK`	Émet vers l’extérieur une charge JSON signée.
`DELAY`	Attend jusqu’à 300 secondes au sein d’une exécution.
`DATABASE`	Enregistre une note ou lit les exécutions récentes.
`OUTPUT`	Définit le résultat final du flux.

Gabarits

La configuration d’un nœud interpole des valeurs issues du contexte d’exécution. Il n’y a aucune évaluation d’expression : un gabarit ne peut jamais exécuter de code.

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

API publique

Créez une clé à portée limitée sur la Page des clés d’API. Le secret n’est affiché qu’une fois ; seul son hachage est conservé.

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

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

Chaque réponse utilise la même enveloppe :

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

Points de terminaison

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

Déclencheurs webhook

Un flux webhook reçoit un jeton public et un secret de signature affiché une seule fois à la création. Signez le corps brut avec ce secret.

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": "…" }