Building a Hermes Platform Adapter

A platform adapter translates between a messaging service and the Hermes gateway. The plugin path is the recommended default because it adds a platform without expanding core gateway conditionals.

Official documentation: https://hermes-agent.nousresearch.com/docs/developer-guide/adding-platform-adapters

Adapter responsibilities

An adapter extends the base platform interface, connects and disconnects cleanly, converts inbound events into common message events, sends outbound content, and reports chat information. Plugin registration can also declare authorization environment variables, message limits, platform hints, automatic configuration, cron delivery, and an out-of-process sender.

Persistent credentials need scoped locks so two profiles cannot connect with the same token. Webhook platforms should acknowledge inbound requests promptly and deliver the eventual agent response through the platform API rather than keeping a short callback open for a long agent run.

Adapter checklist

Prefer a plugin directory with metadata and a registration entry point.
Validate required configuration without printing tokens.
Normalize inbound user, chat, thread, and message identifiers.
Implement connect, disconnect, send, and chat-information behavior.
Add user authorization and allow-all controls.
Acquire and release a scoped credential lock.
Support cron delivery with a standalone sender when required.
Declare message length, platform hints, and setup fields.

Pitfalls

Holding a webhook request open while the model works.
Auto-enabling from one environment variable when several are required.
Supporting live gateway delivery but not out-of-process cron delivery.
Forgetting thread identity or platform message limits.
Adding a new adapter without comparing parity against a mature implementation.

Verification steps

Load the plugin with missing configuration and confirm a clear unavailable state.
Configure a test credential and verify one scoped connection.
Receive a harmless inbound message and inspect normalized identifiers.
Confirm authorization before agent creation.
Send a reply, including chunking if the platform has a limit.
Test a thread or topic when supported.
Run a standalone cron delivery test.
Compare code, docs, setup, toolsets, and tests against an established adapter.