Connect Hermes as a shared agent

How it works

A shared agent is a Hermes profile that any member of your workspace can hand work to in a Room. Members @-mention the agent, and ArtifactBridge sends the message to Hermes as an A2A task. While Hermes works on the task, the ArtifactBridge plugin lets it read the brief, the Room and the documents in scope, post messages, upload images, create documents and propose changes. Everything it posts appears under the agent's name. When Hermes finishes, its final A2A reply becomes the one task result in the Room.

1. ArtifactBridge calls HermesArtifactBridge sends the task over A2A to the HTTPS address you register, with the bearer token you choose for that endpoint.
2. Hermes calls ArtifactBridgeDuring the task, the plugin sends each tool call to the ArtifactBridge tools URL with the agent credential and that task's delegation token. ArtifactBridge checks every call against the task's Room and scope.
3. Hermes repliesThe final A2A reply completes the task. A message the agent posts in the Room does not.

Four different secrets appear in this setup. Keep them apart:

• Agent credential (agw_…). ArtifactBridge shows it once when you add the agent. The plugin reads it from ARTIFACTBRIDGE_SERVICE_CREDENTIAL in the serving profile. It is the only setting the plugin requires.
• A2A bearer token. A secret you make up. Hermes checks it on every inbound A2A request, and ArtifactBridge stores it encrypted and sends it with each task.
• Delegation token (dlt_…). ArtifactBridge puts a new one in the text of each task. The model passes it to the plugin's tools. On its own it grants nothing.
• Personal API token (afb_…). Used by a personal MCP connection to /mcp. The shared agent does not use one; keep it out of the serving profile.

The plugin is a proof of concept. It was tested with Hermes Agent 0.21.3. Read Known limits before you offer the agent to your workspace.

Create a serving profile

Serve shared work from its own Hermes profile. A profile has its own config.yaml, .env, memory, skills and sessions, so every setting below applies to that profile only. The examples call it ab-shared; any name works.

hermes profile create ab-shared

Hermes documents profiles in Profiles ↗.

Expose Hermes over A2A

Hermes ships an A2A platform. ArtifactBridge runs in the cloud, so it must be able to reach the profile's A2A endpoint over HTTPS on a public host name.

1. 01 / ENABLE

   Turn on the A2A platform in the profile's config

   The gateway starts A2A for a profile only when its config enables the platform. A peer token does not turn it on, and hermes gateway setup does not either.

   hermes -p ab-shared config set gateway.platforms.a2a.enabled true

   Copy

   Hermes may report that it saved the key as platforms.a2a.enabled. That is expected.

   A2A listens on port 9900 by default. If another profile on this host already serves A2A, give this profile its own port:

   hermes -p ab-shared config set gateway.platforms.a2a.extra.port 9901

   Copy

   Route your HTTPS proxy to the port you choose.

2. 02 / CONFIGURE

   Add the A2A settings to the profile's .env

   Add values like these. Use a long random token; you enter the same token in ArtifactBridge later.

   ~/.hermes/profiles/ab-shared/.env

   A2A_PEER_TOKENS=artifactbridge:<long random token>
   A2A_PUBLIC_URL=https://hermes.example.com
   A2A_REPLY_TIMEOUT=1800

   Copy

   Replace the token, the host name and the timeout with your own values.

   A2A_PUBLIC_URL is the public HTTPS origin that Hermes advertises on its Agent Card. It must be the same origin you register in ArtifactBridge, or validation fails. A2A_REPLY_TIMEOUT is how many seconds Hermes waits for the agent's reply; the default is 300. Set it to cover the longest task you intend to serve. ArtifactBridge sets no time limit of its own on a task the agent confirms it is running.

3. 03 / HTTPS

   Put HTTPS in front of the port

   Hermes serves plain HTTP on its A2A port (9900 unless you set another). Route your public HTTPS host name to that port through a reverse proxy or tunnel that terminates TLS. If the proxy runs on the same host, keep the default bind address, 127.0.0.1. If it runs on another machine, also set A2A_HOST (for example 0.0.0.0); Hermes widens the bind only when a token is set. Never route public traffic to a profile without a token: in that mode Hermes accepts every caller that reaches it.

4. 04 / CHECK

   Restart and check the Agent Card from outside

   Restart the gateway that serves the profile (see Restart the serving gateway). From another network, open the card in a browser. It must load over HTTPS and name your public address. This URL is only for the check; ArtifactBridge takes the origin instead (see the next section).

   Agent Card (browser check)

   https://hermes.example.com/.well-known/agent-card.json

   Copy

   Replace the host name with yours.

Hermes documents every A2A setting in A2A (Agent-to-Agent) ↗. A2A_TRUSTED_PEERS=artifactbridge limits tasks to the ArtifactBridge peer token if the profile also has other peers.

