SDK Python — Pacerelle Docs

Terminal

pip install --pre pacerelle

Nécessite CPython 3.12. Les wheels embarquent la bibliothèque de chiffrement native pour Windows x64, Linux x64, Linux ARM64 et macOS ARM64.

from pacerelle import AgentGatewayClient

Le SDK est en alpha. Les API peuvent encore évoluer avant la 1.0.

AgentGatewayClient

client = AgentGatewayClient(
    agent_id=os.environ["PACERELLE_AGENT_ID"],
    token=os.environ["PACERELLE_AGENT_TOKEN"],
    e2ee=True,
)

Tous les arguments sont nommés.

agent_idstrrequis

L'identifiant de l'agent affiché dans l'application.

tokenstrrequis

Le jeton de l'agent, ou un jeton d'exécution Agent Connect.

e2eebool

Active le chiffrement de bout en bout. Vaut False par défaut — mettez toujours True hors débogage local.

store_rootstr | PathLike

Dossier de l'état de chiffrement. Par défaut ~/.myagents ; l'état se trouve dans <store_root>/<agent_id>/signal.db.

base_urlstr

URL de l'API. Par défaut https://api.pacerelle.com.

ws_urlstr

URL WebSocket. Déduite de base_url par défaut.

Avec e2ee=True, le client ouvre immédiatement sa base d'état SQLite et restaure les clés de l'agent. Un seul processus par base.

Connexion

Méthode	Description
`await connect()`	Publie si besoin les clés publiques de l'agent, ouvre le WebSocket et traite les messages jusqu'à la fin de la connexion. Ne se reconnecte pas seul — voir la reconnexion.
`close()`	Ferme la base d'état. À appeler avant de créer un nouveau client.
`publish_prekey_bundle()`	Publie les clés publiques de l'agent. Appelé par `connect()` si nécessaire.
`get_verification_code()`	Renvoie le code de vérification, une fois les clés publiées. Voir Vérifier votre agent.

Réception

on_message(handler)

async def handle(message: AgentMessage, agent: AgentGatewayClient) -> None: ...

client.on_message(handle)

La fonction peut être async ou classique. Les messages sont traités un par un, dans l'ordre ; un message est acquitté quand la fonction se termine sans lever d'exception.

Appelé avec un identifiant d'utilisateur quand sa clé d'identité a changé (par exemple après une réinstallation de l'application). Informatif : le SDK continue de fonctionner et ne remplace jamais l'identité propre de l'agent.

Envoi

reply

await agent.reply(message, "C'est fait.", attachments=None)

Répond à un message dans sa conversation — ou son groupe — sur l'appareil qui l'a envoyé, en le liant au message d'origine. La façon recommandée de répondre.

send_message

await agent.send_message(
    conversation_id=message.conversation_id,
    to=message.from_id,
    text="C'est fait.",
    reply_to_message_id=message.id,   # facultatif, recommandé
    attachments=None,                 # facultatif, list[AgentAttachment]
)

Lève RuntimeError si l'agent n'est pas connecté. Passez to=f"group:{conversation_id}" pour écrire à tout un groupe.

Fichiers

Méthode	Description
`await send_file(conversation_id, to, name, data, mime=..., text="", reply_to_message_id=None)`	Chiffre, téléverse et envoie un fichier. Renvoie l'`AgentAttachment`.
`await send_media(conversation_id, to, name, data, mime, text="", width=None, height=None, duration_ms=None)`	Idem, avec des indications média.
`upload_file(name, data, mime=...)`	Chiffre et téléverse sans envoyer.
`await download_attachment(attachment)`	Télécharge un fichier reçu et le déchiffre localement. Renvoie des `bytes`. Voir Fichiers et médias.

Widgets

Chaque méthode prend conversation_id, to, title, et en option widget_id, body et expires_at (ISO 8601). Chacune renvoie l'identifiant du widget. Voir Widgets interactifs.

Méthode	Arguments spécifiques
`send_confirm_widget`	`danger`, `labels={"yes": …, "no": …}`, `response_mode`
`send_choice_widget`	`options=[{"id", "label"}]`, `multi=True`, `response_mode`
`send_permission_widget`	`scopes=["once", "session"]`
`send_form_widget`	`fields=[{"name", "label", "type", "required", …}]`, `submitLabel`
`send_datetime_widget`	`mode="date" \| "time" \| "datetime"`, `min`, `max`
`send_file_picker_widget`	`multiple`, `accept`, `max_files`
`send_progress_widget`	`value`, `max`, `cancellable`
`send_widget_update`	`ref`, `spec`, `expires_at` — met à jour un widget déjà envoyé

response_mode vaut "individual" ou "collective" — voir votes collectifs.

Types

AgentMessage

Une dataclass figée.

Champ	Type	Description
`id`	`str`	Identifiant du message.
`conversation_id`	`str`	Identifiant de la conversation.
`from_id`	`str`	Identifiant de l'expéditeur — à utiliser comme `to` pour répondre.
`from_device_id`	`str \| None`	Appareil de l'expéditeur.
`text`	`str`	Texte du message.
`reply_to_message_id`	`str \| None`	Le message auquel celui-ci répond.
`attachments`	`list[AgentAttachment] \| None`	Fichiers joints.
`widget_response`	`AgentWidgetResponse \| None`	Réponse à un widget : `ref`, `value`, `cancelled`, `id`.
`widget_update`	`AgentWidgetUpdate \| None`	Mise à jour d'un widget.
`encrypted`	`bool`	Le message était-il chiffré de bout en bout.

AgentAttachment

id, name, mime, size, blob_id, et en option width, height, duration_ms, ainsi que la clé du fichier key_b64 / iv_b64.

Autorisations

from pacerelle.permissions import PermissionPolicy, PermissionSession

Même contrat que la politique JavaScript : create_request, receive_response, run_authorized, create_widget_update, revoke, end_session, list_grants. Voir Autorisations.

Agent Connect

Fonctions serveur synchrones pour Agent Connect. Toutes acceptent un base_url facultatif.

Fonction	Renvoie
`begin_agent_connect(connect_key, client_id, redirect_uri, agent_name, agent_description="", state=None)`	`AgentConnectStart` — `authorization_url`, `state`, `code_verifier`, `request_id`, `expires_at`, `expires_in`
`exchange_agent_connect_code(code, code_verifier, client_id, redirect_uri)`	`AgentConnectInstallationToken` — `installation_token`, `agent_id`, `owner_id`, `conversation_id`, `scope`
`request_agent_runtime_token(installation_token)`	`AgentConnectRuntimeToken` — `agent_token`, `agent_id`, `owner_id`, `conversation_id`, `expires_in`