# ExAgent v2.2.0 - Table of Contents

> ExAgent 2.2.0: usage guides and public API reference. A layered agent framework for Elixir: structured output, tool-calling, streaming, stateful supervised agents, multi-agent sessions, durable persistence, compaction/cost/permissions and MCP — powered by the BEAM.

## Pages

- Start here
  - [Welcome](welcome.md)
  - [Getting started](getting-started.md)
  - [Documentation index](documentation.md)

- Build with ExAgent
  - [Tools and structured output](tools-and-output.md)
  - [Skills](skills.md)
  - [Models, budgets and limits](models-and-limits.md)
  - [Runtime, streaming and events](runtime-and-events.md)
  - [Durability and human approvals](durability-and-approvals.md)
  - [Coordinate agents](coordination.md)
  - [Test your integration](testing.md)
  - [Connect MCP tools](mcp.md)
  - [Diagnose an integration](troubleshooting.md)
  - [Optional OpenTelemetry observability](observability.md)

- Integrations
  - [Jobs with persisted approvals](continuation-jobs.md)
  - [Phoenix, LiveView and Oban integrations](framework-integrations.md)
  - [Durable coordination recipes](coordination-recipes.md)
  - [Retrieve external data through a tool](external-retrieval.md)
  - [MCP tools with persisted approval](mcp-continuation-binding.md)
  - [OTLP through an application-owned exporter VM](otlp-isolated-transport.md)
  - [OTLP through an application-owned Collector](otlp-collector-transport.md)

- Reference
  - [Integration notes for coding agents](agents.md)
  - [ExAgent](readme.md)
  - [Supported features and limits](status.md)
  - [Known limits](known-limits.md)
  - [Upgrade from ExAgent 1.x to 2.0](migration.md)
  - [LICENSE](license.md)

- Architecture
  - [Architecture and ownership](architecture.md)

## Modules

- [ExAgent.ExecutionScope](ExAgent.ExecutionScope.md): Ephemeral admission and accounting for one execution tree.
- [ExAgent.Message.Part](ExAgent.Message.Part.md): Request & response part structs.
- [ExAgent.Message.Part.Retry](ExAgent.Message.Part.Retry.md): A retry prompt: validation errors (list of maps) or a plain message,
sent back to the model so it can correct itself.

- [ExAgent.Message.Part.System](ExAgent.Message.Part.System.md): A system / instruction prompt part.
- [ExAgent.Message.Part.Text](ExAgent.Message.Part.Text.md): A plain text chunk returned by the model.
- [ExAgent.Message.Part.Thinking](ExAgent.Message.Part.Thinking.md): A reasoning / chain-of-thought part (provider-dependent).
- [ExAgent.Message.Part.ToolCall](ExAgent.Message.Part.ToolCall.md): The model asking the agent to run a tool.
- [ExAgent.Message.Part.ToolReturn](ExAgent.Message.Part.ToolReturn.md): The return value of a tool call, fed back to the model.
- [ExAgent.Message.Part.User](ExAgent.Message.Part.User.md): A user prompt part: a string or a non-empty list of content parts.
- [ExAgent.Message.Request](ExAgent.Message.Request.md): A message sent *to* the model.
- [ExAgent.Message.Response](ExAgent.Message.Response.md): A message returned *by* the model.
- [ExAgent.Message.Usage](ExAgent.Message.Usage.md): 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.

- Agent &amp; Loop
  - [ExAgent](ExAgent.md): 
  - [ExAgent.RunContext](ExAgent.RunContext.md): The context object threaded through dynamic instructions, tool calls and
output validators during a single run.
  - [ExAgent.UsageLimits](ExAgent.UsageLimits.md): 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.

- Robustness
  - [ExAgent.Compaction](ExAgent.Compaction.md): Behaviour for reducing the conversation context sent to a model.
  - [ExAgent.Compaction.Capability](ExAgent.Compaction.Capability.md): A capability that compacts only the projection sent by `before_model_request`.
  - [ExAgent.Compaction.Summary](ExAgent.Compaction.Summary.md): A compactor that summarizes older messages and keeps a recent window verbatim.
  - [ExAgent.CostGuard](ExAgent.CostGuard.md): Helpers for turning token usage into an estimated cost, used together with
the `max_budget_cents` field of `ExAgent.UsageLimits`.
  - [ExAgent.Permissions](ExAgent.Permissions.md): Per-tool admission control: `:allow`, `:ask` or `:deny`, matched against tool