Add Hermes in Agent Sharing

Agent Sharing appears in Settings only in workspaces where it is turned on. If you do not see it, contact support@omnim.ai.

1. Open Settings → Agent SharingSelect Add agent.
2. Describe the agentEnter the Agent name (the name members see and @-mention in Rooms), a Description, and, in the Agent Card URL field, the public origin only: https://hermes.example.com/. ArtifactBridge adds .well-known/agent-card.json itself, so a full card path fails validation. Keep the Concurrency limit at 1 unless the host can run several tasks at once; extra tasks queue.
3. Set AuthenticationChoose Bearer token (stored encrypted) and enter the token from A2A_PEER_TOKENS, without the artifactbridge: prefix.
4. Validate and publishSelect Validate & publish. ArtifactBridge fetches the card and checks the endpoint. If it cannot, the Agent Card URL field shows why. Publishing lets every workspace member delegate to the agent.
5. Keep the Agent credentialThe Agent published dialog shows the Agent credential once. Copy it straight into the plugin setup in the next section. Never paste it into a chat, a Room or a ticket. The Bootstrap URL in the same dialog is for runtimes that do not use this plugin; you can ignore it.

If you lose the credential, use Rotate credential… on the agent's row, then update the serving profile. The owner who added the agent and workspace admins can manage it; other members see View only. More detail is in Connect an external A2A service.

Install the plugin

Run these on the Hermes host, against the serving profile. Pin the install to a full 40-character commit SHA from omnim-ai/hermes-artifactbridge ↗. The commands use ca23216e9b011d32a4ef40647b14868ab55d1811, the latest published commit when this guide was written.

1. 01 / INSTALL

   Install without enabling

   hermes -p ab-shared plugins install omnim-ai/hermes-artifactbridge --ref ca23216e9b011d32a4ef40647b14868ab55d1811 --no-enable

   Copy

   Hermes also installs the plugin's Python dependencies.

   Hermes warns that this is a custom (unreviewed) source, not from the Hermes catalog. That is expected for a GitHub install, and the install continues.

2. 02 / ENABLE

   Enable it and enter the credential

   Hermes asks for ARTIFACTBRIDGE_SERVICE_CREDENTIAL and saves it in the profile's .env. Paste the Agent credential at that prompt only.

   hermes -p ab-shared plugins enable hermes-artifactbridge

   Copy

   The credential stays in the serving profile.

3. 03 / CHECK

   Check the install

   hermes -p ab-shared plugins doctor hermes-artifactbridge --ci

   Copy

   Exits non-zero when validation reports an error.

4. 04 / RESTART

   Restart the serving gateway

   The running gateway loads the plugin and the credential only when it starts. See Restart the serving gateway.

The plugin sends tool calls to https://app.artifactbridge.com/mcp/agent-gateway by default, so production needs no other setting. For a self-hosted deployment, set ARTIFACTBRIDGE_TOOLS_URL in the profile's .env to that deployment's HTTPS tools URL. An empty or invalid value does not fall back to production: the plugin hides its tools instead. Remove the variable to use production again.

Update the plugin

A pinned install stays on its commit, and hermes plugins update refuses to move it. Move the pin by reinstalling at the new commit:

hermes -p ab-shared plugins install omnim-ai/hermes-artifactbridge --force --ref <new 40-character commit SHA>

An install made without --ref updates in place with hermes -p ab-shared plugins update hermes-artifactbridge. After either update, run plugins enable again if the plugin shows as disabled, then restart the serving gateway. Removing the plugin does not revoke the agent: disable it or rotate its credential in Agent Sharing.

Restart the serving gateway

Hermes reads .env, plugins and A2A settings when the gateway starts. After any change in this guide, restart the gateway process that actually serves the profile. Check which gateway that is:

hermes -p ab-shared gateway status

• A shared gateway serves the profile. When the default profile's gateway serves every profile on the host, restart it with hermes gateway restart. Every profile it serves reconnects. In this arrangement hermes -p ab-shared gateway restart refuses with exit code 78.
• The profile runs its own gateway. Restart only that gateway with hermes -p ab-shared gateway restart.

Hermes explains both arrangements in Running Many Gateways at Once ↗. Hermes keeps running A2A tasks in memory, so a restart during a task loses it. See Known limits.

Run a first task

Start with a task that stays inside one Room. Open a Room you can use for testing and send this message, with your agent's name in place of @Hermes:

@Hermes Read the brief and this Room. Post a one-line acknowledgment in the Room, then finish with a two-sentence summary of what this Room is about.

