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

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 session.
  3. Use handoff() to transfer a subtask.
  4. Use feedback() to record the response to that handoff.
  5. Use getContext() / get_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(
    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", [])),
})

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 handoff() and feedback()
Next agent repeats workShared context was not reassembledCall getContext() before each transition

Next steps