names with glob patterns — the same model opencode uses for tool safety.

- Stateful Runtime
  - [ExAgent.AgentSupervisor](ExAgent.AgentSupervisor.md): A `DynamicSupervisor` that owns `ExAgent.Server` processes.
  - [ExAgent.Server](ExAgent.Server.md): Supervised owner of conversational history, model state and accumulated usage.
  - [ExAgent.Server.Snapshot](ExAgent.Server.Snapshot.md): Version 4 checkpoint of conversational data, with bounded readers for v1/v2/v3.

- Session &amp; Coordination
  - [ExAgent.Coordination](ExAgent.Coordination.md): Orchestration patterns on top of `ExAgent.Session` and the core loop.
  - [ExAgent.Coordination.Composition](ExAgent.Coordination.Composition.md): Experimental trusted-host definition of a bounded agent sequence.
  - [ExAgent.Coordination.Flow](ExAgent.Coordination.Flow.md): A bounded, trusted host router or parallel fan-out/fan-in.
  - [ExAgent.Session](ExAgent.Session.md): Single-writer coordination of application state and a participant roster.
  - [ExAgent.Session.Participant](ExAgent.Session.Participant.md): 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).
  - [ExAgent.Session.SharedState](ExAgent.Session.SharedState.md): 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.
  - [ExAgent.Session.Snapshot](ExAgent.Session.Snapshot.md): JSON checkpoint of coordination data. Version 3 adds bounded continuation
references; unbound sessions still write v2, and valid v1/v2 data remains readable.
  - [ExAgent.Session.StateCodec](ExAgent.Session.StateCodec.md): Optional codec for application state at the Session checkpoint boundary.
  - [ExAgent.Session.TurnPolicy](ExAgent.Session.TurnPolicy.md): Decides the order in which session participants take turns.
  - [ExAgent.Session.TurnPolicy.Initiative](ExAgent.Session.TurnPolicy.Initiative.md): 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.
  - [ExAgent.Session.TurnPolicy.RoundRobin](ExAgent.Session.TurnPolicy.RoundRobin.md): 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.
  - [ExAgent.Session.TurnPolicy.SupervisorPolicy](ExAgent.Session.TurnPolicy.SupervisorPolicy.md): A coordinator-driven turn order: a **supervisor** participant alternates with
each worker in turn, forever.

- Events &amp; PubSub
  - [ExAgent.Event](ExAgent.Event.md): Versioned, serializable event envelope — ExAgent's UI/runtime contract.
  - [ExAgent.PubSub](ExAgent.PubSub.md): Behaviour for broadcasting `ExAgent.Event`s.
  - [ExAgent.PubSub.Local](ExAgent.PubSub.Local.md): In-process PubSub backed by a duplicate-key `Registry`
