sagents-ai / sagents

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, including parallel tool calls where each action can be individually approved/rejected. Works across both main agents and SubAgents — interrupts propagate up to the parent for approval and resume seamlessly • **Composable Execution Modes** - Agent run loops are explicit Elixir pipelines built from reusable steps. Mix and match built-in steps ( , , , , etc.) or write your own. Different agents can use different modes in the same application • **Structured Agent Completion ( )** - Force agents to loop until they call a specific tool, returning the result as a clean tuple. No more hoping the LLM follows your output format — get structured data you can pattern match on • **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, including composable observability callbacks for OpenTelemetry, metrics, or custom logging • **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. *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 to your list of dependencies in : LangChain is automatically included as a dependency. Supervision Tree Setup Add 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 • Structured Completion with Force an agent to return structured output by calling a specific tool: This works through HITL interrupt/resume cycles and with SubAgents — the contract is enforced at every level. Provided Middleware Sagents includes several pre-built middleware components: | Middleware | Description | |------------|-------------| | **TodoList** | Task management with tool for tracking multi-step work | | **FileSystem** | Virtual filesystem with , , , , , , | | **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: • - Execute with original arguments • - Execute with modified arguments • - Skip execution, inform agent of rejection Custom Middleware Create your own middleware by implementing the behaviour: Custom Execution Modes Agent execution in Sagents is an explicit pipeline, not…