# ExAgent v0.4.0 - Table of Contents

> An agent framework for Elixir — structured output, tool-calling and streaming, powered by the BEAM.

## Pages

- [ExAgent](readme.md)
- [Changelog](changelog.md)
- [ExAgent — Design Document](design.md)
- [ExAgent — Roadmap](roadmap.md)
- [LICENSE](license.md)

## Modules

- [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 (text or multimodal content list).
- [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): Token accounting for a single model response.
- [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**.

- Agent &amp; Loop
  - [ExAgent](ExAgent.md): An agent: model + instructions + tools + output spec, runnable as a loop that
alternates between **calling the model** and **executing tools** until a final
result is produced.
  - [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): Run-level safety net: caps on requests, token usage, tool calls and cost,
enforced at well-defined points in the agent loop.

- Robustness
  - [ExAgent.Compaction](ExAgent.Compaction.md): Behaviour for shrinking a conversation history when it grows too large, so a
long-running session stays within a model's context window.
  - [ExAgent.Compaction.Capability](ExAgent.Compaction.Capability.md): A capability that runs a compactor on `before_model_request`, shrinking the
canonical history (and the request about to be sent) when it grows too large.
  - [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): A supervised, stateful wrapper around `ExAgent.run/3`.
  - [ExAgent.Server.Snapshot](ExAgent.Server.Snapshot.md): A serializable checkpoint of an `ExAgent.Server`'s conversational state.

- Session &amp; Coordination
  - [ExAgent.Coordination](ExAgent.Coordination.md): Orchestration patterns on top of `ExAgent.Session` and the core loop.
  - [ExAgent.Session](ExAgent.Session.md): A coordinated, multi-participant interaction with shared state.
  - [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.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.

- Persistence
  - [ExAgent.Store](ExAgent.Store.md): Behaviour for persisting `ExAgent.Server.Snapshot`s (and, in Phase 3, session
snapshots).
  - [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.

- 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.

- Models
  - [ExAgent.Model](ExAgent.Model.md): Behaviour that every provider model implements.
  - [ExAgent.ModelProfile](ExAgent.ModelProfile.md): **Advisory** 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.Anthropic](ExAgent.Models.Anthropic.md): Anthropic Messages API provider, or any endpoint that speaks the same format
(e.g. Z.AI's `/api/anthropic`, which serves GLM models natively in Anthropic
form).
  - [ExAgent.Models.OpenAI](ExAgent.Models.OpenAI.md): OpenAI Chat Completions provider. Talks the real API over Req.
  - [ExAgent.Models.OpenRouter](ExAgent.Models.OpenRouter.md): [OpenRouter](https://openrouter.ai) provider.
  - [ExAgent.Models.Test](ExAgent.Models.Test.md): A deterministic, in-process model for development and tests.
  - [ExAgent.Providers.Anthropic](ExAgent.Providers.Anthropic.md): Implementation for providers that speak the **Anthropic Messages API**:
`POST {base_url}/v1/messages`.
  - [ExAgent.Providers.OpenAIChat](ExAgent.Providers.OpenAIChat.md): Shared implementation for any provider that speaks the OpenAI **Chat
Completions** wire format (`/v1/chat/completions`). This covers OpenAI itself
and OpenRouter (and DeepSeek, Groq, Together, etc.).
  - [ExAgent.Providers.SSE](ExAgent.Providers.SSE.md): Turn a Req asynchronous response into a lazy `Stream` of Server-Sent-Events.

- 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.

- 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.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).

