Tutorials

Browse docs

Tutorials

Tap to expand
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-Key for 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.