Struct AgentRunner 

pub struct AgentRunner<S> { /* private fields */ }

Typestate-parameterized agent runner.

The type parameter S encodes the current FSM state:

• Ready — can call infer
• AwaitingToolCall — can call provide_tool_results
• Finished — can access the final response

Implementations

impl AgentRunner<Ready>

pub fn new( session_id: impl Into<String>, model: impl Into<String>, system_instructions: impl Into<String>, policy: TurnPolicy, session: SessionState, ) -> Self

Create a new runner in the Ready state.

pub async fn infer( self, llm: &(impl LlmPort + ?Sized), tools: &(impl ToolPort + ?Sized), compactor: &(impl ContextCompactorPort + ?Sized), ) -> Result<AgentStepResult, AgentError>

Perform LLM inference and transition to the next state.

Returns AgentStepResult::Finished if the LLM produces a final response, or AgentStepResult::RequiresTool if tool calls are needed.

Errors

Returns an error if the LLM call fails or policy limits are exceeded.

pub async fn run_to_completion( self, llm: &(impl LlmPort + ?Sized), tools: &(impl ToolPort + ?Sized), compactor: &(impl ContextCompactorPort + ?Sized), store: &(impl SessionStore + ?Sized), ) -> Result<AgentRunner<Finished>, AgentError>

Run the agent loop until completion (high-level convenience method).

This is equivalent to calling infer in a loop until a Finished state is reached.

Errors

Returns an error if any LLM call fails.

impl AgentRunner<AwaitingToolCall>

pub fn pending_calls(&self) -> &[ToolCall]

Get the pending tool calls that need to be executed.

pub fn provide_tool_results( self, results: Vec<ToolResult>, ) -> AgentRunner<Ready>

Provide tool execution results and transition back to Ready.

The results must correspond 1:1 with the pending calls in the same order.

pub fn cancel(self, reason: impl Into<String>) -> AgentRunner<Finished>

Cancel the pending tool calls and transition to Finished.

pub fn require_approval( self, reason: impl Into<String>, ) -> AgentRunner<AwaitingApproval>

Require human approval before executing tool calls.

Transitions to AwaitingApproval state, which prevents direct tool execution. Callers must explicitly approve() or deny() to proceed.

This provides compile-time safety: AwaitingToolCall can directly execute tools via provide_tool_results(), but AwaitingApproval cannot — it must go through the approval gate first.

impl AgentRunner<AwaitingApproval>

pub fn pending_calls(&self) -> &[ToolCall]

Get the pending tool calls awaiting approval.

pub fn approval_reason(&self) -> &str

Get the reason approval was required.

pub fn approve(self) -> AgentRunner<AwaitingToolCall>

Approve the tool calls and transition back to AwaitingToolCall.

After approval, call provide_tool_results() with the execution results to continue the agent loop.

pub fn deny(self, reason: impl Into<String>) -> AgentRunner<Finished>

Deny the tool calls and transition to Finished.

The provided reason will be included in the final response for the user/audit trail.

impl AgentRunner<Finished>

pub fn response(&self) -> &AgentResponse

Get a reference to the final response.

pub fn into_response(self) -> AgentResponse

Consume the runner and return the final response.

pub fn session(&self) -> &SessionState

Get the final session state (for persistence).

pub fn context(&self) -> &RunnerContext

Get the execution context with usage stats.

Trait Implementations

impl<S: Debug> Debug for AgentRunner<S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.