Agent State & Goals

Semantic memory alone is not enough for long-running agents. Explicit state and planner history make behavior testable and auditable.

Mental model

Variables hold explicit machine-readable state.
Goals define outcomes and priority.
Actions and cycles record planner decisions over time.
Logs and snapshots make behavior inspectable.

Minimal implementation example

Python
Node / TS
Rust

04-state-and-goals.py

client.control.set_variable({
    "run_id": run_id,
    "name": "resolution_stage",
    "value_json": '{"stage":"needs-billing-review"}',
    "source": "reasoning",
})

goal = client.control.add_goal({
    "run_id": run_id,
    "description": "Resolve ticket with grounded invoice explanation",
    "priority": "high",
})

client.control.submit_action({
    "run_id": run_id,
    "agent_id": "support-agent",
    "action_type": "retrieve",
    "action_json": '{"query":"collect invoice discrepancy details"}',
})

cycle = client.control.run_cycle({
    "run_id": run_id,
    "agent_id": "support-agent",
    "candidates": [{
        "action_type": "reason",
        "action_json": '{"prompt":"choose safest next response step"}',
        "score": 0.89,
        "rationale": "preserve accuracy before response",
    }],
})

print(goal.get("id"), cycle.get("cycle_number"))

agent_state_and_goals.ts

await client.control.setVariable({
  run_id: runId,
  name: "resolution_stage",
  value_json: '{"stage":"needs-billing-review"}',
  source: "reasoning",
});

const goal = await client.control.addGoal({
  run_id: runId,
  description: "Resolve ticket with grounded invoice explanation",
  priority: "high",
});

await client.control.submitAction({
  run_id: runId,
  agent_id: "support-agent",
  action_type: "retrieve",
  action_json: '{"query":"collect invoice discrepancy details"}',
});

const cycle = await client.control.runCycle({
  run_id: runId,
  agent_id: "support-agent",
  candidates: [
    {
      action_type: "reason",
      action_json: '{"prompt":"choose safest next response step"}',
      score: 0.89,
      rationale: "preserve accuracy before response",
    },
  ],
});

console.log(goal.id, cycle.cycle_number);

agent_state_and_goals.rs

use serde_json::json;

client.control.set_variable(json!({
    "run_id": run_id,
    "name": "resolution_stage",
    "value_json": "{\"stage\":\"needs-billing-review\"}",
    "source": "reasoning"
})).await?;

let goal = client.control.add_goal(json!({
    "run_id": run_id,
    "description": "Resolve ticket with grounded invoice explanation",
    "priority": "high"
})).await?;

client.control.submit_action(json!({
    "run_id": run_id,
    "agent_id": "support-agent",
    "action_type": "retrieve",
    "action_json": "{\"query\":\"collect invoice discrepancy details\"}"
})).await?;

let cycle = client.control.run_cycle(json!({
    "run_id": run_id,
    "agent_id": "support-agent",
    "candidates": [{
        "action_type": "reason",
        "action_json": "{\"prompt\":\"choose safest next response step\"}",
        "score": 0.89,
        "rationale": "preserve accuracy before response"
    }]
})).await?;

println!("{:?} {:?}", goal["id"], cycle["cycle_number"]);

Failure modes and troubleshooting

Symptom	Root cause	Fix
State conflicts	Writes spread across multiple runs	Keep deterministic run identity
Goal sprawl	No parent/priority discipline	Define team goal policy
Opaque behavior	Action/cycle logs not reviewed	Add routine log checks in dev and ops

Next steps

Add event-driven wakeups at Pub-sub and events.
Split planner/specialist runs at Sessions and branching.

Overview

Learn the basics

Build with MuBit

Go deeper

Platform

Help

Agent State & Goals

Mental model

Minimal implementation example

Failure modes and troubleshooting

Next steps

Overview

Learn the basics

Build with MuBit

Go deeper

Platform

Help

​Mental model

​Minimal implementation example

​Failure modes and troubleshooting

​Next steps

Mental model

Minimal implementation example

Failure modes and troubleshooting

Next steps