Struct Agent 

pub struct Agent<S>
where
    S: Clone + Send + Sync + 'static,
{ /* private fields */ }

Production agent runtime.

Construct via Agent::builder; finalize with AgentBuilder::build. See module docs for the abstraction model and information-density discipline.

Implementations

impl<S> Agent<S>

where S: Clone + Send + Sync + 'static,

pub fn builder() -> AgentBuilder<S>

Start a fluent builder.

pub fn name(&self) -> &str

Borrow the agent’s stable name. Always non-empty — AgentBuilder::build rejects empty / unset names so trace correlation never silently breaks.

pub fn inner(&self) -> &Arc<dyn Runnable<S, S>>

Borrow the underlying runnable. Useful when an agent is embedded as a node in a larger graph and the parent needs direct access to the inner shape (e.g. for checkpointing).

pub async fn execute( &self, input: S, ctx: &ExecutionContext, ) -> Result<AgentRunResult<S>>

Run to completion, returning the terminal state.

Emits a Started{run_id} opener, fires every registered observer at the appropriate lifecycle point, then emits either Complete{run_id, state} or Failed{run_id, error} on the sink — every run produces exactly one terminal event .

The run_id is inherited from ctx.run_id() when present, otherwise a fresh UUID v7 is generated and propagated to the inner runnable through a cloned context.

pub async fn execute_with( &self, input: S, overrides: RunOverrides, ctx: &ExecutionContext, ) -> Result<AgentRunResult<S>>

Convenience entry that attaches a entelix_core::RunOverrides extension to the context for the duration of the call. Equivalent to agent.execute(input, &ctx.add_extension(overrides)) — shorter at the call site and signals the per-call shape at a glance.

Asymmetric by design — RunOverrides is the agent-loop carrier (model / system prompt / max iterations owned by the loop the Agent itself drives) so a typed convenience belongs on Agent. RequestOverrides (temperature / top_p / top_k / max_tokens / stop_sequences / reasoning_effort / tool_choice / response_format / parallel_tool_calls) is ChatModel-shaped — the dispatch layer downstream picks it up via ExecutionContext::add_extension(RequestOverrides::new()…), no agent-side convenience is needed (and adding one would duplicate the orthogonality that the carrier split S99 established).

Operators threading multiple per-call extensions stay on Self::execute with their own add_extension chain.

pub const fn execution_mode(&self) -> ExecutionMode

Borrow the configured execution mode.

pub fn approver(&self) -> Option<&Arc<dyn Approver>>

Borrow the configured approver (None in Auto mode).

pub fn observer_count(&self) -> usize

Number of registered lifecycle observers.

pub fn execute_stream<'a>( &'a self, input: S, ctx: &'a ExecutionContext, ) -> BoxStream<'a, Result<AgentEvent<S>>>

Run with AgentEvent book-ends as a stream. Sinks attached at construction time receive the same events for fan-out telemetry.

The returned stream is the caller-facing view; the sink is the observability-facing view. Both observe the same Started → Complete(state) sequence that Self::execute produces — the only difference is the return shape (a stream of events vs the awaited terminal state).

Drives the inner runnable via Runnable::invoke rather than Runnable::stream so the lifecycle is identical to execute and the Complete event always fires on successful runs (a previous design routed through Runnable::stream’s Updates mode and could silently skip Complete for runnables that emit no per-node updates).

Construction is synchronous and infallible — every event (including the initial Started) yields lazily as the stream is polled. Callers consume with .next().await like any Stream; no extra .await on the constructor itself.

Trait Implementations

impl<S> Debug for Agent<S>

where S: Clone + Send + Sync + 'static,

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

Formats the value using the given formatter.

impl<S> Runnable<S, S> for Agent<S>

where S: Clone + Send + Sync + 'static,

Agent<S> is itself a Runnable<S, S> so it composes inside larger graphs (recursive sub-agent dispatch).

The composition contract is S → S, so the AgentRunResult envelope is unwrapped here — composing graphs see only the terminal state. Callers that need the per-run UsageSnapshot or run_id go through Agent::execute directly.

fn invoke<'life0, 'life1, 'async_trait>( &'life0 self, input: S, ctx: &'life1 ExecutionContext, ) -> Pin<Box<dyn Future<Output = Result<S>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Single-shot invocation.

fn batch<'life0, 'life1, 'async_trait>( &'life0 self, inputs: Vec<I>, ctx: &'life1 ExecutionContext, ) -> Pin<Box<dyn Future<Output = Result<Vec<O>, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Batch invocation. The default runs invoke sequentially over the input vector. Implementors that can parallelize (e.g. independent provider calls) override this.

fn stream<'life0, 'life1, 'async_trait>( &'life0 self, input: I, mode: StreamMode, ctx: &'life1 ExecutionContext, ) -> Pin<Box<dyn Future<Output = Result<Pin<Box<dyn Stream<Item = Result<StreamChunk<O>, Error>> + Send + 'life0>>, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Streaming invocation, shaped by mode (see StreamMode).

fn name(&self) -> Cow<'_, str>

Human-readable identifier used by tracing and debug output. Default is the Rust type name — implementors may override with a domain label (e.g. "anthropic-messages", "json-parser").