@spec add_message(String.t(), LangChain.Message.t()) :: :ok

Add a message to the agent's state and transition to idle if completed.

This is useful for conversational interfaces where you want to add a new user message after the agent has completed a previous execution.

Returns :ok on success.

Examples

# After agent completes
:ok = AgentServer.add_message("my-agent-1", Message.new_user!("What's next?"))
:ok = AgentServer.execute("my-agent-1")

@spec agent_count() :: non_neg_integer()

Gets count of currently running agents.

Returns the total number of AgentServer processes registered in the Sagents.Registry.

Examples

AgentServer.agent_count()
# => 5

@spec agent_info(String.t()) :: map() | nil

Gets detailed information about a running agent.

Returns a map with agent status and state information, or nil if the agent is not running.

Return Value

If the agent is running, returns a map containing:

• :agent_id - The agent identifier
• :pid - The process ID
• :status - Current execution status (:idle, :running, :interrupted, etc.)
• :state - Exported state snapshot
• :message_count - Number of messages in the state
• :has_interrupt - Boolean indicating if there's pending interrupt data

Examples

AgentServer.agent_info("conversation-1")
# => %{
#   agent_id: "conversation-1",
#   pid: #PID<0.1234.0>,
#   status: :idle,
#   state: %State{...},
#   message_count: 5,
#   has_interrupt: false
# }

AgentServer.agent_info("nonexistent")
# => nil

@spec cancel(String.t()) :: :ok | {:error, term()}

Cancel a running LLM task.

Stops the currently executing agent task and transitions the server to completed status. Returns {:error, reason} if the server is not running (no task to cancel).

Examples

:ok = AgentServer.cancel("my-agent-1")

@spec execute(String.t()) :: :ok | {:error, term()}

Execute the agent.

Starts agent execution asynchronously. The server will broadcast events as the agent runs. Returns :ok immediately.

Returns {:error, reason} if the server is not idle (already running, interrupted, etc.).

Examples

:ok = AgentServer.execute("my-agent-1")

@spec export_state(String.t()) :: map()

Export the current conversation state to a serializable format.

This can be persisted to a database and later used to restore the conversation state. The exported state uses string keys (not atoms) for compatibility with JSON/JSONB storage.

Returns a map with string keys containing:

• "version" - Serialization format version
• "state" - The conversation state (messages, todos, metadata)
• "serialized_at" - ISO8601 timestamp

What is NOT included:

• Agent configuration (middleware, tools, model) - must come from application code
• agent_id - runtime identifier provided when restoring

This design allows you to restore the same conversation state under a different agent_id, enabling use cases like state cloning and conversation forking.

Examples

state = AgentServer.export_state("my-agent-1")
# Save to database
MyApp.Conversations.save_agent_state(conversation_id, state)

@spec get_agent(String.t()) :: {:ok, Sagents.Agent.t()} | {:error, :not_found}

Gets the agent configuration for the given agent.

Returns

• {:ok, Agent.t()} - The agent struct
• {:error, :not_found} - Agent not found

Examples

{:ok, agent} = AgentServer.get_agent("my-agent-1")
# => {:ok, %Agent{agent_id: "my-agent-1", model: %ChatModel{...}, ...}}

@spec get_inactivity_status(String.t()) :: map()

Get the current inactivity status of an agent.

Returns a map with:

• :inactivity_timeout - Configured timeout in milliseconds (or nil/:infinity)
• :last_activity_at - DateTime of last activity
• :timer_active - Boolean indicating if timer is currently running
• :time_since_activity - Milliseconds since last activity (or nil if no activity yet)

Examples

status = AgentServer.get_inactivity_status("my-agent-1")
# => %{
#   inactivity_timeout: 300_000,
#   last_activity_at: ~U[2025-11-06 10:15:30.123Z],
#   timer_active: true,
#   time_since_activity: 45_000
# }

@spec get_info(String.t()) :: map()

Get server info including status, state, and any error or interrupt data.

Returns a map with:

• :status - Current status
• :state - Current State
• :interrupt_data - Interrupt data if status is :interrupted
• :error - Error reason if status is :error

Examples

info = AgentServer.get_info("my-agent-1")

@spec get_metadata(String.t()) :: {:ok, map()} | {:error, :not_found}

Gets metadata about the agent server including status and last activity.

Returns

• {:ok, metadata} - Map with agent metadata
• {:error, :not_found} - Agent not found

Metadata Fields

• :status - Current status atom (:idle, :running, :interrupted, :error, :cancelled)
• :last_activity_at - DateTime of last activity (may be nil)
• :conversation_id - Conversation ID (may be nil)
• :node - The Erlang node where this agent is running

Examples

