# Agent Lifecycle Management
This document covers how agent processes are started, managed, and terminated.
## Process Lifecycle
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Created │──▶│ Running │──▶│ Shutdown │
└─────────────┘ └──────┬──────┘ └─────────────┘
│
▼
┌─────────────┐
│ Interrupted │
└─────────────┘
```
### States
| State | Description |
|-------|-------------|
| `:idle` | Agent is ready, not executing |
| `:running` | Agent is executing (LLM call or tools) |
| `:interrupted` | Waiting for human approval |
| `:cancelled` | Execution was cancelled by user |
| `:error` | Execution failed |
## Starting an Agent
### Basic Start
```elixir
alias Sagents.{Agent, AgentServer, State}
# Create agent configuration
{:ok, agent} = Agent.new(%{
agent_id: "my-agent",
model: model,
middleware: [TodoList, FileSystem]
})
# Create initial state
state = State.new!(%{
messages: [Message.new_user!("Hello")]
})
# Start the AgentServer
{:ok, pid} = AgentServer.start_link(
agent: agent,
initial_state: state,
# `:pubsub` is optional — only used to wire `Phoenix.Presence`
# `presence_diff` broadcasts. Per-agent events are delivered
# directly to subscriber pids via `Sagents.Publisher` regardless.
pubsub: {Phoenix.PubSub, :my_pubsub}
)
```
### Start with Options
```elixir
{:ok, pid} = AgentServer.start_link(
agent: agent,
initial_state: state,
pubsub: {Phoenix.PubSub, :my_pubsub},
# Lifecycle options
inactivity_timeout: 3_600_000, # 1 hour (default: 5 minutes)
# Presence tracking
presence_tracking: [
enabled: true,
presence_module: MyApp.Presence,
topic: "conversation:123"
],
# Auto-save
auto_save: [
callback: &MyApp.save_agent_state/2,
interval: 30_000 # Every 30 seconds
],
# Message persistence
conversation_id: conversation_id,
save_new_message_fn: fn conv_id, message ->
MyApp.Conversations.save_message(conv_id, message)
end
)
```
### Start from Persisted State
The generated Coordinator delegates to `Sagents.Session.start/3`, which
handles the full restore pipeline (router → factory → state load → supervisor):
```elixir
{:ok, session} =
MyApp.Agents.Coordinator.start_conversation_session(conversation_id,
scope: scope,
request_opts: [timezone: "America/Denver"]
)
```
If you need the raw building blocks (e.g. for tests or non-conversation
agents), the contract is:
```elixir
# Load saved state via your AgentPersistence module
{:ok, state} =
Sagents.State.load_or_new(MyApp.AgentPersistence, scope,
%{agent_id: "conv-#{conversation_id}", conversation_id: conversation_id})
# Build %FactoryConfig{} (typically via your Router) and call the factory
{:ok, agent, _session_opts} =
MyApp.AgentFactory.create_agent("conv-#{conversation_id}", factory_config)
# Start with restored state
{:ok, pid} = AgentServer.start_link(
agent: agent,
initial_state: state,
pubsub: {Phoenix.PubSub, :my_pubsub}
)
```
## Inactivity Timeout
Agents automatically shut down after a period of inactivity to free resources.
### Configuration
```elixir
# Default: 5 minutes (300_000 ms)
AgentServer.start_link(
agent: agent,
inactivity_timeout: 300_000
)
# Custom: 1 hour
AgentServer.start_link(
agent: agent,
inactivity_timeout: 3_600_000
)
# Disable timeout (agent runs forever)
AgentServer.start_link(
agent: agent,
inactivity_timeout: nil # or :infinity
)
```
### How It Works
1. Timer resets on any activity:
- Message added
- Execution started
- Resume from interrupt
- State accessed
2. When timer expires:
- Agent saves state (if auto-save configured)
- Broadcasts `{:agent_shutdown, %{reason: :inactivity}}`
- Process terminates normally
3. Clients handle shutdown:
```elixir
def handle_info({:agent, {:agent_shutdown, metadata}}, socket) do
case metadata.reason do
:inactivity ->
# Agent timed out, can restart on next user action
{:noreply, assign(socket, agent_status: :inactive)}
:no_viewers ->
# All viewers left after completion
{:noreply, assign(socket, agent_status: :inactive)}
:manual ->
# Explicitly stopped
{:noreply, assign(socket, agent_status: :stopped)}
end
end
```
## Presence-Based Shutdown
With Phoenix.Presence, agents know when clients are viewing them and can shut down intelligently.
### Setup
1. Create a Presence module:
```elixir
defmodule MyApp.Presence do
use Phoenix.Presence,
otp_app: :my_app,
pubsub_server: MyApp.PubSub
end
```
2. Configure agent with presence tracking:
```elixir
{:ok, pid} = AgentServer.start_link(
agent: agent,
presence_tracking: [
enabled: true,
presence_module: MyApp.Presence,
topic: "conversation:#{conversation_id}"
]
)
```
3. Track presence in LiveView:
```elixir
def mount(%{"id" => id}, _session, socket) do
if connected?(socket) do
# Track this viewer
{:ok, _} = MyApp.Presence.track(
self(),
"conversation:#{id}",
socket.assigns.current_user.id,
%{joined_at: DateTime.utc_now()}
)
end
{:ok, socket}
end
```
### Behavior
| Agent State | Viewers | Action |
|-------------|---------|--------|
| `:running` | Any | Keep running |
| `:idle` | > 0 | Keep running |
| `:idle` | 0 | Start grace period, then shutdown |
| `:interrupted` | Any | Keep running (waiting for approval) |
When an agent completes (`:idle`) and no viewers are present:
1. Broadcasts `{:agent_shutdown, %{reason: :no_viewers}}`
2. Saves state (if configured)
3. Terminates
### Grace Period
To avoid race conditions (viewer refreshing page), there's a short grace period:
```elixir
presence_tracking: [
enabled: true,
presence_module: MyApp.Presence,
topic: "conversation:123",
grace_period: 5_000 # 5 seconds (default)
]
```
## Manual Shutdown
### Stop an Agent
```elixir
# Graceful stop (saves state if configured)
AgentServer.stop("my-agent")
# Stop with custom reason
AgentServer.stop("my-agent", :custom_reason)
```
### Cancel Execution
```elixir
# Cancel current execution (if running)
AgentServer.cancel("my-agent")
# Broadcasts {:status_changed, :cancelled, nil}
```
## State Export and Import
### Export Current State
```elixir
# Get current state for persistence
state = AgentServer.export_state("my-agent")
# Save to database
MyApp.Conversations.save_agent_state(conversation_id, state)
```
### Auto-Save
Configure automatic state saving:
```elixir
AgentServer.start_link(
agent: agent,
auto_save: [
# Called periodically and on shutdown
callback: fn agent_id, state ->
MyApp.Conversations.save_agent_state(agent_id, state)
end,
# Save interval (default: 60 seconds)
interval: 30_000,
# Also save after execution completes
on_idle: true # default: true
]
)
```
Auto-save triggers:
- Every `interval` milliseconds (if changed since last save)
- When execution completes (`:idle`)
- Before shutdown
## Supervision
### Default Supervision Tree
```
AgentsSupervisor (DynamicSupervisor)
│
└── AgentSupervisor ("my-agent")
├── FileSystemServer
├── AgentServer
└── SubAgentsDynamicSupervisor
```
### Restart Strategy
By default, if AgentServer crashes:
1. Supervisor restarts it
2. In-memory state is lost
3. Must restore from persisted state
To customize:
```elixir
# In your application supervisor
children = [
{Sagents.AgentsSupervisor, restart_strategy: :one_for_one}
]
```
### Isolated Failures
Each agent has its own supervisor, so:
- One agent crashing doesn't affect others
- SubAgent crashes don't crash the parent
- FileSystemServer crash restarts just that component
## Coordinator Pattern
For applications managing many conversations, the session-start lifecycle
(idempotent start, router consult, factory invocation, state seeding,
supervisor config, subscriber wiring) lives in `Sagents.Session`. The
generated `Coordinator` is a thin per-app bridge that declares config
and exposes user-editable customization slots:
```elixir
defmodule MyApp.Agents.Coordinator do
@config %{
factory_router: MyApp.Agents.FactoryRouter,
agent_persistence: MyApp.Agents.AgentPersistence,
display_message_persistence: MyApp.Agents.DisplayMessagePersistence,
pubsub: {Phoenix.PubSub, MyApp.PubSub},
presence_module: MyAppWeb.Presence,
inactivity_timeout: :timer.minutes(60),
agent_id_fun: &__MODULE__.conversation_agent_id/1
}
def start_conversation_session(conversation_id, opts \\ []),
do: Sagents.Session.start(@config, conversation_id, opts)
def ensure_agent_session_running(state, request_opts \\ []),
do: Sagents.Session.ensure_running(@config, state, request_opts: request_opts)
def conversation_agent_id(conversation_id),
do: "conversation-#{conversation_id}"
end
```
Run `mix sagents.setup` to generate the Coordinator along with its paired
`Factory` + `FactoryConfig` + `FactoryRouter`. See `Sagents.FactoryRouter`
for routing among multiple factories.
Usage in LiveView:
```elixir
def mount(%{"id" => conversation_id}, _session, socket) do
# Load path: subscribe whether or not the agent is running.
# Sagents.Subscriber records :pending entries and auto-upgrades
# to :subscribed via presence_diff once the agent appears.
subs =
Sagents.Subscriber.subscribe_to_agent(
%{},
Coordinator.conversation_agent_id(conversation_id)
)
{:ok, assign(socket, conversation_id: conversation_id, sagents_subs: subs)}
end
# Action path: when the user actually triggers work, ensure the agent
# is running and the LiveView is subscribed (atomically, via
# initial_subscribers, to avoid the boot-broadcast race).
def handle_event("send_message", %{"text" => text}, socket) do
case Coordinator.ensure_agent_session_running(socket.assigns,
timezone: socket.assigns.timezone
) do
{:ok, changes} ->
socket = assign(socket, changes)
AgentServer.add_message(socket.assigns.agent_id, Message.new_user!(text))
{:noreply, socket}
{:error, reason} ->
{:noreply, put_flash(socket, :error, inspect(reason))}
end
end
```
## Health Checks
### Check Agent Status
```elixir
# Get current status
AgentServer.get_status("my-agent")
# => :idle | :running | :interrupted | :error
# Get detailed info
AgentServer.agent_info("my-agent")
# => %{
# agent_id: "my-agent",
# pid: #PID<0.1234.0>,
# status: :idle,
# message_count: 5,
# has_interrupt: false,
# uptime_ms: 123456
# }
```
### List Running Agents
```elixir
# All running agents
AgentServer.list_running_agents()
# => ["conversation-1", "conversation-2", "user-42"]
# Count
AgentServer.agent_count()
# => 3
# Pattern matching
AgentServer.list_agents_matching("conversation-*")
# => ["conversation-1", "conversation-2"]
```
## Telemetry
Sagents emits telemetry events for monitoring:
```elixir
# Agent lifecycle
[:sagents, :agent, :start]
[:sagents, :agent, :stop]
[:sagents, :agent, :crash]
# Execution
[:sagents, :execution, :start]
[:sagents, :execution, :stop]
[:sagents, :execution, :interrupt]
# LLM calls
[:sagents, :llm, :request]
[:sagents, :llm, :response]
[:sagents, :llm, :error]
```
Attach handlers:
```elixir
:telemetry.attach_many(
"my-handler",
[
[:sagents, :agent, :start],
[:sagents, :agent, :stop],
[:sagents, :execution, :stop]
],
&MyApp.Telemetry.handle_event/4,
nil
)
```