Let a LangGraph Assistant Make a Safe Change

1. Build Agent

Build First

The first checkpoint is intentionally plain: one read-only run, one local SQLite file, and no AIGP connection. No model, cloud account, or paid API is needed.

git clone https://github.com/Bhanuj-AI/labs.git
cd labs/agent-frameworks/langgraph/langgraph-governed-operations-intg
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

python app.py readonly --database /tmp/bhanuj-langgraph-readonly.db

Outcome: READ_COMPLETED
Reason: n/a
SQLite record status: PENDING
AIGP execution ID: not delivered
AIGP evidence status: DISABLED

cd /path/to/ai-governance-oss
uv sync

2. Connect to AIGP

Connect the lab and its two identities

Start the local AIGP stack from its own checkout. This prepares Studio for the user's policy setup in the next step; the authoritative protected run has not started yet.

cd /path/to/ai-governance-oss
./servers.sh up
./servers.sh ps

# Development authentication only. Do not use this in a shared environment.
export AI_GOVERNANCE_BASE_URL=http://localhost:8000
export AI_GOVERNANCE_ORGANIZATION_ID=org_default
export AI_GOVERNANCE_PROJECT_ID=project_default
export AI_GOVERNANCE_ACTOR_ID=local-admin
export AI_GOVERNANCE_RUNTIME_ACTOR_ID=local-admin

python app.py readonly --database /tmp/bhanuj-langgraph-registered.db

Outcome: READ_COMPLETED
SQLite record status: PENDING
AIGP execution ID: <uuid>
AIGP evidence status: COMPLETED

The lab submits the actual LangGraph run ID as the external execution ID. AIGP returns the canonical execution_id, which is then required for authorization, evidence, retrieval, and finalization. An optional LangGraph thread ID is continuity metadata only; a new run on the same thread gets a new AIGP execution.

For Keycloak, the runtime actor must match the service-principal subject AIGP derives from the runtime token; it is checked locally against the returned decision, not sent as an authority claim. The issuer has its own short-lived token and subject. A local Studio administrator may also operate the runtime if that identity has the necessary permissions; it must still remain distinct from the delegation issuer. In production, prefer a least-privilege runtime service account.

# Run in the OSS checkout after ./servers.sh up.
# These generated files contain local development credentials. Do not print,
# commit, or copy either resulting token outside this shell.
set -a
source .env.oauth.generated
source .env.service-accounts.generated
set +a

# Issuer token: the walkthrough service account creates the delegation.
ISSUER_ACCESS_TOKEN="$(uv run python -c 'from ai_governance.oauth.client_credentials import access_token_from_environment; print(access_token_from_environment())')"

# Runtime token: the separate MCP service account asks for the action decision.
RUNTIME_ACCESS_TOKEN="$(AI_GOVERNANCE_OAUTH_TOKEN_URL="$AI_GOVERNANCE_MCP_TOKEN_URL" AI_GOVERNANCE_OAUTH_CLIENT_ID="$AI_GOVERNANCE_MCP_CLIENT_ID" AI_GOVERNANCE_OAUTH_CLIENT_SECRET="$AI_GOVERNANCE_MCP_CLIENT_SECRET" uv run python -c 'from ai_governance.oauth.client_credentials import access_token_from_environment; print(access_token_from_environment())')"

test -n "$ISSUER_ACCESS_TOKEN" && test -n "$RUNTIME_ACCESS_TOKEN"

# These are public service-account subjects, not secrets. Keep them as variables
# so the lab can check the server-derived identities without hard-coding IDs.
export AI_GOVERNANCE_DELEGATION_ISSUER_ACTOR_ID="$AI_GOVERNANCE_WALKTHROUGH_ACTOR_ID"
export AI_GOVERNANCE_RUNTIME_ACTOR_ID="$AI_GOVERNANCE_MCP_ACTOR_ID"

# Keep both short-lived tokens only in this shell or your secret manager.
export AI_GOVERNANCE_BASE_URL=http://localhost:8000
export AI_GOVERNANCE_ORGANIZATION_ID=org_default
export AI_GOVERNANCE_PROJECT_ID=project_default

# Runtime: the identity that runs LangGraph and asks for authorization.
export AI_GOVERNANCE_ACCESS_TOKEN="$RUNTIME_ACCESS_TOKEN"
export AI_GOVERNANCE_RUNTIME_ACTOR_ID="$AI_GOVERNANCE_MCP_ACTOR_ID"