{:ok, metadata} = AgentServer.get_metadata("my-agent-1")
# => {:ok, %{status: :idle, last_activity_at: ~U[2024-01-01 12:00:00Z], conversation_id: "conv-123"}}

@spec get_name(String.t()) :: GenServer.name()

Get the name of the AgentServer process for a specific agent.

Examples

name = AgentServer.get_name("my-agent-1")
GenServer.call(name, :get_status)

@spec get_pid(String.t()) :: pid() | {atom(), node()} | nil

Get the pid of the AgentServer process for a specific agent.

Examples

pid = AgentServer.get_pit("my-agent-1")
send(pid, message)

@spec get_status(String.t()) :: status() | :not_running

Get the current status of the server.

Returns one of:

• :idle - Server ready for work
• :running - Agent executing
• :interrupted - Awaiting human decision
• :cancelled - Execution was cancelled
• :error - Execution failed
• :not_running - Agent process does not exist

Examples

:idle = AgentServer.get_status("my-agent-1")
:not_running = AgentServer.get_status("non-existent-agent")

@spec list_agents_matching(String.t()) :: [String.t()]

Gets all running agents matching a glob pattern.

Supports wildcard patterns using * which matches any sequence of characters.

Examples

# Get all conversation agents
AgentServer.list_agents_matching("conversation-*")
# => ["conversation-1", "conversation-2", "conversation-123"]

# Get all user agents
AgentServer.list_agents_matching("user-*")
# => ["user-42", "user-99"]

# Get specific prefix
AgentServer.list_agents_matching("demo-*")
# => ["demo-agent-001"]

@spec list_running_agents() :: [String.t()]

Lists all currently running agent processes.

Returns a list of agent_ids for all running AgentServer processes registered in the Sagents.Registry.

Examples

AgentServer.list_running_agents()
# => ["conversation-1", "conversation-2", "user-123"]

@spec notify_middleware(String.t(), term(), term()) :: :ok

Send a targeted message to a specific middleware in a running AgentServer.

The message is routed through the middleware registry and delivered to the middleware's handle_message/3 callback. The middleware is identified by its ID (module name by default, or a custom string if configured via :id option).

This is a fire-and-forget operation — the caller does not wait for a response. If the AgentServer is not running, the message is silently dropped.

Use Cases

There are two primary use cases for this function:

1. External notifications (LiveViews, controllers, other processes)

Send context updates or configuration changes to a middleware from outside the agent system. The middleware decides how to handle the message — typically by updating state metadata that before_model/2 reads on the next LLM call.

# LiveView: user switched to editing a different blog post
AgentServer.notify_middleware(agent_id, MyApp.UserContext, {:post_changed, %{
  slug: "/blog/getting-started-with-elixir",
  title: "Getting Started with Elixir"
}})

# Controller: user changed a preference
AgentServer.notify_middleware(agent_id, MyApp.Preferences, {:preference_changed, :verbose, true})

2. Async task results (middleware sending messages to itself)

Middleware that spawns background tasks (e.g., title generation, embedding computation) uses this to send results back to the AgentServer for state updates.

# Inside an async task spawned by the middleware
AgentServer.notify_middleware(agent_id, middleware_id, {:title_generated, title})

Parameters

• agent_id - The agent identifier (used to locate the AgentServer process)
• middleware_id - The middleware ID to route the message to (module name or custom string)
• message - Any term to be delivered to the middleware's handle_message/3 callback

Returns

• :ok — always returns :ok, even if the AgentServer is not running

Examples

# Notify by module name (default middleware ID)
AgentServer.notify_middleware("conv-123", MyApp.Middleware.UserContext, {:post_changed, post})

# Notify by custom ID (when middleware was configured with `id: "english_title"`)
AgentServer.notify_middleware("conv-123", "english_title", {:regenerate, %{}})

@spec publish_debug_event_from(String.t(), term()) :: :ok

Request the AgentServer to publish a specific debug PubSub message or event.

Designed to make it easier for middleware to publish debug messages to the Agent's debug PubSub. Debug events are useful for development and debugging but separate from user-facing events.

A debug PubSub message is only broadcast if the AgentServer is configured with debug_pubsub.

Standardized Middleware Action Pattern

Middleware should use the :middleware_action tuple pattern to avoid event proliferation:

{:middleware_action, middleware_module, action_data}

Where:

• middleware_module - The middleware module (atom) that generated the event
• action_data - Middleware-specific action tuple or data

This pattern allows the debug UI to handle all middleware events generically without needing to know about every possible middleware-specific event type.

Examples

# From ConversationTitle middleware
AgentServer.publish_debug_event_from(
  agent_id,
  {:middleware_action, Sagents.Middleware.ConversationTitle, {:title_generation_started, user_text}}
)

