Agent Runtime Integration
A reference for teams connecting an agent that runs outside AI Governance Control Plane. It describes the small amount of structured evidence the control plane needs—without taking control of your agent or its data.
Purpose & Boundary
Your application remains responsible for running the agent, choosing models and tools, storing customer data, and serving live users. The integration sends a compact, ordered record of what happened to the control plane. That record supports review, deterministic findings, and—where your runtime supports it—controlled replay.
This is an evidence connector, not an agent framework
You can connect a custom agent, an agent framework, or a provider's runtime. The control plane does not promise to run every framework, reproduce a private trace, or inspect hidden model reasoning.Minimum Integration Contract
A useful integration has four parts. Each can be implemented behind a small adapter in your own runtime, so the rest of your application does not need to know the control plane's event format.
| Part | What your runtime provides | Why it matters |
|---|---|---|
| Identity | A stable agent name/version and one external ID for each execution. | Makes a run traceable across deliveries and reviews. |
| Lifecycle | Start an execution, append events, then complete it as succeeded, failed, or cancelled. | Shows a complete, understandable timeline. |
| Evidence | Safe metadata plus durable references and digests for approved evidence. | Lets a reviewer verify a claim without copying sensitive content. |
| Optional replay adapter | A way to resolve approved references and run a safe, isolated variant. | Required only for Causal Audit and controlled replay. |
Events & Ordering
Create the execution when work begins. Append meaningful facts in order, then complete it. Use a stable delivery/idempotency key when your connector retries a request, so a temporary network failure cannot silently create duplicate evidence.
execution started → model call → tool call → governance decision → evaluation or error → execution completed
Supported event types are execution started, model call, tool call, governance decision, evaluation, error, and execution completed. An event identifies its actor (for example, agent, model, tool, governance system, evaluator, or system), occurrence time, sequence number, and safe attributes. Correlation and causation IDs can connect the event to a request or an earlier event.
Sequence numbers must only move forward within an execution. Events that arrive late are still valuable historical evidence, but may be outside a detector's already-finalized observation window. Do not rely on a late event to rewrite an earlier operational finding.
Evidence References
A reference tells the control plane where an approved item can be resolved by your runtime. A digest helps confirm the item has not changed. For a tool call, record the tool identity, timing, result schema identity, and a reference to an allowed result—not the raw result itself.
Example: a payment-check tool can report payment.check, duration 84 ms, result schema payment-check/v1, and a reference such as evidence://payments/checks/9f2a. The payment result remains in the payment system, protected by its existing access controls.
Replay Capability
Normal observation does not require your runtime to replay anything. To enable Causal Audit, however, the runtime must register a replay adapter that can resolve a frozen source execution and run it in isolation. It must accept only an approved intervention, preserve the original as historical evidence, and return a structured outcome for comparison.
The adapter is the boundary between governance authorization and real runtime work. Read Controlled Replay Framework for its full requirements, including lineage, recovery, and cost ownership.
Safe Data Boundary
Event attributes are operational metadata, not a transcript store. Never send prompts, system prompts, model responses, conversation messages, chain-of-thought or reasoning, credentials, API keys, tokens, passwords, secrets, tool arguments, tool payloads, raw tool outputs, or raw tool results.
Treat references as access-controlled data
A reference should be durable, scoped to the correct tenant, and resolvable only by an authorized replay adapter or reviewer workflow. Do not use an unauthenticated public URL as a shortcut for sensitive evidence.Connector Checklist
- Use stable tenant, agent, execution, event, and idempotency identities.
- Send lifecycle events in order and always complete a terminal execution.
- Use timestamps, correlation IDs, safe metadata, evidence references, and digests.
- Keep sensitive content in the system that owns it.
- Apply the control plane's tenant and permission checks to every request.
- Register and test a replay adapter before making Causal Audit available to users.
For a hands-on sequence, follow Observe an Agent Runtime. For the operational rules applied after ingestion, see Runtime Findings.