Struct Conversation 

pub struct Conversation { /* private fields */ }

A stateful wrapper managing an active agentic session and its history.

Conversation consumes step events from an underlying Connection, updates the cumulative history, tracks token usage, and provides high-level APIs to chat, stream structured events, and wait for run completions.

Implementations

impl Conversation

pub fn new(conn: AnyConnection, max_history_size: Option<usize>) -> Self

Creates a new Conversation instance wrapping a Connection.

Optionally restricts the memory storage to max_history_size steps (default is 10,000 steps). If max_history_size is set to 0, state trimming is disabled.

pub fn connection(&self) -> AnyConnection

Returns the underlying Connection.

pub fn conversation_id(&self) -> &str

Returns the conversation ID assigned to the session.

pub fn is_idle(&self) -> bool

Returns whether the connection is currently idle.

pub async fn history(&self) -> Vec<Step>

Retrieves a copy of the current conversation history steps.

pub async fn turn_count(&self) -> usize

Returns the total number of user-initiated turns executed in this session.

pub async fn compaction_indices(&self) -> Vec<usize>

Returns the step indices where compaction (history compression) occurred.

pub async fn last_response(&self) -> String

Scans the history backward and returns the text content of the last completed model response.

pub async fn total_usage(&self) -> UsageMetadata

Returns the total token usage accumulated over all turns in the session.

pub async fn last_turn_usage(&self) -> Option<UsageMetadata>

Returns the token usage metrics from the last completed turn.

pub async fn clear_history(&self)

Resets the conversation state, clearing all steps, compaction boundaries, and usage statistics.

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

Sends a text prompt to the connection and registers the turn start boundary.

Errors

Returns an error if the underlying connection fails to transmit the prompt.

pub fn receive_steps(&self) -> BoxStream<'static, Result<Step, Error>>

Subscribes to step updates from the connection, inserting them into history and enforcing history limits.

pub fn receive_chunks(&self) -> BoxStream<'static, Result<StreamChunk, Error>>

Filters and maps the step event stream to yielding high-level StreamChunk deltas.

pub async fn chat( &self, prompt: &str, ) -> Result<BoxStream<'static, Result<StreamChunk, Error>>, Error>

Starts a prompt turn and returns a stream of StreamChunk events.

Errors

Returns an error if sending the prompt fails.

Examples found in repository

examples/streaming.rs (line 39)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let harness_path = std::env::var("ANTIGRAVITY_HARNESS_PATH").ok();
    let api_key = std::env::var("GEMINI_API_KEY").ok();

    let mut builder = Agent::builder();
    if let Some(path) = harness_path {
        builder = builder.binary_path(path);
    }
    if let Some(key) = api_key {
        builder = builder.api_key(key);
    }

    let agent = builder
        .default_model("gemini-3.5-flash")
        .allow_all()
        .build();

    println!("Starting agent...");
    let agent = agent.start().await?;

    let prompt = "Solve this riddle: I speak without a mouth and hear without ears. I have no body, but I come alive with wind. What am I? Explain your reasoning.";
    println!("\n  User: {}\n", prompt);

    let conversation = agent.conversation();
    let mut stream = conversation.chat(prompt).await?;

    println!("  Agent (Streaming response):");
    println!("  -------------------------------------------------------");

    while let Some(chunk_res) = stream.next().await {
        match chunk_res? {
            StreamChunk::Thought { text, .. } => {
                // Print thought chunks (e.g. in grey or wrapped in brackets if desired, or directly)
                print!("{}", text);
                std::io::Write::flush(&mut std::io::stdout())?;
            }
            StreamChunk::Text { text, .. } => {
                // Print response text chunks
                print!("{}", text);
                std::io::Write::flush(&mut std::io::stdout())?;
            }
            StreamChunk::ToolCall(call) => {
                println!(
                    "\n[Tool Call Requested: {} with args: {}]",
                    call.name, call.args
                );
            }
        }
    }
    println!("\n  -------------------------------------------------------\n");

    agent.stop().await?;
    Ok(())
}

pub async fn chat_to_completion( &self, prompt: &str, ) -> Result<ChatResponse, Error>

Starts a prompt turn and resolves once the model completes its response.

Errors

Returns an error if sending the prompt or receiving chunk responses fails.

pub async fn disconnect(&self) -> Result<(), Error>

Gracefully closes the underlying connection.

Errors

Returns an error if disconnecting the transport layer fails.

Trait Implementations

impl Debug for Conversation

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

Formats the value using the given formatter.