BHANUJ AIGP | Observe OpenAI Agents SDK Handoffs

Overview

Make the ownership transition visible.

A native OpenAI handoff lets the specialist take control of the run. OpenAI Agents SDK remains the execution runtime. Platorm receives independent evidence for the outgoing and incoming agent steps without becoming an orchestrator.

You will learn

Why an SDK handoff is an orchestration transition, not a BHANUJ TOOL_CALL.

You will build

One two-agent run with a visible handoff and one real lookup_policy tool call.

Architecture

Handoff ownership stays with the SDK.

Execution plane

OpenAI Agents SDK

Runs the triage agent, native handoff, specialist, and local function tool.

Evidence plane

BHANUJ Agents Runtime

Records bounded ordered evidence and the peer-agent transition.

Claims Triage AgentPolicy Validation Agentlookup_policyfinal response

The handoff closes the active triage WORKFLOW_STEP with bounded transition facts, then starts the specialist step. It does not create a parent/child hierarchy and never emits TOOL_CALL transfer_to_policy_validation.

Prerequisites

What you need.

Python 3.12 or later and pip.
An OpenAI API key and an available model.
BHANUJ OSS only when you want to send runtime evidence.

Run locally

Run the native handoff first.

The lab pins openai-agents==0.22.2. It needs an OpenAI API key, but no database, cloud infrastructure, or BHANUJ connection.

terminal

git clone https://github.com/Bhanuj-AI/labs.git
cd labs/agent-frameworks/openai/openai-agents-handoff-intg
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
export OPENAI_API_KEY=...
export OPENAI_MODEL=gpt-5-mini

terminal

python app.py

expected model result

Agent result: Policy POL-100: ACTIVE.

Enable evidence

Connect the same run to BHANUJ OSS.

Start BHANUJ OSS in development mode, set the runtime-scope variables, and rerun the unchanged agent workflow.

terminal · AI Governance 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

Agent result: Policy POL-100: ACTIVE.
BHANUJ execution ID: <execution-id>
BHANUJ evidence status: SUCCEEDED

Failure isolation: evidence delivery is fail-open. An unavailable BHANUJ API cannot change the handoff destination, tool result, model output, or original SDK exception. It never fabricates successful evidence.

Inspect the execution

Follow one execution ID across both agents.

The CLI prints the execution ID after start acceptance. Find that exact record in Agents Runtime to inspect the step transition, three model calls, and one real tool call.

Agents Runtime timeline SUCCEEDED

1Claims Triage Agent · Step StartedWORKFLOW_STEP
2Claims Triage Agent · Model Completed · 1MODEL_CALL
3Claims Triage Agent · Step Completed · HandoffWORKFLOW_STEP
4Policy Validation Agent · Step Started · HandoffWORKFLOW_STEP
5Policy Validation Agent · Model Completed · 2MODEL_CALL
6lookup_policy · Tool CompletedTOOL_CALL
7Policy Validation Agent · Model Completed · 3MODEL_CALL
8Policy Validation Agent · Step CompletedWORKFLOW_STEP

The platform adds EXECUTION_STARTED and completion records. Prompts, conversation history, handoff arguments, model output, reasoning, tool arguments, and tool output are excluded from evidence.

OpenAI Agents SDK references

Ready to run it?

Fork the lab, observe the real SDK handoff locally, then enable Agents Runtime evidence.

Fork on GitHub Open repository source

Observe OpenAI Agents SDK handoffs