AI SDK Handoff: Keep Agent Transfers Traceable

An AI SDK handoff is the moment one agent passes control and conversation context to another inside a multi-agent run. Done well, the receiving agent continues without gaps; done poorly, it either repeats work or misses the reason behind each step.

The design question is what belongs in the runtime for this run and what belongs in a record that survives beyond it. Tools like fenbs keep the lasting part — tasks, decisions, and progress — outside the SDK runtime so any agent, in any session, starts from the same shared record. Other handoff patterns for estimating, prompts, and design are covered on their own pages.

What the AI SDK manages at handoff

The Vercel AI SDK's multi-agent support routes a conversation from one agent to another. The calling agent passes a message, optional context, and control moves to the target agent, which continues with its own system prompt and tools.

What transfers is runtime: the accumulated conversation messages and whatever context the calling agent explicitly packs in. When the run ends or the server restarts, that state is gone unless you persist it yourself. The SDK routes the call; it does not store the work.

Runtime state vs. the lasting task record

Treat runtime state and durable history as two separate things with different lifetimes.

• Runtime state: conversation messages, current tool results, the answer being assembled. Cheap to pass, fine to lose when the run completes.
• Lasting record: the task being worked on, what a person decided, what was completed, and where the next session should start.
• Progress note: where the agent stopped, what it checked, and what needs a person's input before continuing.

Mixing the two is the root cause of most traceability problems. An agent that stores its work only in message history forces every reviewer to replay the entire run to understand what happened.

Steps to design a traceable handoff

1. Define a handoff schema: task id, completed steps, current state fields, and open questions. Keep it small — a schema with missing fields breaks silently.
2. Before handing off, have the calling agent write a structured summary to your task store and pack the same summary into the context argument.
3. Give the receiving agent a system prompt that begins with reading and confirming the handoff note before it does anything else.
4. Log both sides — who sent, who received, what the state was — to a persistent record, not just the run's message thread.
5. Test by interrupting the run midway. The receiving agent should reconstruct what it needs from the handoff note alone, without the full conversation history.

Common handoff failures

The most common failure is a receiving agent with no context for why it was called. The calling agent assumed the goal was obvious from conversation history; the receiving agent reads too far back and loses the current state in noise. A short, structured handoff note prevents this.

State drift is another trap. The calling agent's last action changed something in an external system, but the handoff note describes the state before that change. Always write the note after the action, not before.

Loops are a third problem. Two agents that can each hand off to the other will cycle when neither can resolve a blocking question. Track how many times a task has been handed off and surface a question to a person when the count grows.

Separating agent logic from the work record

The SDK harness wires agents together and manages the call graph. It should not be the source of truth for what was decided or what remains. Keep approved rules, task history, and progress notes in a store the harness can read from and write to, but that exists independently of any one run.

This matters most at review. A readable record of what each agent did, the decisions behind each step, and where control transferred gives reviewers the evidence they need without replaying the entire run. The AI brain guide explains how keeping work outside the model protects it across sessions and tools.

How to do this with fenbs

1. Create a free account and add your project as a task with its goal and current plan.
2. Connect your AI assistant from Integrations using MCP. Your agent harness calls the fenbs MCP tools to read project context at the start of each run.
3. Before each SDK handoff, have the calling agent update the task in fenbs with completed steps, checked conditions, and the next agent's starting point.
4. Give the receiving agent's system prompt an instruction to read the fenbs task at startup, before reading the conversation history.
5. After a human review, record any decisions made in Decisions and rules. Those rules appear at the top of the AI context every subsequent agent reads.

fenbs works well when the task has clear phases and a person must sign off between them. It is not a replacement for a runtime state store: fast, in-run state should stay in the SDK's own message context or a dedicated short-term database. The two stores complement each other. See the Vercel AI SDK overview for SDK-level patterns.