Struct AgentOptions 

pub struct AgentOptions {

    pub system_prompt: String,
    pub static_system_prompt: Option<String>,
    pub dynamic_system_prompt: Option<Box<dyn Fn() -> String + Send + Sync>>,
    pub model: ModelSpec,
    pub tools: Vec<Arc<dyn AgentTool>>,
    pub stream_fn: Arc<dyn StreamFn>,
    pub convert_to_llm: Arc<dyn Fn(&AgentMessage) -> Option<LlmMessage> + Send + Sync>,
    pub transform_context: Option<Arc<dyn ContextTransformer>>,
    pub get_api_key: Option<Arc<dyn Fn(&str) -> Pin<Box<dyn Future<Output = Option<String>> + Send>> + Send + Sync>>,
    pub retry_strategy: Box<dyn RetryStrategy>,
    pub stream_options: StreamOptions,
    pub steering_mode: SteeringMode,
    pub follow_up_mode: FollowUpMode,
    pub structured_output_max_retries: usize,
    pub approve_tool: Option<Arc<dyn Fn(ToolApprovalRequest) -> Pin<Box<dyn Future<Output = ToolApproval> + Send>> + Send + Sync>>,
    pub approval_mode: ApprovalMode,
    pub available_models: Vec<(ModelSpec, Arc<dyn StreamFn>)>,
    pub pre_turn_policies: Vec<Arc<dyn PreTurnPolicy>>,
    pub pre_dispatch_policies: Vec<Arc<dyn PreDispatchPolicy>>,
    pub post_turn_policies: Vec<Arc<dyn PostTurnPolicy>>,
    pub post_loop_policies: Vec<Arc<dyn PostLoopPolicy>>,
    pub event_forwarders: Vec<EventForwarderFn>,
    pub async_transform_context: Option<Arc<dyn AsyncContextTransformer>>,
    pub checkpoint_store: Option<Arc<dyn CheckpointStore>>,
    pub custom_message_registry: Option<Arc<CustomMessageRegistry>>,
    pub metrics_collector: Option<Arc<dyn MetricsCollector>>,
    pub token_counter: Option<Arc<dyn TokenCounter>>,
    pub fallback: Option<ModelFallback>,
    pub external_message_provider: Option<Arc<dyn MessageProvider>>,
    pub tool_execution_policy: ToolExecutionPolicy,
    pub plan_mode_addendum: Option<String>,
    pub session_state: Option<SessionState>,
    pub credential_resolver: Option<Arc<dyn CredentialResolver>>,
    pub cache_config: Option<CacheConfig>,
    pub agent_name: Option<String>,
    pub transfer_chain: Option<TransferChain>,
}

Configuration options for constructing an Agent.

Fields

system_prompt: String

System prompt (used as-is when no static/dynamic split is configured).

static_system_prompt: Option<String>

Static portion of the system prompt (cacheable, immutable for the agent lifetime).

When set, takes precedence over system_prompt as the system message.

dynamic_system_prompt: Option<Box<dyn Fn() -> String + Send + Sync>>

Dynamic portion of the system prompt (per-turn, non-cacheable).

Called fresh each turn. Its output is injected as a separate user-role message immediately after the system prompt, so it does not invalidate provider-side caches.

model: ModelSpec

Model specification.

tools: Vec<Arc<dyn AgentTool>>

Available tools.

stream_fn: Arc<dyn StreamFn>

The streaming function implementation.

convert_to_llm: Arc<dyn Fn(&AgentMessage) -> Option<LlmMessage> + Send + Sync>

Converts agent messages to LLM messages (filter custom messages).

transform_context: Option<Arc<dyn ContextTransformer>>

Optional context transformer.

get_api_key: Option<Arc<dyn Fn(&str) -> Pin<Box<dyn Future<Output = Option<String>> + Send>> + Send + Sync>>

Optional async API key resolver.

retry_strategy: Box<dyn RetryStrategy>

Retry strategy for transient failures.

stream_options: StreamOptions

Per-call stream options.

steering_mode: SteeringMode

Steering queue drain mode.

follow_up_mode: FollowUpMode

Follow-up queue drain mode.

