Struct ChatResponseHandle 

pub struct ChatResponseHandle { /* private fields */ }

Handle to a streaming chat response.

Created by AgentHandle::chat(). Provides independent channels for text tokens, thinking tokens, and tool-call events.

Each stream accessor can only be called once — subsequent calls return None because the underlying receiver has already been taken.

Implementations

impl ChatResponseHandle

pub fn take_text_stream(&mut self) -> Option<Receiver<String>>

Take the text token receiver for token-by-token streaming.

Returns None if the receiver was already taken.

pub fn take_thought_stream(&mut self) -> Option<Receiver<String>>

Take the thinking token receiver.

Returns None if the receiver was already taken.

pub fn take_tool_call_stream(&mut self) -> Option<Receiver<ToolCallEvent>>

Take the tool call event receiver.

Returns None if the receiver was already taken.

pub fn take_step_stream(&mut self) -> Option<Receiver<Step>>

Take the raw step receiver.

Returns None if the receiver was already taken. Prefer receive_steps() for StreamExt-compatible usage.

pub fn receive_steps(&mut self) -> Option<impl Stream<Item = Step>>

Take the step stream for consuming with StreamExt::next().

Returns None if the stream was already taken.

Example

use agy_bridge::streaming;
use tokio_stream::StreamExt;

let (_writer, mut handle) = streaming::channel();
drop(_writer); // close the channel so the stream ends
let mut steps = handle.receive_steps().unwrap();
while let Some(step) = steps.next().await {
    println!("step: {:?}", step.step_type);
}

pub fn receive_chunks(&mut self) -> Option<impl Stream<Item = StreamChunk>>

Take the unified chunk stream for consuming with StreamExt::next().

Returns None if the stream was already taken.

Example

use agy_bridge::streaming::{self, StreamChunk};
use tokio_stream::StreamExt;

let (_writer, mut handle) = streaming::channel();
drop(_writer); // close the channel so the stream ends
let mut chunks = handle.receive_chunks().unwrap();
while let Some(chunk) = chunks.next().await {
    match chunk {
        StreamChunk::Text(t) => print!("{t}"),
        StreamChunk::Thought(t) => eprintln!("thought: {t}"),
        StreamChunk::ToolCall(tc) => eprintln!("tool: {}", tc.name),
        _ => {}
    }
}

pub fn take_chunk_stream(&mut self) -> Option<Receiver<StreamChunk>>

Take the unified chunk receiver as a plain mpsc::Receiver.

Returns None if the receiver was already taken. Prefer receive_chunks() for StreamExt-compatible usage; this variant exists for consumers that drain the channel with recv().

pub fn take_event_stream(&mut self) -> Option<Receiver<ResponseEvent>>

Take the timeline event receiver.

Returns None if the receiver was already taken. Prefer resolve() if you want the ordered event timeline; this variant lets a consumer drain event_tx incrementally with recv().

Note

Taking this stream subscribes to the event timeline, so the writer will fan every step out to event_tx. As with any subscribed stream, drain it concurrently (e.g. alongside text()) so it keeps up. Views you never take are simply skipped by the writer and can never stall the stream.

pub async fn text(self) -> Result<ChatResult, StreamError>

Drain the text stream and return the complete response text.

Consumes the handle — use the take_* methods instead if you need to keep streaming individual channels.

Errors

Returns a StreamError if the Python side reported an error.

pub fn finalize(&mut self)

Finalize the response handle by pulling usage and structured output from the shared state. Called after the stream has been fully drained.

pub const fn structured_output(&self) -> Option<&Value>

Return the structured output, if available.

Only populated when the agent was configured with a response_schema and the model returned a valid JSON payload.

pub const fn usage_metadata(&self) -> Option<&UsageMetadata>

Return the token usage metadata, if available.

Populated after finalize() or text().

pub async fn resolve(self) -> Vec<ResponseEvent>

Drain all events and return them as an ordered timeline.

Consumes the handle — use the take_* methods instead if you need to keep streaming individual channels.

Trait Implementations

impl Debug for ChatResponseHandle

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

Formats the value using the given formatter.