ExAgent 2.2 is available on Hex. When upgrading from 1.x, read the migration guide for the runtime, model, event and snapshot changes. See supported features and limits for deployment requirements.

An agent framework for Elixir — structured output, tool-calling, streaming, stateful agents, multi-agent sessions and durable persistence, powered by the BEAM.

ExAgent is layered and opt-in: use just the one-shot core, or stack on the stateful runtime, persistence and coordination as you need them. It is built the Elixir way — recursion, behaviours, Ecto changesets, cheap concurrency for tools, supervision/durability, :telemetry, and events that plug straight into LiveView.

Layer 3  ExAgent.Session          coordinated multi-agent turns + shared state
Layer 2  ExAgent.Store            snapshots: resume after crash / restart
Layer 1  ExAgent.Server           a supervised, stateful, event-emitting agent
Layer 0  ExAgent.run/3            the one-shot model ⇄ tools loop
         ────────────────────────  events (ExAgent.Event) over ExAgent.PubSub

Features

• One-shot agentic loop — a model ⇄ tools recursion built as idiomatic Elixir.
• Type-derived tool schemas — define tools as plain functions; JSON Schema is generated from name :: Type annotations and @doc strings (no hand-written schemas).
• Skills loaded on demand — the model sees a catalog of SKILL.md instructions (the Agent Skills format shared with other agent harnesses) and loads one when a task needs it; skills can unlock their own tools.
• Structured output — any Ecto embedded_schema becomes the output spec; JSON Schema is derived from the schema and its changeset validations, validated with retry-on-failure.
• Streaming — a lazy, demand-driven view of the same tool/output loop, with provisional deltas and one complete result or partial failure.
• Supervised stateful agents — keep history, accumulate usage, thread stateful models across runs, and emit versioned events over PubSub (LiveView-ready).
• Opt-in checkpoints — confirm complete state through a Store and restore a conversation on restart. ETS is in-process; Postgres uses your DB/repo. This does not replay or roll back arbitrary in-flight effects.
• Multi-agent sessions — coordinated turns over shared state with pluggable turn policies (round_robin, initiative, or your own).
• Orchestration — scoped delegation with ancestor budgets/permissions and hand-off between session participants, durable sequences, routing and bounded parallel flows.
• Persisted human approval — pause at an admitted boundary and resume using versioned continuation records, explicit authority and recovery rules.
• Robustness & safety — context compaction, usage/cost limits, and per-tool permissions (allow / ask / deny).
• Model-agnostic — one stock ReqLLM backend with explicitly qualified profiles, custom specs/gateways and the public ExAgent.Model extension behaviour.
• External tools (MCP) — consume stdio or opt-in Streamable HTTP tools with caller-owned timeouts, pending limits and transport cleanup.
• Observable — :telemetry, app-level ExAgent.Event envelopes and opt-in native OpenTelemetry tracing and metrics. ExAgent owns its execution spans; the ReqLLM bridge supplies metadata without duplicate model spans. Content is disabled by default; the application owns its SDK and exporter.
• Offline-first testing — a deterministic ExAgent.Models.Test model drives the full loop with no API key and no network.

Requirements

• Elixir 1.18+ (required by ReqLLM's mandatory llm_db dependency)
• Runtime targets: Elixir 1.18 / OTP 28 and Elixir 1.20 / OTP 29

See supported features and limits for runtime and dependency requirements. These targets do not cover every patch release or dependency combination.

ReqLLM starts its own supervisor and Finch pool alongside ExAgent. Its default startup loads .env in the host's working directory. Applications that manage credentials themselves should set config :req_llm, load_dotenv: false before startup. ExAgent.Models.ReqLLM.new/1 is the general backend; custom Model/Test remain extension points. Tools, Ecto-tool output and streaming use an explicit Chat profile: :chat_tools_v1, or :openrouter_chat_tools_v1 for OpenRouter provider routing. Native JSON Schema uses a separate opt-in profile. Catalogue resolution alone does not enable those capabilities. See models and limits for credentials, profiles, routing, normalized usage and host retention boundaries.

Installation

Add the published package to your application:

def deps do
  [{:exagent, "~> 2.2"}]
end

To develop against a source checkout, replace that dependency with {:exagent, path: "../exAgent"} and adjust the path to your clone.

The library starts its own supervised ExAgent.Finch HTTP pool, a Registry (ExAgent.PubSub.Local), a Task.Supervisor, an ExAgent.Store.ETS table and an ExAgent.AgentSupervisor, so it works out of the box. Tune the Finch pool with:

config :exagent, :finch_pools, %{:default => [size: 32]}

ExAgent does not shadow OTP's Agent unless you alias it as Agent.

Quick start

The fastest way to try ExAgent is with Mix.install/2 (Livebook or a script) — using the built-in ExAgent.Models.Test model, no API key needed:

Mix.install([
  {:exagent, "~> 2.2"}
])

agent = ExAgent.new(model: "test", instructions: "Be concise.")
{:ok, %{output: text}} = ExAgent.run(agent, "Hello!")

Resolve a stock catalogue string or tuple with explicit instance credentials:

{:ok, model} = ExAgent.Model.resolve({:openai, id: "gpt-4o"},
  api_key: System.fetch_env!("OPENAI_API_KEY"))
agent = ExAgent.new(model: model, instructions: "Be concise.")
{:ok, %{output: text}} = ExAgent.run(agent, "Hello!")