Struct Agent 

pub struct Agent { /* private fields */ }

Minimal agent builder/runtime.

Implementations

impl Agent

pub async fn run( &self, prompt: impl Into<AgentInput>, ) -> Result<AgentResult, AgentError>

Run the agent with a user prompt.

Errors

Returns an error when the model, capabilities, validation, tools, or runtime policy fails.

pub async fn run_iter( &self, prompt: impl Into<AgentInput>, ) -> Result<AgentIterResult, AgentError>

Run the agent and collect a compact iteration trace.

Errors

Returns an error when the model, capabilities, validation, tools, or runtime policy fails.

pub async fn run_stream( &self, prompt: impl Into<AgentInput>, ) -> Result<AgentStreamResult, AgentError>

Run the agent and collect typed stream events emitted during execution.

Errors

Returns an error when the model, capabilities, validation, tools, or runtime policy fails.

pub async fn run_with_history_iter( &self, prompt: impl Into<AgentInput>, message_history: Vec<ModelMessage>, ) -> Result<AgentIterResult, AgentError>

Run the agent with prior history and collect a compact iteration trace.

Errors

Returns an error when the model, capabilities, validation, tools, or runtime policy fails.

pub async fn run_with_stream_events( &self, prompt: impl Into<AgentInput>, events: &mut Vec<AgentStreamRecord>, ) -> Result<AgentResult, AgentError>

Run the agent with an explicit typed stream event collector.

Errors

Returns an error when the model, capabilities, validation, tools, or runtime policy fails.

pub async fn run_with_history_and_stream_events( &self, prompt: impl Into<AgentInput>, message_history: Vec<ModelMessage>, events: &mut Vec<AgentStreamRecord>, ) -> Result<AgentResult, AgentError>

Run the agent with prior history and collect typed stream events.

Errors

Returns an error when the model, capabilities, validation, tools, or runtime policy fails.

pub async fn run_with_history( &self, prompt: impl Into<AgentInput>, message_history: Vec<ModelMessage>, ) -> Result<AgentResult, AgentError>

Run the agent with prior canonical message history.

Errors

Returns an error when the model, capabilities, validation, tools, or runtime policy fails.

pub async fn run_with_context_iter( &self, prompt: impl Into<AgentInput>, context: &mut AgentContext, ) -> Result<AgentIterResult, AgentError>

Run the agent using a lifecycle-wide context and collect a compact iteration trace.

Errors

Returns an error when the model, capabilities, validation, tools, or runtime policy fails.

pub async fn run_with_context_and_stream_events( &self, prompt: impl Into<AgentInput>, context: &mut AgentContext, events: &mut Vec<AgentStreamRecord>, ) -> Result<AgentResult, AgentError>

Run the agent using a lifecycle-wide context and typed stream event collector.

Errors

Returns an error when the model, capabilities, validation, tools, or runtime policy fails.

pub async fn run_with_context( &self, prompt: impl Into<AgentInput>, context: &mut AgentContext, ) -> Result<AgentResult, AgentError>

Run the agent using a lifecycle-wide context.

Errors

Returns an error when the model, capabilities, validation, tools, or runtime policy fails.

impl Agent

pub fn new(model: Arc<dyn ModelAdapter>) -> Self

Create an agent with a model adapter.

pub const fn agent_id(&self) -> &AgentId

Return the default agent id used when this agent creates a context.

pub fn agent_name(&self) -> &str

Return the default human-readable agent name.

pub fn with_agent_id(self, agent_id: AgentId) -> Self

Set the default agent id used when this agent creates a context.

pub fn with_agent_name(self, agent_name: impl Into<String>) -> Self

Set the default human-readable agent name.

pub fn with_agent_identity( self, agent_id: AgentId, agent_name: impl Into<String>, ) -> Self

Set both the default agent id and human-readable agent name.

pub fn new_context(&self) -> AgentContext

Create a fresh context using this agent’s configured identity.

pub fn with_instruction(self, instruction: impl Into<String>) -> Self

Add a static instruction.

pub fn with_dynamic_instruction( self, instruction: DynDynamicInstruction, ) -> Self

Add a dynamic instruction.

pub fn with_model_settings(self, settings: ModelSettings) -> Self

Set default model settings.

pub fn with_request_params(self, params: ModelRequestParameters) -> Self

Set default request parameters.

pub fn with_tools(self, tools: ToolRegistry) -> Self

Set runtime tools.

pub fn with_toolset(self, toolset: DynToolset) -> Self

Add one runtime toolset that is materialized for each agent context.

pub fn with_toolsets( self, toolsets: impl IntoIterator<Item = DynToolset>, ) -> Self

Add many runtime toolsets that are materialized for each agent context.

pub fn with_appended_tools(self, tools: &ToolRegistry) -> Self

Merge additional runtime tools into this agent.

pub fn tools(&self) -> ToolRegistry

Return a clone of the runtime tool registry.

pub async fn prepare_tools_for_context( &self, context: &mut AgentContext, ) -> Result<ToolRegistry, AgentError>

Prepare this agent’s static tools and context-aware toolsets for a concrete context.

This uses the same lifecycle-aware path as the normal run loop and is intended for host operations that need to execute a previously suspended tool call.

Errors

Returns an agent error when a context-aware toolset cannot be prepared.

pub async fn close_toolsets_for_context(&self, context: &mut AgentContext)

Close context-aware toolsets after host-side execution outside the normal run loop.

pub const fn with_tool_retries(self, max_retries: usize) -> Self

Set the agent-level retry default for runtime tools.

pub fn with_output_schema(self, schema: OutputSchema) -> Self

Set structured output schema.

pub fn with_output_policy(self, policy: OutputPolicy) -> Self

Apply a complete output policy.

pub fn with_output_validator(self, validator: Arc<dyn OutputValidator>) -> Self

Add an output validator.

pub fn with_output_function(self, function: DynOutputFunction) -> Self

Add an output function.

pub const fn with_usage_limits(self, limits: UsageLimits) -> Self

Set usage limits.

pub fn with_model_config(self, model_config: ModelConfig) -> Self

Set the full model config exposed to AgentContext.

pub fn with_tool_config(self, tool_config: ToolConfig) -> Self

Set tool-level configuration exposed to runtime tools.

pub fn with_context_window(self, context_window: u64) -> Self

Set the model context window exposed to AgentContext runtime instructions.

pub fn with_capability(self, capability: Arc<dyn AgentCapability>) -> Self

Add a capability hook.

pub fn with_stream_observer(self, observer: Arc<dyn AgentCapability>) -> Self

Add a stream observer hook.

pub fn with_cancellation_token(self, token: CancellationToken) -> Self

Set a cooperative cancellation token used by streaming callers.

pub fn with_capability_bundle(self, bundle: &dyn CapabilityBundle) -> Self

Apply a composable capability bundle.

pub fn with_executor(self, executor: DynAgentExecutor) -> Self

Set durable execution checkpoint handler.

pub fn with_trace_recorder(self, recorder: DynTraceRecorder) -> Self

Set runtime trace recorder.

pub const fn with_policy(self, policy: AgentRuntimePolicy) -> Self

Set runtime policy.

pub fn inspect_graph( &self, start: AgentNode, state: &AgentRunState, ) -> Result<AgentGraphTrace, GraphError>

Inspect graph transitions from a state snapshot.

Errors

Returns an error when the inspected transition is invalid for the provided state.

pub fn override_config(&self) -> AgentOverride

Create a scoped override builder for tests and alternate run contexts.

Trait Implementations

impl Clone for Agent

fn clone(&self) -> Agent

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.