Struct Agent 

pub struct Agent { /* private fields */ }

Agent for managing stateful conversations with LLM providers.

Implementations

impl Agent

pub fn new() -> Self

Create a new agent with default configuration.

pub fn with_model(model: Model) -> Self

Create an agent with a model.

pub fn set_provider(&self, provider: ArcProtocol)

Set the LLM provider explicitly.

pub fn set_api_key(&self, key: impl Into<String>)

Set a static API key.

pub fn set_get_api_key<F, Fut>(&self, resolver: F)

where F: Fn(&str) -> Fut + Send + Sync + 'static, Fut: Future<Output = Option<String>> + Send + 'static,

Set a dynamic API key resolver.

Called before each LLM request. Useful for short-lived OAuth tokens that may expire during long-running tool execution phases.

pub fn set_tool_executor<F, Fut>(&self, executor: F)

where F: Fn(&str, &str, &Value, Option<ToolUpdateCallback>) -> Fut + Send + Sync + 'static, Fut: Future<Output = AgentToolResult> + Send + 'static,

Set the tool executor callback.

The executor receives (tool_name, tool_call_id, arguments, update_callback). The update_callback can be called during execution to push streaming partial results (emitted as ToolExecutionUpdate events).

pub fn set_tool_executor_simple<F, Fut>(&self, executor: F)

where F: Fn(&str, &str, &Value) -> Fut + Send + Sync + 'static, Fut: Future<Output = AgentToolResult> + Send + 'static,

Set the tool executor callback (simple version without update callback).

Convenience method for tools that don’t need streaming updates.

pub fn set_before_tool_call<F, Fut>(&self, hook: F)

where F: Fn(BeforeToolCallContext) -> Fut + Send + Sync + 'static, Fut: Future<Output = Option<BeforeToolCallResult>> + Send + 'static,

Set the before_tool_call hook.

Called after arguments are validated but before tool execution. Return BeforeToolCallResult { block: true, .. } to prevent execution.

pub fn set_after_tool_call<F, Fut>(&self, hook: F)

where F: Fn(AfterToolCallContext) -> Fut + Send + Sync + 'static, Fut: Future<Output = Option<AfterToolCallResult>> + Send + 'static,

Set the after_tool_call hook.

Called after tool execution, before the result is committed. Return AfterToolCallResult to override content, details, or is_error.

pub fn set_convert_to_llm<F, Fut>(&self, converter: F)

where F: Fn(Vec<AgentMessage>) -> Fut + Send + Sync + 'static, Fut: Future<Output = Vec<Message>> + Send + 'static,

Set the custom AgentMessage[] → Message[] conversion function.

Called before each LLM request. The default filters out Custom messages and maps User/Assistant/ToolResult directly.

pub fn set_transform_context<F, Fut>(&self, transform: F)

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

Set the context transformation function (applied BEFORE convert_to_llm).

Use this for context window management, message pruning, injecting external context, etc.

pub fn set_on_payload<F, Fut>(&self, hook: F)

where F: Fn(Value, Model) -> Fut + Send + Sync + 'static, Fut: Future<Output = Option<Value>> + Send + 'static,

Set the payload inspection / replacement hook.

Called with the serialized request body before it is sent to the provider.

pub fn set_stream_fn<F, Fut>(&self, stream_fn: F)

where F: Fn(&Model, &Context, StreamOptions) -> Fut + Send + Sync + 'static, Fut: Future<Output = AssistantMessageEventStream> + Send + 'static,

Set a custom stream function to replace the default provider streaming.

Useful for proxy backends, custom routing, etc.

pub fn set_max_turns(&self, max: usize)

Set maximum turns per prompt.

pub fn set_security_config(&self, config: SecurityConfig)

Set the security configuration.

pub fn security_config(&self) -> SecurityConfig

Get the current security configuration.

pub fn set_tool_execution(&self, mode: ToolExecutionMode)

Set tool execution mode.

pub fn set_steering_mode(&self, mode: QueueMode)

Set the steering queue mode.

pub fn steering_mode(&self) -> QueueMode

Get the steering queue mode.

pub fn set_follow_up_mode(&self, mode: QueueMode)

Set the follow-up queue mode.

pub fn follow_up_mode(&self) -> QueueMode

Get the follow-up queue mode.

pub fn set_thinking_budgets(&self, budgets: ThinkingBudgets)

Set custom thinking budgets.

pub fn thinking_budgets(&self) -> Option<ThinkingBudgets>

Get the current thinking budgets.

pub fn set_transport(&self, transport: Transport)

Set the preferred transport.

pub fn transport(&self) -> Transport

Get the preferred transport.

pub fn set_max_retry_delay_ms(&self, ms: Option<u64>)

Set the maximum retry delay in milliseconds.

If the server requests a retry delay exceeding this value, the request fails immediately so higher-level retry logic can handle it with user visibility. None = use default (60_000ms). Some(0) = disable cap.

pub fn max_retry_delay_ms(&self) -> Option<u64>

Get the current max retry delay.

pub fn set_session_id(&self, id: impl Into<String>)

Set the session ID for caching.

pub fn session_id(&self) -> Option<String>

Get the current session ID.

pub fn clear_session_id(&self)

Clear the session ID.

pub fn subscribe<F>(&self, callback: F) -> impl Fn()

where F: Fn(&AgentEvent) + Send + Sync + 'static,

Subscribe to agent events. Returns an unsubscribe closure.

pub fn set_system_prompt(&self, prompt: impl Into<String>)

Set the system prompt.

pub fn set_model(&self, model: Model)

Set the model.

pub fn set_thinking_level(&self, level: ThinkingLevel)

Set the thinking level.

pub fn set_tools(&self, tools: Vec<AgentTool>)

Set the tools.

pub fn replace_messages(&self, messages: Vec<AgentMessage>)

Replace all messages.

pub fn append_message(&self, message: AgentMessage)

Append a message.

pub fn clear_messages(&self)

Clear all messages.

pub fn reset(&self)

Reset the agent.

pub fn steer(&self, message: AgentMessage)

Add a steering message (interrupts current work).

pub fn follow_up(&self, message: AgentMessage)

Add a follow-up message (processed after current work completes).

pub fn clear_steering_queue(&self)

Clear steering queue.

pub fn clear_follow_up_queue(&self)

Clear follow-up queue.

pub fn clear_all_queues(&self)

Clear all queues.

pub fn has_queued_messages(&self) -> bool

Check if there are queued messages.

pub async fn prompt( &self, message: impl Into<AgentMessage>, ) -> Result<Vec<AgentMessage>, AgentError>

Send a prompt to the agent.

Uses atomic compare_exchange to prevent TOCTOU race condition.

pub async fn continue_(&self) -> Result<Vec<AgentMessage>, AgentError>

Continue from current state (e.g., after adding tool results externally).

Uses atomic compare_exchange to prevent TOCTOU race condition.

pub fn abort(&self)

Abort current operation.

pub async fn wait_for_idle(&self)

Wait for the agent to become idle.

pub fn state(&self) -> &Arc<AgentState>

Get the current state.

pub fn snapshot(&self) -> AgentStateSnapshot

Take a consistent point-in-time snapshot of the agent’s full state.

Combines runtime state from AgentState with configuration (model, thinking_level) from AgentConfig.

Trait Implementations

impl Default for Agent

fn default() -> Self

Returns the “default value” for a type.