Struct Client 

pub struct Client { /* private fields */ }

A reusable conversation client with optional automatic tool execution.

Manual mode streams blocks as they arrive. Auto mode runs tool rounds first, then yields the final response. Use Client::interrupt_handle for cancellation from another task without locking the client across an await.

Implementations

impl Client

pub fn new(options: AgentOptions) -> Result<Self>

Creates a reusable HTTP client with the configured timeout and redirect policy.

impl Client

pub async fn send(&mut self, prompt: &str) -> Result<()>

Starts a request from a text prompt, applying UserPromptSubmit hooks first. The prompt enters history before HTTP I/O, even on transport failure. Empty prompts are retained for tool continuation. Starting a new request discards pending output from the previous one.

impl Client

pub async fn send_message(&mut self, message: Message) -> Result<()>

Starts a request with a pre-built message, including image content. UserPromptSubmit hooks apply only to Self::send, which accepts text. The message enters history before HTTP I/O; pending output is discarded.

impl Client

pub async fn receive(&mut self) -> Result<Option<ContentBlock>>

Receives the next content block, or None when the request has finished.

Manual mode records the complete assistant turn at EOF; errors and abandoned streams discard partial history. Auto mode executes tool rounds before yielding final text. Read Self::finish_reason and Self::reasoning after draining.

pub fn interrupt(&self)

Requests cancellation between stream events, tool calls, and hook phases. Pending network reads still wait for data or the HTTP timeout; a running tool or hook future finishes first. A new send resets the flag.

pub fn interrupt_handle(&self) -> Arc<AtomicBool>

Shares the cancellation flag for use from another task.

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

Returns conversation history, excluding the separately configured system prompt.

pub fn history_mut(&mut self) -> &mut Vec<Message>

Allows explicit history edits, such as crate::truncate_messages.

pub fn options(&self) -> &AgentOptions

Returns the client’s configuration.

pub fn finish_reason(&self) -> Option<&FinishReason>

Why the last completed generation stopped, or MaxToolIterations when the auto loop reached its limit. Reset when a new request starts.

pub fn reasoning(&self) -> Option<&str>

Captured reasoning across all rounds of the latest request, when opted in. Reasoning never enters conversation history.

impl Client

pub fn clear_history(&mut self)

Clears conversation history and abandons pending output, retaining options.

pub fn add_tool_result( &mut self, tool_use_id: &str, content: Value, ) -> Result<()>

Adds a manual tool result after flushing the pending assistant tool call. Continue the conversation with send("") after supplying the results.

pub fn get_tool(&self, name: &str) -> Option<&Tool>

Looks up a registered tool by name.