Overview

BeamWeaver is an OTP-native Elixir system for building LLM applications, agents, and graph-orchestrated workflows. It combines the two layers that the Python ecosystem documents separately:

LangChain-style model, message, tool, middleware, retrieval, and agent abstractions.
LangGraph-style durable graph execution, checkpoints, interrupts, streaming, state, and memory.

The Python projects are behavioral references. BeamWeaver's public API is Elixir: modules, structs, behaviours, protocols, supervised tasks, Enumerable streams, telemetry, explicit adapters, and tagged errors.

BeamWeaver is not affiliated with LangChain.

WeaveScope is available for hosted tracing and monitoring. Use the WeaveScope app to create projects, manage API keys, and inspect exported traces.

Install

Add BeamWeaver to your Mix project:

def deps do
  [
    {:beam_weaver, "~> 0.1.16"}
  ]
end

Then run:

mix deps.get
mix compile

Create An Agent

Use use BeamWeaver.Agent for stable application modules and BeamWeaver.Agent.build/1 for runtime-configured agents. Both compile to the same graph-backed runtime. Stable modules should use the semantic DSL so tools, middleware, subagents, graphs, prompts, and schemas stay visibly separate.

The runnable weather-agent walkthrough is in Quickstart . The full module DSL is in Semantic DSL .

Agent features include model and tool calling, middleware, structured output, short-term memory through checkpoints, long-term memory through stores, Deep Agents-style composed capabilities, human-in-the-loop interrupts, typed streaming, retries, fallbacks, and runtime context injection.

Build A Graph

Use graph do inside an agent module when the workflow is not just a model/tool loop, or when you want explicit orchestration:

defmodule MyApp.HelloWorld do
  use BeamWeaver.Agent

  graph do
    state do
      channel :messages, merge: fn existing, update -> existing ++ List.wrap(update) end
    end

    node :mock_llm, fn _state ->
      %{messages: [BeamWeaver.Core.Message.assistant("hello world")]}
    end

    edge start(), :mock_llm
    edge :mock_llm, finish()
  end
end

{:ok, state} =
  MyApp.HelloWorld.invoke(%{
    messages: [BeamWeaver.Core.Message.user("hi")]
  })

Use BeamWeaver.Graph builder functions directly when graph shape is dynamic or generated from configuration. Graphs support reducer-based state, conditional routing, dynamic fan-out, joins, commands, checkpoints, interrupts, state history, and stream_events/3. Agents use the same graph runtime underneath.

Core Benefits

Capability	BeamWeaver surface
Standard model interface	`BeamWeaver.Core.ChatModel` plus provider adapters for OpenAI, Anthropic, Google, DeepSeek, xAI, Z.ai, fake, and replay-backed tests.
Agent architecture	`use BeamWeaver.Agent` and `BeamWeaver.Agent.build/1` for graph-backed model/tool loops.
Low-level orchestration	`BeamWeaver.Graph` for deterministic, agentic, or hybrid workflows.
Durable execution	Checkpoint-backed resumable graph execution .
Fault tolerance	Node retries, timeouts, error handlers, and failure policies .
Human oversight	Graph interrupts and agent human-in-the-loop middleware.
Memory	Short-term memory through checkpoints; long-term memory through `BeamWeaver.Memory` stores.
Composed agent capabilities	Planning, virtual filesystems, permissions, subagents, context compaction, code execution, HITL, skills, and memory files through normal composable agent options and middleware.
Deep Agents quickstart	Build a composed research agent with planning, filesystem tools, and a subagent.
Customization	Configure tools, middleware, models, filesystem access, skills, subagents, tracing, and runtime context with module macros or `Agent.build/1` options.
Prompt caching	Provider-specific cache keys, Anthropic system-prompt cache control, and normalized cache-read usage metadata.
Streaming	Typed `%BeamWeaver.Stream.Envelope{}` values exposed as Elixir `Enumerable` streams.
Observability	Telemetry and tracing/export boundaries under `BeamWeaver.Tracing`.
Retrieval	Document loaders, splitters, embeddings, vector stores, retrievers, and indexing primitives.

Core Surfaces

Surface	Use
`use BeamWeaver.Agent`	Stable application agents and graph modules.
`BeamWeaver.Agent.build/1`	Runtime-configured agents.
`BeamWeaver.Graph`	Explicit workflows, reducers, branches, subgraphs, checkpoints, and interrupts.
`BeamWeaver.Core.Message`	System, user, assistant, and tool messages.
`BeamWeaver.Core.Tool` and `use BeamWeaver.Tool`	Runtime and module-defined tools.
`BeamWeaver.Agent.Middleware`	Lifecycle behavior around agent, model, and tool execution.
`BeamWeaver.Checkpoint.Saver`	Short-term memory and resumable execution.
`BeamWeaver.Memory.Store`	Long-term memory and application stores.
`stream_events/3`	Typed event envelopes for UI, logs, and tracing pipelines.
`BeamWeaver.Tracing`	Local traces and native WeaveScope export.

Start Here

API Reference

Use HexDocs for module and function reference. GitBook is focused on concepts, workflows, and implementation guides.