Replay Adapter Development
A vendor-neutral implementation guide for adapters that support AIGP execution replay at a declared runtime boundary.
Purpose & Prerequisites
This page is for engineers building an adapter for LangGraph, OpenAI Agents SDK, Google ADK, or another agent runtime. It explains the implementation contractβnot the Causal Audit user workflow. Read Execution Replay Architecture first for the control-plane model, then use this page to build and test the runtime-owned part.
Start with one declared boundary
A useful adapter does not need to intercept every runtime surface. Begin with a boundary you can actually observe and replace safely, such as one framework tool dispatcher. Declare custom nodes, direct SDK calls, hosted tools, and any other uncontrolled surface as unsupported.You need all of the following before advertising execution replay:
- A stable way to capture historical tool-call identity and safe evidence references.
- A runtime-owned private store for raw arguments and evidence content.
- A framework hook that can return recorded evidence without calling the original tool.
- An independently installable plugin package using the public Plugin API.
- Tests for successful, rejected, concurrent, and incomplete paths.
Adapter Architecture
Observed runtime execution β capture bounded ToolCall evidence β store private snapshot in runtime environment β receive frozen plan from replay worker β intercept declared framework boundary β resolve planned evidence in memory β materialise private evidence locally β return trace + attestation to AIGP
Keep these responsibilities separate. The control plane creates the replay manifest, intervention, and frozen plan. Your adapter resolves its opaque runtime reference, intercepts only the boundary it declares, and materialises private evidence locally. The replay worker validates your bounded report; it does not enter your runtime or execute an original tool.
Conceptual adapter flow: only the adapter's declared runtime boundary is intercepted, and the resolver returns an outcome rather than calling the original tool.
Plugin API Integration
Install the public package. An external adapter must not import AIGP OSS services, repositories, or persistence models.
python -m pip install 'bhanuj-governance-plugin-api==1.2.0rc1'
Register the independently installed plugin through the canonical entry-point group:
# pyproject.toml [project.entry-points."bhanuj.governance.plugins"] my-runtime = "my_runtime.plugin:plugin"
A replay adapter implements the public ReplayExecutionAdapterprotocol. The host selects it by the versioned contribution nameadapter_id/adapter_version.
from bhanuj_governance_plugin_api import (
ReplayExecutionAdapter,
ReplayExecutionContext,
ReplayExecutionResult,
)
class MyRuntimeReplayAdapter(ReplayExecutionAdapter):
@property
def name(self) -> str:
return "my-runtime/v2"
def validate_configuration(self, source_execution: object, configuration: object) -> None:
# Reject a source or configuration this adapter cannot safely handle.
...
def replay(
self,
source_execution: object,
configuration: object,
context: ReplayExecutionContext,
) -> ReplayExecutionResult:
plan = context.execution_replay_resolution_plan
if plan is None:
raise ValueError("Execution replay requires a frozen resolution plan.")
# Resolve the runtime-owned snapshot and run only the declared boundary.
...Preserve reference replay compatibility
Execution replay is opt-in. Do not replace an existing reference replay adapter with a new incompatible path. Keep the legacy adapter identity available, then introduce a separate versioned execution-replay identity when the semantics differ.Execution Capture
Capture historical calls while the original runtime executes. A future replay can only resolve what you captured and bound to the source execution. Do not infer a tool call from a graph node or a model message; record a tool call only when the runtime actually reaches the tool boundary.
For every replayable call, retain these bounded values in the control-plane record:
- Runtime call ID, graph or subgraph scope, tool symbol, schema version, and occurrence.
- Canonical argument fingerprint with its algorithm, canonicalization, and key version.
- Dependency and retry links when the framework exposes them.
- Private evidence reference, response digest, and result-schema identity.
Use the public canonicalization helper. New persisted fingerprints containing sensitive or low-entropy arguments should use the tenant- and project-scoped HMAC algorithm rather than a plain hash.
from bhanuj_governance_plugin_api import (
ToolArgumentDigestAlgorithm,
create_tool_argument_digest,
)
argument_digest = create_tool_argument_digest(
runtime_arguments,
algorithm=ToolArgumentDigestAlgorithm.HMAC_SHA256_JSON_V1,
organization_id=organization_id,
project_id=project_id,
key_version="v1",
key_provider=runtime_owned_key_provider,
)The key provider stays inside your runtime. Only the digest algorithm and non-secret key version cross the Plugin API boundary.
Snapshot Management
Your runtime owns the private snapshot. It may contain raw arguments, recorded evidence, replacement evidence, and framework state needed to reach the declared boundary. AIGP receives only its opaque replay reference, integrity bindings, evidence references, and digests.
| Requirement | Responsibility |
|---|---|
| Tenant binding | Bind the snapshot to organization, project, source execution, manifest hash, and adapter identity. |
| Integrity | Verify the selected private evidence against the frozen digest before returning it. |
| Access | Expose private content only to the runtime process that performs the declared replay boundary. |
| Retention | Define your own retention, deletion, recovery, and backup policy. AIGP does not manage snapshot content. |
Resolution Plan
The worker supplies an immutable EvidenceResolutionPlan inReplayExecutionContext.execution_replay_resolution_plan. Do not rebuild it from a snapshot, append to it, or change it while replaying. Its canonical digest binds the tenant, source execution, replay manifest, capability, planned calls, and evidence bindings.
A ReplayToolCall identity includes scope, tool symbol, tool-schema version, argument digest, occurrence, retry relationship, and dependencies. It deliberately excludes scheduler timing: independent calls may arrive in another order, while repeated calls remain distinguishable.
Tool Interception
Hook the narrowest framework surface that receives native tool calls. Replace the original implementation with a resolver-backed function at replay time; do not register the historical tool as a fallback. The resolver returns only a selected evidence reference and digest. Your private evidence store materialises the content after that successful selection.
from bhanuj_governance_plugin_api import (
ExecutionReplayResolver,
ReplayResolutionOutcome,
)
resolver = ExecutionReplayResolver(plan, intervention_binding)
resolution = resolver.resolve(
attempted_call,
intervention_digest=intervention_binding.intervention_digest,
)
if resolution.outcome not in {
ReplayResolutionOutcome.RESOLVED_RECORDED,
ReplayResolutionOutcome.RESOLVED_INTERVENTION,
}:
raise RuntimeError(f"Replay call failed closed: {resolution.reason_code}")
content = private_evidence_store.materialize(
resolution.selected_evidence_reference,
resolution.selected_response_digest,
)The resolver never invokes tools, fetches private evidence, contacts a provider, or mutates the plan. The adapter supplies those framework-specific pieces inside its own boundary.
This boundary applies to the framework surface an adapter explicitly supports. It does not claim interception of custom nodes, direct provider calls, or hosted tools.
Controlled Intervention
The existing intervention policy authorizes the evidence change. TheReplayInterventionBinding narrows that approval for the resolver: it binds one replacement reference and digest to one planned call, one manifest, and one resolution-plan digest. It does not transform evidence or create a new tool call.
Apply the replacement only when the bound target call is resolved, and only once. If the target is never reached, finalization is incomplete. If a different call requests the intervention digest, fail closed with an intervention mismatch.
Parallelism & Subgraphs
Declare support conservatively. Async tools, concurrent execution, retries, and subgraphs are independent capability flags. Setting one to truedoes not imply the others.
- Resolve matching, dependency validation, and plan consumption as one protected operation.
- Allow dependency-free calls to resolve in either order when the framework schedules them in parallel.
- Reject a dependent call until every declared predecessor is consumed.
- Represent retries explicitly; a retry must retain the original canonical tool identity.
- Use distinct scope IDs for nested graphs only when your adapter can capture and replay that scope reliably.
Optional does not mean unsupported forever
A useful first adapter can set subgraphs or concurrency tofalse. Add them only with matching capture, interception, and conformance tests.Divergence Handling
The resolver returns stable, bounded reason codes. Convert them into safe runtime failures; do not log raw arguments or substitute an original tool call.
| Condition | Representative Reason | Response |
|---|---|---|
| Unknown call | UNOBSERVED_TOOL_CALL | Stop the supported replay boundary; never invoke the original tool. |
| Identity or argument mismatch | TOOL_IDENTITY_MISMATCH or ARGUMENT_DIGEST_MISMATCH | Record bounded divergence and fail the replay. |
| Duplicate or premature call | DUPLICATE_TOOL_CALL or DEPENDENCY_VIOLATION | Do not consume evidence twice or bypass the dependency graph. |
| Invalid replacement | INTERVENTION_MISMATCH | Do not choose alternate evidence outside the frozen binding. |
| Unfinished session | INCOMPLETE summary | Return the incomplete trace; do not attest success. |
Attestation & Validation
Finalize the resolver session, build a typed ReplayExecutionTrace, and return a typed ReplayExecutionAttestation with the replay result. The attestation binds the manifest, plan digest, intervention digest, Phase 1 safety digest, trace digest, declared and exercised boundaries, and resolution counts.
return ReplayExecutionResult(
execution_status="COMPLETED",
final_state={"causal_audit_outcome_score": outcome_score},
artifact_refs=(outcome_reference,),
runtime_parameters={"evidence_only": True},
metadata={"evidence_only_replay_safety": safety_metadata},
execution_replay_trace=trace,
execution_replay_attestation=attestation,
)The worker reconstructs the expected plan from frozen configuration. It validates every returned identity, evidence selection, intervention target, digest, count, coverage declaration, and blocking divergence. It accepts only a complete resolver summary in which every planned call was consumed and the intervention was applied exactly once. complete=True alone never passes this check.
Conformance Testing
Run these tests before declaring execution replay capability:
| Test | Expected evidence |
|---|---|
| Recorded path | A declared call returns digest-verified recorded evidence; the original implementation counter remains zero. |
| Intervention path | The bound call returns only the approved replacement and records exactly one intervention. |
| Mismatch path | Unknown tool, arguments, occurrence, retry, or dependency fails closed without original-tool execution. |
| Concurrency path | Independent calls resolve safely; duplicate concurrent calls cannot consume the same evidence twice. |
| Completion path | Missing planned calls or a missing intervention produce an incomplete result, not a successful attestation. |
| Worker rejection path | Missing or inconsistent trace, attestation, safety metadata, coverage, or digest reaches the existing replay failure path. |
| Capability | Ref Adapter v1 | LangGraph ToolNode | New Adapter |
|---|---|---|---|
| Precomputed-score reference replay | Supported | Not its purpose | Optional |
| Actual tool interception | No | Declared ToolNode only | Declare exact boundary |
| Historical evidence substitution | Reference-score based | Recorded evidence | Required for tool replay |
| Async and parallel calls | Not applicable | Supported | Capability-dependent |
| Custom-node interception | No | No | Never assume |
| Trace and worker validation | Reference contract | Execution replay contract | Required when declared |
Security Boundaries
Execution replay is not sandboxing. An adapter cannot claim control over arbitrary custom nodes, direct HTTP, database, SDK, subprocess, or provider-hosted tool calls unless it explicitly intercepts and attests to each declared boundary. A private snapshot store also does not authorize production access or make an unsafe tool safe.
- Never include raw private evidence in trace, attestation, diagnostics, fixtures, or logs.
- Never treat a manifest hash, snapshot digest, or adapter report as independent proof of external state.
- Use replay IDs as idempotency keys in the runtime-owned environment.
- Fail when tenant, adapter identity, manifest, snapshot integrity, or declared boundary does not match.
- State unsupported surfaces plainly in capability metadata and public documentation.
Packaging & Compatibility
Version the adapter identity and Plugin API contract deliberately. Build and test your wheel and source distribution independently of the OSS monorepo; verify public imports, entry-point discovery, and resolver tests in a clean environment. Do not package internal AIGP services, persistence models, credentials, local snapshots, or framework-development overlays.
Keep compatibility evidence with the release: supported Plugin API version, adapter version, declared framework boundary, known unsupported surfaces, and conformance-test results. A runtime may add a new execution-replay adapter version without changing legacy reference replay behaviour.
For a concrete implementation, follow the LangGraph ToolNode Evidence Replay guide. For lifecycle and result semantics, return to Execution Replay Architecture and Controlled Replay Framework.
