Struct AgentSession 

pub struct AgentSession<P: EventProducer<StateT>, StateT: AgentState = JsonValue> { /* private fields */ }

Manages an agent session with run lifecycle events.

This struct provides high-level management of agent runs, including starting, finishing, and error handling.

Example

let mut session = AgentSession::new(sender);

// Start a run
let run_id = session.start_run().await?;

// Do work...

// Finish the run
session.finish_run(Some(json!({"result": "success"}))).await?;

Implementations

impl<P: EventProducer<StateT>, StateT: AgentState> AgentSession<P, StateT>

pub fn new(producer: P) -> Self

Create a new session with the given producer.

Generates a random thread ID for the session.

pub fn with_thread_id(producer: P, thread_id: ThreadId) -> Self

Create a new session with a specific thread ID.

pub async fn start_run(&mut self) -> Result<RunId, ServerError>

Start a new run.

Emits a RunStarted event and stores the run ID. Returns an error if a run is already in progress.

pub async fn finish_run( &mut self, result: Option<JsonValue>, ) -> Result<(), ServerError>

Finish the current run.

Emits a RunFinished event with an optional result. Does nothing if no run is in progress.

pub async fn run_error( &mut self, message: impl Into<String>, ) -> Result<(), ServerError>

Signal a run error.

Emits a RunError event and clears the current run.

pub async fn run_error_with_code( &mut self, message: impl Into<String>, code: impl Into<String>, ) -> Result<(), ServerError>

Signal a run error with an error code.

pub fn producer(&self) -> &P

Get a reference to the underlying producer.

pub fn thread_id(&self) -> &ThreadId

Get the thread ID for this session.

pub fn run_id(&self) -> Option<&RunId>

Get the current run ID, if any.

pub fn is_running(&self) -> bool

Check if a run is currently in progress.

pub fn is_connected(&self) -> bool

Check if the connection is still open.

pub async fn start_thinking( &self, title: Option<impl Into<String>>, ) -> Result<ThinkingStep<'_, P, StateT>, ServerError>

Start a thinking step.

Convenience method that creates a ThinkingStep using this session’s producer.

Example

let step = session.start_thinking(Some("Planning response")).await?;
// ... emit thinking content ...
step.end().await?;

pub async fn interrupt( &mut self, reason: Option<impl Into<String>>, payload: Option<JsonValue>, ) -> Result<(), ServerError>

Interrupt the current run for human-in-the-loop interaction.

Finishes the run with an interrupt outcome, signaling that human input is required before the agent can continue. The client should display appropriate UI based on the interrupt info and resume with user input.

Example

session.start_run().await?;

// Request human approval
session.interrupt(
    Some("human_approval"),
    Some(serde_json::json!({"action": "send_email", "to": "user@example.com"}))
).await?;

pub async fn interrupt_with_id( &mut self, id: impl Into<String>, reason: Option<impl Into<String>>, payload: Option<JsonValue>, ) -> Result<(), ServerError>

Interrupt with a specific interrupt ID for tracking.

The interrupt ID can be used by the client to correlate the resume request with the original interrupt.

Example

session.start_run().await?;

// Request approval with tracking ID
session.interrupt_with_id(
    "approval-001",
    Some("database_modification"),
    Some(serde_json::json!({"query": "DELETE FROM users WHERE inactive"}))
).await?;