Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 39 ยท Multi-agent Systems

Agent Handoffs and Shared State

Learn how AI agents pass a conversation to each other with handoffs, share state safely through a blackboard, and avoid loops, lost context and conflicts.

When several agents cooperate, two questions decide whether the system works: how does control move from one agent to another, and how do they share what they know? The first is a handoff. The second is shared state. Get either wrong and agents repeat each other's work, lose the user's request or loop forever.

In this lesson you will build a handoff system where agents transfer a conversation, a shared "blackboard" of state with clear ownership, and a simple message protocol. You will also see the standard safeguards: handoff limits, loop detection and explicit context transfer.

Real agent SDKs expose handoffs as part of their API, but none can run on this site. Everything below is plain Python with stand-in agents; the mechanics are what those SDKs do internally.

What is a handoff?

A handoff transfers control of the conversation from one agent to another. The new agent takes over answering the user, usually with a different prompt and tool set. Think of a phone call being transferred from reception to billing.

A handoff usually carries three things:

  • the target agent,
  • the reason or summary ("customer wants a refund for order 118"),
  • the state that should travel with it (user id, order id, what has been tried).

In most SDKs a handoff is a special kind of tool call: the agent "calls" transfer_to_billing, and the runtime switches the active agent.

A runnable handoff loop

Each agent here is a function that returns either a final answer or a handoff to another agent. The runtime loops until an answer appears, and refuses to bounce forever.

Python Triage, billing and human handoffs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The trail list records which agents touched the conversation. It is invaluable for debugging and appears again in observability and tracing. The max_handoffs limit guarantees the loop ends.

Passing context

The receiving agent starts with an empty mind unless you give it context. There are two common choices:

  • Full history: pass every message. Safe and simple, but expensive and may expose details the new agent does not need.
  • Summary plus state: pass a short handoff note and a few structured fields. Cheaper and focused, but the note must be good.

A good rule: pass the user's original goal, what has already been tried, and the structured facts (ids, dates, preferences). Do not pass another agent's internal reasoning.

Shared state: the blackboard

Instead of passing everything in messages, agents can read and write a shared blackboard (also called state or scratchpad). Each agent reads what it needs, posts results and moves on. This decouples agents: the writer does not need to know who produced the facts.

Python A blackboard with owners and history

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The log answers "who changed this?" which becomes critical when something goes wrong. For safety, give each key one owner (only the researcher writes sources) or use versioning, so two agents never silently overwrite each other.

Direct messages versus shared state

Approach Strength Weakness
Direct messages Clear flow, easy to follow Agents must know each other
Shared blackboard Loose coupling, flexible Conflicts and hidden dependencies
Hybrid Messages for control, state for data More design work

Most real systems use the hybrid: a handoff message says "your turn", and the data lives in typed state.

A message format

Agree on a small, typed envelope instead of free text:

Python
message = {
    "from": "researcher",
    "to": "writer",
    "type": "result",        # request, result, error, question
    "task_id": "t2",
    "content": {"summary": "3 sources found", "sources": ["a", "b", "c"]},
}

Typed messages can be validated, logged and replayed. Free text between agents invites misunderstanding.

Failure modes and safeguards

  • Ping-pong loops: A hands to B, B hands back to A. Cap handoffs and detect repeated pairs.
  • Dropped context: the new agent asks the user to repeat themselves. Pass state, not just history.
  • Conflicting writes: use owners, versions or a single writer per key.
  • Privilege leaks: a handoff to a more powerful agent can bypass a restriction. Re-check permissions after every handoff (see human-in-the-loop and permissions).
  • Stale state: an agent acts on information another agent has already changed. Read just before acting.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does a handoff do?

    The receiving agent takes over answering, usually with its own prompt and tools.
  2. 2. Why cap the number of handoffs?

    A limit guarantees termination even if routing is confused.
  3. 3. What is a good set of things to pass in a handoff?

    That gives the new agent enough to continue without repeating questions.
  4. 4. What is a blackboard in multi-agent design?

    Agents post results to shared state instead of passing everything directly.
  5. 5. How can you avoid two agents overwriting each other's data?

    Ownership or versions make conflicts visible and prevent silent overwrites.

Summary

  • A handoff transfers control; carry the reason and key state with it.
  • Cap handoffs and track the trail to catch loops.
  • A blackboard shares state loosely; log writes and give keys owners.
  • Use typed messages for control and typed state for data.
  • Re-check permissions after each handoff and read state right before acting.

Next: Evaluating Agents