Integration guideAdvanced~35 min

Run LangGraph ToolNode Evidence Replay

SupportedPython 3.12+LangGraphReplayTOOL_CALL + CAUSAL_AUDIT

Run one real LangGraph ToolNode call using recorded evidence, replace that evidence once through an approved policy, and inspect the resulting Causal Audit without calling the original tool again.

Last updated

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.
Why three repositories? OSS owns the control plane and acceptance checks. The adapter owns the LangGraph ToolNode integration and Docker overlay. The lab owns only the runnable example and its synthetic private snapshot.

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.

terminal · clone repositories
# 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.

terminal · build and start the local services
# 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-worker

Wait 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.

terminal · resolve identities and issue tokens
# 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.

terminal · install and run ToolNode tests
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 -q

5. 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.

terminal · record the execution and create the policy
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
expected observed execution and active policy
{
  "scenario": "observe",
  "execution_id": "<observed-execution-id>",
  "policy_id": "<active-policy-id>",
  "policy_version": 1,
  "intervention_policy": {
    "provider": "opaque-reference/v1"
  }
}
Policy creation by Runner: the policy binds 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.

terminal · start the controlled Causal Audit
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.json

Your identifiers and digests will differ. The important terminal state is a successful audit with an aligned result.

expected Causal Audit 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.

1

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.

2

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.

3

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.

4

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.

5

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.

6

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.

7

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.

8

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.

9

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.

10

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.

CaseExpected behaviour
Unknown ToolFails closed. The resolver does not call a historical tool as a fallback.
Mismatched Tool ArgumentsFails closed. The resolver does not call a historical tool as a fallback.
Approved interventionReturns the frozen replacement for exactly one planned call.
Parallel callsIndependent calls can resolve; duplicate concurrent attempts cannot consume the same planned call twice.
Incomplete sessionFinalization 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.

Still useful: the boundary is explicit, testable, and checked again by the replay worker before a Causal Audit result is accepted. That is stronger than assuming a whole agent workflow was replayed because one tool call was observed.

For the platform model, read Causal Audit and Execution Replay Architecture. For the older, broader authorization-and-receipt walkthrough, use Build Governed LangGraph Agent.