内容摘录
Sagents
**Sage Agents** - Combining the wisdom of a Sage) with the power of LLM-based Agents
A sage is a person who has attained wisdom and is often characterized by sound judgment and deep understanding. Sagents brings this philosophy to AI agents: building systems that don't just execute tasks, but do so with thoughtful human oversight, efficient resource management, and extensible architecture.
Key Features
**Human-In-The-Loop (HITL)** - Customizable permission system that pauses execution for approval on sensitive operations
**SubAgents** - Delegate complex tasks to specialized child agents for efficient context management and parallel execution
**GenServer Architecture** - Each agent runs as a supervised OTP process with automatic lifecycle management
**Phoenix.Presence Integration** - Smart resource management that knows when to shut down idle agents
**PubSub Real-Time Events** - Stream agent state, messages, and events to multiple LiveView subscribers
**Middleware System** - Extensible plugin architecture for adding capabilities to agents
**Cluster-Aware Distribution** - Optional Horde-based distribution for running agents across a cluster of nodes with automatic state migration, or run locally on a single node (the default)
**State Persistence** - Save and restore agent conversations via optional behaviour modules for agent state and display messages
**Virtual Filesystem** - Isolated, in-memory file operations with optional persistence
**See it in action!** Try the agents_demo application to experience Sagents interactively, or add the sagents_live_debugger to your app for real-time insights into agent configuration, state, and event flows.
!AgentsDemo Chat Interface
*The AgentsDemo chat interface showing the use of a virtual filesystem, tool call execution, composable middleware, supervised Agentic GenServer assistant, and much more!*
Who Is This For?
Sagents is designed for Elixir developers building **interactive AI applications** where:
Users have real-time conversations with AI agents
Human oversight is required for certain operations (file deletes, API calls, etc.)
Multiple concurrent conversations need isolated agent processes
Agent state must persist across sessions
Real-time UI updates are essential (Phoenix LiveView)
If you're building a simple CLI tool or batch processing pipeline, the core LangChain library may be sufficient. Sagents adds the orchestration layer needed for production interactive applications.
**What about non-interactive agents?** Certainly! Sagents works perfectly well for background agents without a UI. You'd simply skip the UI state management helpers and omit middleware like HumanInTheLoop. The agent still runs as a supervised GenServer with all the benefits of state persistence, middleware capabilities, and SubAgent delegation. The sagents_live_debugger package remains valuable for gaining visibility into what your agents are doing, even without an end-user interface.
Installation
Add sagents to your list of dependencies in mix.exs:
LangChain is automatically included as a dependency.
Supervision Tree Setup
Add Sagents.Supervisor to your application's supervision tree:
This starts the process registry, dynamic supervisors, and filesystem supervisor that Sagents uses to manage agents.
Configuration
Sagents builds on the Elixir LangChain library for LLM integration. To use Sagents, you need to configure an LLM provider by setting the appropriate API key as an environment variable:
Then specify the model when creating your agent:
For detailed configuration options, start here LangChain documentation.
Quick Start
Create an Agent
Start the AgentServer
Handle Events
Handle Human-In-The-Loop Approvals
Provided Middleware
Sagents includes several pre-built middleware components:
| Middleware | Description |
|------------|-------------|
| **TodoList** | Task management with write_todos tool for tracking multi-step work |
| **FileSystem** | Virtual filesystem with ls, read_file, write_file, edit_file, search_text, edit_lines, delete_file |
| **HumanInTheLoop** | Pause execution for human approval on configurable tools |
| **SubAgent** | Delegate tasks to specialized child agents for parallel execution |
| **Summarization** | Automatic conversation compression when token limits approach |
| **PatchToolCalls** | Fix dangling tool calls from interrupted conversations |
| **ConversationTitle** | Auto-generate conversation titles from first user message |
FileSystem Middleware
SubAgent Middleware
SubAgents provide efficient context management by isolating complex tasks:
SubAgents also respect HITL permissions - if a SubAgent attempts a protected operation, the interrupt propagates to the parent for approval.
Human-In-The-Loop Middleware
Configure which tools require human approval:
Decision types:
:approve - Execute with original arguments
:edit - Execute with modified arguments
:reject - Skip execution, inform agent of rejection
Custom Middleware
Create your own middleware by implementing the Sagents.Middleware behaviour:
Quick Setup
Sagents provides generators to scaffold everything you need for conversation-centric agents:
This generates:
**Persistence layer** - Database schemas and migration
**Factory module** - Agent creation with model/middleware configuration
**Coordinator module** - Session management and lifecycle orchestration
All configured to work together seamlessly based on your --owner-type and --owner-field settings.
What Gets Generated
The mix sagents.setup command creates a complete conversation infrastructure:
Persistence Layer
**Context module** (MyApp.Conversations) with CRUD operations
**Schemas**: Conversation, AgentState, DisplayMessage
**Database migration** for all tables
Factory Module
Centralizes agent creation at MyApp.Agents.Factory with:
Model configuration (ChatAnthropic by default, with fallback examples)
Default middleware stack (TodoList, FileSystem, SubAgent, Summarization, etc.)
Human-in-the-Loop co…