BHANUJBHANUJ
LabIntermediate~15 min

Observe Claude Agent SDK subagents

SupportedPython 3.12+Claude Agent SDK 0.2.152Agents RuntimeWORKFLOW_STEP + TOOL_CALL

Follow a Claude agent as it passes work to a research helper, uses a local policy tool, and returns a final answer.

Last updated
Fork the lab repository View source
Execution evidence SUCCEEDED
Main Agentobserved
Research Subagentobserved
lookup_policyobserved
Main Agent final answerobserved

4+ MODEL_CALL · 1 TOOL_CALL · 4 WORKFLOW_STEP events

Overview

Observe a handoff without taking control of it.

Claude Agent SDK owns delegation, isolated subagent execution, the custom tool, final response, and exceptions. BHANUJ Platform receives a one-way, provider-neutral record of lifecycle boundaries only.

You will learn

How public SubagentStart and SubagentStop signals map Claude subagent lifecycle to WORKFLOW_STEP evidence.

You will build

One Claude session containing a visible Main Agent → Research Subagent → Main Agent ownership handoff.

Architecture

One main agent, one real subagent, one local tool.

Main AgentResearch Subagentlookup_policyMain Agent final answer

Execution plane

Claude Agent SDK

Delegates to Research Subagent and executes its local MCP policy tool.

Evidence plane

BHANUJ Platform

Records ordered lifecycle facts without transcripts or tool payloads.

The main agent has only Claude's public Agent capability. Research Subagent is programmatically declared and has only mcp__policy__lookup_policy; it cannot create another agent.

Run locally

Run the Claude handoff without BHANUJ Platform first.

No external MCP process, database, web tool, filesystem tool, or additional agent is required. The local policy fixture is deterministic; Claude's response wording is not.

terminal
git clone https://github.com/Bhanuj-AI/labs.git
cd labs/agent-frameworks/anthropic/claude-agent-subagent-intg
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
export ANTHROPIC_API_KEY=...
export CLAUDE_MODEL=claude-sonnet-4-6
terminal
python app.py
expected output
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 exact same execution to BHANUJ OSS.

Start your BHANUJ OSS deployment, configure its existing runtime scope, then run the same application. The Claude session ID is the external correlation ID; the Platform execution ID is printed after successful evidence creation.

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
BHANUJ Platform evidence: delivered
BHANUJ Platform execution ID: <execution-id>
Failure isolation: evidence transport is one-way, fail-open, non-retrying, and bounded to a short timeout. BHANUJ Platform availability cannot alter delegation, tool execution, the final answer, or application exceptions.

Inspect the execution

See ownership move from main agent to subagent and back.

Search Agents Runtime using the printed execution ID. The ordered timeline makes the handoff visible without recording the prompts, Claude response text, subagent result, tool arguments, or tool result.

Agents Runtime timeline SUCCEEDED
  1. 1Main Agent · Step StartedWORKFLOW_STEP
  2. 2Claude · Main Agent model turnMODEL_CALL
  3. 3Research Subagent · Step StartedWORKFLOW_STEP
  4. 4Claude · Research Subagent model turnsMODEL_CALL
  5. 5lookup_policy · Tool SucceededTOOL_CALL
  6. 6Research Subagent · Step CompletedWORKFLOW_STEP
  7. 7Claude · Main Agent final turnMODEL_CALL
  8. 8Main Agent · Step CompletedWORKFLOW_STEP

The Agent Executions API adds execution-started and completion records. Python's public subagent lifecycle callbacks do not include the main workflow-step ID, so the guide does not invent a parent_step_id; ownership is preserved by ordered subagent lifecycle evidence.

Claude Agent SDK references