Mercurius Agents

An AI operations desk for an InterSystems IRIS integration team, built on IRIS AI Hub and
Interoperability. Your team defines the agents; each one works inside a real production
and acts only with a person’s approval.

The problem

An integration team’s knowledge drifts. A runbook still says partner orders arrive by SFTP
weeks after the team moved partners to a REST API. Alerts arrive faster than anyone
can rate them. Code reviews wait, and nobody knows what the AI tools cost.

A day with Mercurius

Agents are stored records, not generated classes. One runtime runs them all. Each agent has
its own instructions, model, permitted tools, private knowledge and memory.

No OpenAI key? The production still runs: each agent’s fallback rules decide, the run is
labelled Rules, not AI, and it goes to review.

How it works

File inbox or web UI -> DocumentIngress / AlertIngress / CodeIngress / ChatIngress (BS)
                   |
             AgentWorkflow (BP) -> AgentRunner (BO) -> AI Hub agent + permitted tools
                   |
          validated decision routes the message
                   |
      +------------+------------+
      v                         v
 ResultHandler (BO)        ReviewQueue (BO)

An invalid or failed reply never gets accepted: it goes to review.

What agents can do

Screenshots

Measured results

Mercurius.Test.Eval sends 55 labelled inputs through the production, with fresh sample
knowledge for each. On build 109, 2026-11-07 and 2026-11-08:

• Forge went from 12 to 14 of 15 once it could compile code with CheckSyntax. On gpt-4.1-mini it scored 9 to 11, so it uses gpt-4.1.
• Query got every answerable question right: all five generated queries were also checked by hand. Its misses were a guess on a vague question, and “clarify” instead of “refused” for another schema.
• The inputs were written by the author, and model output varies between runs. Treat these as a smoke test, not a benchmark.
• Costs come from list prices and count only the final model call of each run, so they’re lower bounds.
• Documenter: every conflict was caught in both runs. The two misses were the same both times: notes about failed-file handling and restore tests were judged unrelated to the runbook and backup policy, which is debatable. On gpt-4.1-mini it scored 12 to 15 of 15 depending on the run and the example notes, and sometimes missed the main demo conflict, so it uses gpt-4.1.
• Basic text search found the right note every time, so vector search isn’t needed at this size.

Run it yourself:

echo 'Do ##class(Mercurius.Test.Eval).Run() Halt' | docker compose exec -T iris iris session IRIS -U IRISAPP

Requirements

• Docker with Compose
• The AI Hub Community image, build 2027.1.0AI.109.0, from the
  EAP portal.
  It can’t be pulled from a registry, and this repo never publishes it.
• An OpenAI API key. Variable: OPENAI_API_KEY. The default model is gpt-4.1-mini.
• Optional: an Anthropic API key, ANTHROPIC_API_KEY. Each agent can then use a Claude model, chosen in the agent form.

Install

Load the image and give it the short tag used by the Dockerfile:

docker image load -i iris-community-2027.1.0AI.109.0-docker.tar.gz
docker tag docker.iscinternal.com/docker-intersystems/intersystems/iris-community:2027.1.0AI.109.0 iris-community:2027.1.0AI.109.0

Clone, add your key and start:

git clone https://github.com/xJuan21/mercurius-agents.git
cd mercurius-agents
cp .env.example .env      # then put your key in .env
docker compose up -d --build

The build compiles the code, seeds the sample agents and sets the production to start
with IRIS.

Install with IPM

On an IRIS AI Hub instance, build 2027.1.0AI.109.0:

zpm "install mercurius-agents"

This installs the backend: agents, production, API and sign-in. The web UI is built by Docker,
so use the Docker install above for the full app. IRIS needs OPENAI_API_KEY in its
environment.

Verify

docker compose ps                                                          # shows (healthy)
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:52775/mercurius/   # 200

Backend checks, no LLM needed:

echo 'zpm "mercurius-agents test -only" Halt' | docker compose exec -T iris iris session IRIS -U IRISAPP

This writes test records, and demo/run.sh resets them.

Sign in

Open http://localhost:52775/mercurius/ and sign in with an IRIS account. On a fresh local
build, that’s _SYSTEM with the image’s default password. To add a user, create it in the
portal and give it the MercuriusUser role.

Use it

To send the sample events through the file services instead:

./demo/run.sh

LLM judgment varies between runs. The Management Portal is at
http://localhost:52775/csp/sys/UtilHome.csp, and each decision links to its message trace.

Add an agent

Use Build an agent in the UI: no new class is needed. The runtime adds the reply format
from the agent’s decision values. To drive an agent from a file service too, add a Business
Service item and set its AgentName setting.

Web UI

The UI is an Angular app in web/, built in a separate Docker stage. IRIS serves the output.

Sign-in uses the JWT support built into IRIS REST web applications. IRIS checks the password
and provides /login, /refresh and /logout. The access token stays in memory, and the
refresh token stays in sessionStorage, so it ends with the browser tab.

Contest bonuses

Credits

Copyright (c) 2026 Juan Mota Sanchez. Released under the MIT License.

Forge’s review checklist comes from the objectscript-review skill in
iris-agentic-dev (InterSystems,
MIT License). Built on the ai-hub-dev-template.

Why not EnsLib.AI.Agent.PassthroughOperation?

IRIS ships an experimental operation and adapter for calling an agent from a production.
We tested them on build 109 and kept our own AgentRunner operation.

Subclassing the adapter and using its OnAfterAgentInit hook does give per-agent tools,
so it’s a possible later direction once the classes are no longer experimental.

Security

• The runtime binds each tool to its agent, so the LLM never supplies the agent’s identity.
• Mercurius.Runtime.ToolPolicy checks every tool against the agent’s grants, and
  ungranted tools aren’t shown to the LLM.
• KnowledgeService enforces ownership, so relationships can’t cross agents.
• Every tool call is audited in Mercurius.Model.AgentToolCall.
• Agents get no SQL, filesystem or shell tools.
• The API requires a token, and users need the MercuriusAccess resource. /mercurius/ serves only the built web files.
• Use HTTPS or a private network: passwords are sent at sign-in.

Gotchas found on build 109

Known limitations

• Knowledge search is basic text matching, so related notes can be missed.
• A conflict is an AI finding, not a verified fact.
• Approved notifications go to the in-app inbox. To deliver them elsewhere, point the NotifyTarget setting of ActionIngress at another operation.
• An LLM call that hangs has no timeout of its own.
• API keys are redacted from stored errors. Other sensitive text in an error is not.
• Chat shows decisions, not free conversation.
• Agents can be disabled but not deleted from the UI.
• AI Hub is pre-release software.