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.

Unified System

LangChain agents are built on top of LangGraph in Python. BeamWeaver exposes that relationship as one native system: use BeamWeaver.Agent and BeamWeaver.Agent.build/1 compile to graph-backed runtimes, while BeamWeaver.Graph remains available for deterministic or custom orchestration. Use an agent when you want the standard model/tool loop. Use a graph when you need explicit control over state transitions, branches, fan-out, retries, interrupts, or long-running workflows.

Install

Add BeamWeaver to your Mix project:

def deps do
  [
    {:beam_weaver, "~> 0.1.11"}
  ]
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, 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

• Getting Started

• Semantic DSL

• Thinking In BeamWeaver

• Workflows And Agents

• Persistence

• Memory

• Composed Agent Capabilities

• Deep Agents Quickstart

• Customization

• Profiles

• Filesystem

• Filesystem Permissions

• Skills

• Sandboxes

• Subagents

• Async Subagents

• Subgraphs

• Time Travel

• Durable Execution

• Fault Tolerance

• Agents

• Graph

• Models

• Prompt Caching

• Tools

• Messages

• Runtime

• Context Engineering

• Middleware

• Prebuilt Middleware

• Custom Middleware

• Guardrails

• Human-In-The-Loop

• Short-Term Memory

• Long-Term Memory

• Event Streaming

• Structured Output

• Retrieval

• Prompts And Parsers

• Adapters

• Core

• Partner Matrix

• OpenAI

• Anthropic

• Google

• Moonshot/Kimi

• xAI

• Z.ai

• Replay

• Going To Production

• Rate Limiting

• Tracing

API Reference

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