Stateful Task Trees

When planner state stays in app memory, debugging and replay are fragile. MuBit lets you persist goal structure and decision history next to the memory the planner is using.

Mental model

Register planner identity.
Create a goal tree.
Record actions and reasoning cycles.
Save checkpoints before major transitions.
Retrieve the goal tree and action history when you need to replay or diagnose the run.

Minimal implementation example

Python
Node / TS

stateful_task_tree.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")

parent_goal = client.control.add_goal({
    "run_id": run_id,
    "description": "Resolve claim-42 with a policy-safe decision",
    "priority": "critical",
})
client.control.add_goal({
    "run_id": run_id,
    "description": "Verify rental reimbursement coverage",
    "priority": "high",
    "parent_goal_id": parent_goal.get("id", ""),
})

client.control.submit_action({
    "run_id": run_id,
    "agent_id": "planner",
    "action_type": "retrieve",
    "action_json": '{"query":"collect coverage and fraud signals"}',
})
client.control.run_cycle({
    "run_id": run_id,
    "agent_id": "planner",
    "candidates": [{
        "action_type": "reason",
        "action_json": '{"prompt":"pick the safest next verification step"}',
        "score": 0.88,
        "rationale": "coverage confirmation should happen before settlement drafting",
    }],
})

client.checkpoint(
    session_id=run_id,
    agent_id="planner",
    label="after-goal-tree-build",
    context_snapshot="Planner built the first goal tree and recorded an initial decision cycle.",
)

goal_tree = client.control.get_goal_tree({"run_id": run_id})
actions = client.control.get_action_log({"run_id": run_id, "limit": 20})

print({
    "goal_nodes": len(goal_tree.get("goals", [])),
    "actions": len(actions.get("entries", [])),
})

stateful_task_tree.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" });

const parentGoal = await client.control.addGoal({
  run_id: runId,
  description: "Resolve claim-42 with a policy-safe decision",
  priority: "critical",
});
await client.control.addGoal({
  run_id: runId,
  description: "Verify rental reimbursement coverage",
  priority: "high",
  parent_goal_id: parentGoal.id,
});

await client.control.submitAction({
  run_id: runId,
  agent_id: "planner",
  action_type: "retrieve",
  action_json: '{"query":"collect coverage and fraud signals"}',
});
await client.control.runCycle({
  run_id: runId,
  agent_id: "planner",
  candidates: [{
    action_type: "reason",
    action_json: '{"prompt":"pick the safest next verification step"}',
    score: 0.88,
    rationale: "coverage confirmation should happen before settlement drafting",
  }],
});

await client.checkpoint({
  session_id: runId,
  agent_id: "planner",
  label: "after-goal-tree-build",
  context_snapshot: "Planner built the first goal tree and recorded an initial decision cycle.",
});

const goalTree = await client.control.getGoalTree({ run_id: runId });
const actions = await client.control.getActionLog({ run_id: runId, limit: 20 });

console.log({
  goal_nodes: goalTree.goals?.length ?? 0,
  actions: actions.entries?.length ?? 0,
});

Failure modes and troubleshooting

Symptom	Root cause	Fix
Planner decisions are hard to replay	Actions and cycles were not stored	Record both action logs and cycle history
Goal hierarchy becomes flat and noisy	Parent-child goals were not used	Build explicit goal trees and read them through `goals/tree`
Compaction loses planner intent	No checkpoint before the transition	Save checkpoints at major decision boundaries

Next steps

Add event handling at Building event-driven agents.
Review the explicit state surface at State management endpoints.

Recipes

​Mental model

​Minimal implementation example

​Failure modes and troubleshooting

​Next steps

Mental model

Minimal implementation example

Failure modes and troubleshooting

Next steps