Multi-Agent Shared State

Current MuBit coordination is centered on registered agents plus persisted coordination artifacts. Use this pattern when a planner, reviewer, specialist, or resolver must share memory while keeping role boundaries explicit.

Flow

Register each agent with the scopes it should read and write.
Persist shared facts, traces, rules, and lessons in one session.
Use handoff() to transfer a subtask.
Use feedback() to record the response to that handoff.
Use getContext() / get_context() to retrieve shared coordination context for the next agent.

Minimal implementation example

Python
Node / TS

multi_agent_shared_state.py

from mubit import Client
import os

run_id = "claims:planner:claim-42"
client = Client(
    endpoint=os.getenv("MUBIT_ENDPOINT", "https://api.mubit.ai"),
    api_key=os.environ["MUBIT_API_KEY"],
    run_id=run_id,
    transport="http",
)

client.register_agent(session_id=run_id, agent_id="planner", role="planner")
client.register_agent(
    session_id=run_id,
    agent_id="coverage",
    role="coverage",
    read_scopes=["fact", "rule", "lesson", "handoff", "feedback"],
    write_scopes=["fact", "trace", "handoff", "feedback"],
)

client.remember(
    session_id=run_id,
    agent_id="planner",
    content="Policy P-778 includes rental reimbursement after collision claims.",
    intent="fact",
    metadata={"claim_id": "claim-42"},
)

handoff = client.handoff(
    session_id=run_id,
    task_id="claim-42-coverage-review",
    from_agent_id="planner",
    to_agent_id="coverage",
    requested_action="review",
    content="Confirm whether rental reimbursement applies to this collision claim.",
    metadata={"claim_id": "claim-42"},
)

feedback = client.feedback(
    session_id=run_id,
    handoff_id=handoff["handoff_id"],
    from_agent_id="coverage",
    verdict="approve",
    comments="Coverage confirmed. Rental reimbursement applies for up to 14 days.",
    metadata={"claim_id": "claim-42"},
)

context = client.get_context(
    session_id=run_id,
    query="What did coverage conclude for claim-42?",
    mode="sections",
    sections=["handoffs", "feedback", "facts", "active_rules"],
)

print({
    "handoff_id": handoff.get("handoff_id"),
    "feedback_id": feedback.get("feedback_id"),
    "sections": len(context.get("section_summaries", [])),
})

multi_agent_shared_state.ts

import { Client } from "@mubit-ai/sdk";

const runId = "claims:planner:claim-42";
const client = new Client({
  endpoint: process.env.MUBIT_ENDPOINT ?? "https://api.mubit.ai",
  api_key: process.env.MUBIT_API_KEY,
  run_id: runId,
  transport: "http",
});

await client.registerAgent({ session_id: runId, agent_id: "planner", role: "planner" });
await client.registerAgent({
  session_id: runId,
  agent_id: "coverage",
  role: "coverage",
  read_scopes: ["fact", "rule", "lesson", "handoff", "feedback"],
  write_scopes: ["fact", "trace", "handoff", "feedback"],
});

await client.remember({
  session_id: runId,
  agent_id: "planner",
  content: "Policy P-778 includes rental reimbursement after collision claims.",
  intent: "fact",
  metadata: { claim_id: "claim-42" },
});

const handoff = await client.handoff({
  session_id: runId,
  task_id: "claim-42-coverage-review",
  from_agent_id: "planner",
  to_agent_id: "coverage",
  requested_action: "review",
  content: "Confirm whether rental reimbursement applies to this collision claim.",
  metadata: { claim_id: "claim-42" },
});

const feedback = await client.feedback({
  session_id: runId,
  handoff_id: handoff.handoff_id,
  from_agent_id: "coverage",
  verdict: "approve",
  comments: "Coverage confirmed. Rental reimbursement applies for up to 14 days.",
  metadata: { claim_id: "claim-42" },
});

const context = await client.getContext({
  session_id: runId,
  query: "What did coverage conclude for claim-42?",
  mode: "sections",
  sections: ["handoffs", "feedback", "facts", "active_rules"],
});

console.log({
  handoff_id: handoff.handoff_id,
  feedback_id: feedback.feedback_id,
  sections: context.section_summaries?.length ?? 0,
});

Failure modes and troubleshooting

Symptom	Root cause	Fix
Specialist sees too much memory	Agent scopes are too broad	Narrow `read_scopes` and `write_scopes`
Coordination disappears after the turn	Handoff or feedback stayed in app memory only	Persist both with `handoff()` and `feedback()`
Next agent repeats work	Shared context was not reassembled	Call `getContext()` before each transition

Next steps

Add checkpoints before compaction at Support agent memory loop.
See the route-level contract at Control HTTP reference.

Recipes

​Flow

​Minimal implementation example

​Failure modes and troubleshooting

​Next steps

Flow

Minimal implementation example

Failure modes and troubleshooting

Next steps