Crate entelix_agents 

entelix-agents

Production agent SDK on top of the entelix Runnable / StateGraph foundation. Two layers:

• Agent<S> — runtime entity wrapping any Runnable<S, S> with an event sink and (subsequent slices) execution mode + lifecycle observers. The production-facing surface every consumer constructs.
• Recipes — create_react_agent, create_supervisor_agent, create_chat_agent. Each returns a ready-to-stream Agent<StateType> so common patterns are a single call. Nested-supervisor topologies wire a team_from_supervisor adapter into a parent create_supervisor_agent.

Sub-agent permissions follow F7 (default-filtered hand) via Subagent.

Structs

Agent

Production agent runtime.

AgentBuilder

Fluent builder for Agent<S>.

AgentEntry

One named sub-agent in a create_supervisor_agent graph.

AgentRunResult

Terminal artifact of one agent run.

AlwaysApprove

Always returns Approve — useful as the supervised-mode default when an operator wants the supervised event sequence (ToolCallApproved → ToolStart) but no actual gating logic.

ApprovalLayer

tower::Layer<S> that gates a Service<ToolInvocation, Response = Value, Error = Error> through an Approver. Construct via ApprovalLayer::new; attach to a ToolRegistry via entelix_core::tools::ToolRegistry::layer.

ApprovalRequest

Read-only context the Approver sees for each decision.

ApprovalService

tower::Service<ToolInvocation> produced by ApprovalLayer. Public so operators that wire dispatch paths manually can compose it directly.

BroadcastSink

Multi-consumer broadcast sink. Each subscriber gets its own Receiver; slow consumers receive Lagged errors but the agent never blocks. Suitable for SSE fan-out + OTel exporter

CaptureSink

In-memory capture sink for integration tests. Every emitted event is appended to an Arc<Mutex<Vec<_>>>; tests inspect the vector to assert ordering and content.

ChannelApprover

Production-shape approver backed by an mpsc channel.

ChannelApproverConfig

Configurable timeout for waiting on operator decisions.

ChannelSink

Single-consumer mpsc sink. Construct via Self::new — the caller keeps the tokio::sync::mpsc::Receiver for downstream consumption (HTTP SSE driver, file logger, etc.).

ChatState

State for crate::create_chat_agent and the simplest single-turn recipes — just the conversation so far.

DroppingSink

No-op sink — the agent runs to completion without surfacing per-event telemetry. Default when no sink is configured.

FailOpenSink

Composition adapter that swallows the inner sink’s errors and always returns Ok(()).

FanOutSink

Callback-shaped fan-out — every emitted event reaches every inner sink in registration order.

PendingApproval

One in-flight approval — the operator side. Read these from the Receiver paired with ChannelApprover; resolve by sending an ApprovalDecision on the embedded reply.

ReActAgentBuilder

Fluent builder for a ReAct-style Agent<ReActState>.

ReActState

State for crate::create_react_agent — messages plus a step count to make traces easier to inspect.

RunnableCompacting

Runnable<Vec<Message>, Message> wrapper that compacts the input message slice through an operator-supplied Compactor when the total character count meets or exceeds threshold_chars. Below the threshold the wrapper is a no-op delegate — the inner runnable receives the original Vec<Message> unchanged.

RunnableToSummarizerAdapter

Summarizer that delegates to any Runnable<Vec<Message>, Message> — the same shape as a chat model. Prepends a configurable system instruction so the model understands the task even when the buffer itself contains only raw user/assistant turns.

StateErasureSink

Adapter that erases an agent’s state type so a single AgentEventSink<()> can fan in from heterogeneous agents (Agent<ReActState>, Agent<SupervisorState>, operator-defined state types) in a multi-agent system.

Subagent

A bounded brain↔hand pairing.

SubagentBuilder

Builder for Subagent. Construct via Subagent::builder(model, &parent_registry).

SubagentMetadata

Compact metadata snapshot of a Subagent for parent-side inspection — the LLM-facing identity (name, description) plus the tool surface bound at construction. Operators that list available sub-agents in a parent agent’s system prompt reach for this struct rather than calling each accessor individually.

SubagentTool

Wrapper exposing a crate::agent::Agent as a Tool. Built via Subagent::into_tool.

