Parcours d'integration

Le chemin le plus fluide pour connecter un agent reel avec le SDK, MCP ou une pile locale.

Cette page rassemble le parcours valide en test reel: creer un agent dans l'app, lancer un runtime local chiffre, envoyer un message depuis le navigateur, puis verifier que la reponse revient sans exposer le contenu au relais.

Le chemin le plus simple

Utilisez l'app hebergee sauf si vous testez le gateway lui-meme.
Creez un agent dans Agents et copiez la configuration .env.
Lancez un petit agent echo chiffre avec le SDK JavaScript.
Gardez l'etat Signal de l'agent sur disque.
Envoyez un message depuis Conversations et confirmez que la reponse arrive.

Une fois ce flux valide, remplacez l'echo par votre vrai workflow: Ollama, serveur MCP, script interne, worker de build, automation ou agent maison.

Choisir le bon mode

Besoin	Chemin recommande
Integrer un agent existant rapidement	SDK JavaScript avec `@pacerelle/sdk`
Integrer un agent Python	SDK Python avec `pacerelle`
Brancher Claude Desktop, Cursor ou Zed	Serveur MCP `@pacerelle/mcp-server`
Tester le produit complet localement	`docker compose` depuis le repo
Deboguer le gateway	Pile locale + `PACERELLE_BASE_URL` et `PACERELLE_WS_URL`

Variables a copier

Depuis la modale Nouvel agent, copiez au minimum:

PACERELLE_AGENT_ID=agent_...
PACERELLE_AGENT_TOKEN=...

Pour l'app hebergee, ne definissez rien d'autre. Pour un gateway local:

PACERELLE_BASE_URL=http://localhost:8080
PACERELLE_WS_URL=ws://localhost:8080

Le token agent est affiche une seule fois. S'il est perdu, ouvrez l'agent dans l'app, faites une rotation du token, mettez a jour .env, puis relancez le runtime.

Option A: integration hebergee

Installez le SDK:

npm i @pacerelle/sdk

Creez agent.mjs:

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

const agentId = process.env.PACERELLE_AGENT_ID;
const token = process.env.PACERELLE_AGENT_TOKEN;

if (!agentId || !token) {
  throw new Error("PACERELLE_AGENT_ID and PACERELLE_AGENT_TOKEN are required");
}

const signalStore = createNodeSignalSnapshotStore(agentId);

const client = createNodeAgentGatewayClient({
  agentId,
  token,
  baseUrl: process.env.PACERELLE_BASE_URL,
  wsUrl: process.env.PACERELLE_WS_URL,
  e2ee: true,
  signalSnapshot: signalStore.signalSnapshot,
  onSignalSnapshot: signalStore.onSignalSnapshot,
  onOpen: () => console.log("Pacerelle agent connected"),
  onClose: () => console.log("Pacerelle agent disconnected"),
  onError: console.error,
});

client.onMessage(async (message, agent) => {
  await agent.sendMessage({
    conversationId: message.conversationId,
    to: message.from,
    replyToMessageId: message.id,
    text: `Recu: ${message.text}`,
  });
});

await client.connect();

Lancez:

node --env-file=.env agent.mjs

Le helper Node conserve l'identite Signal sous ~/.pacerelle/agents/<agent-id>.signal.b64. Gardez ce fichier avec le meme PACERELLE_AGENT_ID; changer de snapshot avec le meme agent casse les anciennes conversations chiffrees.

Option B: pile locale

Dans ce repo, le chemin complet lance Postgres, Redis, MinIO, les migrations, le gateway et le web:

wsl -e sh -lc "cd /mnt/c/Projects/MyAgents && docker compose --env-file .env.dev up -d"

Si Postgres ou Redis sont deja utilises sur la machine, gardez les ports app par defaut et decalez seulement les ports hote de la base:

wsl -e sh -lc "cd /mnt/c/Projects/MyAgents && POSTGRES_PORT=55432 REDIS_PORT=6380 docker compose --env-file .env.dev up -d"

Verifiez ensuite:

Invoke-WebRequest http://localhost:8080/healthz -UseBasicParsing
Invoke-WebRequest http://localhost:5173 -UseBasicParsing

Le gateway doit repondre 200 sur /healthz et le web doit charger sur http://localhost:5173.

Pour lancer le gateway directement avec Go sous WSL, sans utiliser son conteneur de developpement, demarrez seulement les dependances puis utilisez le script local:

wsl -e bash -lc "cd /mnt/c/Projects/MyAgents && POSTGRES_PORT=55432 REDIS_PORT=6380 docker compose --env-file .env.dev up -d db redis db-migrate"
wsl -e bash -lc "cd /mnt/c/Projects/MyAgents && POSTGRES_PORT=55432 REDIS_PORT=6380 bash scripts/start_gateway_for_smoke.sh"

Le script charge .env.dev et force Postgres, Redis et le mailer de test en local. Il ne reutilise pas les connexions distantes eventuellement presentes dans .env.

Passer de l'echo a un vrai agent

Gardez cette structure:

Recevoir le message dans onMessage.
Lire message.text, message.attachments ou message.widgetResponse.
Executer votre workflow local.
Repondre avec le meme conversationId.
Utiliser message.from comme destinataire.

client.onMessage(async (message, agent) => {
  const answer = await runLocalWorkflow(message.text);

  await agent.sendMessage({
    conversationId: message.conversationId,
    to: message.from,
    replyToMessageId: message.id,
    text: answer,
  });
});

Permissions et widgets

Pour les actions sensibles, demandez une permission avant d'agir. Le flux teste en reel est: envoyer le widget, attendre la reponse, verifier granted: true, puis executer l'action avec le scope choisi.

client.onMessage(async (message, agent) => {
  if (message.widgetResponse?.ref === "permission-web-search") {
    const permission = message.widgetResponse.value as { granted?: boolean; scope?: string };
    if (!permission.granted) return;

    const answer = await runWebSearch({ scope: permission.scope });
    await agent.sendMessage({
      conversationId: message.conversationId,
      to: message.from,
      text: answer,
    });
    return;
  }

  await agent.sendPermissionWidget({
    conversationId: message.conversationId,
    to: message.from,
    id: "permission-web-search",
    title: "Autoriser la recherche web ?",
    body: "L'agent veut appeler un service externe pour repondre.",
    scopes: ["once", "session"],
  });
});

Checklist de validation

L'agent apparait en ligne dans l'app.
Le process local reste ouvert sans erreur d'authentification.
onOpen s'affiche dans les logs.
onMessage recoit le message envoye depuis le navigateur.
La reponse utilise le conversationId entrant et message.from.
Le fichier ~/.pacerelle/agents/<agent-id>.signal.b64 existe apres le premier message chiffre.
Les widgets attendent une reponse utilisateur avant d'executer l'action.

Si ca bloque

Agent hors ligne: verifiez PACERELLE_AGENT_ID, PACERELLE_AGENT_TOKEN et la sortie WebSocket.
unauthorized: le token est absent, ancien, mal copie ou appartient a un autre agent.
Messages non dechiffres: ne regenerez pas l'identite Signal; reutilisez le snapshot stable de l'agent.
Reponses invisibles: verifiez conversationId, to: message.from et e2ee: true.
Localhost inaccessible: verifiez http://localhost:8080/healthz, puis le web sur http://localhost:5173.

Voir aussi Integration SDK, Serveur MCP et Securite.