Agentic Plane

The Agentic Plane lets an AI agent propose and execute platform operations under explicit, narrow, revocable authority. An agent is a first-class accountable actor, but it is never an independent source of permission. The governing rule is delegation, never impersonation.

Status: Partially implemented for local integration and not deployable through GitOps. Registry, Runtime, MCP Gateway, token exchange, delegated relationships, tool pipeline, HITL, and kill switch exist. Cross-replica execution leases, complete idempotency, policy/route deployment, provenance enforcement, sender-constrained tokens, and production failure testing remain open.

agentic_plane · lifecycle, delegated execution, human control

owner / approveragent identity & runtimeauthorization & identitytool execution / dataevents & audit

Components and ownership

Component	Owns	Stores	Status
Agent Registry (dx-agent-registry-go, host :8270)	Agents, versioned templates, ownership, lifecycle, credential binding, kill switch, delegation facade, activity view	PostgreSQL agentreg_db; Keycloak client reference; lifecycle outbox	Partially implemented
Agent Runtime (dx-agent-runtime-go, host :8290)	Sessions, transcripts, SSE, guardrails, planner loop, provider selection, token exchange, tool orchestration	PostgreSQL agentrt_db; Redis counters/hot state	Partially implemented
MCP Gateway (dx-mcp-gateway-go, host :8280)	Tool manifest, discovery, schema/scope/resource/risk controls, token vault, HITL parking, sole egress	Redis session/token/approval state	Partially implemented
Identity Provider	Agent/workload clients and RFC 8693 token exchange	Keycloak realm	Implemented for local flow
Policy Service	Agent delegation grants, validity, resources, scopes, revocation	PostgreSQL and outbox	Implemented locally
Authorization Service	User right ∩ agent delegated right ∩ context/trust decision	OpenFGA now; planned OPA composite policy	Partially implemented
API Gateway	Agent token validation, workload identity, kill-switch deny, agent rate limit, composite PEP, routing	Redis denylist mirror/rate counters	Partially implemented
Audit/Notifications	Durable activity and approval notifications	PostgreSQL/RabbitMQ/SMTP	Partially implemented

Agent identity and registration

An owner selects a certified template version and creates an agent record. A template defines persona, model/provider profile, maximum tool profile, and guardrails; it cannot grant resource permission. The Registry provisions a dedicated confidential identity-provider client and encrypts its secret at rest. The UI never receives the client secret.

The agent record moves through active, suspended, and retired. Suspension and retirement write a lifecycle event in the same transaction as the state change. The Gateway consumes the event into a denylist so a valid-but-still-live delegated token does not defeat the kill switch.

Templates and lifecycle

• Templates are immutable, versioned, reviewed artifacts.
• An agent pins the exact template version used at creation/session assembly.
• Tool visibility is the intersection of template ceiling and active delegation, never the union.
• Updating a template creates a new version; existing sessions do not silently change policy or model configuration.
• Retirement is permanent. Resume is allowed only from suspended state after ownership/administrative checks.

Delegated authority

The owner grants an agent specific operations/resources with expiry. The Policy Service stores the grant and publishes delegation.granted, updated, or revoked; the authorization projector writes agent ownership and delegated-resource relationships.

An agent action allows only when all stages allow:

authenticated user
AND authenticated runtime/MCP workloads
AND active agent
AND active, unexpired delegation
AND user has the requested resource permission
AND agent has the delegated resource permission
AND OPA contextual/tool/risk policy allows
AND every required obligation can be enforced

Delegation cannot create authority the user does not have. Losing the user's own right immediately invalidates the composite decision even if the delegation record remains.

Session and execution lifecycle

1. The authenticated owner creates a session for an active agent.
2. Runtime resolves the pinned agent/template and active grant using workload-authenticated internal calls.
3. Runtime exchanges the user's token for a short-lived delegated token where sub names the user and act.sub names the agent.
4. Runtime bootstraps MCP state, vaults the delegated token, and receives only tools visible under the template/delegation intersection.
5. A user message is appended to the durable transcript. A cross-replica lease must own the turn before execution; this is In development.
6. The LLM proposes a response or tool call. The proposal is untrusted input and cannot skip the MCP pipeline.
7. Tool results are provenance-labelled and size-bounded before re-entering the model. Complete prompt-injection controls remain In development.
8. The final answer and tool/approval outcomes are persisted and streamed over SSE.

Tool discovery and semantic firewall

The MCP Gateway's versioned manifest is the only tool vocabulary. Each tool declares a strict schema, required permission/scope, resource extraction, risk tier, exact upstream operation, response handling, and idempotency expectations.

