Struct Session 

pub struct Session<T, S = Value> { /* private fields */ }

A conversation with an agent.

Holds the thread id, the messages both sides have said, and the application state. S is the type the state deserializes into, and it is inferred from whatever the caller does with an Update::State — a Session handed to a function expecting Session<T, MyState>, or a match arm that keeps the state in a typed local, needs no turbofish at all. Spell it only when nothing else names it: Session::<_>::new(transport, thread) falls back to the serde_json::Value default, and Session::<_, MyState>::new(…) pins it by hand.

To stream updates, S must be Deserialize + Clone + Unpin — an Update::State carries the state by value, so a view can hold it after the run has moved on. #[derive(Clone, Deserialize)] on a plain struct is all that takes.

Implementations

impl<T, S> Session<T, S>

pub fn new(transport: T, thread_id: impl Into<ThreadId>) -> Self

where T: Transport,

A new conversation over transport.

The T: Transport bound is checked here, at the construction site, rather than on Session itself — so something that is not a transport is an error on this line instead of on the first send, which is usually in another file:

use ag_ui::client::Session;

// error[E0277]: the trait bound `str: Transport` is not satisfied,
// and the note lists the types that do implement it.
let session = Session::<_>::new("http://localhost:8080/agent", "thread-1");

(A URL is the mistake worth catching: it is what a transport is made from, so it reads plausible.) The bound stays off the struct because a bound there is viral — every application helper naming Session<T, S> would have to repeat it, including ones that only read messages. tests/bounds.rs is what says so.

pub fn builder( transport: T, thread_id: impl Into<ThreadId>, ) -> SessionBuilder<T, S>

where T: Transport,

A builder, for seeding history, tools, context, or turning verification off.

Takes the same T: Transport bound as new, and for the same reason. Everything after it — including build — is unbounded.

pub fn thread_id(&self) -> &ThreadId

The conversation this session is part of.

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

The assembled conversation, oldest first — everything the user sent and everything the agent has said across every run.

pub fn state(&self) -> Option<&S>

The application state in the caller’s type, once the agent has published one that deserializes.

pub fn raw_state(&self) -> &Value

The application state as raw JSON. Always current, even when the typed view is not.

pub fn reasoning(&self) -> &[ReasoningMessage]

The reasoning messages, kept out of the transcript.

pub fn interrupts(&self) -> &[Interrupt]

What the agent is waiting for, if the last run paused.

pub fn subagents(&self) -> &[Subagent]

The subagent invocations announced so far, across runs — a suspended one stays until the run that resumes it announces it again.

pub fn subagent(&self, run_id: &SubagentRunId) -> Option<&Subagent>

One subagent invocation by id — what a view does with the Message::subagent_run_id on a message it is about to draw.

pub fn applier(&self) -> &Applier

The applier underneath, for a view that wants the raw materialised state.

pub fn agent(&self) -> &RemoteAgent<T>

The low-level agent underneath.

pub fn push_message(&mut self, message: Message)

Appends a message without starting a run — a tool result computed on the client, or history loaded from a store.

pub fn set_state(&mut self, state: impl Into<Value>)

Replaces the state without going through the agent.

pub fn set_tools(&mut self, tools: impl Into<Vec<Tool>>)

Offers a different set of tools from the next run on.

pub fn set_next_run_id(&mut self, run_id: impl Into<RunId>)

Names the next run explicitly, instead of the generated {thread}-run-{n}.

Servers that key resumption on a run id need this; most do not.

impl<T: Transport, S> Session<T, S>

pub fn send(&mut self, text: impl Into<String>) -> RunStream<'_, T, S>

Sends the user’s turn and streams what the agent does about it.

The message is appended to the conversation before the request goes out, so it is in Session::messages whatever happens to the run.

pub fn send_message(&mut self, message: Message) -> RunStream<'_, T, S>

Sends a message of any role and streams the run.

pub fn run(&mut self) -> RunStream<'_, T, S>

Starts a run without adding anything — after pushing a tool result, or to let an agent continue on its own.

pub fn resume( &mut self, interrupt: &Interrupt, payload: impl Into<Value>, ) -> RunStream<'_, T, S>

Answers one interrupt and resumes the paused run.

The answer’s shape is up to the agent; when the interrupt carried a responseSchema, payload should satisfy it.

pub fn cancel(&mut self, interrupt: &Interrupt) -> RunStream<'_, T, S>

Declines one interrupt and resumes the paused run.

pub fn resume_many( &mut self, entries: impl IntoIterator<Item = ResumeEntry>, ) -> RunStream<'_, T, S>

Answers several interrupts at once — a run can pause on more than one.

Any interrupt left unanswered is dropped: the resumed run supersedes the paused one, and the agent only sees what is in this request. Use ResumeBuilder to answer them all.

Trait Implementations

impl<T: Debug, S: Debug> Debug for Session<T, S>

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

Formats the value using the given formatter.