Module run 

A sans-IO, steppable, serializable state machine for the agent prompt loop.

AgentRun owns every decision the agent loop makes — turn counting, tool-call validation, invalid tool-call recovery, chat-history threading, usage aggregation and final response construction — without performing any IO itself. A driver advances the machine by calling AgentRun::next_step and acting on the returned AgentRunStep:

• AgentRunStep::CallModel: send a completion request to the model and feed the result back via AgentRun::model_response.
• AgentRunStep::CallTools: execute the listed tool calls (with whatever concurrency the driver chooses) and feed the results back via AgentRun::tool_results.
• AgentRunStep::Done: the run is complete.

Because the machine never awaits anything, it is runtime-agnostic and the whole run state is Serialize + Deserialize: a driver can serialize a run between steps (for example while tool calls are pending), persist it, and resume it later in another process. Note that serialized run state embeds the full conversation accumulated so far — persisting it inherits whatever sensitivity the conversation content has — and the serialization format carries no cross-version stability guarantee yet: resume with the same rig version that suspended the run.

crate::completion::Prompt::prompt on crate::agent::Agent drives this machine internally; the same machine can be driven by hand for custom control flow:

use rig_core::agent::run::{AgentRun, AgentRunStep, ModelTurn, ModelTurnOutcome};

let mut run = AgentRun::new("What is 2+2?").max_turns(3);
loop {
    match run.next_step()? {
        AgentRunStep::CallModel { prompt, history, .. } => {
            // Send `prompt` + `history` to a model, then:
            // run.model_response(ModelTurn { ... })?;
        }
        AgentRunStep::CallTools { calls } => {
            // Execute `calls`, then: run.tool_results(results)?;
        }
        AgentRunStep::Done(response) => {
            println!("{}", response.output);
            break;
        }
    }
}

Re-exports

pub use streamed::PartialStreamedTurn;

pub use streamed::StreamedInvalidToolCall;

pub use streamed::StreamedResolution;

pub use streamed::StreamedTurn;

pub use streamed::StreamedTurnAssembler;

pub use streamed::StreamedTurnEvent;

Modules

streamed

Streamed-turn assembly for AgentRun.

Structs

AgentRun

The sans-IO agent loop state machine. See the module docs for the driving protocol.

ModelTurn

A completed model turn fed back to AgentRun::model_response.

PendingToolCall

One tool call awaiting execution by the driver.

Enums

AgentRunStep

What a driver must do next to advance an AgentRun.

ModelTurnOutcome

Result of feeding a model turn (or an invalid tool-call resolution) into the machine.