Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content
Cookbook

Multi-Agent Shared State

Coordinate specialist agents with agent registration, scoped access, handoffs, feedback, and shared context assembly.

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

  1. Register each agent with the scopes it should read and write.
  2. Persist shared facts, traces, rules, and lessons in one run.
  3. Use client.agents.handoffs.create() to transfer a subtask.
  4. Use client.agents.handoffs.feedback() to record the response to that handoff.
  5. Use client.memory.context() to retrieve shared coordination context for the next agent.

Minimal implementation example

multi_agent_shared_state.py
from mubit import Client
import os
 
run_id = "claims:planner:claim-42"
client = Client(
    api_key=os.environ["MUBIT_API_KEY"],
    endpoint=os.getenv("MUBIT_ENDPOINT", "https://api.mubit.ai"),
    transport="http",
)
 
client.agents.register(agent_id="planner", role="planner", run_id=run_id)
client.agents.register(
    agent_id="coverage",
    role="coverage",
    run_id=run_id,
    read_scopes=["fact", "rule", "lesson", "handoff", "feedback"],
    write_scopes=["fact", "trace", "handoff", "feedback"],
)
 
client.memory.remember(
    "Policy P-778 includes rental reimbursement after collision claims.",
    kind="fact",
    metadata={"claim_id": "claim-42"},
    run_id=run_id,
    agent_id="planner",
)
 
handoff = client.agents.handoffs.create(
    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.agents.handoffs.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.memory.context(
    "What did coverage conclude for claim-42?",
    lane="legacy",
    mode="sections",
    sections=["handoffs", "feedback", "facts", "active_rules"],
    run_id=run_id,
)
 
print({
    "handoff_id": handoff.get("handoff_id"),
    "feedback_id": feedback.get("feedback_id"),
    "sections": len(context.get("section_summaries", [])),
})

Failure modes and troubleshooting

SymptomRoot causeFix
Specialist sees too much memoryAgent scopes are too broadNarrow read_scopes and write_scopes
Coordination disappears after the turnHandoff or feedback stayed in app memory onlyPersist both with client.agents.handoffs.create() and client.agents.handoffs.feedback()
Next agent repeats workShared context was not reassembledCall client.memory.context() before each transition

Next steps