Connect Hermes as a shared agent

How it works

A shared agent is a Hermes profile that members of your workspace can hand work to in a Room, once you share it with them. 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.

Hermes and Executors

Outside the pooled rollout: this guide's service credential, per-agent concurrency, optional per-task Space, and legacy restart instructions describe the retained original-agent endpoint. They are not a pooled cloud enrollment or compatibility certificate. In the prerelease pool, identities are created in the rail Agents view; only admins add cloud runners in Settings → Executors. Any current admin manages any workspace-owned runner. See the rollout distinction.

Settings → Executors lists cloud runners only. It no longer offers Share an agent, so a new Hermes endpoint cannot be added there. To run Hermes for pooled tasks, connect its listener as a cloud runner: see Connect a cloud runner. The plugin steps below apply to a Hermes service that is already registered and has its Agent key.

The Agent Card URL of a registered Hermes service is the public origin only: https://hermes.example.com/. ArtifactBridge adds .well-known/agent-card.json itself. It must be the same origin as A2A_PUBLIC_URL in Expose Hermes over A2A.

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 released commit 036c1cb1671673e6c81a987c56ca844453b9ef5f.

1. 01 / INSTALL

   Install without enabling

   hermes -p ab-shared plugins install omnim-ai/hermes-artifactbridge --ref 036c1cb1671673e6c81a987c56ca844453b9ef5f --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 036c1cb1671673e6c81a987c56ca844453b9ef5f

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: pause it or replace its key in Executors.

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 Rechecking or Delivery uncertain, even while Hermes works normally. It can change to Running after a status check, or go straight to Answered. 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. A Hermes agent that works in a Room through the artifactbridge CLI, not through a delegation, shares an image file from its computer with artifactbridge rooms upload-image --room ROOM_ID PATH instead of sending the image as base64.

Tasks that come with a Space

Pooled cloud tasks differ: the agent has one fixed Space, with no per-task override. Initial cloud tasks require the six supported cloud capabilities, not same_session_continuation, plus current connection proof and explicit admin open-pool consent. The plugin pin in the legacy instructions below is not proof of pooled readiness. If a pooled cloud task needs an answer, including after a Space read fails, its informational question and Failed outcome are persisted together. The original task will not resume. Send a new request with your answer and needed context; there is no automatic resend, Resume, or replacement session. A failed or unconfirmed Room post must never be described as posted. Details retain the question when authorized and available, or state that it is unavailable. Closed Rooms and revoked access do not allow a fallback post. Computers retain same-session continuation. AI-4105 is future cloud support, not a release prerequisite or authorization. See pooled task behavior.

Prerelease: a pooled task in a Room with a space. The task keeps the agent's fixed space and the Room's space, both pinned when the task is accepted. In the task's Details each space has its own line, with its role, and is named only to people who can open it; see how the two spaces are shown. A task in a Room without a space keeps its one Uses Space line.

A member can attach one Space to a task for the agent: with Add a Space in the Room composer after they @-mention the agent, or with space_id on artifactbridge_delegate_to_gateway_service. The Space is optional and picked for each task. There is no Room or agent default. It stays the same for the whole task, also after an answer to the agent's question. A task without a Space works as before.

• The sender is told. When the sender picks a Space, the composer shows, for example: Hermes runs in the cloud and reads Marketing with your access, private documents included. Results post to this Room.
• The agent reads with the sender's access, live. It sees what the sender sees in the Space at the moment of each read, private documents included, and nothing the sender cannot see. The Space adds to the documents the task can read without it. It grants no write: the agent proposes changes only to the documents the task lists for that. A synced document that the Space reaches opens from its cached copy, read-only; the agent cannot refresh it or propose a change to it.
• Skills load when they match. The agent reads the Space's overview and description first, pages through all of its skills, and loads each skill that matches the task at its current version. Nothing is installed on the Hermes host.
• The Space is named only to people who can open it. The task in the Room shows Uses Space Marketing, with a link, to each member who can open the Space now. Everyone else, and everyone after the Space is deleted, sees Uses a Space you can't open. The task's brief names the Space only while the sender can still open it: This task comes with the Space "Marketing". After that it says This task comes with a Space.
• Content leaves ArtifactBridge. What the agent reads reaches the Hermes host, where Hermes keeps it in its sessions, and the agent can quote it in the Room. There is no sandbox. When the sender later loses access, new reads stop, but content that was already delivered cannot be recalled. There is no erasure guarantee.

The Space tools

The agent reads the Space with two plugin tools, artifactbridge_read_space_context and artifactbridge_read_skill. They need the released plugin pin 036c1cb1671673e6c81a987c56ca844453b9ef5f (see Install the plugin). ArtifactBridge offers the tools only for a task that comes with a Space. They read; neither one changes a Space or a skill.

• Arguments. artifactbridge_read_space_context takes the task's delegation_token and optional delegation_id (default: this task), space_id (default: the task's Space; another Space is refused with space_out_of_scope), limit (1 to 100, default 50), cursor and include_archived (default false). artifactbridge_read_skill takes delegation_token, the skill's slug, optional delegation_id, and version_policy: registered (the default) or current. The brief tells the agent to use current for a skill the Space lists.
• Transport. The plugin sends each call to the tools URL with the Agent credential that it holds. It takes the delegation_token that the agent passes out of the tool arguments and sends it in the x-artifactbridge-delegation-token header. It never uses a personal /mcp connection. Never paste either secret into a Room, a ticket or an example.
• Answers. The plugin passes each answer and error through unchanged, including page cursors. It does not retry a refused call.

The brief of every task with a Space contains this line: If you can't read the Space, or you don't have artifactbridge_read_space_context, say in the Room that you can't load the Space and ask what to do. Don't carry on as if you had read it. An agent on an older plugin therefore reports that it cannot load the Space; it does not work on without it. ArtifactBridge does not detect the plugin version and does not install or update the plugin for you.

When the Space is deleted, the sender can no longer open it, or Spaces is turned off during a task, the next Space read answers space_unavailable: Space unavailable. Tell the person who sent this task, and ask what to do. Documents that the task reached only through the Space stop being readable at the same time. The agent asks in the Room (a reply that starts with [INPUT_REQUIRED]), for example: I can't load the Space for this task anymore, so I've stopped. Should I carry on without it? It never falls back to a folder. The answer resumes the task with the same Space.

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 Executors 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 Rechecking 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 canceled, failed or closed in ArtifactBridge. The agent should stop; start a new task if needed.
• The agent says that it cannot load the Space. Either the plugin does not have the Space tools (see The Space tools), or a read answered space_unavailable because the Space was deleted, the sender can no longer open it, or Spaces is off for the workspace. Answer the agent's question in the Room: tell it how to continue, or cancel the task.
• 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. Canceling 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 Rechecking 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 Rechecking 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. This applies to an agent that you add on this page. A prerelease agent with a fixed Space that runs on a Hermes cloud runner does not resume after a question: the task ends as failed, and the sender sends the task again as a new request (see Delegate work to an external service).
• 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.