Operate a Google Chat Gateway with Pub/Sub Controls

The Google Chat adapter uses Google Cloud services to carry Chat events to Hermes. A reliable setup is more than creating a bot: the Chat app, service account, Pub/Sub topic, subscription, IAM bindings, and Hermes authorization policy must agree.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/google_chat

Map the event path first

Google Chat publishes user activity into a Pub/Sub topic. A subscription makes those events available to the Hermes gateway, and a service account supplies the credentials used by the adapter. Diagram this path before changing IAM. It makes permission errors easier to isolate and discourages broad project-level roles that hide a missing resource-level binding.

Use a dedicated GCP project or clearly bounded existing project. Keep the service-account key outside the repository and public support artifacts. Where your operating environment supports keyless or managed identity, prefer that over a long-lived downloaded key.

Provisioning checklist

Create or select the intended GCP project.
Enable the Google Chat API and Pub/Sub API.
Create a dedicated service account for the gateway.
Create the documented Pub/Sub topic and subscription.
Grant the Chat publishing principal access to the topic.
Grant the Hermes runtime only the subscription permissions it needs.
Configure the Google Chat app to use the matching project resources.
Run hermes gateway setup and select Google Chat.
Configure an allowlist or pairing policy before inviting users.

Separate cloud readiness from agent readiness

A healthy subscription does not prove Hermes can answer, and a running gateway does not prove Google Chat can publish. Test each boundary independently: APIs enabled, IAM effective, subscription receiving, adapter consuming, sender authorized, model available, and response delivered.

For team spaces, decide whether the bot responds only when mentioned. Give scheduled reports a designated home channel instead of using the most recently active conversation. Keep high-risk tools out of shared-room sessions unless the room's authorization model and approval policy explicitly support them.

Common pitfalls

Granting a broad project role instead of the documented topic or subscription access.
Creating the Chat app and Pub/Sub resources in different projects by accident.
Treating a service-account JSON file as a normal project asset.
Forgetting that shared spaces can include users outside the original test group.
Assuming message receipt proves outbound replies and threads are mapped correctly.
Deleting an apparently idle subscription before checking whether the gateway uses it.

Verification steps

Confirm both required APIs are enabled in the selected project.
Publish or receive a test event and verify it reaches the intended subscription.
Start the gateway and confirm it consumes without repeated permission or acknowledgement errors.
Send a direct message from an allowed user and verify the reply returns to the correct conversation.
Test an unauthorized identity and a shared-space mention according to policy.
Restart the adapter, repeat one message, and confirm no duplicate reply is produced.
Review GCP audit logs and gateway logs for denied permissions, secret exposure, or unexpected principals.