Handing off between agents

Two things cross a handoff#

The concierge’s model saw a request, a search result, an availability check, a booking call and a timeout. That is the conversation most handoff mechanisms are designed to move.

The runtime, the code that executes tools and tracks the work, knew things the model did not. It had assigned the booking’s key. It had marked the operation as in doubt. It knew the task had started with the user, rather than with a restaurant webhook. If an approval were pending, it would also know which action the user was being asked to approve.

There is a good reason to keep those details out of the model’s context, but they still have to move with the task.

These payloads serve different readers. A summary can be a good input to the next model. An unsettled operation needs an exact identifier and a known state. It should survive the handoff whether or not a summary mentions it.

What the frameworks pass#

The common handoff styles make different choices about conversation history. These are the documented mechanisms the demo starts from, in the docs’ own words:

There are good reasons to argue about how much history to send. Cognition, the company behind the Devin coding agent, makes the case for sharing “full agent traces, not just individual messages” (Don’t Build Multi-Agents), to preserve the context behind earlier decisions. A short brief costs less to read, but it can leave out something the next model needs.

Neither choice, by itself, settles what happens to work already in progress. These conversation mechanisms do not define the application’s record of outstanding restaurant requests. A framework may give you a place to carry that record, such as shared context or a structured message part. You still have to write it and make the receiver use it.

What Bookings’ model actually gets#

The demo compares five ways of forwarding words with a sixth option that adds the runtime’s record. It scripts the receiving model to behave sensibly: if anything it reads suggests a booking was attempted, it looks for that booking before making another. There are no live model calls, so the comparison isolates what the handoff carries.

Start with the full transcript. This is the companion program’s plain rendering of the messages; a provider’s API would wrap them in its own format.