# Issuer: a different identity allowed to create this execution's delegation.
export AI_GOVERNANCE_DELEGATION_ISSUER_ACCESS_TOKEN="$ISSUER_ACCESS_TOKEN"
export AI_GOVERNANCE_DELEGATION_ISSUER_ACTOR_ID="$AI_GOVERNANCE_WALKTHROUGH_ACTOR_ID"

# This development-only header must not be sent in Keycloak mode.
unset AI_GOVERNANCE_ACTOR_ID

3. Create Policies Before the Run

The user configures two policies in Studio

This happens once as integration setup, before anyone runs aigp. The integration owner creates and activates these two policies. The agent never creates policies, selects a policy, or supplies a policy ID to the PDP.

1. STEP 1. Open the correct page

   In the Studio sidebar choose Policies Engine, then Create Policy. Complete the Policy Definition form, press Create Draft, open version 1, then press Activate.

2. STEP 2. Create and activate both

   Create Policy 1 first, then Policy 2. Check that each appears as ACTIVE in the policy inventory before starting the protected run.

3. STEP 3. Do not configure policy IDs in the lab

   Policies remain active setup rules. On each run, the issuer creates only an immutable execution-scoped delegation after registration; the PDP resolves the active applicable policies itself.

Fill these common definition fields for both policies: use your configured organization and project (the local lab uses org_default and project_default), category SECURITY, a unique descriptive name, and the integration owner as Owner and Created by. Give the one rule a unique rule ID, priority 10, severity LOW, a plain-language reason, and effect APPROVE.

Create and activate this first. It identifies the issuer, runtime, action, resource type, and OPS-001 resource that may be delegated.

Create and activate this next. Permits the registered operations.update_status action on the SQLite resource after a valid delegation.

4. Run the Authoritative Action

Now start the protected run

Only after both policies are ACTIVE, run aigp. The lab registers the canonical execution; the issuer uses Policy 1 to create its immutable delegation; the runtime uses that delegation plus Policy 2 to request authorization immediately before SQLite.

For a changed scope, the user who administers the integration creates and activates a new policy version before the affected run. The prior activated version remains historical evidence. See the Policy Engine documentation for Studio policy creation and version lifecycle.

{
  "runtime_action_authorization": {
    "purpose": "runtime_action_authorization",
    "registered_actions": ["operations.update_status"],
    "registered_resource_types": ["sqlite.row"]
  }
}

LAB_ROOT="$(pwd)"
OSS_ROOT=/path/to/ai-governance-oss
LAB_SITE_PACKAGES="$("$LAB_ROOT/.venv/bin/python" -c 'import site; print(site.getsitepackages()[0])')"
PYTHONPATH="$LAB_ROOT:$LAB_SITE_PACKAGES" \
  "$OSS_ROOT/.venv/bin/python" "$LAB_ROOT/app.py" aigp \
  --database /tmp/bhanuj-langgraph-aigp.db

Outcome: WRITE_COMPLETED
Reason: ALLOW_POLICY_MATCHED
SQLite record status: MAINTENANCE
AIGP execution ID: <uuid>
AIGP evidence status: COMPLETED

5. Compare Live Results

A permitted write and a safely refused one

These are two live outcomes validated against the local OSS API. Read the execution status separately from the authorization and tool results: a workflow may finish successfully because it handled a denied request safely.

LAB_ROOT="$(pwd)"
OSS_ROOT=/path/to/ai-governance-oss
LAB_SITE_PACKAGES="$("$LAB_ROOT/.venv/bin/python" -c 'import site; print(site.getsitepackages()[0])')"
PYTHONPATH="$LAB_ROOT:$LAB_SITE_PACKAGES" \
  "$OSS_ROOT/.venv/bin/python" "$LAB_ROOT/app.py" aigp \
  --database /tmp/bhanuj-langgraph-aigp.db

RUNTIME_ACTION_AUTHORIZATION with ALLOW, then the successful TOOL_CALL whose causation ID points back to the decision.

PENDING SQLite result, no successful tool call, and terminal execution status.

6. Fixture Cases

Compare Offline Fixtures

All scenarios share the same LangGraph workflow and evidence adapter. Only aigp calls the authoritative policy endpoint. The fixture cases are retained for deterministic teaching and failure exercises; they never represent an AIGP policy decision.

# These decisions come from a local fixture; no authoritative policy call occurs.
python app.py allowed --database /tmp/bhanuj-langgraph-allowed.db
python app.py denied --database /tmp/bhanuj-langgraph-denied.db
python app.py outage --database /tmp/bhanuj-langgraph-outage.db