(`ExAgent.PubSub.Registry`, started by the application supervisor).
  - [ExAgent.PubSub.None](ExAgent.PubSub.None.md): 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`).

  - [ExAgent.PubSub.Phoenix](ExAgent.PubSub.Phoenix.md): Delegates to `Phoenix.PubSub` when available, with **no hard dependency**.

- Persistence
  - [ExAgent.Store](ExAgent.Store.md): Behaviour for persisting agent/session snapshots and optional atomic records.
  - [ExAgent.Store.ETS](ExAgent.Store.ETS.md): In-process, ETS-backed `ExAgent.Store` implementation (dev/test default).
  - [ExAgent.Store.Postgres](ExAgent.Store.Postgres.md): A durable `ExAgent.Store` backed by PostgreSQL, for resume across crashes and
multiple nodes.

- Continuation &amp; Recovery
  - [ExAgent.CheckpointError](ExAgent.CheckpointError.md): A state transition whose checkpoint was not confirmed by the configured Store.
  - [ExAgent.Continuation](ExAgent.Continuation.md): Administrative queries and host-authorized decisions for atomic records.
  - [ExAgent.Continuation.Checkpoint](ExAgent.Continuation.Checkpoint.md): Experimental persistence-only retry state for a continuation runtime owner.
  - [ExAgent.Continuation.Record](ExAgent.Continuation.Record.md): 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.

- External Tools (MCP)
  - [ExAgent.MCP.Client](ExAgent.MCP.Client.md): A client for [Model Context Protocol](https://modelcontextprotocol.io) servers
over **stdio** or opt-in **Streamable HTTP**, exposing tools as `ExAgent.Tool`s.
  - [ExAgent.MCP.Protocol](ExAgent.MCP.Protocol.md): Pure JSON-RPC 2.0 encoding/decoding for the Model Context Protocol, plus the
mapping from an MCP tool spec to an `ExAgent.Tool`.
  - [ExAgent.MCP.StreamableHTTP](ExAgent.MCP.StreamableHTTP.md): Bounded MCP 2025-06-18 POST transport using stock Finch's public API.

- Messages
  - [ExAgent.Message](ExAgent.Message.md): Message and part types exchanged between the agent and a model.

- Tools &amp; Output
  - [ExAgent.OutputSchema](ExAgent.OutputSchema.md): Structured output via Ecto schemas and changesets.
  - [ExAgent.Schema](ExAgent.Schema.md): Convert Elixir type expressions (as written in `::` annotations / typespecs)
into JSON Schema fragments — the foundation for `deftool` and structured
output.
  - [ExAgent.Tool](ExAgent.Tool.md): A tool the model may call.
  - [ExAgent.Tools](ExAgent.Tools.md): Define tools as plain Elixir functions, with their JSON Schema derived from
`::` type annotations and `@doc` strings — no hand-written schemas.

- Skills
  - [ExAgent.Skill](ExAgent.Skill.md): A skill: instructions for one kind of task, loaded by the model when needed.
  - [ExAgent.Skills](ExAgent.Skills.md): Skills that the model loads on demand (progressive disclosure).
  - [ExAgent.Skills.Gate](ExAgent.Skills.Gate.md): Capability that offers a skill's tools only after the skill is loaded.
  - [ExAgent.Skills.Restore](ExAgent.Skills.Restore.md): Capability that restores loaded skills removed from the request projection.

- Models
  - [ExAgent.Model](ExAgent.Model.md): Behaviour that every provider model implements.
  - [ExAgent.ModelProfile](ExAgent.ModelProfile.md): 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.
  - [ExAgent.ModelRequestParameters](ExAgent.ModelRequestParameters.md): 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).
  - [ExAgent.ModelSettings](ExAgent.ModelSettings.md): Per-request knobs sent to the model. Provider-specific options that are not
first-class fields can be carried in the immutable `:extra` map.

- Providers
  - [ExAgent.Models.Fallback](ExAgent.Models.Fallback.md): Retries transient provider failures and falls back to other models.
  - [ExAgent.Models.ReqLLM](ExAgent.Models.ReqLLM.md): Model adapter over ReqLLM's public one-interaction APIs.
  - [ExAgent.Models.Test](ExAgent.Models.Test.md): A deterministic, in-process model for development and tests.

- Capabilities &amp; Telemetry
  - [ExAgent.Capability](ExAgent.Capability.md): 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.
  - [ExAgent.Telemetry](ExAgent.Telemetry.md): Telemetry event helpers.

- Observability
  - [ExAgent.Observability.BoundedProcessor](ExAgent.Observability.BoundedProcessor.md): An application-owned, bounded native OpenTelemetry span processor.
  - [ExAgent.Observability.OpenTelemetry](ExAgent.Observability.OpenTelemetry.md): Optional native OpenTelemetry instrumentation, using the application's tracer.
  - [ExAgent.Observability.ReqLLM](ExAgent.Observability.ReqLLM.md): Application-owned ReqLLM tracing with one generation span per request.
  - [ExAgent.Observability.ReqLLM.Maintenance](ExAgent.Observability.ReqLLM.Maintenance.md): Optional application-supervised cleanup of the integrated ReqLLM bridge.
  - [ExAgent.Observability.ReqLLM.Metrics](ExAgent.Observability.ReqLLM.Metrics.md): Optional histogram adapter for the published OTel experimental API 0.6.

- Exceptions
  - [ExAgent.ModelRetry](ExAgent.ModelRetry.md): 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.

  - [ExAgent.RequestError](ExAgent.RequestError.md): Structured error returned by providers for transport/API failures.
  - [ExAgent.RunError](ExAgent.RunError.md): An operational run failure with the last confirmed execution state.
  - [ExAgent.UnexpectedModelBehavior](ExAgent.UnexpectedModelBehavior.md): Raised/returned when the model behaves in a way the loop cannot recover from
(retries exhausted, no progress, usage limits hit).