structured_output_max_retries: usize

Max retries for structured output validation.

approve_tool: Option<Arc<dyn Fn(ToolApprovalRequest) -> Pin<Box<dyn Future<Output = ToolApproval> + Send>> + Send + Sync>>

Optional async callback for approving/rejecting tool calls before execution.

approval_mode: ApprovalMode

Controls whether the approval gate is active. Defaults to Enabled.

available_models: Vec<(ModelSpec, Arc<dyn StreamFn>)>

Additional model specs for model cycling (each with its own stream function).

pre_turn_policies: Vec<Arc<dyn PreTurnPolicy>>

Pre-turn policies evaluated before each LLM call.

pre_dispatch_policies: Vec<Arc<dyn PreDispatchPolicy>>

Pre-dispatch policies evaluated per tool call, before approval.

post_turn_policies: Vec<Arc<dyn PostTurnPolicy>>

Post-turn policies evaluated after each completed turn.

post_loop_policies: Vec<Arc<dyn PostLoopPolicy>>

Post-loop policies evaluated after the inner loop exits.

event_forwarders: Vec<EventForwarderFn>

Event forwarders that receive all dispatched events.

async_transform_context: Option<Arc<dyn AsyncContextTransformer>>

Optional async context transformer (runs before the sync transformer).

checkpoint_store: Option<Arc<dyn CheckpointStore>>

Optional checkpoint store for persisting agent state.

custom_message_registry: Option<Arc<CustomMessageRegistry>>

Optional registry used to deserialize persisted CustomMessage values when restoring from a Checkpoint or LoopCheckpoint.

When set, the agent’s restore_from_checkpoint / load_and_restore_checkpoint / resume / resume_stream paths thread this registry into Checkpoint::restore_messages so that custom messages survive a round trip through the checkpoint store. When None, persisted custom messages are silently dropped on restore (legacy behavior).

metrics_collector: Option<Arc<dyn MetricsCollector>>

Optional metrics collector for per-turn observability.

token_counter: Option<Arc<dyn TokenCounter>>

Optional custom token counter for context compaction.

When set, the default SlidingWindowTransformer uses this counter instead of the chars / 4 heuristic. Has no effect if a custom transform_context is provided (use SlidingWindowTransformer::with_token_counter directly in that case).

fallback: Option<ModelFallback>

Optional model fallback chain tried when the primary model exhausts its retry budget on a retryable error.

external_message_provider: Option<Arc<dyn MessageProvider>>

Optional external message provider composed with the internal queues.

Set via with_message_channel or with_external_message_provider.

tool_execution_policy: ToolExecutionPolicy

Controls how tool calls within a turn are dispatched.

Defaults to Concurrent.

plan_mode_addendum: Option<String>

Optional addendum appended to the system prompt when entering plan mode.

Falls back to DEFAULT_PLAN_MODE_ADDENDUM when None.

session_state: Option<SessionState>

Optional initial session state for pre-seeding key-value pairs.

credential_resolver: Option<Arc<dyn CredentialResolver>>

Optional credential resolver for tool authentication.

When set, tools that return Some from auth_config() will have their credentials resolved before execution.

cache_config: Option<CacheConfig>

Optional context caching configuration.

When set, the turn pipeline annotates cacheable prefix messages with CacheHint markers and emits AgentEvent::CacheAction events.

agent_name: Option<String>

Optional agent name used for transfer chain safety enforcement.

When set, the loop pushes this name onto the TransferChain at startup so circular transfers back to this agent are detected.

transfer_chain: Option<TransferChain>

Optional transfer chain carried from a previous handoff.

When set, the loop starts with this chain instead of an empty one.

Implementations

impl AgentOptions