Every invocation passes:

1. Tool visibility: the tool was present in the session's filtered catalogue.
2. Schema: unknown/missing fields and invalid types are rejected.
3. Scope/resource: current grant state covers the exact tool and target.
4. Authorization: the platform composite decision checks user, agent, context, and trust.
5. Risk: high-risk tools park for human approval.
6. Credential: the delegated token and workload credential attach only at the egress boundary; the model never handles them.
7. Sole egress: execution goes through the normal API Gateway and the same service operation policy as human traffic.
8. Output handling: the response is bounded, labelled as untrusted, and audited before the model sees it.

Human-in-the-loop approval

High-risk operations—such as a purchase or paid subscription—enter a durable approval state with action ID, owner, agent, session, exact tool and arguments, decision/grant references, expiry, and idempotency key. Only the owner or an explicitly authorized approver may approve or reject.

Approval executes the exact parked action, not a new model-generated variant. The side-effect owner stores the idempotency key and returns the original result on retry. Timeout and rejection cause no side effect. There is no auto-approve configuration.

Kill switch and revocation

Mechanism	Scope	Expected behavior
Token expiry	One delegated credential	Bounds exposure by a short lifetime
Grant revocation	Selected resources/operations	Removes delegated relationship; new decisions deny
Agent suspension	All agent activity	Gateway denylist blocks immediately within the published event SLO
Agent retirement	Permanent identity lifecycle	Disables future sessions/exchange and remains denied
Session cancellation	One execution	Cancels planner/tools and releases durable lease; reconciles uncertain side effects

Kill-switch and revocation paths must be measured under broker delay, cache, gateway restart, and multiple replicas. A missed lifecycle event triggers reconciliation; it never authorizes a new action.

Interaction with Control and Data Planes

• Agent registration, ownership, templates, delegations, token exchange, policy, credits, approvals, audit, and notifications use Control Plane services.
• Tools enter through the gateway and invoke the same Catalogue, Marketplace, Subscription, File, NGSI-LD, and OGC operations available to conventional clients.
• Data services receive the same carried decision/obligations plus agent/delegation context. They do not trust model rationale or tool names as authorization.
• A deployment without Agentic Plane services continues to operate; no core service depends on an agent component.

Threat model

Threat	Control	Remaining gap
Model requests out-of-scope tool	Filtered catalogue + scope/resource stage + platform authorization	Manifest/operation conformance automation
Prompt injection in resource/tool output	Sole ingress wrapping, provenance labels, size bounds, fixed system/policy instructions	Complete content-policy and red-team suite
Compromised Runtime	Destination-bound workload identity, Registry/MCP caller allowlists, active grant checks	Sender-constrained delegated token
Compromised MCP Gateway	Gateway workload identity, composite authorization, service ownership checks	Tool-call attestation and stronger isolation
Replayed approval/tool call	Stable action ID and side-effect-owner idempotency	Fleet-wide idempotency coverage and crash suite
Two replicas execute one turn	Durable session lease	Not yet implemented
Stolen delegated token	Short lifetime, vault encryption, audience/actor context, revocation/kill switch	DPoP or equivalent sender constraint
Redis loss	Deny/stop in-flight work; durable session/transcript recovery	Durable approval/token-vault topology decision
LLM provider outage	Bounded timeout, no tool execution without a completed proposal	Retry/cost SLO and fallback policy

Failure behavior and recovery

• Registry, grant, token-exchange, authorization, vault, or MCP bootstrap failure prevents session creation.
• A planner or tool timeout ends the bounded turn and persists an error; it never assumes a side effect failed.
• If execution outcome is uncertain, reconciliation queries the side-effect owner by idempotency key before retry.
• Redis loss invalidates in-flight sessions/approvals according to the selected durability mode; high-risk actions default to not executed.
• Broker delay may slow kill-switch propagation; Gateway restart rebuilds from durable agent state/denylist before accepting agent traffic.
• SSE disconnect does not cancel an already accepted turn unless the API explicitly requests cancellation; the session remains queryable.

Audit trail

Agent events include subject user, agent, runtime workload, MCP workload, delegation/grant, template version, model provider/model, session/turn, tool, normalized arguments hash, authorization decision, obligations, approval/action ID, approver, idempotency key, external side-effect reference, result classification, and timestamps. Prompt or result bodies are handled under retention and sensitivity policy rather than logged by default.

See Agent Delegation and Tool Execution for the end-to-end flow.