AgentServer.publish_debug_event_from(
  agent_id,
  {:middleware_action, Sagents.Middleware.ConversationTitle, {:title_generation_completed, title}}
)

# From custom middleware
AgentServer.publish_debug_event_from(
  agent_id,
  {:middleware_action, MyApp.CustomMiddleware, {:validation_started, params}}
)

@spec publish_event_from(String.t(), term()) :: :ok

Request the AgentServer to publish an specific PubSub message or event.

Designed to make it easier for a middleware desiring to publish messages to the Agent's PubSub.

A PubSub message is only broadcast if the AgentServer is configured with PubSub.

@spec reset(String.t()) :: :ok

Reset the agent's state and filesystem to start fresh.

This clears:

• All messages
• All TODOs
• Middleware state
• Memory-only files (completely removed)
• In-memory modifications to persisted files (discarded)

This preserves:

• Metadata (configuration)
• Persisted files (reverted to pristine state from storage)

Status transitions:

• :completed, :error, or :cancelled → :idle (ready for new execution)
• Other statuses remain unchanged

Returns :ok on success.

Examples

# After agent completes or encounters error
:ok = AgentServer.reset("my-agent-1")
# Now you can execute again with clean state
:ok = AgentServer.execute("my-agent-1")

@spec restore_state(String.t(), map()) :: :ok | {:error, term()}

Restore agent state from a previously exported state.

This updates an already-running agent to restore its state from a previously serialized format. The state should be a map with string keys (as returned by export_state/1).

Returns :ok on success or {:error, reason} on failure.

Examples

# Load from database
{:ok, persisted_state} = MyApp.Conversations.load_agent_state(conversation_id)

# Restore into existing agent
:ok = AgentServer.restore_state("my-agent-1", persisted_state)

@spec resume(String.t(), term()) :: :ok | {:error, term()}

Resume agent execution after an interrupt.

Parameters

• agent_id - The agent identifier
• resume_data - Data to resume with (polymorphic per middleware). For HITL: list of decision maps. For AskUserQuestion: response map.

Examples

# HITL resume
decisions = [
  %{type: :approve},
  %{type: :edit, arguments: %{"path" => "safe.txt"}},
  %{type: :reject}
]
:ok = AgentServer.resume("my-agent-1", decisions)

# AskUserQuestion resume
:ok = AgentServer.resume("my-agent-1", %{type: :answer, selected: ["PostgreSQL"]})

Check if an agent is running.

@spec send_middleware_message(String.t(), term(), term()) :: :ok

Deprecated: Use notify_middleware/3 instead.

This is an alias for notify_middleware/3 retained for backwards compatibility.

Start an AgentServer.

Options

• :agent - The Agent struct (required)
• :initial_state - Initial State (default: empty state)
• :pubsub - PubSub configuration as {module(), atom()} tuple or nil to disable (default: nil) Example: {Phoenix.PubSub, :my_app_pubsub}
• :debug_pubsub - Optional separate PubSub for debug events as {module(), atom()} or nil (default: nil) Example: {Phoenix.PubSub, :my_debug_pubsub}
• :name - Server name registration (optional, defaults to get_name(agent.agent_id))
• :inactivity_timeout - Timeout in milliseconds for automatic shutdown due to inactivity (default: 300_000 - 5 minutes) Set to nil or :infinity to disable automatic shutdown
• :shutdown_delay - Delay in milliseconds to allow the supervisor to gracefully stop all children (default: 5000)
• :conversation_id - Optional conversation identifier for message persistence (default: nil)
• :agent_persistence - Module implementing Sagents.AgentPersistence for state snapshots (default: nil)
• :display_message_persistence - Module implementing Sagents.DisplayMessagePersistence for display messages (default: nil)

Examples

# Start with automatic name (recommended)
{:ok, pid} = AgentServer.start_link(
  agent: agent,
  initial_state: state
)

# With PubSub enabled
{:ok, pid} = AgentServer.start_link(
  agent: agent,
  initial_state: state,
  pubsub: {Phoenix.PubSub, :my_app_pubsub}
)

# Start with explicit name (advanced use cases)
{:ok, pid} = AgentServer.start_link(
  agent: agent,
  initial_state: state,
  name: :my_custom_name
)

# With custom inactivity timeout
{:ok, pid} = AgentServer.start_link(
  agent: agent,
  inactivity_timeout: 600_000  # 10 minutes
)

# Disable automatic shutdown
{:ok, pid} = AgentServer.start_link(
  agent: agent,
  inactivity_timeout: nil
)

# Enable debug pubsub
{:ok, pid} = AgentServer.start_link(
  agent: agent,
  pubsub: {Phoenix.PubSub, :my_app_pubsub},
  debug_pubsub: {Phoenix.PubSub, :my_debug_pubsub}
)

