BeamWeaver
Build AI agents and durable workflows inside your Elixir application. Declare an agent, expose application actions as typed tools, and inspect its results. Use the graph DSL for explicit steps, branches and parallel work.
These docs target 1.0.0. The Hex dependency {:beam_weaver, "~> 1.0.0"}
becomes installable when that release is published. See
Installation for application setup and credentials.
Your first agent
Follow Installation to create a Mix application and
configure OpenAI. Then define this module under lib/my_app/ and run the
invocation in iex -S mix:
defmodule MyApp.SupportAgent do
use BeamWeaver.Agent
model "openai:gpt-5.4-mini", max_tokens: 512, timeout: 60_000
system_prompt "Help customers with orders. Be brief and do not invent order details."
end
{:ok, result} = MyApp.SupportAgent.invoke(%{messages: ["What do you need to look up my order?"]})
answer = result.messages |> List.last() |> BeamWeaver.Core.Message.text()
true = is_binary(answer) and byte_size(answer) > 0
IO.puts(answer)The Quickstart explains the result and offers a Google alternative. Build a Support Agent adds an order lookup, checks its actual result and continues the conversation. Then use the concepts guide to connect agents, state and resource lifetimes.
Learn, extend and operate
| Capability | Guide |
|---|---|
| Declare agents, typed tools and structured answers | Agents, Tools, Structured Output |
| Stream progress and integrate per-request context | Streaming, Runtime Context |
| Keep conversations and cross-thread memory | Short-Term Memory, Long-Term Memory |
| Review actions before they run | Human-in-the-Loop |
| Add files, planning, skills and delegation | Deep Agents |
| Control workflow steps, branches and parallel work | Graphs, Workflow Patterns |
| Persist checkpoints and recover interrupted work | Storage, Durable Execution |
| Search documents with embeddings and vector stores | Retrieval |
| Apply retries, limits, caching and context policies | Built-in Middleware, Context Management |
| Test and inspect production behavior | Testing, Tracing, Going to Production |
Providers
OpenAI, Anthropic, Google Gemini, xAI, DeepSeek, Moonshot, Z.ai and TypeSafe. The provider guides distinguish chat, embedding and decision models and explain each provider's supported features. Fake models and replay transports support deterministic application tests.
Documentation and examples
When contributing to BeamWeaver, run mix test for deterministic checks and
mix docs.verify --all for isolated documentation execution, including
required live providers and services. The verification report identifies failures and unmet prerequisites;
compilation alone is not reported as executed coverage.
Apache-2.0. See LICENSE.