TutorialsUpdated 2026-05-25
Build a Multi-Agent Handoff
Record planner decisions and hand context to a builder agent with Agent Memory Bus.
This tutorial shows a planner agent handing work to a builder agent.
1. Create the task
ts
import { RetainDB } from "@retaindb/sdk";
const db = new RetainDB({
apiKey: process.env.RETAINDB_API_KEY,
project: "production"
});
const planner = db.agent("planner").task("checkout-redesign");2. Record the planner's decision
ts
await planner.event({
type: "decision",
summary: "Use hosted checkout for the first release.",
details: {
constraints: ["avoid custom PCI scope", "ship in one week"],
rejected: ["custom card form"]
},
salience: 0.9
});3. Ask RetainDB for task context
ts
const context = await planner.context(
"What should the builder know before implementation?"
);4. Create the handoff
ts
const handoff = await planner.handoff({
toAgentId: "builder",
summary: "Implement hosted checkout using the recorded constraints.",
context: JSON.stringify(context)
});5. Resume as the builder
ts
const builder = db.agent("builder").task("checkout-redesign");
const resumed = await builder.handoffResume(String(handoff.handoff_id), {
sessionId: "builder-session-001"
});The builder can now start with the planner's decisions and related task memory instead of rediscovering them.
Production notes
- Use deterministic task ids from your job system.
- Send
Idempotency-Keyfor retried writes. - Record failures as events, not just successes.
- Store constraints and decisions with high salience.
Next: Agent Memory Bus API.
Was this page helpful?
Your feedback helps us prioritize docs improvements weekly.