@spec start_link_from_state(
  map(),
  keyword()
) :: GenServer.on_start()

Start a new AgentServer with restored state.

This is the preferred way to resume a conversation from persisted state. The persisted_state should be a map with string keys (as returned by export_state/1).

The agent_id will be used as the runtime identifier for this agent, enabling process registration and PubSub topic setup. You can restore the same conversation state under a different agent_id, which is useful for state cloning or conversation forking.

Agent Configuration from Code

REQUIRED: You MUST provide the agent from your application code using the :agent option. The persisted state contains ONLY conversation state (messages, todos, metadata). Agent configuration (middleware, tools, model) comes from your application code.

This design ensures:

• Library upgrades automatically benefit all conversations
• Code changes automatically apply to all conversations
• Per-user capabilities can be controlled via application logic

Options

• :agent_id - The runtime identifier for this agent (required)
• :agent - Agent struct from code (REQUIRED)
• :pubsub - PubSub configuration as {module(), atom()} tuple or nil (default: nil)
• :debug_pubsub - Optional separate PubSub for debug events as {module(), atom()} or nil (default: nil)
• :name - Server name registration (optional, defaults to get_name(agent_id))
• :inactivity_timeout - Timeout in milliseconds (default: 300_000)
• :shutdown_delay - Delay in milliseconds (default: 5000)

Examples

# Standard restoration pattern
{:ok, persisted_state} = MyApp.Conversations.load_agent_state(conversation_id)

# Agent from code (ALWAYS required)
{:ok, agent} = MyApp.Agents.create_agent(
  agent_id: "my-agent-1",
  model: model,
  middleware: [TodoList, FileSystem, SubAgent]
)

# Start with restored state
{:ok, pid} = AgentServer.start_link_from_state(
  persisted_state,
  agent: agent,
  agent_id: "my-agent-1",
  pubsub: {Phoenix.PubSub, :my_app_pubsub}
)

# Clone conversation with a different agent_id
{:ok, pid} = AgentServer.start_link_from_state(
  persisted_state,
  agent: agent,
  agent_id: "my-agent-clone",
  pubsub: {Phoenix.PubSub, :my_app_pubsub}
)

@spec stop(String.t()) :: :ok

Stop the AgentServer.

Examples

:ok = AgentServer.stop("my-agent-1")

@spec subscribe(String.t()) :: :ok | {:error, term()}

Subscribe to events from this AgentServer.

The calling process will receive messages for all events broadcast by this server.

Returns :ok on success or {:error, reason} if PubSub is not configured.

Examples

AgentServer.subscribe("my-agent-1")

@spec subscribe_debug(String.t()) :: :ok | {:error, term()}

Subscribe to debug events from this AgentServer.

The calling process will receive messages for all debug events broadcast by this server. Debug events provide additional debugging insight into what the agent is doing, such as middleware state updates.

Returns :ok on success or {:error, reason} if debug PubSub is not configured.

Examples

AgentServer.subscribe_debug("my-agent-1")

@spec touch(String.t()) :: :ok

Touch the agent to indicate activity and reset the inactivity timer.

This is useful when external events indicate activity (e.g., user viewing the agent in the UI, clicking tabs, etc.) to keep the agent alive and prevent automatic shutdown due to inactivity.

Returns :ok immediately (non-blocking).

Examples

:ok = AgentServer.touch("my-agent-1")

@spec unsubscribe(String.t()) :: :ok | {:error, term()}

Unsubscribe from events from this AgentServer.

The calling process will stop receiving messages broadcast by this server.

Returns :ok on success or {:error, reason} if PubSub is not configured.

Examples

AgentServer.unsubscribe("my-agent-1")

@spec unsubscribe_debug(String.t()) :: :ok | {:error, term()}

Unsubscribe from debug events from this AgentServer.

The calling process will stop receiving debug messages broadcast by this server.

Returns :ok on success or {:error, reason} if debug PubSub is not configured.

Examples

AgentServer.unsubscribe_debug("my-agent-1")

Updates both the agent configuration and state.

This is the recommended way to restore a conversation:

1. Create agent from current code using your agent factory
2. Load state from database
3. Call this function to update the running AgentServer

Parameters

• agent_id - The agent server's identifier
• agent - The new agent configuration (from current code)
• state - The restored state (from database)

Examples

# Restore conversation
{:ok, agent} = MyApp.Agents.create_demo_agent(agent_id: "demo-123")
{:ok, state_data} = MyApp.Conversations.load_state(conversation_id)
{:ok, state} = Sagents.State.from_serialized(state_data["state"])

:ok = AgentServer.update_agent_and_state("demo-123", agent, state)

Returns

• :ok - Agent and state updated successfully
• {:error, reason} - If agent server is not running or update fails