Skip to content

ADR-0008: Managed Definitions and the Governed Chat Surface

Target architecture — not the current operating contract

This decision records the implemented boundary for Mission-Control-managed definitions and the AG-UI chat surface. Use Current release for operating procedures.

Partially superseded

ADR-0010 replaced this record's Run lifecycle, managed per-run key, chat-token, /apps/v1, and Run-visibility decisions. Managed drafts, versions, publications, local transcripts, approvals, and the private stateless runtime remain accepted.

Status

Accepted — 2026-08-27

Context

ADR-0007 reduced external runtime identity to Agent, environment, and Agent key, and reserved Mission-Control-managed authoring for a separate design. Organizations also need agents that Mission Control itself executes: an agent manager writes instructions, picks a governed virtual model and Connector tools, tests the draft, publishes it, and lets members or customer frontends chat with it — without any component gaining direct provider or MCP access.

Decision

  • A managed definition belongs to exactly one existing Agent identity and consists of instructions, one virtual model resource, and a tool allowlist. It has one mutable draft per Agent and immutable, numbered versions created only by Publish. A publication points one environment at one version; Publish again is rollback and Unpublish is containment.
  • Every chat run is an ordinary Run started with a managed Agent key (agent_key.kind = managed, 15-minute expiry, scope equal to the definition's model and tools from current grants). The gateway owns transcripts and the Run lifecycle; the private PydanticAI runtime is stateless and reaches models and tools only through the Model and MCP Gateways with that key.
  • Who initiates is a chat principal (member or external end user) carried in a short-lived chat token; who executes is always the Agent. run_initiator records the principal, thread, chat run, and the exact draft hash or version.
  • Instruction text and transcripts live only in a purpose-named application store; the control database keeps ids, hashes, rationale, and authorship so its no-content promise stays verifiable.
  • action-classified tool calls pause for the thread principal's approval through AG-UI interrupts; the MCP Gateway re-evaluates scope, grant, and policy when the approved call executes.

Consequences

  • Unpublish, Agent suspension, and grant revocation contain managed agents without touching transcripts or evidence.
  • Versions are auditable (definition.publish, definition.unpublish) and hash-verified on every read; a damaged application store fails closed.
  • The same /apps/v1 AG-UI contract serves the console and external frontends; external token minting with Agent keys is the remaining slice of this design.
  • No new human role exists: agent managers publish, any active member chats, and Run visibility rules are unchanged.

Rejected alternatives

  • Store instructions in the control database. Rejected because it breaks the documented no-content invariant and the artifact scans that enforce it.
  • Pin threads to a version. Rejected in favor of pinning Runs, so rollback contains live conversations immediately.
  • A per-thread or per-conversation Agent key. Rejected because one key per run keeps the key's scope equal to the definition at the moment of execution and lets revocation act within one run.

Relationship to ADR-0007

ADR-0007 remains the identity boundary for external runtimes. Managed definitions add Mission-Control-owned authoring on the same Agent identity without reintroducing caller-asserted deployment state.

Current governance mapping

The current source release uses Organizations, Teams, real user/service-account virtual keys and separate human management roles. Agent is managed application content; deployments own secretless execution access and publisher funding. Observe uses Requests, Traces, Sessions and Usage with separate metadata/content/export permissions. Historical identity terms in this target proposal are not the operating contract. See Current release.