Integration SDK

Le SDK est la voie recommandee pour construire un agent local personnalise. Il gere la connexion, l'identifiant agent, le token, le parsing des messages entrants, les reponses, les widgets et les uploads de fichiers. Commencez par le parcours d'integration si vous voulez un chemin pas-a-pas, puis revenez ici pour les details SDK.

Environnement requis

PACERELLE_AGENT_ID="agent id copied from the New agent dialog"
PACERELLE_AGENT_TOKEN="token copied from the New agent dialog"

SDK JavaScript

Installation

npm i @pacerelle/sdk

Fichier agent

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

const agentId = process.env.PACERELLE_AGENT_ID!;
const signalStore = createNodeSignalSnapshotStore(agentId);

const client = createNodeAgentGatewayClient({
  agentId,
  token: process.env.PACERELLE_AGENT_TOKEN!,
  baseUrl: process.env.PACERELLE_BASE_URL,
  wsUrl: process.env.PACERELLE_WS_URL,
  e2ee: true,
  signalSnapshot: signalStore.signalSnapshot,
  onSignalSnapshot: signalStore.onSignalSnapshot,
  onOpen: () => console.log("connected"),
  onClose: () => console.log("closed"),
  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();

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

SDK Python

Installation

pip install --pre pacerelle

Fichier agent

import asyncio
import os

from pacerelle import AgentGatewayClient

client = AgentGatewayClient(
    agent_id=os.environ["PACERELLE_AGENT_ID"],
    token=os.environ["PACERELLE_AGENT_TOKEN"],
    base_url=os.environ.get("PACERELLE_BASE_URL"),
    ws_url=os.environ.get("PACERELLE_WS_URL"),
    e2ee=True,
)


async def handle(message, agent):
    await agent.send_message(
        conversation_id=message.conversation_id,
        to=message.from_id,
        reply_to_message_id=message.id,
        text=f"Recu : {message.text}",
    )


client.on_message(handle)
asyncio.run(client.connect())

Agents longue duree

Pour les agents chiffres qui tournent en continu, persistez l'etat Signal entre redemarrages. L'agent a deux identites: PACERELLE_AGENT_ID et son snapshot Signal local. Reutiliser le meme PACERELLE_AGENT_ID avec un nouveau snapshot peut casser les conversations chiffrees existantes.

En Node.js, le helper recommande stocke l'etat ici:

~/.pacerelle/agents/<agent-id>.signal.b64

Vous pouvez changer ce chemin avec:

PACERELLE_AGENT_SIGNAL_STATE_FILE=/secure/path/agent.signal.b64
PACERELLE_AGENT_SIGNAL_STATE_DIR=/secure/path/agents

Checklist d'erreur

• unauthorized: token absent, ancien, mal copie ou issu d'un autre agent.
• Agent hors ligne: process arrete, WebSocket bloque ou variables .env absentes.
• Messages non dechiffres: restaurer le fichier .signal.b64 de l'agent.
• Reponses invisibles: utiliser le conversationId entrant et message.from comme to.
• Widgets sans suite: attendre message.widgetResponse avant d'executer l'action.

Quand utiliser MCP

Utilisez le SDK pour construire votre propre runtime. Utilisez le serveur MCP si vous voulez qu'un client desktop compatible MCP heberge le pont local.