Cross-agent handoff

Why hand off?

A planner finishes its part and a separate writer agent should take over. Or a run moves between two processes, two machines, even two teams. Because every checkpoint is already a content-addressed blob on Walrus, handing off doesn't copy any state. It just passes a small descriptor, the receiver pulls the real bytes itself.

How it works

handoff_checkpoint emits a portable descriptor: the blob_id, its blob_sha256, and provenance (source thread/checkpoint, optional to_agent label). The receiver calls adopt_checkpoint, which re-fetches that exact blob straight from Walrus, recomputes the SHA-256, and compares it to the sender's hash. On a match it writes the state as the genesis checkpoint of a new thread with an adopted_from lineage link. On a hash mismatch it refuses the adoption, since the blob was altered in transit.

Step 1: export the handoff (sender)

handoff_checkpoint(
  thread_id="run-42",
  checkpoint_id="0c3b84d1-…",
  to_agent="writer",
)

It returns a descriptor you pass to the receiver as-is:

{
  "source": "run-42:0c3b84d1-…",
  "thread_id": "run-42",
  "checkpoint_id": "0c3b84d1-…",
  "blob_id": "WL4TgZgqRE9Pwq1UEclzBJu89KFaaLe75p004_9gJyw",
  "blob_sha256": "e3b0c44298fc1c149afbf4c8996fb924…",
  "to_agent": "writer",
  "summary": "researcher gathered 3 sources"
}

Step 2: adopt it (receiver)

The receiving agent passes the descriptor and a fresh thread id. Adopt re-fetches and verifies before writing anything:

adopt_checkpoint(
  handoff_json={ /* the descriptor from step 1 */ },
  new_thread_id="run-42-writer",
)

{
  "adopted_from": "run-42:0c3b84d1-…",
  "new_thread_id": "run-42-writer",
  "checkpoint_id": "1f164ec0-…",
  "blob_id": "PsdXuRtdH0GiLO5R8rkqYTG7ZO_jQc8axU_mRiw3us4",
  "verified": true
}

Via the Python API

from langgraph_checkpoint_walrus import WalrusSaver, WalrusClient

saver = WalrusSaver(WalrusClient())

# Sender:
descriptor = saver.handoff_checkpoint(
    thread_id="run-42",
    checkpoint_id="0c3b84d1-…",
    to_agent="writer",
)

# Receiver (could be a different process / machine):
result = saver.adopt_checkpoint(descriptor, new_thread_id="run-42-writer")
print(result["verified"])  # True