-- Bookings' model reads: full transcript, 9 item(s), 1838 B
 1  user                               Book Friday at seven for four at Chez Lili and text the group once it's confirmed.
 2  assistant, tool call               search_restaurants {"q": "Chez Lili", "near": "Paris"}
 3  tool result, search_restaurants    [{"name": "Chez Lili", "cuisine": "bistro", "rating": 4.6,... (1053 B in all)
 4  assistant, tool call               check_availability {"day": "Fri", "time": "19:00", "party": 4}
 5  tool result, check_availability    available
 6  assistant                          Friday at 19:00 is free. Booking it now.
 7  assistant, tool call               reserve_table {"day": "Fri", "time": "19:00", "party": 4}
 8  tool result, reserve_table         error: no reply from the restaurant within 10 s
 9  assistant                          The restaurant isn't answering. Handing over to Bookings: Friday at 19:00 for four.
-- no record: Bookings' runtime has nothing of its own to act on

Item 7 has the arguments the model supplied: day, time and party size. It has no idempotency key. The runtime attached s1:op-a2 when it sent the request, so sending more of this conversation cannot recover it. Item 3 alone accounts for 1,053 bytes of the payload.

A delegation brief removes most of that bulk. This one retains the fact that a booking went out:

-- Bookings' model reads: model brief, mentions the call, 1 item(s), 265 B
 1  user                               task: Book the table
                                      context: User wants Chez Lili, Friday 19:00, party of 4; text the group once confirmed.
                                        I already sent the booking request but the restaurant didn't reply within 10 s.
                                      coworker: Bookings
-- no record: Bookings' runtime has nothing of its own to act on

That last sentence is useful. It gives Bookings a reason to look for an existing reservation, though still no way to identify the exact request. Without it, the brief falls to 185 bytes, and Bookings has no reason to look before booking.

With a runtime record attached, the model gets the shortest input of all: the user’s original request, one item and 112 bytes. The separate 310-byte record goes to the receiving runtime.

-- Bookings' model reads: runtime handoff record, 1 item(s), 112 B
 1  user                               Book Friday at seven for four at Chez Lili and text the group once it's confirmed.
-- not for the model: the record, 310 B, which Bookings' runtime acts on first
    {
      "task": "book Fri 19:00 for 4 at Chez Lili, then text the group",
      ...
    }

Here are the outcomes under both network timings. “Landed” means the restaurant made the booking but its reply was lost. “Delayed” means the request was still travelling at the handoff.

From python -m agent_runtime.handoff. Bytes measure the payload as compact JSON, the way JavaScript’s JSON.stringify writes it. They are not token counts.

The last-pair handoff illustrates one of those gaps. It retains enough narration for the scripted receiver to look for a booking, but it loses the user’s instruction to text the group after confirmation. Counting reservations alone would miss that broken promise.

”Nothing found” doesn’t mean “nothing will happen”#

The first four rows use the same fallback: look for a table on Friday at 19:00 for four people. If the original request has already landed, the lookup finds it and Bookings stops, though that outcome comes from when the network delivered the request rather than from anything Bookings knew. If the request is still travelling, the lookup finds nothing and Bookings makes another reservation. The lookup answers what is in the restaurant’s database now. It says nothing about a request that may arrive next.

This is the in-doubt operation from the revision post, now crossing an agent boundary. The sender dispatched a request and does not know whether it took effect, and a timeout does not settle that question.

The demo’s restaurant supports closing a key: in one operation, it reports whether that request landed and refuses any later attempt under the same key. If the service cannot do that, the alternative described in the revision post is to wait for the call to finish, or for a deadline enforced by the service to pass. Either approach needs the identity of the outstanding request.

A lookup by details has a second problem: those details need not belong to this booking. In another run, a different customer already has a Friday 19:00 table for four. Bookings finds that reservation and reports it as the user’s. The user’s delayed request then arrives separately.

 1  restaurant        R1 Fri 19:00 x4 is another customer's booking
 ...
 6  model.read        sees reserve_table sent, and no result
 7  lookup.details    Fri 19:00 x4: R1 (no key to close)
 8  restaurant        committed R2 Fri 19:00 x4
-- restaurant holds: R1 (Fri 19:00, another customer's), R2 (Fri 19:00)
-- agent's last message: Booked Fri 19:00 for 4 (R1). Texting the group.

A request key identifies the operation, while a date, time and party size only describe what it was trying to do. The companion tests check that the key is absent from every words-only style in this example.

The filter that erases the call#

Removing tool history is an appealing shortcut. Search results are large, availability checks go stale, and the receiving agent can often repeat a read. The OpenAI Agents SDK ships a remove_all_tools handoff filter for this, documented as “Filters out all tool items: file search, web search and function calls+output”.

At the commit used here, its removal list includes ToolCallItem, ToolCallOutputItem and ToolApprovalItem. Those item types cover more than disposable context. A booking in doubt and an approval awaiting a decision are removed along with the search results. After filtering this conversation, only three messages remain:

-- Bookings' model reads: transcript, tools removed, 3 item(s), 303 B
 1  user                               Book Friday at seven for four at Chez Lili and text the group once it's confirmed.
 2  assistant                          Friday at 19:00 is free. Booking it now.
 3  assistant                          The restaurant isn't answering. Handing over to Bookings: Friday at 19:00 for four.
-- no record: Bookings' runtime has nothing of its own to act on

The actual call is gone, and “Booking it now” is all that remains of the attempt. The scripted reader notices that sentence and looks for a reservation, which gives this row the same outcomes as the full transcript:

 ...
 5  handoff           concierge -> bookings: transcript, tools removed (words 303 B, record none)
 6  model.read        reads "Booking it now", and no result
 7  lookup.details    Fri 19:00 x4: R1 (no key to close)
-- restaurant holds: R1 (Fri 19:00)
-- agent's last message: Booked Fri 19:00 for 4 (R1). Texting the group.

That result depends on the model having narrated the call. A quieter assistant could leave no trace of it in ordinary messages. The brief that omits the call demonstrates the consequence: Bookings starts a new reservation under either network timing. There is still a good reason to trim the conversation, provided the unfinished work is preserved before a filter removes its visible trace.

The handoff record#

The sending runtime therefore needs to write down what it knows before handing the task over. In the demo, that is a task description and four fields. The record is written out by hand, standing for what the sending runtime would fill in from its operations log:

1
RECORD = {
2
    "task": "book Fri 19:00 for 4 at Chez Lili, then text the group",
3
    "origin": "user",
4
    "constraints": ["text the group only after the booking is confirmed"],
5
    "open_operations": [{"op": "op-a2", "tool": "reserve_table", "args": {"day": "Fri", "time": "19:00", "party": 4},
6
                         "key": CONCIERGE_KEY, "state": "unknown"}],
7
    "pending_actions": [],
8
}

• origin preserves who started the task. A request from the user and a request triggered by a restaurant’s webhook can look similar in a chat message, but they do not carry the same permission to act. The turn post made this the rule for every turn.
• constraints preserves the limits on the plan. “Text the group once it’s confirmed” means confirmation must come first, and the obligation has to survive a handoff that trims away the original message.
• open_operations names each request with an effect that has not been settled. Its arguments describe it, its key identifies it, and unknown records that its outcome is in doubt.
• pending_actions carries decisions waiting for the user. It is empty in this run. When an approval is pending, the action and its ID need to move together, so the receiver does not ask again or treat silence as approval.

The receiver acts on the open operation before its model plans another booking:

1
in_doubt = [o for o in (record or {}).get("open_operations", []) if o["state"] == "unknown"]
2
if in_doubt:
3
    op = in_doubt[0]
4
    rid = restaurant.close(op["key"])
5
    tl.add("resolve", f"{op['key']}: {rid or 'nothing has landed'}; key closed")
6
    if rid:
7
        return rid

This example has one in-doubt operation, which is why the snippet takes the first entry. A receiver taking over several operations would have to settle each one before proceeding. The ordering is the same either way: resolve existing work, then plan new work.

restaurant.close checks and closes the key in one step. If the reservation already exists, the receiver adopts it. If it does not, the restaurant records that the old key is closed, and Bookings can make a new request under its own key without leaving the first one able to create a second table:

 ...
 4  handoff           concierge -> bookings: runtime handoff record (words 112 B, record 310 B)
 5  resolve           s1:op-a2: nothing has landed; key closed
 6  tool.sent         s2 reserve_table(Fri, 19:00, 4) key=s2:op-a1
 7  restaurant        committed R1 Fri 19:00 x4
 8  tool.result       s2 reserve_table -> R1
 9  restaurant        refused a late request: key s1:op-a2 is closed
-- restaurant holds: R1 (Fri 19:00)
-- agent's last message: Booked Fri 19:00 for 4 (R1). Texting the group.

The old request still arrives, and this time it is refused.

In the lab, you can switch between all six handoff styles and both network timings. Start with the full transcript and a delayed request, then change only the handoff to the runtime’s record. Compare what the model reads with the last lines of the runtime log:

Authority doesn’t cross by itself#

The booking race is visible in the restaurant’s final count. Losing the task’s origin can be harder to spot, because the next agent may complete exactly what it was told to do, under authority the sender never had.

Suppose a restaurant webhook starts the task. By the time it reaches Bookings or Messaging, it may be wrapped in an ordinary message from the concierge. That wrapper does not turn the restaurant’s request into the user’s instruction to book something or text the group.

The event-bus post covers the attack. The handoff’s responsibility is narrower: preserve the origin, so the receiving runtime can apply the same approval rule as the sender. The record must come from the runtime’s account of the task, not from a model’s guess about who seems to be speaking.

What to drop on purpose#

Once the runtime state has somewhere reliable to go, the conversation becomes easier to cut. The full transcript’s largest item is a search result: five restaurants, with addresses, ratings and phone numbers. It occupies 1,053 of the 1,838 bytes, and Bookings already knows which restaurant the user chose. For this task, I would make these cuts:

There is a privacy reason to make those cuts as well. The OpenAI docs warn that nesting the history “does not redact sensitive data” and say to “Treat the receiving agent and its model provider as recipients of the forwarded history” (handoffs.md). Putting old messages inside a summary wrapper does not change who can read them.

On the multi-agent platform I architected for inbound communications, handoffs between agents were events, and the privacy design limited what each stage could see. The small record here follows the same approach. Work that the next runtime must resolve crosses explicitly, and the model receives only the context it needs for its part of the task.

Check what actually crosses#

The thing worth inspecting is the payload that reaches the next agent, after any filters or summaries have run. Capture it at the receiving side, then compare it with the sending runtime’s operations log. For every request with an effect that is still in doubt, the key should appear in the record, not only a description of the call in the words.

If the sending runtime doesn’t write a record yet, this is the shape to start from. Every placeholder is something the runtime knows and the transcript does not:

1
{
2
  "origin": "<user, or the system that started the task>",
3
  "constraints": ["<what the user asked for that limits the plan>"],
4
  "open_operations": [
5
    {"tool": "<the call with an effect>", "key": "<its idempotency key>", "state": "unknown"}
6
  ],
7
  "pending_actions": []
8
}

Fill it from the operations log, not from the conversation. A key that never reached the transcript cannot be recovered from it later.

Five questions for your handoff#

For a handoff that can trigger real actions, these are the questions I would put in the review:

1. Which operations are unsettled, and does each key cross? Check the runtime’s operations log against the receiving payload. A transcript that mentions a call is not enough if it omits the identifier needed to settle it.
2. What does the receiver do before planning? Close or otherwise settle each in-doubt operation under the service’s contract, and make that ordering part of the runtime.
3. Whose authority does the task carry? Preserve its origin independently of message roles and summaries, then apply the corresponding permission rules.
4. What is waiting for the user’s yes? Carry the pending action with the same ID and scope, so that moving between agents does not change what a later approval means.
5. Which words still need to cross? Once the first four have a reliable representation, remove the context the next model does not need.

Run the two timings#

The handoff runs live in mainlog-code/turn-without-the-user, in agent_runtime/handoff.py. They reuse the fake restaurant, idempotency keys and log format from the turn and revision posts.

cd mainlog-code/turn-without-the-user

python -m agent_runtime.handoff                          # compare the six handoff styles
python -m agent_runtime.handoff --sees full              # what Bookings' model reads, one style
python -m agent_runtime.demo handoff-full-delayed        # the opening
python -m agent_runtime.demo handoff-record-delayed      # with the record

python -m pip install pytest
python -m pytest tests                                   # 83 tests, 11 of them for handoffs

CI checks the lab’s recorded runs, the comparison table and each style’s model input. It also checks the two outcomes the argument depends on: two tables in the opening run, and the refusal of the late request in the record run.

The limits are in the README. Both agents run in one process, and the receiving model is scripted. “Lookup by details” is a helper over the fake restaurant’s bookings, not an API every restaurant provides. The demo shows what these payloads allow under two specific timings; it is not a benchmark of the frameworks or a complete distributed handoff protocol.

For an existing system, I would start with those same two timings. First let the request take effect while its reply is lost, then delay the request itself until after the handoff. A receiver tested only on the first case will pass, and still book twice when the second one happens.

This record carries one task across an agent boundary. Some information needs to survive well beyond that task: what the user said last month, what the restaurant claimed, and what has changed since. That is the subject of What an agent should remember.