BHANUJ AIGP | Connect Claude Agent SDK workflow

Overview

Observe the run. Keep Claude Agent SDK in control.

The lab runs a real Claude Agent SDK session with one real local custom tool. Claude Agent SDK owns the model turns, tool selection, tool execution, final answer, and exceptions. BHANUJ Platform receives a separate, one-way record of runtime boundaries.

You will learn

How public Claude Agent SDK messages and MCP tool hooks map a session, model calls, and one custom tool to runtime evidence.

You will build

One correlated execution for one Claude session, with no custom SDK internals, tracing interception, or external MCP process.

Architecture

One agent and one actual application tool.

Execution plane

Claude Agent SDK

Runs Claude, the in-process MCP server, and the policy tool.

Evidence plane

BHANUJ Platform

Records bounded, ordered runtime evidence only.

Claude Agent SDKPolicy Validation Agentlookup_policyBHANUJ Platform runtime evidence

The SDK is configured with tools=[] to disable built-in tools, and it pre-approves only mcp__policy__lookup_policy. The policy fixture remains local and deterministic.

Prerequisites

What you need.

Python 3.11 or later and pip.
An Anthropic API key and an available Claude model.
The BHANUJ OSS repository only when you want to send runtime evidence.

Run locally

Run without BHANUJ Platform first.

The lab pins claude-agent-sdk==0.2.152. It needs Anthropic credentials and a model, but no database, cloud infrastructure, external MCP server, or BHANUJ Platform connection.

terminal

git clone https://github.com/Bhanuj-AI/labs.git
cd labs/agent-frameworks/anthropic/claude-agent-tool-intg
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
export ANTHROPIC_API_KEY=...
export CLAUDE_MODEL=...

terminal

python app.py

expected model result

Policy: POL-1001
Claude session ID: <uuid>
Final answer: Policy POL-1001 is active, so the claim can proceed.
BHANUJ Platform evidence: disabled

Enable evidence

Connect the unchanged run to BHANUJ OSS.

Start BHANUJ OSS in development mode, set the three runtime-scope variables, and run the same app. Claude Agent SDK remains independently owned by the application.

terminal · BHANUJ OSS

cd /path/to/ai-governance-oss
AI_GOVERNANCE_AUTH_MODE=development \
  uv run uvicorn ai_governance.api.app:app --reload

terminal · lab repository

export AI_GOVERNANCE_BASE_URL=http://localhost:8000
export AI_GOVERNANCE_ORGANIZATION_ID=org_default
export AI_GOVERNANCE_PROJECT_ID=project_default
python app.py

expected governed output

Policy: POL-1001
Final answer: <Claude answer>
BHANUJ Platform evidence: delivered
BHANUJ Platform execution ID: <execution-id>

Failure isolation: evidence delivery is fail-open with one short, non-retrying attempt. An unavailable API cannot change Claude's tool selection, the local tool result, Claude's final answer, or application exceptions—and it never fabricates successful evidence.

Inspect the execution

One Claude session ID correlates the run.

The app creates a public Claude session ID before it starts the query and reuses it as the external execution identity. When creation succeeds, the CLI also prints the BHANUJ Platform execution ID. Find either correlation in Agents Runtime to inspect ordered evidence.

Agents Runtime timeline SUCCEEDED

1Policy Validation Agent · Step StartedWORKFLOW_STEP
2Claude model · Model Completed · 1MODEL_CALL
3lookup_policy · Tool SucceededTOOL_CALL
4Claude model · Model Completed · 2MODEL_CALL
5Policy Validation Agent · Step CompletedWORKFLOW_STEP

The execution also contains platform-generated EXECUTION_STARTED and completion records. BHANUJ Platform receives no prompt, Claude response text, tool arguments, tool result, credentials, or raw SDK payload.

Claude Agent SDK references

Ready to run it?

Fork the lab, run the real Claude agent and local tool, then enable runtime evidence when BHANUJ OSS is available.

Fork on GitHub Open repository source