Référence
SDK Python
Référence complète du paquet pacerelle — options du client, méthodes, types de messages et fonctions Agent Connect.
pip install --pre pacerelleNécessite CPython 3.12. Les wheels embarquent la bibliothèque de chiffrement native pour Windows x64/ARM64, Linux x64/ARM64 et macOS ARM64.
from pacerelle import AgentGatewayClientLe 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_idstrrequistokenstrrequise2eeboolFalse par défaut — mettez toujours True hors débogage local.store_rootstr | PathLike~/.myagents ; l'état se trouve dans <store_root>/<agent_id>/signal.db.base_urlstrhttps://api.pacerelle.com.ws_urlstrbase_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.
on_identity_changed(handler)
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, PermissionSessionMê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 |