Verify outcomes
Verify ToolNode Evidence Replay
The lab first records a synthetic account_lookup call with medium-risk evidence. It then freezes the call identity and evidence reference. During the controlled replay, LangGraph calls a resolver-backed ToolNode; the original Python tool is not given to that node. The resolver returns the recorded evidence, or the single approved low-risk replacement, only after the call matches the frozen plan.
What AIGP receives
Bounded execution metadata, opaque references, identities, and digests. It does not receive raw tool arguments or private evidence content.
What the worker checks
The frozen plan, consumed calls, intervention target, trace digest, safety attestations, and declared ToolNode coverage.
Prepare first
Prepare Local Environment
- Git, Docker Desktop, Python 3.12 or newer, and uv on your development machine.
- Ports 8000 and 3000 available for the local AIGP API and Studio.
- Three sibling checkouts: ai-governance-oss, labs, and aigp-langgraph-replay-adapter.
- Permission to create short-lived tokens for the local service accounts.
If this is your first local AIGP setup, complete Getting Started first. This guide uses synthetic evidence only; do not put production tool payloads or credentials into the lab files.
Run lab
Run Controlled Replay
1. Clone Repositories
These environment variables avoid guessing relative paths later. Keep the terminal open: the following steps reuse them.
# Keep these three repositories as siblings. The commands below assume one parent folder.
git clone https://github.com/Bhanuj-AI/ai-governance-oss.git
git clone https://github.com/Bhanuj-AI/labs.git
git clone https://github.com/Bhanuj-AI/aigp-langgraph-replay-adapter.git
export AIGP_OSS="$PWD/ai-governance-oss"
export AIGP_LABS="$PWD/labs"
export AIGP_ADAPTER="$PWD/aigp-langgraph-replay-adapter"
export AIGP_V2_LAB="$AIGP_LABS/agent-frameworks/langgraph/langgraph-execution-assurance-lab-v2"2. Start Replay Services
The overlay adds the released LangGraph adapter only to the replay worker. It also mounts the lab's private SQLite snapshot read-only into that worker. The API and Studio do not mount or read the snapshot.
# Start from a clean shell after cloning the repositories.
cd "$AIGP_OSS"
uv sync
cp .env.local.example .env.local
cp keycloak-postgres/.env.keycloak.example keycloak-postgres/.env.keycloak
# The adapter owns this development overlay and the worker-only private snapshot mount.
export AIGP_LANGGRAPH_REPLAY_ADAPTER_DIR="$AIGP_ADAPTER"
export AIGP_LANGGRAPH_REPLAY_SNAPSHOT_DIR="$AIGP_V2_LAB/live/runtime-data"
export AIGP_BASE_WORKER_IMAGE=ai-governance-platform:local
export AIGP_LANGGRAPH_REPLAY_WORKER_IMAGE=ai-governance-platform-langgraph-v2:local
docker compose build ai-governance-platform
docker compose -f docker-compose.yml \
-f ../aigp-langgraph-replay-adapter/docker-compose.replay-worker.yml \
build ai-governance-replay-worker
docker compose -f docker-compose.yml \
-f ../aigp-langgraph-replay-adapter/docker-compose.replay-worker.yml \
up -d --force-recreate ai-governance-platform ai-governance-replay-workerWait until the API is healthy before continuing: curl --fail http://localhost:8000/ready. Studio is available at http://localhost:3000.
3. Configure Identities and Tokens
The tutorial uses two identities. The issuer creates and activates the intervention policy. The runtime records execution evidence and starts the audit. Do not replace these with invented names or copy a bearer token into a file.
# The local identity provider creates these service-account identities.
cd "$AIGP_OSS"
./scripts/keycloak/get-service-account-actorids.sh
set -a
source .env.oauth.generated
source .env.service-accounts.generated
source keycloak-postgres/.env.keycloak
set +a
export AIGP_BASE_URL=http://localhost:8000
export AIGP_ORGANIZATION_ID=org_default
export AIGP_PROJECT_ID=project_default
export AIGP_ISSUER_ACTOR_ID="$AI_GOVERNANCE_WALKTHROUGH_ACTOR_ID"
export AIGP_RUNTIME_ACTOR_ID="$AI_GOVERNANCE_SYNTHETIC_RUNTIME_ACTOR_ID"
# Keep these short-lived bearer tokens in this shell. Never save them in Git or a screenshot.
export AIGP_ISSUER_TOKEN="$(
uv run python -c 'from ai_governance.oauth.client_credentials import access_token_from_environment; print(access_token_from_environment())'
)"
export AIGP_RUNTIME_TOKEN="$(
AI_GOVERNANCE_OAUTH_TOKEN_URL="$AI_GOVERNANCE_OAUTH_TOKEN_URL" \
AI_GOVERNANCE_OAUTH_CLIENT_ID=synthetic-agent-runtime \
AI_GOVERNANCE_OAUTH_CLIENT_SECRET="${SYNTHETIC_RUNTIME_CLIENT_SECRET:-local-synthetic-runtime-client-secret}" \
uv run python -c 'from ai_governance.oauth.client_credentials import access_token_from_environment; print(access_token_from_environment())'
)"
printf 'Issuer: %s\nRuntime: %s\n' "$AIGP_ISSUER_ACTOR_ID" "$AIGP_RUNTIME_ACTOR_ID"4. Install Packages and Run Tests
The version checks ensure that the lab uses the published Plugin API release and adapter tag. The tests run a real ToolNode with recorded evidence; they do not need the Docker platform.
cd "$AIGP_V2_LAB"
python -m venv live/.venv
. live/.venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
# Confirm that the guide uses released packages, not an editable adapter checkout.
python -c "from importlib.metadata import version; assert version('aigp-langgraph-replay-adapter') == '0.3.1'; print('Adapter:', version('aigp-langgraph-replay-adapter'))"
python -c "from importlib.metadata import version; assert version('bhanuj-governance-plugin-api') == '1.2.0rc1'; print('Plugin API:', version('bhanuj-governance-plugin-api'))"
# These tests prove the local ToolNode boundary before a Docker-backed audit is attempted.
PYTHONPATH=. python -m pytest -q5. Record Evidence & Create Intervention Policy
Run the observation phase first. It records the synthetic account_lookup ToolNode execution, captures the private snapshot in the runtime-owned store, and creates or reuses the exact reference-only replacement policy. The runner validates and activates that policy before it reports the execution and policy identifiers.
cd "$AIGP_V2_LAB"
. live/.venv/bin/activate
# This records one ToolNode execution, creates or reuses the exact
# opaque-reference REPLACE policy, validates it, and activates it.
python live/run_live_lab.py observe | tee live/artifacts/toolnode-v2-observe.json{
"scenario": "observe",
"execution_id": "<observed-execution-id>",
"policy_id": "<active-policy-id>",
"policy_version": 1,
"intervention_policy": {
"provider": "opaque-reference/v1"
}
}account_lookup, langgraph-tool-node-account-risk-v2 v1, the REPLACE strategy, and a runtime-owned replacement reference and digest. Do not guess, copy, or expose the private evidence value or digest in Studio. The issuer-authenticated runner creates the exact bounded configuration, then Studio lets you inspect its policy lineage.6. Confirm Active Policy in Studio
Open http://localhost:3000/agents-runtime?view=causal-audit, select Intervention Policies, and locate the policy ID printed by the observation command. Open it and confirm that it is ACTIVE, targets account_lookup with schema langgraph-tool-node-account-risk-v2 v1, and permits only REPLACE. The later Studio walkthrough shows each screen in order.
7. Run Docker Causal Audit
Start the audit with the exact observed execution and active policy version emitted in the first phase. The replay worker uses those bindings to run one controlled counterfactual; it does not call the original Python tool.
cd "$AIGP_V2_LAB"
. live/.venv/bin/activate
# Copy these three values from toolnode-v2-observe.json.
python live/run_live_lab.py audit \
--execution-id <execution_id> \
--policy-id <policy_id> \
--policy-version <policy_version> \
| tee live/artifacts/toolnode-v2-audit.jsonYour identifiers and digests will differ. The important terminal state is a successful audit with an aligned result.
{
"scenario": "audit",
"status": "SUCCEEDED",
"classification": "EVIDENCE_ALIGNED"
}Inspect Studio
Inspect Returned Evidence
The terminal artifact contains direct Studio URLs for the execution and audit. Use those URLs when available. Otherwise, follow this Studio walkthrough in order: it moves from the observed LangGraph execution, through the approved intervention, to the controlled replay, audit result, and worker job. Studio shows bounded references, identities, digests, policy lineage, and result—not raw evidence from the worker-only snapshot.
Before you begin
Open Studio at http://localhost:3000/agents-runtime locally, or replace http://localhost:3000 with your configured Studio hostname. Use the organization and project in which you ran the lab. Identifiers, timestamps, and digests vary by run.
Studio walkthrough
Open Agent Executions Overview
In Agents Runtime, leave the Executions tab selected. Execution Evidence begins with the Observed Agents inventory; it is the entry point for recorded runtime evidence.
Step 1 · In Agents Runtime, leave the Executions tab selected. Execution Evidence begins with the Observed Agents inventory; it is the entry point for recorded runtime evidence.
Studio walkthrough
Choose LangGraph Lab Agent
In Observed Agents, select LangGraph ToolNode evidence replay v2 lab. Confirm the runtime is langgraph and the agent identifier is langgraph-tool-node-evidence-replay-v2 before using a completed execution.
Step 2 · In Observed Agents, select LangGraph ToolNode evidence replay v2 lab. Confirm the runtime is langgraph and the agent identifier is langgraph-tool-node-evidence-replay-v2 before using a completed execution.
Studio walkthrough
Inspect LangGraph Execution Timeline
Open the completed execution and inspect its ordered timeline. Confirm the completed TOOL_CALL for account_lookup and its bounded evidence facts; do not expect or expose raw tool arguments or evidence content.
Step 3 · Open the completed execution and inspect its ordered timeline. Confirm the completed TOOL_CALL for account_lookup and its bounded evidence facts; do not expect or expose raw tool arguments or evidence content.
Studio walkthrough
Open Intervention Policies
Return to Agents Runtime, open Causal Audit, then choose Intervention Policies. This is where Studio lists the governed evidence changes that may be used in a counterfactual replay.
Step 4 · Return to Agents Runtime, open Causal Audit, then choose Intervention Policies. This is where Studio lists the governed evidence changes that may be used in a counterfactual replay.
Studio walkthrough
Verify Active Intervention Policy
Open the active policy used for account_lookup. Verify its target schema is langgraph-tool-node-account-risk-v2 and that REPLACE is the permitted strategy; the policy version is the lineage for the controlled evidence change.
Step 5 · Open the active policy used for account_lookup. Verify its target schema is langgraph-tool-node-account-risk-v2 and that REPLACE is the permitted strategy; the policy version is the lineage for the controlled evidence change.
Studio walkthrough
Open Replay Management
Use the Replay navigation item to open Replay Management. Find the replay associated with the observed execution and identify the Causal Replay marker, which distinguishes this controlled run from an ordinary historical replay.
Step 6 · Use the Replay navigation item to open Replay Management. Find the replay associated with the observed execution and identify the Causal Replay marker, which distinguishes this controlled run from an ordinary historical replay.
Studio walkthrough
Open Causal Audit
Return to Agents Runtime, open Causal Audit, and select the audit created by the lab. This view connects the observed execution, the approved intervention, and the audit lifecycle without exposing private snapshot contents.
Step 7 · Return to Agents Runtime, open Causal Audit, and select the audit created by the lab. This view connects the observed execution, the approved intervention, and the audit lifecycle without exposing private snapshot contents.
Studio walkthrough
Review Controlled Causal Replay
Expand the controlled replay lineage in the audit. Verify that the replay execution and governed policy version belong to this audit; this proves which isolated counterfactual was evaluated, not that the original execution changed.
Step 8 · Expand the controlled replay lineage in the audit. Verify that the replay execution and governed policy version belong to this audit; this proves which isolated counterfactual was evaluated, not that the original execution changed.
Studio walkthrough
Confirm Causal Classification
Confirm the audit reached its terminal state and the expected EVIDENCE_ALIGNED classification. Record the audit ID and replay lineage as bounded evidence of the outcome.
Step 9 · Confirm the audit reached its terminal state and the expected EVIDENCE_ALIGNED classification. Record the audit ID and replay lineage as bounded evidence of the outcome.
Studio walkthrough
Confirm Causal Replay Worker Job
Open Jobs and locate the replay worker job for the same audit or replay. Confirm its terminal job state as operational evidence that the worker processed the controlled replay; Studio does not expose the worker's private SQLite snapshot.
Step 10 · Open Jobs and locate the replay worker job for the same audit or replay. Confirm its terminal job state as operational evidence that the worker processed the controlled replay; Studio does not expose the worker's private SQLite snapshot.
Verify Safety Controls
Verify Failure Controls
The automated tests exercise the cases a happy-path screenshot cannot show. Keep their output with your tutorial notes or CI evidence.
| Case | Expected behaviour |
|---|---|
| Unknown Tool | Fails closed. The resolver does not call a historical tool as a fallback. |
| Mismatched Tool Arguments | Fails closed. The resolver does not call a historical tool as a fallback. |
| Approved intervention | Returns the frozen replacement for exactly one planned call. |
| Parallel calls | Independent calls can resolve; duplicate concurrent attempts cannot consume the same planned call twice. |
| Incomplete session | Finalization marks it incomplete. A completion flag alone is not enough for OSS to accept an audit result. |
Know coverage limits
Understand Coverage Limits
This guide proves evidence resolution for declared LangGraph ToolNode calls. It does not intercept custom graph nodes, direct SDK or HTTP calls, provider-hosted tools, or tools in other frameworks. It also does not create sandbox-level isolation. Those surfaces are outside the declared capability and must not be described as covered.
For the platform model, read Causal Audit and Execution Replay Architecture. For the older, broader authorization-and-receipt walkthrough, use Build Governed LangGraph Agent.
