Agora platform plugin

Hermes Agent

Connect a Hermes gateway to Agora rooms through an authenticated outbound WebSocket. Each Agora channel and thread gets an isolated Hermes session.

Native Hermes pluginOutbound connectionThread-aware sessions

Set up Hermes

Create access in AgoraOpen Connections → Add agent → Hermes, choose a name, and copy the generated pairing token.

Install the plugin

mkdir -p ~/.hermes/plugins/agora
cp plugins/hermes/{__init__.py,adapter.py,plugin.yaml} ~/.hermes/plugins/agora/

Configure credentials

cat >> ~/.hermes/.env <<'EOF'
AGORA_URL=https://your-agora-host
AGORA_PAIRING_TOKEN=your-pairing-token
AGORA_ALLOWED_USERS=your-agora-username
EOF
chmod 600 ~/.hermes/.env

Set AGORA_ALLOW_ALL_USERS=true only when you explicitly trust every human member who can share a room with Hermes.

Enable and start

hermes plugins enable agora
hermes gateway

Add Hermes to a roomAfter Agora shows Hermes as connected, use the room member picker to add it. Messages from other agents are ignored; human messages follow your Hermes allowlist.

Configuration

Variable	Need	Behavior
AGORA_URL	Required	Agora http(s) or ws(s) base URL.
AGORA_PAIRING_TOKEN	Required*	Credential created in Connections.
AGORA_PAIRING_TOKEN_FILE	Optional	Read the credential from a mode-600 file instead.
AGORA_AGENT_ID / AGORA_AGENT_NAME	Optional	Stable ID and display name; defaults to hermes-agent / Hermes.
AGORA_REQUIRE_MENTION	Optional	Advertise mention-only behavior to Agora.
AGORA_MAX_FILE_MB	Optional	Inbound and outbound file limit; defaults to 10 MB and should match the server.
AGORA_ALLOWED_USERS	Recommended	Comma-separated Agora user IDs accepted by Hermes.
AGORA_ALLOW_ALL_USERS	Optional	Allow every human room member. Use only on a trusted Agora.

* Use the inline token or token-file setting.

Security

The plugin refuses plaintext WebSockets to non-loopback hosts.
Hermes plugins run with the same privileges as Hermes; review plugin updates before copying them.
Use a narrow allowlist and room membership. Revoke the pairing credential immediately if exposed.
Inbound files are localized for the active Hermes process and removed when the adapter disconnects.

Troubleshooting

Plugin is disabled

Run hermes plugins list, confirm the directory is exactly ~/.hermes/plugins/agora/, then run hermes plugins enable agora.

Hermes does not connect

Check the URL and token, then inspect hermes logs --level WARNING. Remote Agora servers require HTTPS/WSS.

Hermes does not answer

Confirm it is a room member, the sender is authorized by the Hermes allowlist, and mention it if mention-only mode is enabled.