Struct Agent 

pub struct Agent { /* private fields */ }

Running or persisted agent managed by a crate::Runtime.

Implementations

impl Agent

pub async fn send( &mut self, content: impl Into<Vec<ContentBlock>>, ) -> Result<Message, RuntimeError>

Sends a user turn using default run options.

pub async fn resume(&mut self) -> Result<Message, RuntimeError>

Replays the most recent failed or interrupted user turn using default run options.

pub async fn resume_with_options( &mut self, options: RunOptions, ) -> Result<Message, RuntimeError>

Replays the most recent failed or interrupted user turn with explicit execution options.

pub async fn run( &mut self, content: impl Into<Vec<ContentBlock>>, options: RunOptions, ) -> Result<Message, RuntimeError>

Runs a user turn with explicit execution limits and cancellation settings.

impl Agent

pub fn steering_handle(&self) -> SteeringHandle

Returns an agent-scoped handle suitable for use while run(&mut self) holds the mutable agent borrow.

pub fn steer(&self, content: impl Into<Vec<ContentBlock>>)

Idle convenience for enqueueing a steer on this agent.

pub fn follow_up(&self, content: impl Into<Vec<ContentBlock>>)

Idle convenience for enqueueing a would-stop follow-up on this agent.

pub async fn run_queued( &mut self, options: RunOptions, ) -> Result<Message, RuntimeError>

Starts an idle run from the next queued steer.

This is the only automatic consumption point for a steer while no run is active. Follow-ups remain reserved for a running turn’s would-stop boundary. A failed run prepends the consumed entry back onto the queue.

impl Agent

pub fn task_board(&self) -> TaskBoard

Returns a task-board view with this agent’s own access identity.

Lead agents retain lead privileges. Teammates remain constrained to their own tasks and cannot edit dependency edges. Task-board mutations update the shared store immediately; this agent’s cached snapshot is refreshed at the next normal task refresh/run boundary.

impl Agent

pub async fn spawn_teammate( &mut self, name: impl Into<String>, role: impl Into<String>, prompt: Option<String>, ) -> Result<TeamMemberSummary, RuntimeError>

pub fn send_team_message( &self, to: &str, content: impl Into<String>, ) -> Result<TeamDispatch, RuntimeError>

pub fn broadcast_team_message( &self, content: impl Into<String>, ) -> Result<Vec<TeamDispatch>, RuntimeError>

pub fn read_team_inbox(&self) -> Result<Vec<TeamMessage>, RuntimeError>

pub fn request_team_protocol( &self, to: &str, protocol: impl Into<String>, content: impl Into<String>, ) -> Result<TeamProtocolRequestSummary, RuntimeError>

pub fn respond_team_protocol( &self, request_id: &str, approve: bool, reason: Option<String>, ) -> Result<TeamProtocolRequestSummary, RuntimeError>

impl Agent

pub async fn run_to_output<T: DeserializeOwned>( &mut self, content: impl Into<Vec<ContentBlock>>, options: RunOptions, spec: TerminalOutputSpec, ) -> Result<FinalOutput<T>, RuntimeError>

Runs until a generated, agent-scoped terminal tool returns a typed value.

The helper does not use provider-level response_format. It exposes only one forced terminal tool during this run, preserves the tool input as transcript details, and extracts it by the exact tool_use_id from the newly committed final transcript item. Internally a terminal run commits successfully but Agent::run reports RuntimeError::EmptyAssistantResponse because the final message is a user-role tool result; this helper accepts that error only when the expected new detail is present.

impl Agent

pub fn wait_handle(&self) -> AgentWaitHandle

Returns a cloneable observation handle that does not borrow this agent.

pub fn wait_for_snapshot<P>( &self, predicate: P, ) -> AgentWaitFuture<AgentSnapshot>

where P: Fn(&AgentSnapshot) -> bool + Send + 'static,

Owned-future convenience for AgentWaitHandle::wait_for_snapshot.

pub fn wait_until_idle(&self) -> AgentWaitFuture<AgentSnapshot>

Owned-future convenience for AgentWaitHandle::wait_until_idle.

pub fn wait_for_teammate_reply( &self, ) -> AgentWaitFuture<Result<Vec<TeamMessage>, RuntimeError>>

Owned-future convenience for AgentWaitHandle::wait_for_teammate_reply.

impl Agent

pub fn name(&self) -> &str

Returns the agent’s display name.

pub fn id(&self) -> &str

Returns the stable persisted agent identifier.

pub fn model(&self) -> &str

Returns the model identifier used by the agent.

pub fn set_model(&mut self, model: ModelInfo) -> Result<(), RuntimeError>

Updates the model and provider used for future turns, then persists the new agent record so resumed sessions continue with the same setting.

pub fn set_reasoning( &mut self, reasoning: Option<ReasoningOptions>, ) -> Result<(), RuntimeError>

Updates the reasoning options requested on future turns, then persists the agent record so resumed sessions continue with the same setting.

Mirrors set_model: a stateful override threaded into every subsequent model request (the runner reads config.provider_request_options.reasoning live). It composes with set_model for per-phase tiering — e.g. run the gather rounds at a low reasoning effort, then raise the effort (and switch to a stronger model) for a final synthesis turn on the same agent, without re-spawning and losing the gathered context. None clears any configured reasoning, restoring the provider’s default effort.

pub fn config(&self) -> &AgentConfig

Returns the effective agent configuration.

pub fn history(&self) -> &[Message]

Returns the committed transcript history.

pub fn transcript(&self) -> &AgentTranscript

Returns the canonical transcript items stored for this agent.

pub fn leaf(&self) -> Option<&EntryId>

The transcript entry the next turn will continue from.

pub fn branch_from(&mut self, entry: &EntryId) -> Result<usize, RuntimeError>

Returns to an earlier entry, so the next turn explores a new path from there.

The abandoned entries stay in the transcript, reachable through children — nothing is deleted, so the path just left can be returned to the same way. Returns how many entries left the active path.

pub fn children(&self, entry: &EntryId) -> Vec<&TranscriptItem>

The entries recorded as continuing from entry. More than one means the conversation branched there.

pub fn is_teammate(&self) -> bool

Returns whether this agent is a persistent teammate rather than the lead agent.

pub fn last_message(&self) -> Option<&Message>

Returns the most recent committed message, if any.

pub fn subscribe_events(&self) -> Receiver<AgentEvent>

Subscribes to the agent’s transient event stream.

pub fn watch_snapshot(&self) -> Receiver<AgentSnapshot>

Watches the current agent snapshot for state updates.