Une documentation encyclopedique pour comprendre, integrer et operer Aurels: le pare-feu d'intention qui verifie les actions sensibles des agents IA avant execution.
Ce qu'Aurels protege: les moments ou un agent IA s'apprete a agir dans le monde reel.
Une action autonome est une operation declenchee par un agent: envoyer un email, payer une facture, modifier un CRM, lire une base interne ou appeler un outil sensible.
Aurels se place juste avant l'execution. L'agent peut raisonner librement, mais l'action finale passe par une verification d'intention.
Un banc d'essai reproductible pour comparer les defenses contre les actions dangereuses.
Le benchmark mesure si un systeme laisse passer des attaques d'injection, bloque des actions legitimes ou produit une decision difficile a auditer.
Il sert de preuve technique sans promesse marketing inverifiable: les scenarios sont consultables et executables localement.
Les cles identifient le workspace et autorisent les appels a la verification.
Chaque appel machine-to-machine vers Aurels doit fournir une cle via l'en-tete x-api-key. Le dashboard permet de creer et revoquer les cles de workspace.
Les humains peuvent se connecter au dashboard par magic link Supabase Auth quand leur compte est relie au workspace dans workspace_members. Un admin peut provisionner ces acces depuis /dashboard/members ou via POST /api/v1/workspace/members.
En production, une cle doit rester cote serveur. Ne l'expose jamais dans un navigateur, une app mobile publique ou un repository.
Aurels renvoie toujours une reponse simple: allow, flag ou block.
allow signifie que l'action respecte les regles connues. flag signifie qu'une revue humaine est recommandee. block signifie que l'action ne doit pas etre executee.
La decision inclut aussi une raison, un score de risque, la couche qui a declenche le verdict et une trace d'audit signee quand l'action est persistee.
{
"decision": "flag",
"reason": "Recipient is outside the mandate recipient list",
"risk_score": 95,
"triggered_rule": "mandate_recipient"
}Le coeur du produit: verifier que l'action demandee correspond bien a l'intention autorisee.
L'evaluation combine des regles deterministes, des limites de velocite, des politiques de workspace, des mandats signes et des signaux semantiques.
Le but n'est pas de juger toute la conversation de l'agent. Le but est de prendre une decision fiable au moment exact ou une action sensible va partir.
Le mode intermediaire pour ne pas tout bloquer quand une validation humaine suffit.
flag est utile pour les actions inhabituelles, les montants proches d'une limite ou les recipients qui meritent une verification.
Une equipe peut router ces cas vers une file de revue, un webhook, un SIEM ou un process interne.
Le chemin le plus court pour proteger une premiere action.
Cree une cle, installe le SDK, decris l'action que ton agent veut executer, puis respecte la decision renvoyee par Aurels.
Pour un test local, commence avec un paiement fictif ou une action email. Ensuite seulement, branche Aurels a un outil de production.
import { createAurelsClient } from "aurels/sdk";
const aurels = createAurelsClient({
apiKey: process.env.AURELS_API_KEY!,
baseUrl: "https://aurels.dev",
});
const decision = await aurels.verify({
intent_id: "act_001",
agent_id: "agent_finance",
amount: 250,
currency: "USD",
recipient: "billing@stripe.com",
metadata: { category: "saas" },
});Aurels garde l'humain dans la boucle quand le risque depasse ce qui est acceptable.
Toutes les actions ne doivent pas etre automatisees a 100%. Le bon compromis est souvent: allow pour le banal, flag pour l'ambigu, block pour le dangereux.
Cette logique permet a une startup de garder de la vitesse sans donner un pouvoir illimite a ses agents.
Aurels peut s'inserer dans plusieurs stacks d'agents et de workflows.
Le repository inclut des integrations et guides pour OpenAI Agents, LangGraph, CrewAI, Claude Code, MCP, Hermes et OpenClaw.
L'integration ideale est celle qui enveloppe l'appel outil sensible: paiement, email, CRM, base interne, commande shell ou acces document.
L'API Aurels est volontairement simple: une requete JSON, une decision JSON.
L'endpoint principal accepte une description structuree de l'action: montant, devise, destinataire, agent, contexte et metadata.
Utilise des champs stables et explicites. Plus l'intention est precise, plus la decision est facile a auditer.
curl -X POST "https://aurels.dev/api/v1/verify" \
-H "content-type: application/json" \
-H "x-api-key: $AURELS_API_KEY" \
-d '{
"intent_id": "pay_001",
"agent_id": "agent_finance",
"amount": 250,
"currency": "USD",
"recipient": "billing@stripe.com"
}'Le block est le frein d'urgence pour les actions qui ne doivent pas partir.
Quand Aurels renvoie block, l'application appelante doit stopper l'action et enregistrer la raison.
Un block peut venir d'une signature invalide, d'un mandat expire, d'un montant trop eleve, d'une destination interdite ou d'une contradiction avec les limites du workspace.
Les limites transforment une mission vague en cadre operationnel.
Une limite peut etre un plafond de montant, une devise, une liste de recipients, un type d'action, une fenetre de temps ou une categorie autorisee.
Les limites sont le langage le plus important d'Aurels: elles disent a l'agent ce qu'il peut faire sans demander a nouveau.
Un mandat definit ce qu'un agent peut faire, pour qui, combien, jusqu'a quand.
Un mandat signe est une permission verifiable. Il contient un scope, une expiration, des contraintes et une signature HMAC.
Si l'action sort du mandat, Aurels bloque ou signale selon la politique. C'est le mecanisme cle pour deleguer sans perdre le controle.
Les evenements importants peuvent partir vers les outils de ton equipe.
Aurels peut notifier les escalades, exports d'audit et evenements de workspace via webhooks.
Les payloads doivent etre verifies cote recepteur avec la signature fournie, surtout si l'evenement declenche une action interne.
Chaque decision utile doit pouvoir etre relue, expliquee et rattachee a une action.
L'observabilite couvre les logs, les scores, les raisons de decision, les signatures, les webhooks et les exports.
Elle permet de comprendre pourquoi un agent a ete bloque sans relire toute son execution.
Les policies sont les regles de securite appliquees a un workspace.
Une policy exprime ce que l'organisation accepte: seuils, recipients, categories, fail mode semantique, webhooks et limites d'exposition.
Commence strict sur les actions a fort impact, puis assouplis seulement quand les traces montrent que le workflow est stable.
Une integration minimale tient en trois etapes.
1. Recupere une cle. 2. Appelle /api/v1/verify avant l'outil sensible. 3. Execute uniquement si la decision est allow.
Pour flag, cree une revue humaine. Pour block, stoppe l'action et montre la raison dans tes logs internes.
if (decision.decision === "allow") {
await runSensitiveTool();
} else {
await createReviewOrStop(decision);
}La readiness indique si le workspace est pret pour un usage plus serieux.
Aurels peut verifier des signaux de preparation: configuration des secrets, webhooks, audit, politiques et integrations.
C'est une checklist produit: elle reduit les angles morts avant de brancher un agent sur des donnees ou des actions reelles.
Le SDK evite de reecrire l'appel HTTP, la normalisation et les erreurs a la main.
Utilise le SDK cote serveur pour decrire l'intention et recevoir une decision typee.
Les adapters permettent d'encapsuler des outils d'agent afin que le check Aurels devienne une etape naturelle du workflow.
Une trace d'audit repond a une question simple: qui a voulu faire quoi, quand, et pourquoi c'etait autorise ou refuse.
Les traces d'audit doivent etre suffisamment detaillees pour une revue interne, mais jamais contenir plus de donnees sensibles que necessaire.
Les signatures rendent la trace verifiable apres export ou incident.
Les meilleurs premiers cas sont les actions frequentes, repetables et sensibles.
Exemples: paiements SaaS, support client, CRM et sales ops, acces aux documents internes, outils dev, exports et commandes de back-office.
Aurels est moins utile pour une simple question-reponse. Il devient critique quand l'agent peut agir.
La verification doit etre appelee avant l'action, pas apres.
Verifier apres coup transforme Aurels en simple outil de reporting. Verifier avant l'action en fait un pare-feu.
Le bon point d'integration est donc l'adapter, le tool wrapper, le middleware ou l'orchestrateur qui controle l'appel final.
Les webhooks relient Aurels a ton stack operationnel.
Ils peuvent alimenter Slack, un SIEM, un outil de support, une file de revue ou un pipeline d'audit.
Chaque webhook doit etre signe et verifie. Un webhook non verifie devient lui-meme une surface d'attaque.
L'en-tete d'authentification principal pour les appels machine-to-machine.
Le header x-api-key doit etre envoye par ton backend a chaque verification.
Si la cle est absente, invalide ou revoquee, l'appel doit echouer et l'action protegee ne doit pas partir.
fetch("https://aurels.dev/api/v1/verify", {
method: "POST",
headers: {
"content-type": "application/json",
"x-api-key": process.env.AURELS_API_KEY!,
},
body: JSON.stringify(intent),
});Un agent utile sait rendre le controle quand une action devient ambigue.
La securite des agents ne consiste pas seulement a dire non. Elle consiste a rendre le controle au bon moment.
Aurels formalise ce passage de relais avec flag, les revues humaines et les raisons lisibles.
Le principe fondateur: ne jamais supposer qu'un agent agit toujours dans le bon contexte.
Un agent peut etre brillant et quand meme suivre une mauvaise instruction cachee dans un email, une page web ou un document.
Aurels applique une logique zero-trust aux actions: chaque action sensible doit prouver qu'elle respecte le cadre avant d'etre executee.