Sagents

The FileSystem middleware provides agents with tools to interact with a virtual filesystem (e.g., list_files, read_file, create_file).

Crucially, the middleware is a thin client that does not hold data itself. Instead, it delegates all operations to a FileSystemServer GenServer. These servers are identified by a scope key (e.g., {:user, 123}).

Key Lifecycle Rules:

• Pre-requisite: The FileSystemServer must be started via Sagents.FileSystem.ensure_filesystem/3 before an agent session begins. If the server for a specific scope is not running, the middleware will fail.
• Persistence: The FileSystemServer is independent of agent lifecycles. It is managed by a FileSystemSupervisor and can outlive individual agent sessions.
• Sharing: Multiple agents or conversations can share the same filesystem by using the same scope key. Any agent configured with filesystem_scope: {:user, 123} will access the same files.

Your Application
  └── FileSystemSupervisor (DynamicSupervisor)
        └── FileSystemServer {:user, 1}   ← started by your app, not by the agent
        └── FileSystemServer {:user, 2}

  └── AgentsDynamicSupervisor
        └── AgentSupervisor (conversation-101)
              └── AgentServer   ← uses FileSystemServer {:user, 1} via scope key

Sagents separates conversation data into three distinct layers to optimize for both intelligence and performance:

• Conversations Table: The central link between the conversation and your application's owner model (e.g., user_id).
• Agent State (Internal View): Stored in the agent_states table as JSONB. This contains the complete LLM context required for intelligent responses. It is optimized for the agent's reasoning process.
• Display Messages (External View): Stored in the display_messages table as individual rows. This is optimized for fast UI queries and rendering. It supports rich content types (like thinking, images, or tool status) that are useful for the user but not necessarily needed by the LLM.

Key Benefit: This separation allows for fast UI updates and progressive message streaming without the overhead of deserializing large agent state blobs every time a message is displayed.

When an LLM calls a tool, the tool function receives two arguments: args (the LLM-provided JSON arguments) and context (runtime data). The context map is composed of three distinct channels, each with a different purpose and lifetime:

1. scope: The canonical channel for tenancy and authorization. It identifies who the agent is running on behalf of. It is a first-class field on the Agent and is automatically merged into the tool's context under the top-level :scope key.
2. tool_context: A static, read-only "grab-bag" of caller-supplied data (e.g., feature flags, request IDs). These are merged flat into the context map and are accessible as top-level keys.
3. state.metadata: A mutable, persistent key-value store. Middleware and tools can read from and write to this during execution. It is nested inside the context.state struct.

Understanding these differences is critical for writing tools that behave correctly in both main agents and SubAgents.

fn args, context ->
  # args: the LLM-provided arguments (parsed from JSON)
  # context: runtime data from the agent system
end

Middleware execution follows a specific order depending on the hook being used. This is critical for managing dependencies and human-in-the-loop gates.

Execution Patterns

• before_model: Executes in the order provided in the middleware list (Top $\rightarrow$ Bottom).
• after_model: Executes in reverse order (Bottom $\rightarrow$ Top).
• handle_resume: Executes in the order provided in the middleware list.

The Sandwich Pattern

This ordering creates a 'sandwich' where early middleware can set up context for later middleware, and early middleware also sees the final processed result after the after_model reverse pass.

Human-In-The-Loop (HITL) Placement

HumanInTheLoop middleware must be the last item in your middleware list.

Why? During the handle_resume cycle, HITL executes all tool calls from an interrupted message. If an auto-approved tool produces its own interrupt (e.g., via ask_user), HITL detects it and returns {:cont}. The resume cycle then re-scans the stack so the owning middleware can claim the interrupt. All interrupt-producing middleware (like AskUserQuestion) must be positioned before HITL in the stack.

In Sagents, configuration and runtime data are strictly separated into two distinct structs:

Agent (Configuration)

The Agent struct is immutable. It defines how the agent should behave but does not change during execution. It includes:

• agent_id: Unique identifier.
• model: The LLM configuration (e.g., %ChatAnthropic{}).
• base_system_prompt: The core instructions.
• middleware: A list of middleware configurations.
• tools: Additional tools beyond those provided by middleware.
• callbacks: Event callbacks.

State (Runtime)

The State struct holds the mutable runtime data that evolves as the agent interacts with users and tools. It includes:

• agent_id: The ID of the associated agent.
• messages: The history of user and LLM messages.
• todos: Middleware-specific task lists.
• metadata: Arbitrary metadata.
• interrupt: Data related to Human-In-The-Loop (HITL) pauses.

# Agent (Immutable Configuration)
%Agent{
  agent_id: "conversation-123",
  model: %ChatAnthropic{...},
  base_system_prompt: "You are helpful.",
  middleware: [{TodoList, []}, {FileSystem, [enabled_tools: [...]]}, ...],
  tools: [custom_tool],
  callbacks: %{...}
}

# State (Runtime Data)
%State{
  agent_id: "conversation-123",
  messages: [%Message{...}, ...],
  todos: [%Todo{...}, ...],
  metadata: %{...},
  interrupt: nil | %InterruptData{...}
}