moonbitstack/moonkoog/agent does not have a README file

    Listener

    type Listener = (Event) -> Unit

    The subscriber a run reports to. Every run has one; the default drops what it is told.

    NodeFn

    A node body: what a custom position in a strategy does.

    Chooser

    pub(open) trait Chooser {
    async fn choose(Self, Array[
    Reply
    ]) ->
    Reply

    }

    Picks one reply out of several candidates for the same request.

    Asking more than once and choosing is how a run buys diversity without asking the provider for n completions it may not support: every candidate is a normal call, so middleware, limits and retries apply to each of them.

    Middleware

    pub(open) trait Middleware {
    fn name(Self) -> String
    fn install(Self, Tools) -> Unit
    async fn before_agent(Self, RunContext) -> Array[Update]
    async fn wrap_model(Self, RunContext, ModelCall, async (ModelCall) -> ModelOutcome) -> ModelOutcome
    async fn wrap_tool(Self, RunContext, ToolCall, async (ToolCall) -> ToolOutcome) -> ToolOutcome
    async fn after_agent(Self, RunContext, AgentState) -> Array[Update]
    }

    A hook into a run, between the graph and the provider.

    Four places to act: before the run starts, around each model call, around each tool call, and after the run ends. The around-hooks take the next step as a function, so a middleware can retry it, replace it, or skip it — and the pipeline nesting is the composition order, first registered outermost.

    A middleware may also install tools, which is how a feature that is best expressed as something the model calls (a todo list, a shell, a file search) joins a run.

    AgentError

    pub(all) suberror AgentError {
    Exhausted(limit~ : Int)
    Refused(reason~ : String)
    Engine(
    GraphError
    )
    }

    A run that went wrong, or one that was interrupted and can be resumed.

    Engine carries the graph engine's own error unchanged so that an interrupt, a step limit and a backend failure stay distinguishable to the caller.

    Agent

    pub struct Agent {
    runtime : Runtime
    graph :
    Graph
    [AgentState, Update]
    strategy_name : String
    saver : &
    Saver
    ?
    }

    An agent: a runtime, the graph its strategy compiled to, and the operations a caller runs.

    The graph is the same engine a plain state machine uses — an agent is a graph whose nodes happen to talk to a model, which is what keeps checkpoints, interrupts, resumption and multi-agent composition available without a second mechanism.

    Agent::continue_run

    async fn Agent::continue_run(self : Agent, thread : String) -> String raise AgentError

    Continue a thread from its latest checkpoint without adding a turn to the conversation.

    This is what a rewound thread needs: the checkpoint says which nodes were about to run, and the run picks up there. It is also what a caller uses after a run stopped on a cap, when the input that started the thread has already been read.

    Agent::graph

    The compiled graph, for a strategy that composes this agent as a node of its own.

    Agent::history

    async fn Agent::history(self : Agent, thread : String) -> Array[
    Snapshot
    [AgentState]] raise AgentError

    Every checkpoint of a thread, in the order they were written.

    Agent::model

    fn Agent::model(self : Agent) -> String

    The model it calls.

    Agent::name

    fn Agent::name(self : Agent) -> String

    The agent's name.

    Agent::resume_from

    async fn Agent::resume_from(self : Agent, thread : String, answer :
    Json
    ) -> String raise AgentError

    Resume an interrupted run with the answer to the question it stopped on.

    Agent::rewind

    async fn Agent::rewind(self : Agent, thread : String, id : String) -> Unit raise AgentError

    Move a thread's head back to the checkpoint id, so the next continue_run picks the run up where that checkpoint left it.

    The target is copied forward as the thread's newest checkpoint instead of deleting the ones after it: a saver here is append-only, and history stays a record of what actually happened, including the branch that was abandoned.

    Agent::run

    async fn Agent::run(self : Agent, input : String, thread? : String) -> String raise AgentError

    Run the agent on input and return its answer.

    thread names the run's checkpoint thread: passing the same name again resumes from what was checkpointed, which is what makes a durable agent possible without a separate API.

    Agent::runtime

    fn Agent::runtime(self : Agent) -> Runtime

    The runtime an agent runs on — what a composed strategy or a protocol adapter needs in order to add nodes of its own.

    Agent::state

    async fn Agent::state(self : Agent, thread : String) ->
    Snapshot
    [AgentState]? raise AgentError

    The state of a thread, when one was checkpointed.

    Agent::strategy_name

    fn Agent::strategy_name(self : Agent) -> String

    The strategy it runs.

    Agent::stream

    async fn Agent::stream(self : Agent, input : String, listener : (Event) -> Unit, thread? : String) -> String raise AgentError

    Run and report each graph event to listener, which is how a caller watches a run as it happens rather than after it ends.

    AgentConfig

    pub(all) struct AgentConfig {
    name : String
    model : String
    instructions : String?
    tools : Array[ToolSpec]
    options : Options
    limits : Limits
    middleware : Array[&Middleware]
    strategy : Strategy?
    structured : Structured?
    events : EventHandler
    exit_tool : String?
    missing_tools : MissingTools
    nodes : Map[String, async (Runtime, AgentState,
    Run
    ) -> Array[
    Step
    [AgentState, Update]]]
    }

    Everything an agent is configured with, short of the provider and the checkpoint stores.

    A config is data plus a strategy: copying it and changing one field is how a second agent is made, and the presets are the three shapes a run usually takes.

    AgentConfig::chat

    fn AgentConfig::chat(model : String, name? : String) -> AgentConfig

    A config for the chat loop: the model must call tools, and calls __exit__ to finish.

    AgentConfig::exit_tool_spec

    fn AgentConfig::exit_tool_spec() -> ToolSpec

    The tool a chat strategy ends on: the model calls it when the conversation is over.

    AgentConfig::new

    fn AgentConfig::new(model : String, name? : String) -> AgentConfig

    A config for model that runs the single-run loop.

    AgentConfig::react

    fn AgentConfig::react(model : String, name? : String, reasoning_prompt? : String, interval? : Int) -> AgentConfig

    A config for the reason-and-act loop.

    AgentConfig::with_events

    fn AgentConfig::with_events(self : AgentConfig, events : EventHandler) -> AgentConfig

    A copy reporting to the given handlers.

    AgentConfig::with_instructions

    fn AgentConfig::with_instructions(self : AgentConfig, instructions : String) -> AgentConfig

    A copy with the system instructions replaced.

    AgentConfig::with_limits

    fn AgentConfig::with_limits(self : AgentConfig, limits : Limits) -> AgentConfig

    A copy with the given caps.

    AgentConfig::with_middleware

    fn AgentConfig::with_middleware(self : AgentConfig, middleware : &Middleware) -> AgentConfig

    A copy with one more middleware, outermost last.

    AgentConfig::with_missing_tools

    fn AgentConfig::with_missing_tools(self : AgentConfig, policy : MissingTools) -> AgentConfig

    A copy that rewrites the tool calls and results naming tools it does not have, so a conversation recorded under a wider tool set can still be sent to a provider.

    AgentConfig::with_node

    A copy with a custom node body registered under name, for a strategy that names it. The body is handed the agent's runtime, so a composed strategy reaches the model, the tools and the middleware exactly as a built-in node does.

    AgentConfig::with_options

    fn AgentConfig::with_options(self : AgentConfig, options : Options) -> AgentConfig

    A copy with the given request settings.

    AgentConfig::with_strategy

    fn AgentConfig::with_strategy(self : AgentConfig, strategy : Strategy) -> AgentConfig

    A copy running the given strategy.

    AgentConfig::with_structured

    fn AgentConfig::with_structured(self : AgentConfig, structured : Structured) -> AgentConfig

    A copy asking for structured output against schema.

    AgentConfig::with_tools

    fn AgentConfig::with_tools(self : AgentConfig, tools : Array[ToolSpec]) -> AgentConfig

    A copy with tools added.

    AgentState

    pub(all) struct AgentState {
    messages : Array[
    Message
    ]
    storage : Map[String,
    Json
    ]
    model_calls : Int
    tool_calls : Int
    answer : String?
    }

    What a run carries between nodes: the conversation, the run's own scratch space, how many model and tool calls it has spent, and the answer once one is set.

    The whole value is the graph's state, so it round-trips through JSON for the saver — a checkpoint restores the conversation and the counters, which is what lets a run resume with the budgets it had already spent.

    AgentState::get

    fn[T :
    FromJson
    ] AgentState::get(self : AgentState, key : String) -> T?

    A value this run put in its storage, at the type the call site asks for. None when the key is unset or holds something that does not decode to that type.

    AgentState::messages

    The conversation so far.

    AgentState::new

    fn AgentState::new() -> AgentState

    The state a run starts from.

    AgentState::raw

    fn AgentState::raw(self : AgentState, key : String) ->
    Json
    ?

    The raw JSON stored under key.

    AgentState::text

    fn AgentState::text(self : AgentState) -> String

    The text of the last assistant message, or the empty string when the model has not spoken yet.

    AgentState::to_json

    AgentState::with_messages

    A copy with messages replacing the conversation.

    Compressed

    pub(all) enum Compressed {
    Done(Array[
    Message
    ])
    Refused(reason~ : String)
    }

    The result of compressing a conversation: the messages to carry on with, or why the summary could not be written.

    Event

    pub(all) enum Event {
    AgentStarted(name~ : String)
    AgentFinished(name~ : String, text~ : String)
    AgentFailed(name~ : String, reason~ : String)
    ModelStarted(name~ : String, model~ : String)
    ModelFinished(name~ : String, usage~ :
    Usage
    )
    ToolStarted(name~ : String, call_id~ : String)
    ToolFinished(name~ : String, call_id~ : String, failed~ : Bool)
    HandedOver(from~ : String, to~ : String)
    NodeStarted(name~ : String)
    NodeFinished(name~ : String)
    }

    What a run broadcasts: one variant per boundary worth observing. The stream is data so it can be rendered as log lines, counted in tests, or translated into OpenTelemetry spans without the observer reaching into the graph.

    EventHandler

    pub struct EventHandler {
    listener : (Event) -> Unit
    on_agent_starting : (String) -> Unit
    on_agent_completed : (String) -> Unit
    on_agent_execution_failed : (String) -> Unit
    on_strategy_starting : (String) -> Unit
    on_strategy_completed : (String, String) -> Unit
    on_llm_call_starting : (
    Request
    ) ->
    Request

    on_llm_call_completed : (
    Reply
    ) ->
    Reply

    on_llm_streaming_starting : (
    Request
    ) -> Unit
    on_llm_streaming_frame : (String) -> Unit
    on_llm_streaming_completed : (
    Reply
    ) -> Unit
    on_tool_call_starting : (String,
    Json
    ) ->
    Json

    on_tool_call_completed : (String, String) -> String
    on_tool_call_failed : (String, String) -> Unit
    on_tool_validation_failed : (String,
    Json
    , String) -> Unit
    on_node_execution_starting : (String) -> Unit
    on_node_execution_completed : (String) -> Unit
    on_node_execution_failed : (String, String) -> Unit
    on_subgraph_execution_starting : (String) -> Unit
    on_subgraph_execution_completed : (String, String) -> Unit
    }

    Hooks over an agent run: observers that watch, and interceptors that rewrite the value in flight. Every registration chains after what was registered before, so several handlers fire and several interceptors compose left to right.

    The interceptors are the only way to change what is sent, what comes back and what a tool receives, which keeps a run's conversation and a hook's edits in one place. Hooks are synchronous; anything that has to await belongs in middleware, whose hooks are async.

    EventHandler::intercept_llm_call_completed

    Rewrite a reply: what comes back is what the graph routes on and what the conversation records. Chains.

    EventHandler::intercept_llm_call_starting

    Rewrite a request just before it is sent: what comes back is what the provider receives, while the conversation the run keeps is untouched. Chains.

    EventHandler::intercept_tool_call_completed

    fn EventHandler::intercept_tool_call_completed(self : EventHandler, handler : (String, String) -> String) -> EventHandler

    Rewrite a tool's result — where a long output is truncated or a secret redacted before the model reads it. Chains.

    EventHandler::intercept_tool_call_starting

    fn EventHandler::intercept_tool_call_starting(self : EventHandler, handler : (String,
    Json
    ) ->
    Json
    ) -> EventHandler

    Rewrite a tool call's arguments before the tool runs. Chains.

    EventHandler::new

    A handler with every observer a no-op and every interceptor the identity.

    EventHandler::observe

    fn EventHandler::observe(self : EventHandler, listener : (Event) -> Unit) -> EventHandler

    Subscribe to the run's event stream. Chains.

    EventHandler::on_agent_completed

    fn EventHandler::on_agent_completed(self : EventHandler, handler : (String) -> Unit) -> EventHandler

    Observe the agent completing, with its answer. Chains.

    EventHandler::on_agent_execution_failed

    fn EventHandler::on_agent_execution_failed(self : EventHandler, handler : (String) -> Unit) -> EventHandler

    Observe a run ending without an answer, with the reason. Chains.

    EventHandler::on_agent_starting

    fn EventHandler::on_agent_starting(self : EventHandler, handler : (String) -> Unit) -> EventHandler

    Observe the agent starting, with the text it was given. Chains.

    EventHandler::on_llm_call_completed

    fn EventHandler::on_llm_call_completed(self : EventHandler, handler : (
    Reply
    ) -> Unit) -> EventHandler

    Observe each reply. Chains, and changes nothing in flight.

    EventHandler::on_llm_call_starting

    fn EventHandler::on_llm_call_starting(self : EventHandler, handler : (
    Request
    ) -> Unit) -> EventHandler

    Observe each request just before it is sent, as the interceptors left it. Chains, and changes nothing in flight.

    EventHandler::on_llm_streaming_completed

    fn EventHandler::on_llm_streaming_completed(self : EventHandler, handler : (
    Reply
    ) -> Unit) -> EventHandler

    Observe a streamed reply once the stream ended. Chains.

    EventHandler::on_llm_streaming_frame

    fn EventHandler::on_llm_streaming_frame(self : EventHandler, handler : (String) -> Unit) -> EventHandler

    Observe each text delta off a streamed reply. Chains.

    EventHandler::on_llm_streaming_starting

    fn EventHandler::on_llm_streaming_starting(self : EventHandler, handler : (
    Request
    ) -> Unit) -> EventHandler

    Observe a streamed request starting. Chains.

    EventHandler::on_node_execution_completed

    fn EventHandler::on_node_execution_completed(self : EventHandler, handler : (String) -> Unit) -> EventHandler

    Observe each node after it runs. Chains.

    EventHandler::on_node_execution_failed

    fn EventHandler::on_node_execution_failed(self : EventHandler, handler : (String, String) -> Unit) -> EventHandler

    Observe a node that raised; the error still ends the run. Chains.

    EventHandler::on_node_execution_starting

    fn EventHandler::on_node_execution_starting(self : EventHandler, handler : (String) -> Unit) -> EventHandler

    Observe each node before it runs. Chains.

    EventHandler::on_strategy_completed

    fn EventHandler::on_strategy_completed(self : EventHandler, handler : (String, String) -> Unit) -> EventHandler

    Observe the strategy completing, with its name and the answer. Chains.

    EventHandler::on_strategy_starting

    fn EventHandler::on_strategy_starting(self : EventHandler, handler : (String) -> Unit) -> EventHandler

    Observe the strategy starting, by name. Chains.

    EventHandler::on_subgraph_execution_completed

    fn EventHandler::on_subgraph_execution_completed(self : EventHandler, handler : (String, String) -> Unit) -> EventHandler

    Observe a nested strategy after it finished, with its answer. Chains.

    EventHandler::on_subgraph_execution_starting

    fn EventHandler::on_subgraph_execution_starting(self : EventHandler, handler : (String) -> Unit) -> EventHandler

    Observe a nested strategy before it is walked. Chains.

    EventHandler::on_tool_call_completed

    fn EventHandler::on_tool_call_completed(self : EventHandler, handler : (String, String) -> Unit) -> EventHandler

    Observe each tool result. Chains, and changes nothing in flight.

    EventHandler::on_tool_call_failed

    fn EventHandler::on_tool_call_failed(self : EventHandler, handler : (String, String) -> Unit) -> EventHandler

    Observe a call that produced no result — the tool raised, or the model named one that does not exist — with the reason that goes back to the model. Chains.

    EventHandler::on_tool_call_starting

    fn EventHandler::on_tool_call_starting(self : EventHandler, handler : (String,
    Json
    ) -> Unit) -> EventHandler

    Observe each tool call before it runs. Chains, and changes nothing in flight.

    EventHandler::on_tool_validation_failed

    fn EventHandler::on_tool_validation_failed(self : EventHandler, handler : (String,
    Json
    , String) -> Unit) -> EventHandler

    Observe arguments rejected before the tool ran. Chains.

    EventHandler::report

    fn EventHandler::report(self : EventHandler, event : Event) -> Unit

    Report one event to the subscriber.

    ExecuteMode

    pub(all) enum ExecuteMode {
    All
    Single(Int)
    }

    Which calls an execution node runs.

    FirstChoice

    pub struct FirstChoice {
    }

    Take the first candidate.

    FirstChoice::choose

    FirstChoice::new

    The first-candidate chooser.

    HistoryPolicy

    pub(all) enum HistoryPolicy {
    Whole
    FromLast(Int)
    }

    Which part of the conversation a compression node folds into a summary.

    Limits

    pub(all) struct Limits {
    iterations : Int
    tool_calls : Int
    steps : Int
    }

    What a run may spend. iterations counts model calls, tool_calls counts executions, and steps bounds the graph walk itself so a strategy that loops on its own still terminates.

    The numbers follow the agent frameworks this one is built for: 50 model calls is the cap their default agent uses, and a thousand node visits is the walk limit a compiled graph gets. Raise them for a run that legitimately needs more, lower them in a test.

    Limits::new

    fn Limits::new() -> Limits

    The caps of a plain agent: [default_limits].

    Limits::with_iterations

    fn Limits::with_iterations(self : Limits, iterations : Int) -> Limits

    A copy with the model-call cap replaced.

    Limits::with_steps

    fn Limits::with_steps(self : Limits, steps : Int) -> Limits

    A copy with the walk cap replaced.

    Limits::with_tool_calls

    fn Limits::with_tool_calls(self : Limits, tool_calls : Int) -> Limits

    A copy with the tool-call cap replaced.

    MissingTools

    pub(all) enum MissingTools {
    Keep
    Convert
    ConvertAll
    }

    What to do with the tool calls and results a conversation already carries when the agent reading it does not offer those tools.

    A thread outlives the configuration that wrote it: a checkpoint recorded by an agent with a search tool may be resumed by one without it, and a provider that is handed a call it never advertised, or a result whose call it cannot see, has every right to refuse the request. The two converting policies replace those parts with text that says what happened, so the conversation stays readable.

    ModelCall

    pub(all) struct ModelCall {
    request :
    Request

    }

    One model call about to be made.

    ModelChoice

    pub struct ModelChoice {
    provider : &
    Provider

    model : String
    }

    Ask a model which candidate answers best, and keep that one.

    ModelChoice::choose

    ModelChoice::new

    fn ModelChoice::new(provider : &
    Provider
    , model : String) -> ModelChoice

    A chooser that judges with provider / model.

    ModelOutcome

    pub(all) enum ModelOutcome {
    Replied(
    Reply
    )
    Failed(reason~ : String, retryable~ : Bool)
    Halted(String)
    }

    What a model call came to. Halted is a middleware refusing to spend the call, carrying the text the run ends with — the shape a call limit takes.

    NodeKind

    pub(all) enum NodeKind {
    Start(then~ : String)
    Request(RequestMode)
    Execute(ExecuteMode)
    Compress(HistoryPolicy)
    Finish
    Think(prompt~ : String, every~ : Int)
    Advise(String)
    Custom(String)
    Turn(mode~ : RequestMode, then~ : String)
    Delegate(
    Graph
    [AgentState, Update])
    }

    One position in a strategy graph.

    Four kinds cover the twenty-six node functions the graph DSL of the framework this one is designed after exposes: every request variant is one Request mode, every tool-result variant folds into the request that follows it, tool execution is one node, history compression and the exit are one each. The moderation nodes are a middleware here, because what they do — inspect or rewrite messages on the way through — is a pipeline concern.

    Options

    pub(all) struct Options {
    temperature : Double?
    max_tokens : Int?
    choice :
    ToolChoice

    stop : Array[String]
    extra : Map[String,
    Json
    ]
    }

    The request settings every call from this agent carries. The provider's own defaults apply to anything left unset, so an empty record means "let the model decide".

    Passthrough

    pub struct Passthrough {
    label : String
    }

    A middleware that changes nothing, for a caller that wants one hook and no others.

    Passthrough::after_agent

    async fn Passthrough::after_agent(_self : Passthrough, _context : RunContext, _state : AgentState) -> Array[Update]

    Passthrough::before_agent

    async fn Passthrough::before_agent(_self : Passthrough, _context : RunContext) -> Array[Update]

    Passthrough::install

    fn Passthrough::install(_self : Passthrough, _toolbox : Tools) -> Unit

    Passthrough::name

    fn Passthrough::name(self : Passthrough) -> String

    The name it was built with.

    Passthrough::new

    fn Passthrough::new(name : String) -> Passthrough

    A pass-through middleware under name.

    Passthrough::wrap_model

    async fn Passthrough::wrap_model(_self : Passthrough, _context : RunContext, call : ModelCall, next : async (ModelCall) -> ModelOutcome) -> ModelOutcome

    Passthrough::wrap_tool

    async fn Passthrough::wrap_tool(_self : Passthrough, _context : RunContext, call : ToolCall, next : async (ToolCall) -> ToolOutcome) -> ToolOutcome

    RequestMode

    pub(all) enum RequestMode {
    Tools
    NoTools
    OnlyCalling
    ForceOne(String)
    Choice(Int)
    Streaming
    StructuredOutput
    }

    Which way a request node asks the model.

    This is the whole of the request side: the many request nodes a Kotlin-style DSL spells out separately differ only in what they put in the request — the tools, the choice, the number of candidates, whether the answer is streamed or shaped by a schema.

    RunContext

    pub(all) struct RunContext {
    name : String
    model : String
    thread : String
    step : Int
    state : AgentState
    answer :
    Json
    ?
    runtime : Runtime
    handover :
    Ref
    [String?]
    pending : Array[Update]
    }

    What a middleware is handed about the run it is taking part in: the agent's identity, the thread it belongs to, the step it is on, and the state as of this node.

    The state is a snapshot — a middleware that wants to change it returns updates, so every change goes through the graph and lands in the checkpoint like a node's own write.

    Runtime

    pub struct Runtime {
    name : String
    provider : &
    Provider

    model : String
    instructions : String?
    tools : Tools
    options : Options
    limits : Limits
    middleware : Array[&Middleware]
    events : EventHandler
    structured : Structured?
    chooser : &Chooser?
    exit_tool : String?
    missing_tools : MissingTools
    custom : Map[String, async (Runtime, AgentState,
    Run
    ) -> Array[
    Step
    [AgentState, Update]]]
    nodes : Array[String]
    }

    Everything a node needs that is not the state: who is running, how to reach the model, what may be called, which middleware is installed, what the caps are, and where events go.

    Nodes are closures over one of these, so a graph is bound to a runtime at compile time and two agents with different providers are two graphs over the same strategy.

    Runtime::context

    fn Runtime::context(self : Runtime, run :
    Run
    , state : AgentState) -> RunContext

    The context a middleware sees for this node.

    Runtime::has_node

    fn Runtime::has_node(self : Runtime, name : String) -> Bool

    Whether this graph has a node of that name.

    Runtime::provider

    The provider a run calls, for a middleware or a composed strategy that needs to reach it.

    Runtime::request_for

    fn Runtime::request_for(self : Runtime, mode : RequestMode, state : AgentState) ->
    Request

    The request this node sends: the conversation so far, the tools the mode allows, and the agent's options.

    Runtime::tool

    fn Runtime::tool(self : Runtime, name : String) -> ToolSpec?

    The tool of this name, if one is installed.

    Runtime::tool_specs

    The descriptors advertised on a call.

    Strategy

    pub(all) struct Strategy {
    name : String
    entry : String
    nodes : Array[(String, NodeKind)]
    edges : Array[(String, String)]
    limit : Int
    }

    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.

    Strategy::compile

    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.

    Strategy::edge

    fn Strategy::edge(self : Strategy, from : String, to : String) -> Strategy

    Add a fixed edge.

    Strategy::new

    fn Strategy::new(name : String, limit? : Int) -> Strategy

    An empty strategy starting at the agent node, with the engine's default walk limit.

    Strategy::node

    fn Strategy::node(self : Strategy, name : String, kind : NodeKind) -> Strategy

    Add a node.

    Strategy::node_names

    fn Strategy::node_names(self : Strategy) -> Array[String]

    The names of the strategy's nodes, in the order they were added.

    Structured

    pub(all) struct Structured {
    name : String
    schema :
    Json

    }

    Ask the model for an object that matches schema, in a call that advertises a single tool of that shape. The model's answer is the tool call's arguments, which is how a provider without a response_format field can still be held to a schema.

    Structured::new

    fn Structured::new(name : String, schema :
    Json
    ) -> Structured

    A structured-output request named name, validated against schema.

    ToolCall

    pub(all) struct ToolCall {
    part :
    Part

    }

    One tool call about to be made.

    ToolOutcome

    pub(all) enum ToolOutcome {
    Done(String)
    Failed(String)
    Suspend(
    Json
    )
    }

    What a tool call came to. Failed records the reason as an error result, which is what the model reads and what a retry policy looks at.

    ToolSpec

    pub(all) struct ToolSpec {
    tool :
    Tool

    run : async (
    Json
    , RunContext) -> String
    }

    A tool the model may call and the function behind it. The descriptor is what the model sees; the function is handed the arguments object and the run it belongs to, and returns the text the model reads back.

    The run context is what makes a stateful tool possible — a todo list remembers itself, a retrieval tool can see what the run already looked at — without a second tool interface.

    ToolSpec::new

    fn ToolSpec::new(name~ : String, description~ : String, run~ : async (
    Json
    , RunContext) -> String, schema? :
    Json
    ) -> ToolSpec

    A tool with a JSON-schema descriptor.

    ToolSpec::of

    A tool whose descriptor is already built.

    Tools

    pub struct Tools {
    specs : Array[ToolSpec]
    }

    The tools being collected for an agent: what the config brings, and what each middleware adds when the agent is built.

    Tools::add

    fn Tools::add(self : Tools, spec : ToolSpec) -> Unit

    Add one, replacing a tool of the same name so a later registration wins.

    Tools::new

    fn Tools::new() -> Tools

    An empty collection.

    Tools::register

    fn Tools::register(self : Tools, name~ : String, description~ : String, run~ : async (
    Json
    , RunContext) -> String, schema? :
    Json
    ) -> Unit

    Add a tool by name, description and body.

    Tools::specs

    fn Tools::specs(self : Tools) -> Array[ToolSpec]

    The collected tools.

    Update

    pub(all) enum Update {
    Append(Array[
    Message
    ])
    Replace(Array[
    Message
    ])
    Store(key~ : String, value~ :
    Json
    )
    Forget(key~ : String)
    Spend(model_calls~ : Int, tool_calls~ : Int)
    Answer(String)
    Adopt(AgentState)
    }

    One change a node makes to the state. A node returns these as Step::Write, and the graph applies them in order through [merge]; they are also what a checkpoint's pending writes replay.

    Update::to_json

    after_agent_hooks

    async fn after_agent_hooks(runtime : Runtime, context : RunContext, state : AgentState) -> Array[Update]

    Run the run-end hooks in order and return what they asked to write.

    agent_node

    let agent_node : String

    The node an agent run starts from: it seeds the system message, runs the middleware's run-start hooks, and hands over to the model node.

    answer_only

    fn answer_only(name? : String) -> Strategy

    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.

    before_agent_hooks

    async fn before_agent_hooks(runtime : Runtime, context : RunContext) -> Array[Update]

    Run the run-start hooks in order and return what they asked to write.

    chat

    fn chat() -> Strategy

    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.

    compress

    async fn compress(runtime : Runtime, context : RunContext, messages : Array[
    Message
    ], policy : HistoryPolicy) -> Compressed

    Fold older conversation into a summary, keeping the system message and the newest turns.

    A run that goes on long enough meets the model's context window; compressing is cheaper than failing, and the summary keeps the thread of the work. Whole summarises everything but the system message, FromLast(n) keeps the last n messages word for word.

    convert_missing_tools

    fn convert_missing_tools(messages : Array[
    Message
    ], known : Array[String], policy : MissingTools) -> Array[
    Message
    ]

    The conversation as the request should carry it, with the parts that name unknown tools replaced by text.

    known is the tool names this agent offers. A part is converted when the policy says so and the tool is missing; text and image parts are never touched, and a message with nothing to convert is returned unchanged rather than rebuilt.

    create_agent

    Build an agent. The strategy defaults to [single_run]; tools from the config are installed first, then whatever the middleware contributes, so a middleware can replace a default tool of the same name.

    default_limits

    let default_limits : Limits

    The default caps.

    default_options

    let default_options : Options

    Nothing pinned: the provider's defaults, tools left to the model's judgement, no stop sequences.

    describe

    fn describe(error : AgentError) -> String

    A failure as a line of text, for hooks that only report.

    error_key

    let error_key : String

    The storage key a run records its own failure under. The graph cannot raise a library error from a node, so the node records what went wrong and the walk ends; the agent turns that record back into the error a caller expects.

    error_text

    fn error_text(error : Error) -> String

    The text of an error, without the type path a suberror's to_string prepends.

    finish_node

    let finish_node : String

    The node a run ends on.

    handoff_key

    let handoff_key : String

    The storage key a tool writes to ask the run to hand over to another agent. The value is the node name of the agent to continue with.

    install_tools

    fn install_tools(runtime : Runtime) -> Unit

    Let every middleware add its tools. Done once, when the agent is built.

    merge

    fn merge(state : AgentState, update : Update) -> AgentState

    Apply one update.

    model_node

    let model_node : String

    The node that makes one model call.

    node_agent

    async fn node_agent(runtime : Runtime, then : String, state : AgentState, run :
    Run
    ) -> Array[
    Step
    [AgentState, Update]]

    The run-start node.

    node_compress

    The compression node: replace older messages with a summary the model wrote.

    node_custom

    async fn node_custom(runtime : Runtime, name : String, state : AgentState, run :
    Run
    ) -> Array[
    Step
    [AgentState, Update]]

    A node the caller registered on the runtime, by name.

    node_execute

    The tool node: run the calls, feed the results back, and route to the next agent when a tool asked for a handover.

    node_finish

    The run-end node: settle the answer, then let the middleware add anything it kept for the end. A node with no successors ends the walk.

    node_request

    The model node: one call, then route on what came back.

    node_request_to

    async fn node_request_to(runtime : Runtime, mode : RequestMode, then : String, state : AgentState, run :
    Run
    ) -> Array[
    Step
    [AgentState, Update]]

    The model node with a different destination for a prose answer.

    node_think

    async fn node_think(runtime : Runtime, state : AgentState, run :
    Run
    , prompt~ : String, every~ : Int) -> Array[
    Step
    [AgentState, Update]]

    The reasoning node: ask the model what it has learned, without tools, and keep its answer in the conversation so the next action is informed by it. Skipped on rounds that are not due.

    pipeline_model

    async fn pipeline_model(runtime : Runtime, context : RunContext, call : ModelCall, mode : RequestMode) -> ModelOutcome

    How one model call is made: the middleware chain, outermost first, ending at the provider. Each middleware receives the rest of the chain, so a retry policy re-runs the ones inside it and a cache short-circuits them.

    The event handler's two model-call interceptors wrap the whole chain: the request is the one they let through, and the reply is the one they hand back, so a hook sees every call whatever the strategy and whatever the mode.

    pipeline_tool

    async fn pipeline_tool(runtime : Runtime, context : RunContext, call : ToolCall) -> ToolOutcome

    How one tool call is made: the middleware chain, ending at the toolbox. A tool that raises or is not registered comes back as a failed outcome, which is what the model reads.

    react

    fn react(reasoning_prompt? : String, interval? : Int) -> Strategy

    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.

    role_code

    fn role_code(role :
    Role
    ) -> String

    The wire name of a role, the same spelling the providers use.

    role_of

    fn role_of(code : String) ->
    Role
    ?

    A role from its wire name.

    single_run

    fn single_run(streaming? : Bool) -> Strategy

    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.

    store

    fn[T :
    ToJson
    ] store(key : String, value : T) -> Update

    Store value under key — the update a node writes to remember something across nodes.

    structured_output

    fn structured_output(name? : String) -> Strategy

    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.

    tool_result

    fn[T :
    ToJson
    ] tool_result(value : T) -> String

    What a tool hands back to the model, from any value its function returns: the JSON text of the value. A String is passed through as it is by the code #tool generates, so a tool that answers in prose is not quoted.

    tools_node

    let tools_node : String

    The node that executes the calls a reply asked for.