Skip to content
roleALPHA Docs

AI Agents

Dependencies · Data Nodes

  • Links to: Competences (via AGENT_USES_COMPETENCE), Policies (via AGENT_BOUND_BY_POLICY), Value creation (via AGENT_SUPPORTS_PROCESS), Roles (via AGENT_FULFILLS_ROLE)
  • Linked from: Demands (via REQUESTS_MEMBER)

The “AI Agent” entity type manages a digital actor as a first-class node in the org graph. For the why, see AI Agents — Overview.

Purpose

Section titled “Purpose”

An agent carries a purpose, instructions (persona/system prompt), optional capabilities and a status (draft, active, retired). Its actual context, however, comes not from these fields but from its links in the graph.

Default view

Section titled “Default view”

Cards with name, purpose and status. Like all entity types, with drafts, visibility and audit history.

Key relationships

Section titled “Key relationships”

Four dedicated relationship types ground the agent:

  • AGENT_FULFILLS_ROLE (agent → role) — “fulfills role” / “is fulfilled by agent”
  • AGENT_SUPPORTS_PROCESS (agent → value stream) — “supports value stream”
  • AGENT_USES_COMPETENCE (agent → competence) — “uses competence”
  • AGENT_BOUND_BY_POLICY (agent → policy) — “bound by policy” / “binds agent” — the guardrail edge.

These types only come into existence once the agent module is active in your tenant — and each one additionally requires its counterpart to have a module: AGENT_SUPPORTS_PROCESS needs the value stream module, AGENT_USES_COMPETENCE the competence module. If a side is missing, the type simply is not there and is added by itself at the next activation.

Details: Relationship Types.

Step by step

Section titled “Step by step”
  1. Create an agent — in the “AI Agents” view click “New Agent”, enter purpose and instructions.
  2. Link — in the detail pane under “Relationships”, connect the agent to a role (AGENT_FULFILLS_ROLE), value streams, competences and binding policies (AGENT_BOUND_BY_POLICY).
  3. View context — the detail page shows, under Agent Context, the bundled result: split into Guardrails (binding policies) and Context (roles/value streams/competences).
  4. Retrieve over MCP — external agents and automations pull the same bundle via the MCP tool get_agent_context or GET /api/agents/{uuid}/context.

Example schema to copy

Section titled “Example schema to copy”
{
  "type": "object",
  "properties": {
    "purpose": { "type": "string", "title": "Purpose" },
    "instructions": { "type": "string", "title": "Instructions (persona)" },
    "capabilities": { "type": "string", "title": "Capabilities" },
    "status": { "type": "string", "title": "Status", "enum": ["draft", "active", "retired"] },
    "defaultModel": { "type": "string", "title": "Preferred model" }
  }
}

Schema option details: JSON Schema for Entity Types.

Limits: throughput and budget

Section titled “Limits: throughput and budget”

An AI agent is not an infinite employee. When demand planning is active for the tenant, the agent type therefore carries two more fields:

FieldWhat it limits
Weekly hoursThroughput — even with unlimited budget an agent only manages so much per period. Deliberately the same unit as for humans, so it is comparable with the demand.
Budget per periodMoney — every run costs tokens. A different currency, hence not converted into hours but shown alongside.

Both are commitments, not measurements: they say how much work and how much money the agent is entitled to — not what it could technically deliver. Just like a human: their capacity is in the contract, not on a stopwatch.

If either is missing, utilization shows “limit not recorded” — never an infinity sign. The difference between has no limit and we recorded no limit is exactly where planning goes wrong.

roleALPHA does not run agents. It describes them and supplies them with context; they run in your environment. Actual consumption arises there and cannot be measured here. If you want to put it side by side, report it from the agent runtime; without a report it says “consumption is not reported” — not zero. Zero would mean the agent consumed nothing, and roleALPHA does not know that.

More on this: AI agents have limits.

The context bundle

Section titled “The context bundle”

Every item in the bundle is self-describing: kind (role/value stream/competence/policy), binding (guardrail vs. informational), provenance (relationship type, direct/inherited), a version for policies and the sourceService. This means a consuming agent can never mistake a policy for mere context. The bundle also carries a contextVersion — a cheap change hash (see below).

Access for external agents (API key)

Section titled “Access for external agents (API key)”

So a real external agent can pull its context, each agent gets its own, individually revocable API keys under Agent access keys in the detail pane. The key is shown only once — copy it immediately.

The agent presents it as the header x-agent-key: agt_… (REST and MCP) and pulls only its own context:

  • REST: GET /api/agents/<uuid>/context (returns the canonical, unfiltered agent view)
  • MCP: tool get_agent_context against the agent MCP endpoint

The concrete, copyable REST and MCP URL for this specific agent is shown in the detail pane under Agent access keys → Connection (the host is deployment-dependent). Typical form:

  • REST: https://<host>/api/agents/<uuid>/context
  • MCP: https://<host>/mcp/agent/mcp

A key is bound to its agent — trying to pull another agent’s context with it is rejected with 403.

Detecting context changes

Section titled “Detecting context changes”
  • Pull (default): the agent pulls context before each run — always fresh.
  • Cheap check: GET /api/agents/<uuid>/context/version returns only the contextVersion. If it changes (new link, changed purpose), the agent re-pulls the full bundle.
  • Push (optional): register a URL under Context webhooks. On a change roleALPHA sends a signed notification (X-RA-Signature: sha256=…, HMAC over the body with the once-shown signing secret).

Debug pull (for administrators)

Section titled “Debug pull (for administrators)”

In expert mode the agent context section shows a Debug area with the raw JSON (copyable) and the contextVersion. Via “View as agent” an admin sees exactly the unfiltered bundle the agent itself would receive via its key.

rAlph

Section titled “rAlph”

The rAlph assistant can call get_agent_context itself once the tenant enables the AI Agents module in the AI settings (allowed_services) and the user has agent:read. To see exactly the unfiltered, external-agent view (the same as “View as agent” above) directly in the chat — instead of your own filtered view — use the dedicated /agent-context slash command (admins only).

Section titled “Related”