Sagents (Sage Agents)

Overview#

Sagents is a production-grade AI agent orchestration framework built on Elixir LangChain, designed for scenarios requiring real-time interaction and human-AI collaboration. Current version v0.2.1, licensed under Apache-2.0.

Core Capabilities#

OTP Native Architecture#

• Each agent runs as a supervised GenServer process with automatic fault recovery
• Complete supervision tree managed via Sagents.Supervisor
• Registry-Based Discovery for process discovery
• Uses :rest_for_one supervision strategy

Human-in-the-Loop (HITL)#

• Configurable permission system that pauses execution for sensitive operations (file deletion, API calls) awaiting human approval
• Three decision types: approve, edit (modify parameters then execute), reject

SubAgents Delegation#

• Delegate complex tasks to specialized sub-agents
• Efficient context management and parallel execution
• Independent SubAgentsDynamicSupervisor manages sub-agent lifecycle

Middleware System#

Extensible plugin architecture by implementing Sagents.Middleware behaviour. Pre-built middleware includes:

• TodoList: Task management, track multi-step work
• FileSystem: Virtual file system (ls, read_file, write_file, edit_file, search_text, edit_lines, delete_file)
• HumanInTheLoop: Human approval interception
• SubAgent: Task delegation
• Summarization: Auto-compress conversations when token limit approaches
• PatchToolCalls: Fix pending tool calls in interrupted conversations
• ConversationTitle: Auto-generate conversation title

Phoenix LiveView Integration#

• Real-time streaming of agent status, messages, and events via PubSub
• Phoenix.Presence smart resource management, auto-shutdown idle agents when no clients viewing
• Support multiple LiveView subscribers synchronization

Cluster-Aware Distribution#

• Optional Horde distributed support
• Cross-node agent execution with automatic state migration
• Configuration: config :sagents, :distribution, :horde

State Persistence & Virtual File System#

• Optional behaviour module for saving and restoring agent sessions
• Isolated in-memory file operations with optional persistence
• Independent filesystem scoping

Architecture Design#

Sagents.Supervisor
├── Sagents.ProcessRegistry (Registry or Horde.Registry)
├── Sagents.ProcessSupervisor (DynamicSupervisor or Horde.DynamicSupervisor)
│   └── AgentSupervisor
│       ├── AgentServer
│       └── SubAgentsDynamicSupervisor
└── FileSystemSupervisor
    └── FileSystemServer

Dual-View Session Mode#

• Agent State: LLM thinking content, complete message history, todos, middleware state
• Display Messages: User-facing, UI-friendly records, optimized for rendering and streaming

Installation & Configuration#

# mix.exs
def deps do
  [{:sagents, "~> 0.2.1"}]
end

LLM Provider Configuration#

Supports Anthropic (Claude), OpenAI (GPT), Google (Gemini) via environment variable API keys.

Quick Agent Creation#

alias Sagents.{Agent, AgentServer, State}
alias Sagents.Middleware.{TodoList, FileSystem, HumanInTheLoop}

{:ok, agent} = Agent.new(%{
  agent_id: "my-agent-1",
  model: ChatAnthropic.new!(%{model: "claude-sonnet-4-5-20250929"}),
  base_system_prompt: "You are a helpful coding assistant.",
  middleware: [TodoList, FileSystem, {HumanInTheLoop, [interrupt_on: %{"write_file" => true, "delete_file" => true}]}]
})

{:ok, _pid} = AgentServer.start_link(
  agent: agent,
  initial_state: State.new!(%{messages: [Message.new_user!("Create a hello world program")]}),
  pubsub: {Phoenix.PubSub, :my_app_pubsub},
  inactivity_timeout: 3_600_000
)

Code Generator CLI#

# Generate conversation infrastructure
mix sagents.setup MyApp.Conversations --scope MyApp.Accounts.Scope --owner-type user

# Generate LiveView helpers
mix sagents.gen.live_helpers MyAppWeb.AgentLiveHelpers --context MyApp.Conversations

Use Cases#

• Real-time conversational AI applications (streaming responses, state sync)
• Sensitive operation approval workflows (file operations, external APIs)
• Multi-agent collaborative systems
• Interactive applications requiring session persistence
• Distributed deployment scenarios

Not Suitable For#

• Simple CLI tools or batch processing pipelines (recommend using LangChain directly)
• Non-BEAM platform deployments

Dependencies#

• Core dependency: Elixir LangChain
• Inspiration: LangChain Deep Agents project
• Optional: Horde (distributed support)