Struct Conversation 

#[non_exhaustive]
pub struct Conversation {

    pub model: ModelId,
    pub max_tokens: u32,
    pub system: Option<SystemPrompt>,
    pub messages: Vec<MessageInput>,
    pub temperature: Option<f32>,
    pub top_p: Option<f32>,
    pub top_k: Option<u32>,
    pub stop_sequences: Option<Vec<String>>,
    pub tools: Vec<Tool>,
    pub tool_choice: Option<ToolChoice>,
    pub thinking: Option<ThinkingConfig>,
    pub metadata: Option<MessageMetadata>,
    pub service_tier: Option<RequestServiceTier>,
    pub mcp_servers: Vec<McpServerConfig>,
    pub container: Option<String>,
    pub auto_cache: AutoCacheMode,
    pub compaction: Option<ContextCompactionPolicy>,
    pub usage_history: Vec<UsageRecord>,
}

Available on crate feature conversation only.

Multi-turn conversation state plus per-request defaults.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

model: ModelId

Model used for new turns (also recorded with each UsageRecord).

max_tokens: u32

Maximum output tokens per turn.

system: Option<SystemPrompt>

Optional system prompt; survives across turns.

messages: Vec<MessageInput>

Conversation history, oldest first.

temperature: Option<f32>

Default sampling temperature.

top_p: Option<f32>

Default nucleus sampling cutoff.

top_k: Option<u32>

Default top-k cutoff.

stop_sequences: Option<Vec<String>>

Default stop sequences.

tools: Vec<Tool>

Tools made available to every turn.

tool_choice: Option<ToolChoice>

Default tool-use policy.

thinking: Option<ThinkingConfig>

Default extended-thinking config.

metadata: Option<MessageMetadata>

Default request metadata.

service_tier: Option<RequestServiceTier>

Default request-side service tier.

mcp_servers: Vec<McpServerConfig>

MCP servers exposed on every turn.

container: Option<String>

Container ID for the code-execution built-in tool.

auto_cache: AutoCacheMode

Auto-cache configuration applied at request-build time.

compaction: Option<ContextCompactionPolicy>

Optional context-compaction policy. When set, oldest user/assistant roundtrips are dropped before each send once the estimated input exceeds ContextCompactionPolicy::max_input_tokens. See Self::compact_if_needed.

usage_history: Vec<UsageRecord>

Per-turn Usage records, oldest first. Updated by Self::send.

Implementations

impl Conversation

pub fn new(model: impl Into<ModelId>, max_tokens: u32) -> Self

Begin a new conversation with the given model and per-turn max_tokens.

pub fn with_compaction(self, policy: ContextCompactionPolicy) -> Self

Attach a context-compaction policy. Without one, conversation history grows unbounded.

pub fn system(self, s: impl Into<SystemPrompt>) -> Self

Set the system prompt.

pub fn with_cache_breakpoint_on_system(self) -> Self

Shorthand for setting AutoCacheMode::System via Self::with_auto_cache.

pub fn with_auto_cache(self, mode: AutoCacheMode) -> Self

Set the auto-cache mode. See AutoCacheMode.

pub fn with_tools(self, tools: Vec<Tool>) -> Self

Replace the tool list.

pub fn with_tool_choice(self, choice: ToolChoice) -> Self

Set the tool-use policy.

pub fn with_thinking(self, t: ThinkingConfig) -> Self

Enable extended thinking.

pub fn with_temperature(self, t: f32) -> Self

Set the sampling temperature default.

pub fn push_user(&mut self, content: impl Into<MessageContent>)

Append a user-authored turn.

pub fn push_assistant(&mut self, content: impl Into<MessageContent>)

Append an assistant-authored turn (typically used for prefill before the first send).

pub fn pop(&mut self) -> Option<MessageInput>

Remove and return the most recent message. Useful when aborting a turn before sending.

pub fn turn_count(&self) -> usize

Number of completed turns (request/response cycles via Self::send).

pub fn cumulative_usage(&self) -> Usage

Sum of every recorded Usage for this conversation.

pub fn cost(&self, pricing: &PricingTable) -> f64

Available on crate feature pricing only.

Total cost in USD across all recorded turns, using the given pricing table to look up rates for each turn’s model.

pub fn estimate_input_tokens(&self) -> u32

Heuristic estimate of how many input tokens this conversation would consume on the next request.

Uses a fast local approximation (~4 characters per token), summed across the system prompt, all messages, and tool definitions. Adequate for compaction decisions; for exact billing-quality numbers call count_tokens via the API.

pub fn complete_roundtrip_count(&self) -> usize

Number of complete user→assistant roundtrips in the history. A “complete” roundtrip ends with an Assistant turn that has no outstanding tool_use blocks and is not the most recent message.

pub fn compact_if_needed(&mut self) -> bool

If a ContextCompactionPolicy is set and the estimated input exceeds the configured budget, drop oldest complete roundtrips until either the estimate fits or keep_recent_turns remain.

Tool-use / tool-result pairs are preserved as a unit. Returns true if any messages were dropped.

pub fn build_request(&self) -> CreateMessageRequest

Build the CreateMessageRequest this conversation would send next, including any auto-cache breakpoints. Pure – does not touch state.

Panics

Will not panic in practice: the conversation always carries model and max_tokens, so the inner builder’s build() always succeeds.

pub async fn send(&mut self, client: &Client) -> Result<Message>

Available on crate feature async only.

Drive one turn against the API. Appends the assistant response to the history and records the usage.

pub async fn send_with_beta( &mut self, client: &Client, betas: &[&str], ) -> Result<Message>

Available on crate feature async only.

Like Self::send but with per-request beta headers merged in.

Trait Implementations

impl Clone for Conversation

fn clone(&self) -> Conversation

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Conversation

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Conversation

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Conversation

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.