API Reference ExAgent v#2.0.1

A DynamicSupervisor that owns ExAgent.Server processes.

Composable middleware that observes/transforms an agent run at well-defined points. This is ExAgent's "capabilities" spine, modelled the Elixir way: a behaviour whose callbacks default to no-ops via use ExAgent.Capability, so a capability overrides only the hooks it cares about.

A state transition whose checkpoint was not confirmed by the configured Store.

Behaviour for reducing the conversation context sent to a model.

A capability that compacts only the projection sent by before_model_request.

A compactor that summarizes older messages and keeps a recent window verbatim.

Administrative queries and host-authorized decisions for atomic records.

Experimental persistence-only retry state for a continuation runtime owner.

Experimental, data-only continuation envelope. Existing snapshot codecs remain authoritative for history and qualified usage. No stored value resolves a module, template, credential or callable. Application JSON must already be secret-free.

Orchestration patterns on top of ExAgent.Session and the core loop.

Experimental trusted-host definition of a bounded agent sequence.

A bounded, trusted host router or parallel fan-out/fan-in.

Helpers for turning token usage into an estimated cost, used together with the max_budget_cents field of ExAgent.UsageLimits.

Versioned, serializable event envelope — ExAgent's UI/runtime contract.

Ephemeral admission and accounting for one execution tree.

A client for Model Context Protocol servers over stdio or opt-in Streamable HTTP, exposing tools as ExAgent.Tools.

Pure JSON-RPC 2.0 encoding/decoding for the Model Context Protocol, plus the mapping from an MCP tool spec to an ExAgent.Tool.

Bounded MCP 2025-06-18 POST transport using stock Finch's public API.

Message and part types exchanged between the agent and a model.

Request & response part structs.

A retry prompt: validation errors (list of maps) or a plain message, sent back to the model so it can correct itself.

A system / instruction prompt part.

A plain text chunk returned by the model.

A reasoning / chain-of-thought part (provider-dependent).

The model asking the agent to run a tool.

The return value of a tool call, fed back to the model.

A user prompt part (text or multimodal content list).

A message sent to the model.

A message returned by the model.

Qualified metrics for a response or aggregate. accounting is a versioned, string-keyed JSON map, separate from additive token details. Reported means reported to the host by the Model contract, not audited provider presence. Cost is always an estimate in cents, never an invoice.

Behaviour that every provider model implements.

Declaration of what a given model/provider supports, so callers and future capabilities can negotiate gracefully per model — e.g. whether the provider can do native JSON-schema output, forced tool calls, or extended thinking.

The per-request contract handed to a model. It bundles the tools the agent has prepared (function tools + output tools), the negotiated output mode, and the structured-output schema (if any).

A tool or output validator can return/raise this to ask the model to try again. In Elixir we mostly use {:error, reason} tuples, but this exception exists for the rescue-based escape hatch.

Per-request knobs sent to the model. Provider-specific options that are not first-class fields can be carried in the immutable :extra map.

Model adapter over ReqLLM's public one-interaction APIs.

A deterministic, in-process model for development and tests.

An application-owned, bounded native OpenTelemetry span processor.

Optional native OpenTelemetry instrumentation, using the application's tracer.

Application-owned ReqLLM tracing with one generation span per request.

Optional application-supervised cleanup of the integrated ReqLLM bridge.

Optional histogram adapter for the published OTel experimental API 0.6.

Structured output via Ecto schemas and changesets.

Per-tool admission control: :allow, :ask or :deny, matched against tool names with glob patterns — the same model opencode uses for tool safety.

Behaviour for broadcasting ExAgent.Events.

In-process PubSub backed by a duplicate-key Registry (ExAgent.PubSub.Registry, started by the application supervisor).

No-op PubSub (default). Broadcasts are discarded; subscribe/2 is unsupported. Use when you don't need to observe events (e.g. pure one-shot ExAgent.run/3).

Delegates to Phoenix.PubSub when available, with no hard dependency.

Structured error returned by providers for transport/API failures.

The context object threaded through dynamic instructions, tool calls and output validators during a single run.

An operational run failure with the last confirmed execution state.

Convert Elixir type expressions (as written in :: annotations / typespecs) into JSON Schema fragments — the foundation for deftool and structured output.

Supervised owner of conversational history, model state and accumulated usage.

Version 4 checkpoint of conversational data, with bounded readers for v1/v2/v3.

Single-writer coordination of application state and a participant roster.

A member of an ExAgent.Session: either an :agent (typically backed by an ExAgent.Server) or a :human (a real person driving via LiveView/a channel).

A handle placed in RunContext.deps so tools running inside an agent run can read the session's shared state and propose changes — without ever holding a mutable reference to it.

JSON checkpoint of coordination data. Version 3 adds bounded continuation references; unbound sessions still write v2, and valid v1/v2 data remains readable.

Optional codec for application state at the Session checkpoint boundary.

Decides the order in which session participants take turns.

Cycles participants in an explicitly given order, forever. Use it when participants act in a fixed, possibly uneven sequence — D&D initiative order, priority-based triage, etc.

Cycles participants in insertion order, forever (each full pass is a "round"). The simplest fair policy — good for chat, brainstorming, or any turn-taking where everyone gets equal time.

A coordinator-driven turn order: a supervisor participant alternates with each worker in turn, forever.

Behaviour for persisting agent/session snapshots and optional atomic records.

In-process, ETS-backed ExAgent.Store implementation (dev/test default).

A durable ExAgent.Store backed by PostgreSQL, for resume across crashes and multiple nodes.

Telemetry event helpers.

A tool the model may call.

Define tools as plain Elixir functions, with their JSON Schema derived from :: type annotations and @doc strings — no hand-written schemas.

Raised/returned when the model behaves in a way the loop cannot recover from (retries exhausted, no progress, usage limits hit).

Execution-tree safety net: each run's limits also constrain its framework descendants. Admission is serialized by ExAgent.ExecutionScope; these functions provide the pure checks. Token/cost thresholds are retrospective, so already in-flight requests can exceed them.