SummaryCompactor

LLM-summary Compactor — drops the oldest turns past keep_recent_turns into a single summarised Turn::User, leaving the most recent turns verbatim.

SupervisorState

State for crate::create_supervisor_agent — messages plus the last-active sub-agent identifier for traceability.

ToolApprovalEventSinkHandle

Refcounted handle for ToolApprovalEventSink. Stored in entelix_core::ExecutionContext extensions so ApprovalLayer finds the sink without taking it as a constructor argument.

ToolEventLayer

Layer that emits per-tool AgentEvent variants to the configured sink.

ToolEventService

Service produced by ToolEventLayer. Generic over the inner service so the layer composes with any tower-stacked tool path.

ToolHookLayer

Layer that applies a ToolHookRegistry around tool dispatch.

ToolHookRegistry

Ordered collection of tool hooks.

ToolHookRequest

Immutable snapshot of one tool dispatch as seen by hooks.

ToolHookService

Service produced by ToolHookLayer.

Enums

AgentEvent

Runtime events emitted by the agent during a single execute / execute_stream call.

ApprovalDecision

Outcome of a single tool-dispatch approval decision.

EffectGate

Selector for which tool dispatches the ApprovalLayer gates through the Approver. Routes by the calling tool’s ToolMetadata::effect so operators express intent once at metadata time and the layer honours it without per-tool wiring.

ExecutionMode

Agent-level switch between immediate and human-supervised tool execution.

SupervisorDecision

Decision a supervisor router emits each turn.

ToolHookDecision

Decision returned by ToolHook::before_tool.

Constants

DEFAULT_SUMMARY_KEEP_RECENT_TURNS

Default count of newest turns the SummaryCompactor keeps verbatim before summarising the older history into one synthetic turn. Four matches the typical LLM-agent rhythm (most recent user/assistant pair plus one preceding pair) — small enough that summarisation kicks in early, large enough that adjacent context survives.

DEFAULT_SUMMARY_SYSTEM_PROMPT

Default system prompt the SummaryCompactor sends to its summariser model when the operator does not override. Phrased as a neutral compress-the-prior-conversation instruction so it works across vendors that route system prompts identically.

Traits

AgentEventSink

Consumer trait the agent calls for every emitted event.

AgentObserver

Turn-level agent-lifecycle observer.

Approver

Decision-maker for supervised tool execution.

MessageRunnableCompactionExt

Extension trait that attaches RunnableCompacting to any Runnable<Vec<Message>, Message>. Blanket-impl’d for every such runnable so a model accepting messages — including layered models (OtelLayer, PolicyLayer, RetryService) — can chain .with_compaction(.) without a separate import per concrete type.

ToolApprovalEventSink

Type-erased sink for tool-approval events. The agent runtime produces an implementation by adapting its Arc<dyn AgentEventSink<S>> (see ToolApprovalEventSinkHandle::for_agent_sink); operators implementing custom downstream observability (OTel direct, audit-log direct) can implement this trait directly without going through AgentEventSink<S>.

ToolHook

Hook for tool lifecycle policy and audit extensions.

Functions

build_chat_graph

Build the single-node chat graph (system message prepend → model → finish) without wrapping it into an Agent. Use this when you want to configure the agent surface (name, sink, approver, observers) via Agent::builder directly.

build_react_graph

Builds the compiled ReAct graph (planner ↔ tools ↔ finish loop) without wrapping it into an Agent. Use this when you want to configure the agent-level surface (name, sink, approver, observers) directly via Agent::builder:

build_supervisor_graph

Build a supervisor graph that picks among agents each turn.

create_chat_agent

Build a single-turn chat agent: prepends system (if non-empty) to the conversation, calls model, appends the reply, and finishes.

create_react_agent

Builds a ReAct-style agent: model decides; if it emits tool calls, dispatch and loop back; otherwise finish.

create_supervisor_agent

Build a supervisor graph that picks among agents each turn.

team_from_supervisor

Adapt a supervisor Agent<SupervisorState> into a Runnable<Vec<Message>, Message> so it can be embedded as one AgentEntry inside a parent supervisor — the nested-supervisor pattern.

Type Aliases

DynObserver

Convenience type alias for the dynamic-dispatch handle the agent stores internally.