Debugging Multi-Agent Handoffs: Tracing Context Loss During Agent Transitions

The Invisible Context Drop

A user tells your triage agent they want to reschedule their appointment for Tuesday at 2 PM. The triage agent hands off to the scheduling agent. The scheduling agent asks: "What time would you like to schedule your appointment?" The user is frustrated — they just said Tuesday at 2 PM.

Context loss during agent handoffs is one of the hardest bugs to diagnose because it is invisible in logs that only capture text. The handoff succeeds — no errors, no exceptions. But the receiving agent does not have the information it needs because the conversation context was not transferred correctly.

Anatomy of a Handoff

In the OpenAI Agents SDK, a handoff transfers control from one agent to another. The key question is: what data travels with the handoff?

flowchart TD
    START["Debugging Multi-Agent Handoffs: Tracing Context L…"] --> A
    A["The Invisible Context Drop"]
    A --> B
    B["Anatomy of a Handoff"]
    B --> C
    C["Building a Handoff Inspector"]
    C --> D
    D["Debugging Context Variable Serialization"]
    D --> E
    E["State Verification After Handoff"]
    E --> F
    F["Enriching Handoffs with Summaries"]
    F --> G
    G["FAQ"]
    G --> DONE["Key Takeaways"]
    style START fill:#4f46e5,stroke:#4338ca,color:#fff
    style DONE fill:#059669,stroke:#047857,color:#fff

from agents import Agent, handoff

scheduling_agent = Agent(
    name="Scheduling Agent",
    instructions="Help users schedule and reschedule appointments.",
)

triage_agent = Agent(
    name="Triage Agent",
    instructions="Route user requests to the appropriate agent.",
    handoffs=[scheduling_agent],
)

When the triage agent decides to hand off, the conversation history is passed to the new agent. But the quality of that history depends on what the triage agent included in its messages and how the handoff was configured.

Building a Handoff Inspector

Create an inspector that captures and displays the exact state being transferred:

import json
from dataclasses import dataclass, field
from typing import Any

@dataclass
class HandoffSnapshot:
    from_agent: str
    to_agent: str
    conversation_history: list[dict]
    context_variables: dict
    timestamp: float
    history_token_count: int = 0

class HandoffInspector:
    def __init__(self):
        self.snapshots: list[HandoffSnapshot] = []

    def capture(
        self,
        from_agent: str,
        to_agent: str,
        messages: list[dict],
        context: dict,
    ):
        snapshot = HandoffSnapshot(
            from_agent=from_agent,
            to_agent=to_agent,
            conversation_history=json.loads(json.dumps(messages)),
            context_variables=json.loads(json.dumps(context)),
            timestamp=__import__("time").time(),
        )
        self.snapshots.append(snapshot)
        return snapshot

    def diff_context(self, index_a: int, index_b: int):
        """Compare context between two handoff snapshots."""
        a = self.snapshots[index_a].context_variables
        b = self.snapshots[index_b].context_variables

        added = {k: v for k, v in b.items() if k not in a}
        removed = {k: v for k, v in a.items() if k not in b}
        changed = {
            k: {"before": a[k], "after": b[k]}
            for k in a
            if k in b and a[k] != b[k]
        }

        print(f"Context diff: snapshot {index_a} -> {index_b}")
        if added:
            print(f"  Added: {json.dumps(added, indent=2)}")
        if removed:
            print(f"  Removed: {json.dumps(removed, indent=2)}")
        if changed:
            print(f"  Changed: {json.dumps(changed, indent=2)}")

Debugging Context Variable Serialization

Context variables must be serializable. Non-serializable objects silently fail or get dropped:

from datetime import datetime, date

class ContextValidator:
    SAFE_TYPES = (str, int, float, bool, type(None), list, dict)

    @classmethod
    def validate(cls, context: dict) -> list[str]:
        """Find context values that may fail serialization."""
        issues = []
        for key, value in context.items():
            cls._check_value(key, value, issues)
        return issues

    @classmethod
    def _check_value(cls, path: str, value: Any, issues: list):
        if isinstance(value, datetime):
            issues.append(
                f"{path}: datetime object — convert to ISO string"
            )
        elif isinstance(value, date):
            issues.append(
                f"{path}: date object — convert to ISO string"
            )
        elif isinstance(value, set):
            issues.append(
                f"{path}: set — convert to list"
            )
        elif isinstance(value, dict):
            for k, v in value.items():
                cls._check_value(f"{path}.{k}", v, issues)
        elif isinstance(value, list):
            for i, v in enumerate(value):
                cls._check_value(f"{path}[{i}]", v, issues)
        elif not isinstance(value, cls.SAFE_TYPES):
            issues.append(
                f"{path}: unsupported type {type(value).__name__}"
            )

# Usage
context = {
    "user_name": "Alice",
    "appointment_time": datetime(2026, 3, 17, 14, 0),
    "preferences": {"tags": {"urgent", "follow-up"}},
}
issues = ContextValidator.validate(context)
for issue in issues:
    print(f"  WARNING: {issue}")
# WARNING: appointment_time: datetime object — convert to ISO string
# WARNING: preferences.tags: set — convert to list

State Verification After Handoff

Add assertions that verify the receiving agent has everything it needs:

class HandoffVerifier:
    def __init__(self):
        self.requirements: dict[str, list[str]] = {}

    def register_agent(self, agent_name: str, required_context: list[str]):
        self.requirements[agent_name] = required_context

    def verify_handoff(self, to_agent: str, context: dict) -> list[str]:
        required = self.requirements.get(to_agent, [])
        missing = [key for key in required if key not in context]
        return missing

# Define what each agent needs
verifier = HandoffVerifier()
verifier.register_agent("Scheduling Agent", [
    "user_id", "requested_date", "requested_time",
])
verifier.register_agent("Billing Agent", [
    "user_id", "account_id", "issue_type",
])

# Check before handoff
missing = verifier.verify_handoff("Scheduling Agent", context)
if missing:
    print(f"HANDOFF BLOCKED — missing context: {missing}")

Enriching Handoffs with Summaries

When conversation history is long, the receiving agent may lose important details buried in earlier messages. Add a handoff summary:

from agents import handoff

def create_summarized_handoff(target_agent, summary_fn):
    async def on_handoff(ctx):
        summary = await summary_fn(ctx.messages)
        ctx.messages.append({
            "role": "system",
            "content": f"Handoff summary: {summary}",
        })

    return handoff(
        agent=target_agent,
        on_handoff=on_handoff,
    )

FAQ

How do I tell if context was lost versus the receiving agent just ignoring available context?

Compare the conversation history at the point of handoff against what the receiving agent actually processes. If the information is in the message history but the agent does not use it, the problem is the receiving agent's instructions — it needs explicit guidance to review prior messages. If the information is missing from the history, the problem is in the handoff mechanism.

Should I pass context as conversation history or as structured context variables?

Use both. Conversation history provides natural language context the model can reason over. Context variables provide structured data like user IDs, dates, and settings that must be exact. Relying solely on conversation history risks the model misinterpreting or overlooking critical details buried in long message chains.

How do I debug context loss in production without exposing user data in logs?

Implement a redaction layer that replaces sensitive values with tokens before logging. Log the structure and keys of context variables without their values. Use correlation IDs to link handoff events across agents so you can trace the flow without seeing the actual content.

---

#Debugging #MultiAgent #Handoffs #ContextManagement #AIAgents #AgenticAI #LearnAI #AIEngineering