Trait Agent 

pub trait Agent: Send {
    // Required methods
    fn prompt_messages_with_sender<'life0, 'async_trait>(
        &'life0 mut self,
        messages: Vec<AgentMessage>,
        tx: UnboundedSender<AgentEvent>,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn continue_loop_with_sender<'life0, 'async_trait>(
        &'life0 mut self,
        tx: UnboundedSender<AgentEvent>,
        kind: ContinuationKind,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn messages(&self) -> &[AgentMessage];
    fn is_streaming(&self) -> bool;
    fn agent_id(&self) -> &str;
    fn session_id(&self) -> &str;
    fn clear_messages(&mut self);
    fn append_message(&mut self, msg: AgentMessage);
    fn replace_messages(&mut self, msgs: Vec<AgentMessage>);
    fn save_messages(&self) -> Result<String, Error>;
    fn restore_messages(&mut self, json: &str) -> Result<(), Error>;
    fn set_tools(&mut self, tools: Vec<Arc<dyn AgentTool>>);
    fn abort(&self);
    fn reset(&mut self);

    // Provided methods
    fn prompt_with_sender<'life0, 'async_trait>(
        &'life0 mut self,
        text: String,
        tx: UnboundedSender<AgentEvent>,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn prompt<'life0, 'async_trait>(
        &'life0 mut self,
        text: String,
    ) -> Pin<Box<dyn Future<Output = UnboundedReceiver<AgentEvent>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn prompt_messages<'life0, 'async_trait>(
        &'life0 mut self,
        messages: Vec<AgentMessage>,
    ) -> Pin<Box<dyn Future<Output = UnboundedReceiver<AgentEvent>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn continue_loop<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = UnboundedReceiver<AgentEvent>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn last_loop_id(&self) -> Option<&str> { ... }
    fn steer(&self, _msg: AgentMessage) { ... }
    fn follow_up(&self, _msg: AgentMessage) { ... }
    fn clear_steering_queue(&self) { ... }
    fn clear_follow_up_queue(&self) { ... }
    fn clear_all_queues(&self) { ... }
    fn set_steering_mode(&mut self, _mode: QueueMode) { ... }
    fn set_follow_up_mode(&mut self, _mode: QueueMode) { ... }
    fn profile(&self) -> Option<&AgentProfile> { ... }
    fn system_prompt(&self) -> &str { ... }
    fn model_config(&self) -> Option<&ModelConfig> { ... }
    fn thinking_level(&self) -> ThinkingLevel { ... }
    fn temperature(&self) -> Option<f32> { ... }
    fn max_tokens(&self) -> Option<u32> { ... }
    fn context_config(&self) -> Option<&ContextConfig> { ... }
    fn execution_limits(&self) -> Option<&ExecutionLimits> { ... }
    fn cache_config(&self) -> CacheConfig { ... }
    fn tool_execution(&self) -> ToolExecutionStrategy { ... }
    fn tool_timeout(&self) -> Option<Duration> { ... }
    fn response_format(&self) -> ResponseFormat { ... }
    fn retry_config(&self) -> RetryConfig { ... }
    fn session(&self) -> Option<&Session> { ... }
    fn workspace(&self) -> Option<&Path> { ... }
    fn set_before_turn(&mut self, _f: Option<BeforeTurnFn>) { ... }
    fn set_after_turn(&mut self, _f: Option<AfterTurnFn>) { ... }
    fn set_before_loop(&mut self, _f: Option<BeforeLoopFn>) { ... }
    fn set_after_loop(&mut self, _f: Option<AfterLoopFn>) { ... }
    fn set_before_tool_execution(&mut self, _f: Option<BeforeToolExecutionFn>) { ... }
    fn set_after_tool_execution(&mut self, _f: Option<AfterToolExecutionFn>) { ... }
    fn set_before_tool_execution_update(
        &mut self,
        _f: Option<BeforeToolExecutionUpdateFn>,
    ) { ... }
    fn set_after_tool_execution_update(
        &mut self,
        _f: Option<AfterToolExecutionUpdateFn>,
    ) { ... }
    fn set_convert_to_llm(&mut self, _f: Option<ConvertToLlmFn>) { ... }
    fn set_transform_context(&mut self, _f: Option<TransformContextFn>) { ... }
    fn set_block_compaction_strategy(
        &mut self,
        _s: Option<Arc<dyn BlockCompactionStrategy>>,
    ) { ... }
    fn set_before_compaction_start(
        &mut self,
        _f: Option<BeforeCompactionStartFn>,
    ) { ... }
    fn set_after_compaction_end(&mut self, _f: Option<AfterCompactionEndFn>) { ... }
    fn set_prun_enabled(&mut self, _enabled: bool) { ... }
    fn set_context_translation(
        &mut self,
        _s: Option<Arc<dyn ContextTranslationStrategy>>,
    ) { ... }
    fn context_translation(&self) -> Option<Arc<dyn ContextTranslationStrategy>> { ... }
    fn build_config(&self) -> Result<AgentLoopConfig, AgentBuildError> { ... }
}

The core runtime interface for an agent.

Programs against this trait to remain independent of the specific agent implementation. Use BasicAgent for the default in-memory implementation, or implement this trait for richer implementations with persistence, branching, or distributed execution.

Required Methods

The two primary required methods are prompt_messages_with_sender and continue_loop_with_sender — all other prompting variants have default implementations that delegate to these.

Required Methods

fn prompt_messages_with_sender<'life0, 'async_trait>( &'life0 mut self, messages: Vec<AgentMessage>, tx: UnboundedSender<AgentEvent>, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Send messages as a prompt, streaming events to a caller-provided sender.

This is the primary required prompting method — all other prompt* variants have default implementations that delegate here.

fn continue_loop_with_sender<'life0, 'async_trait>( &'life0 mut self, tx: UnboundedSender<AgentEvent>, kind: ContinuationKind, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Continue from current context, streaming events to a caller-provided sender.

kind describes how this continuation relates to prior loops:

• Default — unspecified continuation
• Rerun { tag } — retry from the same context state
• Branch { tag } — explore a different path from the same starting point

fn messages(&self) -> &[AgentMessage]

Full message history.

fn is_streaming(&self) -> bool

Whether the agent is currently running a loop.

fn agent_id(&self) -> &str

Stable UUID assigned at construction; included in every AgentStart event.

fn session_id(&self) -> &str

Stable UUID assigned at construction; groups all loops from this instance.

fn clear_messages(&mut self)

Clear all messages from history.

fn append_message(&mut self, msg: AgentMessage)

Append a single message to history.

fn replace_messages(&mut self, msgs: Vec<AgentMessage>)

Replace the entire message history.

fn save_messages(&self) -> Result<String, Error>

Serialize message history to JSON.

fn restore_messages(&mut self, json: &str) -> Result<(), Error>

Restore message history from JSON.

fn set_tools(&mut self, tools: Vec<Arc<dyn AgentTool>>)

Replace the tool set.

fn abort(&self)

Cancel the current run via CancellationToken.

fn reset(&mut self)

Clear all state (messages, queues, streaming flag).

Provided Methods

fn prompt_with_sender<'life0, 'async_trait>( &'life0 mut self, text: String, tx: UnboundedSender<AgentEvent>, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Send a text prompt, streaming events to a caller-provided sender.

Default: wraps text in AgentMessage::Llm(LlmMessage::new(Message::user(text))) and calls prompt_messages_with_sender.

fn prompt<'life0, 'async_trait>( &'life0 mut self, text: String, ) -> Pin<Box<dyn Future<Output = UnboundedReceiver<AgentEvent>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Send a text prompt. Returns a stream of AgentEvents.

Default: creates an internal channel and calls prompt_with_sender.

fn prompt_messages<'life0, 'async_trait>( &'life0 mut self, messages: Vec<AgentMessage>, ) -> Pin<Box<dyn Future<Output = UnboundedReceiver<AgentEvent>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Send messages as a prompt. Returns a stream of AgentEvents.

Default: creates an internal channel and calls prompt_messages_with_sender.

fn continue_loop<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = UnboundedReceiver<AgentEvent>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Continue from current context. Returns a stream of AgentEvents.

Default: creates an internal channel and calls continue_loop_with_sender(Default).

fn last_loop_id(&self) -> Option<&str>

The loop_id of the most recently started loop; None before first run.

Default: returns None. Override to track loop identity.

fn steer(&self, _msg: AgentMessage)

Queue a steering message — interrupts the agent mid-tool-execution.

Default: no-op. Override to support mid-run interrupts.

fn follow_up(&self, _msg: AgentMessage)

Queue a follow-up message — processed after the current agent turn completes.

Default: no-op.

fn clear_steering_queue(&self)

Clear all pending steering messages. Default: no-op.

fn clear_follow_up_queue(&self)

Clear all pending follow-up messages. Default: no-op.

fn clear_all_queues(&self)

Clear both steering and follow-up queues.

fn set_steering_mode(&mut self, _mode: QueueMode)

Set how steering messages are delivered. Default: no-op.

fn set_follow_up_mode(&mut self, _mode: QueueMode)

Set how follow-up messages are delivered. Default: no-op.

fn profile(&self) -> Option<&AgentProfile>

The agent’s profile blueprint. Default: None.

fn system_prompt(&self) -> &str

The agent’s system prompt. Default: empty string.

fn model_config(&self) -> Option<&ModelConfig>

The agent’s model configuration. Default: None.

fn thinking_level(&self) -> ThinkingLevel

The agent’s thinking level. Default: ThinkingLevel::Off.

fn temperature(&self) -> Option<f32>

The agent’s temperature setting. Default: None.

fn max_tokens(&self) -> Option<u32>

The agent’s max tokens setting. Default: None.

fn context_config(&self) -> Option<&ContextConfig>

The agent’s context config. Default: None.

fn execution_limits(&self) -> Option<&ExecutionLimits>

The agent’s execution limits. Default: None.

fn cache_config(&self) -> CacheConfig

The agent’s cache config. Default: CacheConfig::default().

fn tool_execution(&self) -> ToolExecutionStrategy

The agent’s tool execution strategy. Default: ToolExecutionStrategy::default().

fn tool_timeout(&self) -> Option<Duration>

The agent’s per-tool execution timeout. Default: None (no per-tool timeout).

When Some(d), each AgentTool::execute() call is bounded by d. An individual tool’s AgentTool::timeout() override takes precedence. On timeout the tool’s child cancel token is fired and a ToolError::Timeout is returned to the LLM — the agent loop continues.

fn response_format(&self) -> ResponseFormat

The agent’s desired output shape. Default: ResponseFormat::Text (free-form text).

Override on agents that want JSON-mode output by default. See provider::ResponseFormat and the capability matrix in docs/specs/developer/provider.md for per-provider coverage.

fn retry_config(&self) -> RetryConfig

The agent’s retry config. Default: RetryConfig::default().

fn session(&self) -> Option<&Session>

The agent’s current session. Default: None.

fn workspace(&self) -> Option<&Path>

The agent’s workspace directory. File paths in system prompt blocks resolve relative to this. Default: None (uses current directory).

fn set_before_turn(&mut self, _f: Option<BeforeTurnFn>)

Set the before-turn hook. Default: no-op.

fn set_after_turn(&mut self, _f: Option<AfterTurnFn>)

Set the after-turn hook. Default: no-op.

fn set_before_loop(&mut self, _f: Option<BeforeLoopFn>)

Set the before-loop hook. Default: no-op.

fn set_after_loop(&mut self, _f: Option<AfterLoopFn>)

Set the after-loop hook. Default: no-op.

fn set_before_tool_execution(&mut self, _f: Option<BeforeToolExecutionFn>)

Set the before-tool-execution hook. Default: no-op.

fn set_after_tool_execution(&mut self, _f: Option<AfterToolExecutionFn>)

Set the after-tool-execution hook. Default: no-op.

fn set_before_tool_execution_update( &mut self, _f: Option<BeforeToolExecutionUpdateFn>, )

Set the before-tool-execution-update hook. Default: no-op.

fn set_after_tool_execution_update( &mut self, _f: Option<AfterToolExecutionUpdateFn>, )

Set the after-tool-execution-update hook. Default: no-op.

fn set_convert_to_llm(&mut self, _f: Option<ConvertToLlmFn>)

Set the convert-to-LLM function. Default: no-op.

fn set_transform_context(&mut self, _f: Option<TransformContextFn>)

Set the transform-context function. Default: no-op.

fn set_block_compaction_strategy( &mut self, _s: Option<Arc<dyn BlockCompactionStrategy>>, )

Set the block compaction strategy. Default: no-op.

fn set_before_compaction_start(&mut self, _f: Option<BeforeCompactionStartFn>)

Set the before-compaction-start hook (G1). Default: no-op.

fn set_after_compaction_end(&mut self, _f: Option<AfterCompactionEndFn>)

Set the after-compaction-end hook (G1). Default: no-op.

fn set_prun_enabled(&mut self, _enabled: bool)

Enable or disable the prun tool. Default: no-op.

fn set_context_translation( &mut self, _s: Option<Arc<dyn ContextTranslationStrategy>>, )

Set the context translation strategy (G8). Default: no-op.

fn context_translation(&self) -> Option<Arc<dyn ContextTranslationStrategy>>

Get the context translation strategy (G8). Default: None.

fn build_config(&self) -> Result<AgentLoopConfig, AgentBuildError>

Assemble an AgentLoopConfig from this agent’s current settings.

The default implementation builds a config from the trait’s accessor methods. BasicAgent overrides this to additionally wire steering queues, hooks, and other implementation-specific state.

Errors

Returns Err(AgentBuildError::MissingModelConfig) if model_config() returns None. Implementors of custom Agent types must either override model_config() to return Some(...) or override build_config() entirely. BasicAgent always returns Ok(...) because its constructor requires a ModelConfig.

Implementors

impl Agent for BasicAgent