Documentation API
Connecter un agent, alimenter l’inventaire, vérifier un dossier de preuves
Écrit pour les ingénieurs et les auditeurs. La façon dont un test est noté et ce que signifie un taux de réussite sont expliqués dans Notre méthode.
Connecter un agent
Vidimus joint votre agent par l’interface qu’il expose déjà. Collez une requête qui fonctionne déjà (une commande curl, par exemple), vérifiez que l’agent répond à un vrai message, puis lancez les tests. Il n’y a rien à installer.
| Interface | Quand la choisir |
|---|---|
| JSON sur HTTP | Votre agent prend un corps JSON et répond en JSON dans le même appel. La plupart des agents internes fonctionnent ainsi. |
| JSON sur HTTP, avec appels d’outils dans la réponse | Comme ci-dessus, et la réponse liste aussi les outils que l’agent a appelés, que nous consignons comme preuves. |
| Agent A2A | Un agent qui publie une fiche d’agent A2A (protocole 1.0, 0.3 ou 0.2). Nous lisons la fiche et suivons chaque tâche jusqu’à son terme. |
| Serveur MCP | Un serveur Model Context Protocol sur HTTP. Nous listons ses outils et testons ce qu’il fait lorsqu’ils sont appelés. |
| Flux (server-sent events) | Votre agent diffuse sa réponse en server-sent events. Nous lisons le flux jusqu’au bout avant de l’évaluer. |
| Événement ou webhook (agent de back-office) | Un agent de back-office déclenché par un message de file ou un webhook plutôt que par un tour de conversation. |
| Microsoft Direct Line (Copilot Studio) | Un agent Microsoft joint par Direct Line. Nous ouvrons une conversation, postons le message et attendons la réponse. |
JSON sur HTTP
- Quand la choisir
- Votre agent prend un corps JSON et répond en JSON dans le même appel. La plupart des agents internes fonctionnent ainsi.
JSON sur HTTP, avec appels d’outils dans la réponse
- Quand la choisir
- Comme ci-dessus, et la réponse liste aussi les outils que l’agent a appelés, que nous consignons comme preuves.
Agent A2A
- Quand la choisir
- Un agent qui publie une fiche d’agent A2A (protocole 1.0, 0.3 ou 0.2). Nous lisons la fiche et suivons chaque tâche jusqu’à son terme.
Serveur MCP
- Quand la choisir
- Un serveur Model Context Protocol sur HTTP. Nous listons ses outils et testons ce qu’il fait lorsqu’ils sont appelés.
Flux (server-sent events)
- Quand la choisir
- Votre agent diffuse sa réponse en server-sent events. Nous lisons le flux jusqu’au bout avant de l’évaluer.
Événement ou webhook (agent de back-office)
- Quand la choisir
- Un agent de back-office déclenché par un message de file ou un webhook plutôt que par un tour de conversation.
Microsoft Direct Line (Copilot Studio)
- Quand la choisir
- Un agent Microsoft joint par Direct Line. Nous ouvrons une conversation, postons le message et attendons la réponse.
Les sept protocoles qu’une campagne de test sait utiliser.
Les tests en plusieurs échanges conservent la conversation : historique des messages, contexte A2A, conversation Direct Line.
| Méthode | Quand la choisir |
|---|---|
| Aucune | Quiconque connaît l’URL peut l’appeler. Fréquent pour un agent déjà placé derrière un VPN ou sur un réseau privé. |
| En-tête | Une valeur fixe envoyée à chaque requête. La forme la plus courante pour un point de terminaison interne. |
| Clé d’API dans l’adresse | La clé circule dans l’URL plutôt que dans un en-tête. C’est ainsi qu’Azure Functions et API Management exposent habituellement un agent. |
| OAuth 2.0 (client credentials) | Un client machine à machine déclaré auprès de votre fournisseur d’identité. Choisissez cette option si votre passerelle émet des jetons de courte durée. |
| Compte de service Google | Une clé JSON de compte de service, pour les agents posés directement sur une API Google. |
| TLS mutuel | Votre passerelle exige un certificat client que nous présentons lors de la négociation TLS. Téléversez le certificat que nous devons utiliser. |
Aucune
- Quand la choisir
- Quiconque connaît l’URL peut l’appeler. Fréquent pour un agent déjà placé derrière un VPN ou sur un réseau privé.
En-tête
- Quand la choisir
- Une valeur fixe envoyée à chaque requête. La forme la plus courante pour un point de terminaison interne.
Clé d’API dans l’adresse
- Quand la choisir
- La clé circule dans l’URL plutôt que dans un en-tête. C’est ainsi qu’Azure Functions et API Management exposent habituellement un agent.
OAuth 2.0 (client credentials)
- Quand la choisir
- Un client machine à machine déclaré auprès de votre fournisseur d’identité. Choisissez cette option si votre passerelle émet des jetons de courte durée.
Compte de service Google
- Quand la choisir
- Une clé JSON de compte de service, pour les agents posés directement sur une API Google.
TLS mutuel
- Quand la choisir
- Votre passerelle exige un certificat client que nous présentons lors de la négociation TLS. Téléversez le certificat que nous devons utiliser.
Les six façons dont une campagne de test peut s’authentifier.
Les identifiants sont dans un coffre. Vidimus ne conserve que leur référence. Un secret trouvé dans une commande collée n’est jamais enregistré, sauf si vous le saisissez à nouveau.
Les réglages prêts à l’emploi par plateforme, les plateformes que nous ajoutons sur demande et les connecteurs de registre sont sur la page Intégrations.
Ce qu’envoie une campagne de test
Ce que reçoit votre agent pendant une campagne et ce que Vidimus conserve.
| Par campagne | À quoi vous attendre |
|---|---|
| Tests par campagne | Jusqu’à 150. Au-delà, les tests sont retenus par ordre de gravité, et ceux qui sont écartés sont nommés. |
| Tentatives par test | 10 : une campagne fait donc au plus 1 500 tentatives. Une tentative en plusieurs échanges envoie un message par échange, jusqu’à cinq, et Direct Line et A2A interrogent l’agent jusqu’à l’arrivée de la réponse. |
| Rythme | Parallélisme borné et débit limité par agent. |
| Arrêt | Toute campagne peut être annulée à tout moment. |
| Durée type | 28 tests et 280 tentatives ont pris 22 minutes dans notre campagne de référence. |
| Ce qui est consigné | Chaque prompt, chaque réponse et chaque appel d’outil que l’agent expose sont conservés dans l’UE. |
| Appels d’outils | Les appels d’outils sont lus dans la réponse, le journal d’outils ou la trace d’événements, et tenus pour la preuve face à ce que dit l’agent. L’appel d’un outil que l’agent n’a jamais déclaré est un constat, tout comme une action que l’agent dit refuser mais que son journal d’outils montre accomplie. |
| Sous-agents | Votre orchestrateur (LangGraph, AutoGen, CrewAI) peut envoyer ses traces à un webhook propre à chaque agent (section 06), et chaque trace est rattachée au test qui l’a provoquée. |
Tests par campagne
- À quoi vous attendre
- Jusqu’à 150. Au-delà, les tests sont retenus par ordre de gravité, et ceux qui sont écartés sont nommés.
Tentatives par test
- À quoi vous attendre
- 10 : une campagne fait donc au plus 1 500 tentatives. Une tentative en plusieurs échanges envoie un message par échange, jusqu’à cinq, et Direct Line et A2A interrogent l’agent jusqu’à l’arrivée de la réponse.
Rythme
- À quoi vous attendre
- Parallélisme borné et débit limité par agent.
Arrêt
- À quoi vous attendre
- Toute campagne peut être annulée à tout moment.
Durée type
- À quoi vous attendre
- 28 tests et 280 tentatives ont pris 22 minutes dans notre campagne de référence.
Ce qui est consigné
- À quoi vous attendre
- Chaque prompt, chaque réponse et chaque appel d’outil que l’agent expose sont conservés dans l’UE.
Appels d’outils
- À quoi vous attendre
- Les appels d’outils sont lus dans la réponse, le journal d’outils ou la trace d’événements, et tenus pour la preuve face à ce que dit l’agent. L’appel d’un outil que l’agent n’a jamais déclaré est un constat, tout comme une action que l’agent dit refuser mais que son journal d’outils montre accomplie.
Sous-agents
- À quoi vous attendre
- Votre orchestrateur (LangGraph, AutoGen, CrewAI) peut envoyer ses traces à un webhook propre à chaque agent (section 06), et chaque trace est rattachée au test qui l’a provoquée.
Le trafic d’une campagne de test et ce qui est consigné.
Alimenter l’inventaire par API
Alimentez l’inventaire Vidimus depuis votre CMDB ou votre outil de gouvernance. Jusqu’à 500 agents et 2 Mo par appel.
POST /api/v1/registry/agents
Authorization: Bearer <organisation key>
Content-Type: application/json
{
"agents": [
{
"external_id": "cmdb-4821",
"name": "Claims triage assistant",
"description": "Routes motor claims under 25 000 EUR.",
"endpoint_url": "https://agents.example.com/claims",
"protocols": [
"http"
],
"owner": "claims-ops@example.com",
"region": "europe-west1"
}
]
}Authentifiez-vous avec la clé entrante de votre organisation, envoyée comme jeton Bearer. La clé est émise sur la page Paramètres de la plateforme, sous Registres connectés. Elle est affichée une seule fois, puis conservée sous forme de condensat. Les agents arrivent en brouillon : rien de ce qu’une personne a accepté n’est écrasé, et une modification venue de chez vous ouvre un point à examiner.
Réponses
- Acceptée. Le corps compte les agents acceptés et rejetés, liste les 50 premiers problèmes par ligne, et donne l’identifiant et le statut de la synchronisation lancée (ci-dessous).
- Le corps n’est pas du JSON, ou aucun agent n’y est valide. Les problèmes sont listés.
- Le jeton Bearer manque ou n’est pas une clé entrante active.
- Le corps dépasse 2 Mo.
- Plus de 30 envois en une minute sur cette connexion. Attendez le nombre de secondes indiqué par l’en-tête Retry-After, puis renvoyez.
- La synchronisation a échoué de notre côté. Renvoyez plus tard.
HTTP/1.1 202 Accepted
{
"accepted": 1,
"rejected": 0,
"issues": [],
"run_id": "…",
"status": "ok"
}Le document OpenAPI 3.1 décrit chaque champ.
Vérifier un dossier de preuves
Donnez à votre auditeur le PDF et sa ligne du registre : le condensat et la signature Ed25519 se vérifient hors ligne avec notre clé publiée. Aucun compte n’est nécessaire, et la vérification elle-même ne fait aucun appel à Vidimus.
Hors ligne en quatre étapes
- Calculez le SHA-256 du PDF, écrit en 64 caractères hexadécimaux. C’est ce texte que Vidimus a signé.
- Prenez la ligne du dossier dans le registre des preuves exporté en CSV depuis la page Dossiers de preuves : sha256, signing_key_id et signature_ed25519_hex.
- Prenez la clé publique dont le kid vaut signing_key_id dans la liste des clés publiées. Les clés retirées restent listées : un dossier plus ancien se vérifie toujours.
- Vérifiez la signature Ed25519 du condensat hexadécimal avec cette clé.
sha256sum evidence-pack.pdf
printf '%s' "$(sha256sum evidence-pack.pdf | cut -d' ' -f1)" > digest.txt
echo '<signature_ed25519_hex>' | xxd -r -p > sig.bin
curl -s https://www.vidimus.fr/.well-known/vidimus-signing-keys.json > vidimus-signing-keys.json
jq -r '.keys[] | select(.kid == "<signing_key_id>") | .public_key_pem' vidimus-signing-keys.json > key.pem
openssl pkeyutl -verify -pubin -inkey key.pem -rawin -in digest.txt -sigfile sig.binAvec OpenSSL 3, jq et xxd. OpenSSL répond « Signature Verified Successfully ». Sur macOS, utilisez shasum -a 256 et l’openssl@3 de Homebrew : le LibreSSL fourni avec macOS ne sait pas vérifier Ed25519.
Vous pouvez aussi utiliser Node 18 ou plus récent, à côté du PDF et d’une copie enregistrée de la liste des clés. Le script affiche true.
const { createHash, createPublicKey, verify } = require('node:crypto');
const pdf = require('node:fs').readFileSync('evidence-pack.pdf');
const line = { sha256: '<sha256>', signing_key_id: '<signing_key_id>', signature_ed25519_hex: '<signature_ed25519_hex>' };
const { keys } = require('./vidimus-signing-keys.json');
const key = createPublicKey(keys.find((k) => k.kid === line.signing_key_id).public_key_pem);
const hex = createHash('sha256').update(pdf).digest('hex');
console.log(hex === line.sha256 && verify(null, Buffer.from(hex), key, Buffer.from(line.signature_ed25519_hex, 'hex')));Essayez d’abord sur un spécimen de dossier signé de la même façon : les fichiers sont sur la page du dossier de preuves.
L’empreinte imprimée sur la couverture et sur chaque page est une autre valeur : elle identifie le contenu, car un fichier ne peut pas porter son propre condensat.
Dans le produit
Les membres connectés de l’organisation peuvent aussi faire recalculer le condensat et vérifier la signature par la plateforme :
GET /api/evidence-pack/<reviewId>/verify?pack=<packId>
{
"pack_id": "…",
"pack_version": 2,
"byte_size": 412873,
"content_sha256": {
"recorded": "9f2c…",
"actual": "9f2c…",
"matches": true
},
"fingerprint_sha256": "41ab…",
"signature": {
"status": "valid",
"kid": "vidimus-pack-…",
"value": "…"
},
"signed": true,
"legacy": false,
"ok": true
}Lire la réponse
- Le SHA-256 recalculé à partir du PDF conservé est égal à celui enregistré quand le dossier a été généré.
- Soit « valid », soit « invalid ». Il vaut « absent » pour un dossier généré avant que les dossiers ne soient signés, et « unknown_key » quand la clé qui l’a signé n’est plus publiée.
- Vrai seulement quand les condensats concordent et que la signature vaut « valid » : le champ à exiger si vous voulez un dossier signé.
- Vrai pour un dossier généré avant l’enregistrement des condensats : il n’y a rien à comparer, donc ok est faux.
- Vrai quand les condensats concordent et que la signature n’est pas « invalid ». Il est aussi vrai quand la signature est « absent » ou « unknown_key » : ok seul ne signifie donc jamais que le dossier est signé. Pour n’accepter qu’un dossier signé, vérifiez que signed vaut true.
Sans session, le point d’entrée répond 401. Un membre qui n’a pas validé l’étape d’authentification à deux facteurs reçoit 403. Un dossier que l’appelant ne peut pas voir, y compris tout dossier d’une autre organisation, renvoie 404. Un identifiant mal formé renvoie 400, et 502 signifie que le fichier conservé n’a pas pu être lu : rien n’a été vérifié.
Format du dossier de preuves
Il y a un PDF par décision. Il est rédigé dans la langue de l’organisation (français ou anglais) et couvre chaque règlement au regard duquel l’agent a été testé. Le règlement y est cité d’après son texte anglais sur EUR-Lex. Les sections suivent cet ordre.
- Couverture. L’agent, la décision, la date d’émission et la version, l’empreinte du contenu (répétée sur chaque page) et la façon de vérifier la signature.
- Synthèse. La classification au regard de l’AI Act, le règlement européen sur l’intelligence artificielle. Puis l’examen au titre de l’article 5, les obligations de l’article 50, le nombre de tests et de verdicts sur documents, et la décision. Si la fiche d’enregistrement a laissé le périmètre ouvert, la synthèse dit ce que la campagne n’a pas pu atteindre avant tout constat.
- Fiche d’enregistrement. Ce que fait l’agent et ses outils, ses données et son public tels qu’enregistrés.
- Classification juridique. Chaque fondement avec l’article sur lequel il repose, et le rôle de l’opérateur. La priorité de revue n’est pas imprimée.
- Évaluation des contrôles. Chaque contrôle avec ses preuves et son raisonnement, avec les corrections du relecteur signalées et la profondeur de chaque référentiel indiquée.
- Synthèse de la campagne de test. Les chiffres de la campagne et sa date, les tests échoués ou à valider, et les appels d’outils observés.
- Couverture obligation par obligation. Chaque obligation applicable citée mot pour mot, puis chaque test avec son prompt, le comportement attendu et une réponse. Un test échoué ou à valider donne aussi le constat et le raisonnement de l’évaluateur. Les documents figurent avec les passages cités. Les obligations qui ne s’appliquent pas à l’agent sont listées. Celles qui s’appliqueront plus tard sont présentées à part.
- Décision du relecteur. La décision (Approuvé, Approuvé sous conditions ou Refusé), les conditions et la mention de séparation des tâches.
- Piste d’audit. Les événements dans l’ordre, avec l’état de la chaîne de condensats.
- Annexe méthodologique. Les versions avec lesquelles le dossier a été produit (ci-dessous).
L’annexe nomme la version du prompt de l’évaluateur, la bibliothèque de modèles de tests et le corpus d’obligations. Chaque terme renvoie à sa définition dans le glossaire.
Un dossier ne peut pas être modifié : une réédition est une nouvelle version, et les deux restent dans votre registre des preuves. Chaque obligation porte le texte littéral du règlement dont elle est tirée, si bien qu’un désaccord porte sur le droit, pas sur notre résumé.
Les autres documents
Le dossier de classification et l’attestation article 50 sont chacun versionnés et dotés d’un condensat. Le rapport de campagne existe en PDF et en CSV, par test ou par tentative. Le relevé de maîtrise de l’IA de l’article 4 est en CSV. Le dossier de preuves est le seul document signé.
Toutes les interfaces en une liste
Tout ce qu’un client, un auditeur ou un programme peut atteindre en dehors des écrans du produit.
Points d’entrée
- Alimenter l’inventaire (section 03) avec la clé Bearer de l’organisation.
- Le document OpenAPI 3.1 de l’API du registre.
- Les traces des sous-agents envoyées par votre orchestrateur. Chaque requête de test porte un en-tête X-Vidimus-Probe-Id : renvoyez cet identifiant avec la trace. La requête est authentifiée par un secret propre à chaque agent, transmis dans X-Vidimus-Telemetry-Secret.
- Pour les membres connectés : recalculer le condensat d’un dossier et vérifier sa signature (section 04).
- Toutes les clés publiques de signature, y compris les clés retirées.
Les fichiers que vous pouvez exporter
- Registre des preuves (CSV)
- Chaque version de dossier de preuves et de dossier de classification, avec sha256, signing_key_id et signature_ed25519_hex, pour qu’un auditeur fasse sa propre vérification.
- Registre des agents (CSV)
- Chaque agent avec sa classification AI Act, sous des noms de colonnes stables pour un outil GRC.
- Relevé de maîtrise de l’IA de l’article 4 (CSV)
- Une ligne par agent, issue des questions de la fiche d’enregistrement sur la maîtrise de l’IA.
- Rapport de campagne (PDF et CSV)
- Une campagne détaillée par test ou par tentative.
L’accès à l’API est ouvert avec un pilote. Demander un pilote.