1. Watch the Delegations panelStock Hermes answers the A2A request only when the agent finishes. Until then the delegation can show Status unknown or Delivery uncertain, even while Hermes works normally. It can change to Working after a status check, or go straight to done. These labels mean that ArtifactBridge cannot confirm the task's state. Neither label, nor the time the task has taken, shows that the task is lost; Known limits names the one sign that it is.
2. Look for the acknowledgmentIt appears in the Room under the agent's name. This proves the plugin, the credential and the tools URL work.
3. Look for the task resultThe summary arrives as the one task result and the delegation shows done. This proves the A2A reply path works.

To test images as well, ask for one in the same way, for example: "Make a small image that sums up this Room, upload it, and post it in the Room." The plugin accepts PNG, JPEG, WebP or GIF up to 3 MiB and returns Markdown that the agent posts in its message. This needs a Hermes profile that can make images.

Troubleshooting

• Hermes says the plugin is already installed. Do not install again. For a pinned install, use the --force --ref command under Update the plugin. For an unpinned install, use plugins update. Then enable it if it is disabled.
• Validate & publish fails. Check that the Agent Card URL field holds the origin, for example https://hermes.example.com/, not the full card path. Open the card from outside your network. If it does not load, check that the profile's config enables A2A (step 01 under Expose Hermes over A2A), that HTTPS works, that the proxy reaches the Hermes port (set A2A_HOST when the proxy is on another machine), and that A2A_PUBLIC_URL is the same origin you registered.
• Hermes rejects the task as unauthorized (401). The bearer token in Agent Sharing does not match A2A_PEER_TOKENS in the serving profile. Use Change endpoint… on the agent's row to replace the token.
• The agent has no ArtifactBridge tools, or they return not_configured. ARTIFACTBRIDGE_SERVICE_CREDENTIAL is missing from the serving profile, or ARTIFACTBRIDGE_TOOLS_URL is present but empty or invalid. Fix the value in that profile's .env, not in your shell or another profile, then restart the serving gateway.
• A change seems to have no effect. The gateway that serves the profile was not restarted, or you restarted a different one. The Hermes dashboard can show old state after a restart; check the gateway itself, for example by opening the Agent Card URL.
• The task fails after about five minutes. One possible cause is A2A_REPLY_TIMEOUT (default 300 seconds): when it passes, Hermes stops waiting for the agent's reply and reports the task as failed. If the task needs longer, raise it in the serving profile and restart.
• The delegation shows Status unknown or Delivery uncertain. ArtifactBridge cannot confirm the task's state. With stock Hermes this is normal while the agent works, and it also appears when Hermes cannot be reached. Nothing is resent, and Reconcile asks Hermes again. The label does not show that the task is lost; see Known limits.
• A tool returns credential_revoked or delegation_not_active. The task was cancelled, failed or closed in ArtifactBridge. The agent should stop; start a new task if needed.
• Sign-in fails with invalid_redirect_uri. That error comes from the personal MCP sign-in, not from this setup. The shared agent never signs in through the browser. See Connect your AI tools: Hermes.

Known limits

This is a proof of concept on stock Hermes A2A. These notes describe how it behaves today. They are not a security guarantee.

• Reply timeout. When A2A_REPLY_TIMEOUT passes, Hermes reports the task as failed while the agent keeps running. ArtifactBridge then revokes the task's access, so the agent's next tool call is refused.
• Cancel. Cancelling is your decision to abandon the work. ArtifactBridge revokes the task's access at once and asks Hermes to cancel. A cancel does not show that Hermes stopped: the Hermes turn can keep running, but it cannot act in ArtifactBridge.
• Restart. Hermes keeps A2A tasks in memory, so a restart during a task loses it. ArtifactBridge does not fail the delegation and sets no time limit: it keeps the slot and shows Status unknown or Delivery uncertain, the same labels it shows while it cannot confirm a running task. Positive evidence that Hermes no longer has the task is Status unknown with task_not_found in its Details note: Hermes answered that it holds no such task. Only then is it safe to cancel and delegate the work again.
• Questions. A question the agent posts in the Room through the plugin is a Room message: the task keeps running and does not wait for an answer. The task waits for input only when the agent's reply starts with [INPUT_REQUIRED]. Hermes then marks the A2A task as needing input, and ArtifactBridge posts the question in the Room. After a Room participant answers, the task resumes as a new Hermes task with a new delegation token.
• Delegation token. The token is part of the task text, so the model sees it, and Hermes stores it in its sessions and A2A audit log. Anyone who holds both the token and the Agent credential can act within that task's scope until it ends. Limit who can read the serving profile's files on the host.
• Host trust. The plugin does not stop the serving profile from reading other secrets on the host or making its own network calls. Run it on a host and profile you trust. ArtifactBridge still enforces the task's scope, the task state, and human approval of every proposed change.