Trait Agent 

pub trait Agent: Send + Sync {
    type State: AgentState;

    // Required method
    fn run(
        &self,
        ctx: &mut RunContext<Self::State>,
    ) -> impl Future<Output = Result<RunOutcome>> + Send;
}

An agent that can serve one AG-UI run.

This is the hosting side of the word. The consuming side — a handle onto somebody else’s agent — is crate::client::RemoteAgent, deliberately spelled differently so that an agent which calls another agent can import both.

use ag_ui::RunOutcome;
use ag_ui::server::{Agent, Result, RunContext};

struct Echo;

impl Agent for Echo {
    type State = ();

    async fn run(&self, ctx: &mut RunContext<()>) -> Result<RunOutcome> {
        let mut message = ctx.assistant_message()?;
        message.delta("you said something")?;
        message.end()?;
        Ok(RunOutcome::Success)
    }
}

Why async fn and not #[async_trait]

The trait uses a native -> impl Future + Send return (an RPITIT), so implementations are plain async fn with no macro, no Box::pin per call and no allocation. The cost is that the trait is not dyn-compatible; when you need Box<dyn …> — a registry of agents behind one endpoint, say — DynAgent is the boxed adapter, and BoxAgent implements Agent again, so the driver takes it like any other.

Why &mut RunContext and not RunContext

The driver has to emit RUN_FINISHED or RUN_ERROR after the agent returns, through the same transformer chain and the same ordering verifier the agent used. Handing the context over by value would drop both with the agent’s last statement.

Required Associated Types

type State: AgentState

The run’s shared state, deserialized from RunAgentInput::state and published through RunContext::set_state.

Required Methods

fn run( &self, ctx: &mut RunContext<Self::State>, ) -> impl Future<Output = Result<RunOutcome>> + Send

Serves one run.

Returning Ok(RunOutcome::Success) finishes the run; Ok(RunOutcome::Interrupt { .. }) pauses it for human input; Err becomes a RUN_ERROR event, never a panic and never a truncated stream.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementations on Foreign Types

impl<A: Agent> Agent for &A

type State = <A as Agent>::State

async fn run(&self, ctx: &mut RunContext<Self::State>) -> Result<RunOutcome>

impl<A: Agent> Agent for Arc<A>

type State = <A as Agent>::State

async fn run(&self, ctx: &mut RunContext<Self::State>) -> Result<RunOutcome>

Implementors

impl<S: AgentState> Agent for BoxAgent<S>

type State = S