Agent Connect — Pacerelle Docs

Agent Connect s'adresse aux produits qui font tourner un agent pour leurs utilisateurs — un assistant de recherche, un bot de support, un service domotique. Au lieu de demander à l'utilisateur de copier un jeton, votre application demande une installation, l'utilisateur l'approuve dans Pacerelle, et votre serveur reçoit des identifiants limités à cet agent.

Principe

L'utilisateur crée une clé de connexion

Dans Pacerelle, l'utilisateur ouvre Paramètres → Sécurité → Agent Connect, crée une clé de connexion à usage unique et la colle dans votre application.

Votre serveur lance l'installation

Il appelle beginAgentConnect avec la clé et redirige le navigateur vers l'URL d'autorisation renvoyée.

L'utilisateur approuve dans Pacerelle

Pacerelle affiche le nom et la description de votre agent. Après approbation, il crée l'agent et une conversation directe, puis redirige vers votre callback avec un code à usage unique.

Votre serveur échange le code

Il reçoit un jeton d'installation durable, puis demande des jetons d'exécution de courte durée pour connecter l'agent.

1. Enregistrer votre application

Enregistrez une fois un client OAuth, avec toutes les URL de callback que vous utiliserez. Conservez le client_id renvoyé dans la configuration de votre serveur.

Terminal

curl -X POST https://api.pacerelle.com/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Acme Recherche",
    "redirect_uris": ["https://acme.example/pacerelle/callback"]
  }'

2. Lancer l'installation

À exécuter sur votre serveur. Stockez state et codeVerifier dans la session serveur de l'utilisateur.

import { beginAgentConnect } from "@pacerelle/sdk";

const pending = await beginAgentConnect({
  connectKey: keyPastedByTheUser,
  clientId: process.env.PACERELLE_CLIENT_ID,
  redirectUri: "https://acme.example/pacerelle/callback",
  agentName: "Acme Recherche",
  agentDescription: "Résume votre veille chaque matin.",
});

session.pacerelleState = pending.state;
session.pacerelleVerifier = pending.codeVerifier;
response.redirect(pending.authorizationUrl);

3. Traiter le callback

Vérifiez d'abord state, puis échangez le code contre un jeton d'installation. Stockez ce jeton chiffré, uniquement côté serveur.

import { exchangeAgentConnectCode } from "@pacerelle/sdk";

if (request.query.state !== session.pacerelleState) throw new Error("State invalide");

const installation = await exchangeAgentConnectCode({
  code: request.query.code,
  codeVerifier: session.pacerelleVerifier,
  clientId: process.env.PACERELLE_CLIENT_ID,
  redirectUri: "https://acme.example/pacerelle/callback",
});

await saveEncrypted(user.id, {
  installationToken: installation.installationToken,
  agentId: installation.agentId,
});

4. Faire tourner l'agent

Demandez un jeton d'exécution, puis connectez l'agent exactement comme n'importe quel autre.

import { requestAgentRuntimeToken } from "@pacerelle/sdk";
import {
  createNodeAgentGatewayClient,
  createNodeSignalSnapshotStore,
} from "@pacerelle/sdk/node";

const runtime = await requestAgentRuntimeToken({ installationToken });
const state = createNodeSignalSnapshotStore(runtime.agentId);

const agent = createNodeAgentGatewayClient({
  agentId: runtime.agentId,
  token: runtime.agentToken,
  e2ee: true,
  signalSnapshot: state.signalSnapshot,
  onSignalSnapshot: state.onSignalSnapshot,
});

agent.onMessage(async (message, client) => {
  await client.reply(message, { text: "Bonjour ! Je suis connecté. Comment puis-je aider ?" });
});

await agent.connect();

Jetons et cycle de vie

Jeton	Durée de vie	Où il vit
Clé de connexion	Usage unique	Collée par l'utilisateur dans votre application.
Jeton d'installation	Jusqu'à ce que l'utilisateur révoque l'installation	Votre serveur, chiffré au repos. Jamais dans un navigateur.
Jeton d'exécution	15 minutes	Le processus de votre agent. Demandez-en un nouveau avant chaque reconnexion.

Un état par agent. Conservez l'état de chiffrement de chaque agentId que vous faites tourner. Le changer change l'identité de l'agent.
L'utilisateur parle en premier. L'installation crée une conversation directe ; dès que l'utilisateur envoie le premier message, la session chiffrée est établie et votre agent peut répondre.
La révocation est immédiate. Si l'utilisateur révoque l'installation dans Pacerelle, les nouveaux jetons d'exécution sont refusés. Traitez cette erreur en arrêtant l'agent et en marquant l'installation comme déconnectée.