Mastra AI Handoff: Pass Control With the Right Context
Design a Mastra handoff that separates who runs next from stored execution state and the project decisions a person needs to review.
Updated 5 min read
A Mastra AI handoff transfers responsibility for the next part of an interaction to another agent. To make it useful, define who receives control, which evidence and instructions they receive, and where the run can resume after a pause. Those choices are separate from maintaining a durable record of the project’s decisions and unfinished work.
You can keep that human-readable work record in fenbs, while Mastra manages your application’s execution and configured memory. fenbs does not replace workflow storage or provide a ready-made Mastra integration. Keep the two responsibilities explicit rather than treating a project note as an executable checkpoint.
How do you plan the transfer before writing code?
- Define the receiving specialist and the exact condition that sends work to it.
- List the goal, verified inputs, applicable decisions and source references it needs. Leave out unrelated conversations.
- Specify its output and acceptance checks, including when it must ask a person rather than proceed.
- Choose how execution state and conversational memory will be stored, scoped and recovered.
- Test a normal transfer, missing input, denied access and a restart before connecting the flow to consequential actions.
For example, a research assistant might pass a reviewed source inventory to a drafting assistant. The next assistant needs those sources, the audience and the approved scope. It does not automatically need every exploratory search or every private note that helped the first assistant reach that point.
Who stays in control after a handoff?
Mastra’s multi-agent systems guide (opens in a new tab) distinguishes a handoff from supervision: in a handoff, the next specialist takes over the interaction; a supervisor continues coordinating delegated work. Its workflows put the execution path in code. Choose based on who should own the next response, not simply on the number of agents involved.
Write that ownership into your design. If a reviewer merely returns findings to the original assistant, describe it as a review delegation. If a different specialist now speaks to the user and carries the task forward, describe the transfer and define what brings control back. Clear naming makes failures easier to diagnose.
The broader guide to using AI at work explains why responsibility still needs a person, even when software chooses the next worker.
Which state belongs at each layer?
| Record | Question it answers | Example contents |
|---|---|---|
| Transfer input | What does the next agent need now? | Goal, allowed sources, constraints and expected result. |
| Execution checkpoint | Where can this application run continue? | Run identity, step state and data needed for resumption. |
| Project work record | What has the team agreed and what remains? | Task progress, human decisions, evidence links and next steps. |
A stored conversation can preserve useful history without documenting why a person approved a particular outcome. Conversely, a readable handoff note cannot tell the runtime exactly which workflow step to resume. Connect the records with identifiers, but do not make them interchangeable.
In Mastra’s memory documentation (opens in a new tab), resource and thread identifiers control how message history is addressed. Review those boundaries for your application rather than assuming every agent shares every conversation. Use trusted application identity when selecting the relevant record, and check that the next agent receives only the context intended for its task.
This distinction also explains the role of an AI brain: it keeps useful work knowledge available, while application code still controls execution.
What should the receiving agent actually get?
Use a small, explicit input contract. A contract is an agreed structure for the information crossing a boundary. Mastra’s workflow control-flow guide (opens in a new tab) explains how step input and output schemas connect; a schema describes the expected shape of the data. Align the business meaning of each field as carefully as its type.
{
"goal": "Draft the approved installation guide",
"taskRef": "FET-014",
"sources": ["approved-installation-spec"],
"decision": "Use the short setup path approved by the owner",
"verified": ["Source document opened and version checked"],
"unknown": ["Screenshots still need human review"],
"allowedNextAction": "Draft text only",
"acceptance": "Every setup step points to the approved specification"
}Validate required fields before calling the next agent. If a source reference is missing or access is denied, return an explicit incomplete result. Do not let an empty list quietly mean “all sources checked.” Distinguish an actual negative finding from a check that could not be performed.
For wording you can adapt to a session boundary, use the AI handoff prompt; application validation still belongs in code.
How do you pause and resume without repeating actions?
Mastra’s suspend and resume documentation (opens in a new tab) describes saving execution state as a snapshot when a workflow suspends, with snapshots held in the configured storage provider. Check your provider’s persistence settings and test recovery in your own environment. A development setup that loses its storage cannot provide a reliable restart.
Record run identifiers alongside the task, and keep sensitive execution data inside the application’s storage. On resumption, confirm whether any outside action already happened. If the workflow creates a document or sends a request, make repeated attempts recognize the same operation instead of creating a second one.
Test interruptions before and after the outside action. Include a case where the action succeeds but recording its result fails. Your restart logic should inspect the destination or use a stable operation identifier before trying again. This is a design check for your application, not a guarantee supplied by a handoff summary.
Keep the project explanation outside the run
Keep the task’s current plan, human decisions and unresolved checks in fenbs. Save Where we left off with a reference to the relevant run, so someone reviewing the project can understand what remains without reading internal workflow data.
Create a free accountFree for one person · No credit card · Works with Claude, ChatGPT, Cursor and more
How to do this with fenbs
- Create a free account. One person can use fenbs free, with no credit card.
- Add the project and tasks that the workflow supports. Record the intended result and the acceptance checks in the task plan.
- Record decisions made by people in Decisions and rules. Keep proposals open until a person chooses an answer.
- Manually save a reviewed run summary, evidence references and the next step. Keep runtime snapshots and credentials in your application’s own storage.
- When continuing in a supported assistant app, follow Integrations and ask it to read the project context before starting.
fenbs is not the right fit for storing serialized workflow snapshots or orchestrating agent transfers. Use Mastra and your chosen storage for those jobs. Its handoff workflow helps people and supported assistants continue the work around those runs.
What should you check before calling the flow ready?
Verify that the receiver gets the intended inputs and nothing from an unrelated project. Try an outdated decision, a missing source and an unapproved action. Confirm that the application reports the problem clearly and leaves enough evidence for someone to understand where it stopped.
Then restart the application and recover a deliberately paused test run. Compare the final result with the acceptance checks rather than with the assistant’s confidence. The AI handoffs topic covers session-level transitions; this test checks the boundary your application actually implements.