pub fn new( system_prompt: impl Into<String>, model: ModelSpec, stream_fn: Arc<dyn StreamFn>, convert_to_llm: impl Fn(&AgentMessage) -> Option<LlmMessage> + Send + Sync + 'static, ) -> Self

Create options with required fields and sensible defaults.

pub fn new_simple( system_prompt: impl Into<String>, model: ModelSpec, stream_fn: Arc<dyn StreamFn>, ) -> Self

Simplified constructor using default_convert and sensible defaults.

Equivalent to AgentOptions::new(system_prompt, model, stream_fn, default_convert).

pub fn from_connections( system_prompt: impl Into<String>, connections: ModelConnections, ) -> Self

Build options directly from a ModelConnections bundle.

This avoids the manual into_parts() decomposition. The primary model and stream function are extracted, and any extra models are set as available models for cycling.

pub fn with_tools(self, tools: Vec<Arc<dyn AgentTool>>) -> Self

Set the available tools.

pub fn with_default_tools(self) -> Self

Convenience: register all built-in tools (bash, read-file, write-file).

pub fn with_retry_strategy(self, strategy: Box<dyn RetryStrategy>) -> Self

Set the retry strategy.

pub fn with_stream_options(self, options: StreamOptions) -> Self

Set the stream options.

pub fn with_transform_context( self, transformer: impl ContextTransformer + 'static, ) -> Self

Set the context transformer.

pub fn with_transform_context_fn( self, f: impl Fn(&mut Vec<AgentMessage>, bool) + Send + Sync + 'static, ) -> Self

Set the context transform hook using a closure.

Backward-compatible with the old closure-based API. The closure receives (&mut Vec<AgentMessage>, bool) where the bool is the overflow signal.

pub fn with_get_api_key( self, f: impl Fn(&str) -> Pin<Box<dyn Future<Output = Option<String>> + Send>> + Send + Sync + 'static, ) -> Self

Set the API key resolver.

pub const fn with_steering_mode(self, mode: SteeringMode) -> Self

Set the steering mode.

pub const fn with_follow_up_mode(self, mode: FollowUpMode) -> Self

Set the follow-up mode.

pub const fn with_structured_output_max_retries(self, n: usize) -> Self

Set the max retries for structured output.

pub fn with_approve_tool( self, f: impl Fn(ToolApprovalRequest) -> Pin<Box<dyn Future<Output = ToolApproval> + Send>> + Send + Sync + 'static, ) -> Self

Set the tool approval callback.

pub fn with_approve_tool_async<F, Fut>(self, f: F) -> Self

where F: Fn(ToolApprovalRequest) -> Fut + Send + Sync + 'static, Fut: Future<Output = ToolApproval> + Send + 'static,

Sets the tool approval callback using an async closure.

This is a convenience wrapper around with_approve_tool that avoids the Pin<Box<dyn Future>> return type ceremony.

pub const fn with_approval_mode(self, mode: ApprovalMode) -> Self

Set the approval mode.

pub fn with_available_models( self, models: Vec<(ModelSpec, Arc<dyn StreamFn>)>, ) -> Self

Set additional models for model cycling.

pub fn with_pre_turn_policy(self, policy: impl PreTurnPolicy + 'static) -> Self

Add a pre-turn policy (evaluated before each LLM call).

pub fn with_pre_dispatch_policy( self, policy: impl PreDispatchPolicy + 'static, ) -> Self

Add a pre-dispatch policy (evaluated per tool call, before approval).

pub fn with_post_turn_policy( self, policy: impl PostTurnPolicy + 'static, ) -> Self

Add a post-turn policy (evaluated after each completed turn).

pub fn with_post_loop_policy( self, policy: impl PostLoopPolicy + 'static, ) -> Self

Add a post-loop policy (evaluated after the inner loop exits).

pub fn with_event_forwarder( self, f: impl Fn(AgentEvent) + Send + Sync + 'static, ) -> Self

Add an event forwarder that receives all events dispatched by this agent.

pub fn with_async_transform_context( self, transformer: impl AsyncContextTransformer + 'static, ) -> Self

Set the async context transformer (runs before the sync transformer).

pub fn with_checkpoint_store( self, store: impl CheckpointStore + 'static, ) -> Self

Set the checkpoint store for persisting agent state.

pub fn with_custom_message_registry( self, registry: CustomMessageRegistry, ) -> Self

Set the CustomMessageRegistry used to decode persisted custom messages when restoring from a checkpoint.

Without this, Checkpoint::restore_messages and LoopCheckpoint::restore_messages are called with None in the public agent restore/resume APIs, and any persisted CustomMessage values are silently dropped.

pub fn with_custom_message_registry_arc( self, registry: Arc<CustomMessageRegistry>, ) -> Self

Set the CustomMessageRegistry from a shared Arc, for sharing a single registry across multiple agents.

pub fn with_metrics_collector( self, collector: impl MetricsCollector + 'static, ) -> Self

Set the metrics collector for per-turn observability.

pub fn with_token_counter(self, counter: impl TokenCounter + 'static) -> Self

Set a custom token counter for context compaction.

Replaces the default chars / 4 heuristic used by the built-in SlidingWindowTransformer. Supply a tiktoken or provider-native tokenizer for accurate budget enforcement.

pub fn with_model_fallback(self, fallback: ModelFallback) -> Self

Set the model fallback chain.

When the primary model exhausts its retry budget on a retryable error, each fallback model is tried in order (with a fresh retry budget) before the error is surfaced.

pub fn with_message_channel(&mut self) -> MessageSender

Attach a push-based message channel and return the sender handle.

Creates a ChannelMessageProvider that is composed with the agent’s internal steering/follow-up queues. External code can push messages via the returned MessageSender.

Example

let mut opts = AgentOptions::new_simple("prompt", model, stream_fn);
let sender = opts.with_message_channel();
// later, from another task:
sender.send(user_msg("follow-up directive"));

pub fn with_external_message_provider( self, provider: impl MessageProvider + 'static, ) -> Self

Set an external MessageProvider to compose with the internal queues.

For push-based messaging, prefer with_message_channel.

pub fn with_tool_execution_policy(self, policy: ToolExecutionPolicy) -> Self

Set the tool execution policy.

Controls whether tool calls are dispatched concurrently (default), sequentially, by priority, or via a fully custom strategy.

pub fn with_plan_mode_addendum(self, addendum: impl Into<String>) -> Self

Override the system prompt addendum appended when entering plan mode.

When not set, DEFAULT_PLAN_MODE_ADDENDUM is used.

pub fn with_initial_state(self, state: SessionState) -> Self

Pre-seed session state with initial key-value pairs.

pub fn with_state_entry( self, key: impl Into<String>, value: impl Serialize, ) -> Self

Add a single key-value pair to initial state.

pub fn with_credential_resolver( self, resolver: Arc<dyn CredentialResolver>, ) -> Self

Configure a credential resolver for tool authentication.

When set, tools that declare auth_config() will have their credentials resolved before execution.

pub const fn with_cache_config(self, config: CacheConfig) -> Self

Set context caching configuration.

pub fn with_static_system_prompt(self, prompt: String) -> Self

Set a static system prompt (cacheable, immutable for the agent lifetime).

When set, takes precedence over system_prompt.

pub fn with_dynamic_system_prompt( self, f: impl Fn() -> String + Send + Sync + 'static, ) -> Self

Set a dynamic system prompt closure (called fresh each turn).

Its output is injected as a separate user-role message after the system prompt so it does not invalidate provider-side caches.

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

Set the agent name for transfer chain safety enforcement.

When set, the agent loop pushes this name onto the TransferChain at startup. Transfers back to this agent (circular) or exceeding max depth are rejected.

pub fn with_transfer_chain(self, chain: TransferChain) -> Self

Seed transfer chain state from a previous handoff signal.

Use this on the target agent so transfer safety checks continue across agent boundaries.

pub fn effective_system_prompt(&self) -> &str

Return the effective system prompt (static portion only).

Returns static_system_prompt if set, otherwise falls back to system_prompt. Does NOT include dynamic content.

impl AgentOptions

pub fn to_config(&self) -> AgentConfig

Extract a serializable AgentConfig from these options.

Tool implementations are represented by name only. Trait objects (transformers, policies, callbacks) are omitted — their presence must be restored by the consumer after deserialization.

pub fn from_config( config: AgentConfig, stream_fn: Arc<dyn StreamFn>, convert_to_llm: impl Fn(&AgentMessage) -> Option<LlmMessage> + Send + Sync + 'static, ) -> Self

Construct AgentOptions from a deserialized AgentConfig.

Equivalent to AgentConfig::into_agent_options — provided here for discoverability.