///|
/// A node body: what a custom position in a strategy does.
pub type NodeFn = async (Runtime, AgentState, @moonstate.Run) -> Array[
@moonstate.Step[AgentState, Update],
]
///|
/// A node body bound to one runtime: what the graph engine calls.
type NodeBody = async (AgentState, @moonstate.Run) -> Array[
@moonstate.Step[AgentState, Update],
]
///|
/// A strategy as data: named positions, what each one does, and the edges between them.
///
/// Keeping it data means a strategy can be inspected, compared and documented without a
/// provider in hand, and compiled against whichever runtime an agent was built with. A node
/// that decides where to go next does so by returning a `Goto`, so edges only describe the
/// fixed part of the flow.
pub(all) struct Strategy {
name : String
entry : String
nodes : Array[(String, NodeKind)]
edges : Array[(String, String)]
limit : Int32
}
///|
/// An empty strategy starting at the agent node, with the engine's default walk limit.
pub fn Strategy::new(name : String, limit~ : Int32 = 1000) -> Strategy {
{ name, entry: agent_node, nodes: [], edges: [], limit, }
}
///|
/// Add a node.
pub fn Strategy::node(
self : Strategy,
name : String,
kind : NodeKind,
) -> Strategy {
let nodes = self.nodes.copy()
nodes.push((name, kind))
{ ..self, nodes, }
}
///|
/// Add a fixed edge.
pub fn Strategy::edge(self : Strategy, from : String, to : String) -> Strategy {
let edges = self.edges.copy()
edges.push((from, to))
{ ..self, edges, }
}
///|
/// The names of the strategy's nodes, in the order they were added.
pub fn Strategy::node_names(self : Strategy) -> Array[String] {
self.nodes.map(pair => pair.0)
}
///|
/// Compile against a runtime into the graph engine's own graph. `saver`, `store` and `executor`
/// are what the engine checkpoints through and runs nodes on; without a saver a run keeps its
/// checkpoints in memory for the length of the call.
pub fn Strategy::compile(
self : Strategy,
runtime : Runtime,
saver? : &@moonstate.Saver,
store? : &@moonstate.Store,
executor? : &@moonstate.Executor,
) -> @moonstate.Graph[AgentState, Update] raise @moonstate.Refused {
let names = self.node_names()
let runtime = { ..runtime, nodes: names, }
let builder = @moonstate.Builder::new(merge~, initial=AgentState::new())
let mut builder = builder.entry(self.entry)
for pair in self.nodes {
let (name, kind) = pair
match kind {
Delegate(graph) =>
builder = builder.subgraph(
name,
graph,
enter=state => {
(runtime.events.on_subgraph_execution_starting)(name)
state
},
leave=state => {
(runtime.events.on_subgraph_execution_completed)(name, state.text())
Adopt(state)
},
)
_ =>
builder = builder.node(
name,
node_named(runtime, name, node_run(runtime, kind)),
)
}
}
for pair in self.edges {
let (from, to) = pair
builder = builder.edge(from, to)
}
// The walk limit is the tighter of the strategy's own and the run's budget: `Limits.steps` is
// what a caller lowers to make a looping strategy stop, and it has to reach the engine.
let limit = if runtime.limits.steps < self.limit {
runtime.limits.steps
} else {
self.limit
}
builder.compile(self.name, saver?, store?, executor?, limit~)
}
///|
/// A node body with the boundary reports around it: the stream says which position the run is at,
/// which is what a caller watching a run needs and what a stream translates into a protocol's
/// per-node notifications. A node that raises still reports its failure before the run ends.
fn node_named(runtime : Runtime, name : String, body : NodeBody) -> NodeBody {
async fn(state, run) {
(runtime.events.on_node_execution_starting)(name)
runtime.events.report(NodeStarted(name~))
let outcome = Ok(body(state, run)) catch { error => Err(error) }
match outcome {
Ok(steps) => {
(runtime.events.on_node_execution_completed)(name)
runtime.events.report(NodeFinished(name~))
steps
}
Err(error) => {
(runtime.events.on_node_execution_failed)(name, error_text(error))
raise error
}
}
}
}
///|
/// The closure a node kind compiles to.
fn node_run(runtime : Runtime, kind : NodeKind) -> NodeBody {
match kind {
Start(then~) =>
async fn(state, run) { node_agent(runtime, then, state, run) }
Request(mode) =>
async fn(state, run) { node_request(runtime, mode, state, run) }
Turn(mode~, then~) =>
async fn(state, run) { node_request_to(runtime, mode, then, state, run) }
Execute(mode) =>
async fn(state, run) { node_execute(runtime, mode, state, run) }
Compress(policy) =>
async fn(state, run) { node_compress(runtime, policy, state, run) }
Finish => async fn(state, run) { node_finish(runtime, state, run) }
Think(prompt~, every~) =>
async fn(state, run) { node_think(runtime, prompt~, every~, state, run) }
Advise(text) =>
fn(_state, _run) {
[
@moonstate.Step::Write(Append([@moonmuse.Message::user(text)])),
@moonstate.Step::Goto(model_node),
]
}
Custom(name) =>
async fn(state, run) { node_custom(runtime, name, state, run) }
// Compiled through the graph engine's own subgraph support, never as a plain node.
Delegate(_) => fn(_state, _run) { [@moonstate.Step::Goto(finish_node)] }
}
}
///|
/// The one-run loop: ask, run whatever was asked for, ask again until the model answers in
/// prose. This is the strategy an agent gets when nothing else is asked for.
///
/// `streaming` asks each model call to report its deltas as they arrive
/// (`on_llm_streaming_frame`), instead of handing back one finished reply.
pub fn single_run(streaming~ : Bool = false) -> Strategy {
Strategy::new("single_run")
.node(agent_node, Start(then=model_node))
.edge(agent_node, model_node)
.node(model_node, Request(if streaming { Streaming } else { Tools }))
.node(tools_node, Execute(All))
.node(finish_node, Finish)
.edge(model_node, tools_node)
.edge(model_node, finish_node)
.edge(tools_node, model_node)
.edge(tools_node, finish_node)
}
///|
/// The chat loop: the model must call a tool rather than answer in prose, and the run ends when
/// it calls the exit tool. `exit_tool` is what the run watches for.
pub fn chat() -> Strategy {
Strategy::new("chat")
.node(agent_node, Start(then=model_node))
.edge(agent_node, model_node)
.node(model_node, Request(OnlyCalling))
.node(tools_node, Execute(All))
.node(finish_node, Finish)
.edge(model_node, tools_node)
.edge(tools_node, model_node)
.edge(tools_node, finish_node)
.edge(model_node, finish_node)
}
///|
/// Reason-and-act: after each round of tools the model is asked to think about what it learned,
/// without tools in reach, before it acts again. `interval` spaces the thinking out, so a long
/// loop does not pay for a reasoning call on every round.
pub fn react(
reasoning_prompt~ : String = "Think about what you have learned and what the next step should be.",
interval~ : Int32 = 1,
) -> Strategy {
guard interval >= 1 else {
abort(
"react: the reasoning interval is at least 1, not " + interval.to_string(),
)
}
Strategy::new("re_act")
.node(agent_node, Start(then=model_node))
.edge(agent_node, model_node)
.node(model_node, Request(Tools))
.node(tools_node, Execute(All))
.node("reason", Think(prompt=reasoning_prompt, every=interval))
.node(finish_node, Finish)
.edge(model_node, tools_node)
.edge(model_node, finish_node)
.edge(tools_node, "reason")
.edge(tools_node, finish_node)
.edge("reason", model_node)
.edge("reason", finish_node)
}
///|
/// Tools first, then one answer that has to fit the schema the agent was configured with
/// (`AgentConfig::with_structured`). The model may call tools for as many rounds as it needs;
/// the prose answer that would have ended a `single_run` is instead sent to a final request in
/// structured mode, whose answer is the JSON object the run returns.
///
/// Without a schema on the config the final request returns an empty answer, which is why the
/// strategy is only worth choosing together with `with_structured`.
pub fn structured_output(
name~ : String = "structured_output_with_tools",
) -> Strategy {
Strategy::new(name)
.node(agent_node, Start(then=model_node))
.edge(agent_node, model_node)
.node(model_node, Turn(mode=Tools, then="structure"))
.node(tools_node, Execute(All))
.node("structure", Request(StructuredOutput))
.node(finish_node, Finish)
.edge(model_node, tools_node)
.edge(tools_node, model_node)
.edge(model_node, "structure")
.edge("structure", finish_node)
}
///|
/// A strategy with a single model call: no tools, one answer. Useful as a judge, a classifier or
/// the planner half of a plan-and-execute run.
pub fn answer_only(name~ : String = "answer") -> Strategy {
Strategy::new(name)
.node(agent_node, Start(then=model_node))
.edge(agent_node, model_node)
.node(model_node, Request(NoTools))
.node(finish_node, Finish)
}