7. Handle Failures

Visible Failures

The transport-failure scenarios are fault injectors around the same REST client; they do not create a second architecture. Evidence delivery can degrade a read-only result, but an authoritative protected write is stricter: any authorization denial, timeout, expiry, binding mismatch, malformed response, or missing canonical execution blocks SQLite.

# Registration never reaches OSS; the local read still completes.
python app.py registration-failure --database /tmp/bhanuj-langgraph-registration-failure.db

# Registration succeeds, then evidence delivery exhausts bounded retries.
python app.py evidence-failure --database /tmp/bhanuj-langgraph-evidence-failure.db

# The workflow stops after its read and finalizes as cancelled.
python app.py readonly --interrupt-after-read \
  --database /tmp/bhanuj-langgraph-interrupted.db

Status Meaning. AIGP evidence status: COMPLETED means the reporter delivered and finalized the evidence stream. It does not mean the business operation succeeded. Conversely, retryable evidence delivery is never authorization: a protected write requires one valid, current, operation-bound AIGP allow immediately before the tool call.

8. Inspect Evidence

See What Happened in Studio

After the aigp run completes, you do not need to read a database or decode raw events. Open Studio and follow the same path a reviewer would use.

1. STEP 1

   Open Agents Runtime

   Choose Agents Runtime in the Studio sidebar, then stay on the Executions tab.

2. STEP 2

   Choose the LangGraph assistant

   Select LangGraph governed operations assistant to reveal its recent runs.

3. STEP 3

   Open the new run

   Choose the run you just made to see the authorization, tool call, and completion record.

Start in Studio's Agents Runtime area. The Executions tab is where observed assistants and their execution evidence appear. Select LangGraph governed operations assistant. Its recent executions appear directly below the selected-agent summary; choose the run you just created.

The execution inspector shows the ordered evidence: the authorization before the tool call, followed by the completed execution. Event payloads are intentionally not shown.

Policy 1, Delegation-issuance; Policy 2, Runtime-action authorization.

Need the exact IDs for an API check or automated test? Copy the AIGP execution ID printed by the authoritative run. The read route returns that tenant-scoped execution and its timeline; the lab never reads AIGP's SQLite or graph stores directly.

export EXECUTION_ID='<AIGP execution ID printed by the lab>'
curl "$AI_GOVERNANCE_BASE_URL/api/v1/agent-executions/$EXECUTION_ID" \
  -H "Authorization: Bearer $AI_GOVERNANCE_ACCESS_TOKEN" \
  -H "X-AI-Governance-Organization-Id: $AI_GOVERNANCE_ORGANIZATION_ID" \
  -H "X-AI-Governance-Project-Id: $AI_GOVERNANCE_PROJECT_ID"

unset ISSUER_ACCESS_TOKEN RUNTIME_ACCESS_TOKEN AI_GOVERNANCE_ACCESS_TOKEN AI_GOVERNANCE_DELEGATION_ISSUER_ACCESS_TOKEN

python -m pytest -q

export BHANUJ_LAB_INTEGRATION_ENABLED=true
export BHANUJ_LAB_INTEGRATION_BASE_URL=http://localhost:8000
export BHANUJ_LAB_INTEGRATION_ORGANIZATION_ID=org_default
export BHANUJ_LAB_INTEGRATION_PROJECT_ID=project_default
export BHANUJ_LAB_INTEGRATION_ACTOR_ID=local-admin
export BHANUJ_LAB_INTEGRATION_RUNTIME_ACTOR_ID=local-admin
LAB_ROOT="$(pwd)"
OSS_ROOT=/path/to/ai-governance-oss
LAB_SITE_PACKAGES="$("$LAB_ROOT/.venv/bin/python" -c 'import site; print(site.getsitepackages()[0])')"
PYTHONPATH="$LAB_ROOT:$LAB_SITE_PACKAGES" \
  "$OSS_ROOT/.venv/bin/python" -m pytest "$LAB_ROOT/tests/test_oss_api_integration.py" -m integration -q

9. Production Identities

Bring your own identity system

The lab uses Keycloak because it makes the issuer and runtime identities visible locally. In production, your identity system can authenticate those applications, issue short-lived credentials, and manage platform permissions. It does not automatically create AIGP's execution-specific delegation; the integrating application still calls the OSS public API to issue a narrowly scoped delegation.

10. Understand Boundaries

Scope Boundaries