AI agent (Claude with tools)

How the in-app /admin/ai chat and its underlying API read and mutate Atrium state via role-tiered tool calls, with a confirm-card audit gate on every mutation.

The Atrium AI exists in three places that share one tool catalog:

There is also an MCP endpoint that exposes the same catalog, role-tier-filtered, over JSON-RPC for Claude Desktop and ChatGPT.

This page is about the agent surfaces.

The tier tables are not the permission model

Read this before the tables below, because taking them as an access-control reference will mislead you.

RBAC here is two layers, and both are load-bearing:

1. minRole is a coarse catalog filter. It decides which tools the MCP server lists for a caller. Omitting it defaults the tool to super-admin.
2. A per-resource check inside the executor is the real gate: app-ownership and group-ownership asserts, top-level-group creation rules, and field-tier filtering on patches.

Layer 2 exists because Atrium's real permission model is (role tier x ownership of this specific app or group x field tier), which a single minRole cannot express. A tool an app owner may use on their own app therefore carries minRole: 'user' plus an ownership assert. The floor is deliberately low and the executor is the real gate, exactly as the matching REST route does it.

Concretely: delete_app sits in the user tier. That does not mean any signed-in user can delete any app. It means the catalog filter lets the tool through, and the executor then refuses unless you own that specific app. Likewise update_app drops any field above your tier before writing, and refuses outright if nothing survives the filter; get_group resolves the group first and then asserts ownership, so a name lookup cannot be used to probe the group namespace.

Some tools narrow instead of refusing. A non-DISCOVERABLE app raises not-found rather than forbidden for get_app, so the existence of a slug is not confirmed to someone who should not see it.

Tool catalog

86 tools today. mutates marks the ones that require confirmation.

User tier

Visible to any caller with a valid Atrium session or personal key. Most of these carry an ownership assert in the executor; see the section above.

Extra guardrails worth knowing: create_atrium_group gates on a top-level-group rule rather than a flat role, and records a non-admin creator as the group's owner. update_group_metadata additionally makes tags admin-only, refuses to set kind to DEPARTMENT, and refuses to edit a group that already is one.

Admin tier

Super-admin tier

These four declare no minRole at all and fall through to the super-admin default, which is applied by the MCP server rather than by the tool definition.

script_author is a legal tier value but no tool currently uses it.

The criterion for adding a tool: it should be a single administrative operation mapping cleanly onto a service-layer function. Tools delegate to the same code path the route handlers use, so adding a field to an app patch schema reaches both the REST route and update_app. The services themselves do not check auth; that is the tool layer's job and the route handlers' job.

The protocol: confirm-card on mutations

Every mutation creates an AtriumAiAuditLog row in REJECTED state at proposal time. Approval flips it to EXECUTED. The server never trusts the client to echo the tool input back unchanged: the confirm path loads the stored input from the audit row, so the user approves the exact bytes that ran.

Confirmation goes back to the same path; there is no /confirm sub-route (every guess at one — /agent/confirm, /ai/confirm, /agent/execute — is a 404, and an API caller who guessed concluded the agent was read-only). So the pending response carries a confirm block holding the literal follow-up request: { method, path, body }, where body is POSTable verbatim. prompt is optional on that call — the confirm branch never reaches the model.

The confirm branch also checks that the audit row belongs to the caller (403 otherwise), that it has not already executed (409), and that the tool name matches (400).

Confirming is the same route, not a sub-route. There is no /agent/confirm; every guess at one answers 404. So the pending payload ships the instruction with it — pendingToolCall.confirm is a ready-made { method, path, body } an API caller POSTs back verbatim. Two consequences worth stating, because an API caller who missed them concluded the agent was read-only over the API (2026-08-21):

• A confirm turn is stateless. It needs no history and no memory of the planning turn: the stored input on the audit row is what executes, so an echoed toolInput changes nothing. (The agent route keeps no server-side conversation state at all — a plain follow-up turn must re-send history.)
• The tool that proposed the call is the tool that runs. Editing the proposal means asking for a new one, not confirming this one.

AtriumAiAuditLog rows surface every call:

• EXECUTED: a read tool ran, or a mutation was confirmed and ran.
• REJECTED: a mutation was proposed but never confirmed.
• ERROR: an exception was thrown during execution; errorMessage populated.

The MCP endpoint reuses the same table but stamps conversationId = "mcp:<apiKeyId>", so MCP-driven calls are filterable from the in-app flow.

Read-tool results are fed back on the tool role rather than as free-text user input, so a hostile result body containing something like "ignore previous instructions" is not read by the model as an instruction from the user. The loop is capped at 10 iterations and one tool call per turn.

Try it from the CLI

Mint an API key at /admin/api-keys, then:

TOKEN="atr_live_..."

# Ask a question. The agent calls read tools as needed.
curl -X POST -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     https://atrium.ommax-intelligence.de/api/admin/actions/ai/agent \
     -d '{
       "conversationId": "demo-001",
       "prompt": "How many shared-credential apps do we have, and who owns Oxylabs?"
     }'
# → { type: "text", text: "There are 5 shared-credential apps..." }

# Propose a mutation. The server returns pending and NEVER executes.
curl -X POST -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     https://atrium.ommax-intelligence.de/api/admin/actions/ai/agent \
     -d '{
       "conversationId": "demo-001",
       "prompt": "Create an Atrium group called Sales Engineering."
     }'
# → { type: "pending_tool_call",
#     pendingToolCall: { auditLogId: "cmp...", toolName: "create_atrium_group",
#                        toolInput: { name: "Sales Engineering" }, ... },
#     confirm: { method: "POST", path: "/api/admin/actions/ai/agent",
#                body: { conversationId: "demo-001", confirmation: {...} } } }

# Confirm: POST `confirm.body` back, unchanged. The server loads toolInput
# from the audit row, so your echo of it is ignored either way.
curl -X POST -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     https://atrium.ommax-intelligence.de/api/admin/actions/ai/agent \
     -d '{
       "conversationId": "demo-001",
       "confirmation": {
         "toolName": "create_atrium_group",
         "toolInput": { "name": "Sales Engineering" },
         "auditLogId": "cmp..."
       }
     }'
# → { type: "tool_result", toolName: "create_atrium_group", result: { id, name, ... } }

Why the agent is lean

The /ask chat preloads the directory, secret names, action templates and example scripts into the system prompt. That is useful for thinking-partner answers but costs roughly 30k to 60k tokens per turn. The agent path builds a slim context instead and tells Claude to call tools to find directory state. Every turn fits comfortably under the gateway's per-key rate ceiling, and the agent learns actual current state rather than a snapshot baked into the prompt.

The trade-off: broad questions ("describe every app") cost more model iterations. Specific questions are fast.

Permission model

The agent route is gated by super-admin, via session or bearer key. That has not changed now that scoped API keys exist: scoped keys carry no roles, so they cannot reach this route at all, and the gate did not widen when they landed.

So on the agent surfaces you see the whole catalog, because only super-admins get in. MCP is the surface where the tier filter is actually observable: a regular user's key sees the user-tier slice, an admin key adds the curation surface. The MCP server re-checks the tier at call time as well as at list time, so a client cannot invoke a tool name it discovered elsewhere.

The route also returns 503 when the model gateway is unconfigured and 502 on an upstream failure, rather than surfacing a partial result.

The audit log is queryable by user, status and kind. A UI panel is queued; for now go directly:

SELECT "toolName", "status", "durationMs", "createdAt", "errorMessage"
FROM "AtriumAiAuditLog"
WHERE "userId" = '<zitadel sub>'
ORDER BY "createdAt" DESC
LIMIT 50;