A Phoenix LiveView dashboard for debugging and monitoring Sagents agents in real-time. Provides visibility into agent execution, message history, tool calls, middleware actions, todos, sub-agents, and event streams.

• Real-time Agent Monitoring: View all running agents with status, uptime, and viewer counts
• Presence-Based Discovery: Agents are discovered instantly via Phoenix Presence (no polling)
• Auto-Follow First: Automatically follow the first matching agent that appears for immediate debugging
• Sub-Agent Visibility: Monitor sub-agents spawned by parent agents with full event tracking
• Message Inspection: Browse complete message history with tool calls, results, and thinking blocks
• Event Stream: Live feed of agent events (LLM calls, middleware actions, tool executions)
• Todo Tracking: Monitor agent task lists and progress in real-time
• Production Safe: Filter-based agent selection for production environments

Add sagents_live_debugger to your list of dependencies in mix.exs:

def deps do
  [
    {:sagents_live_debugger, "~> 0.3.0"}
  ]
end

Add the debugger to your Phoenix router:

# lib/my_app_web/router.ex
import SagentsLiveDebugger.Router

scope "/dev" do
  pipe_through :browser

  sagents_live_debugger "/debug/agents",
    coordinator: MyApp.Agents.Coordinator,
    presence_module: MyAppWeb.Presence
end

Important: Ensure your application has configured the timezone database in config/config.exs:

# config/config.exs
import Config

# Required for timezone support
config :elixir, :time_zone_database, Tzdata.TimeZoneDatabase

That's it! Visit http://localhost:4000/dev/debug/agents to access the debugger.

Try it out yourself in the AgentsDemo project. It's built-in and ready to explore!

The sagents_live_debugger macro accepts the following options:

• :coordinator - Your application's agent coordinator module (created through a mix task)

• :presence_module - Phoenix Presence module for real-time agent discovery and viewer tracking

sagents_live_debugger "/debug/agents",
  coordinator: MyApp.Agents.Coordinator,
  presence_module: MyApp.Presence

The debugger discovers agents in real-time using Phoenix Presence. When an agent starts with presence_module configured, it immediately appears in the debugger's agent list - no polling required.

Configure your AgentServer with presence:

AgentServer.start_link(
  agent: agent,
  pubsub: {Phoenix.PubSub, :my_pubsub},
  presence_module: MyApp.Presence
)

Agent presence metadata includes:

• status - Current agent status (:idle, :running, :interrupted, etc.)
• started_at - When the agent started (for uptime display)
• last_activity_at - Last activity timestamp
• conversation_id - Associated conversation (if any)
• Custom scope fields from filesystem_scope (e.g., project_id, user_id)

In development mode, the debugger automatically follows the first agent that appears. This eliminates the need for manual agent selection during local development.

Toggle auto-follow using the checkbox in the header, or configure the default in your application's config:

# To disable auto-follow by default (e.g., in production)
config :sagents_live_debugger,
  auto_follow_default: false

Note: The library defaults to dev-friendly settings (auto-follow on). You only need to add config to change this default.

Get insights into the message exchange from the perspective of the agent. Middleware is used to build the system prompt for your agent. See exactly how the agent is configured quickly and easily. Browse the complete message history including tool calls, tool results, and thinking blocks.

A significant feature of Sagents is how middleware makes an agent's abilities composable and powerful. See the middleware your agent was configured with and explore the configured settings for each middleware.

Tools are the way agents get things done. See all the tools, their configuration, and instructions to the agent revealed in one easy location.

When working with agents, being able to see the stream of events they are receiving and emitting is incredibly valuable. The SagentsLiveDebugger subscribes to the additional and optional debug event stream to give even greater insights into what's happening with your agent.

When an agent spawns sub-agents (via the Task tool), they appear in the Sub-Agents tab with full visibility:

• Lifecycle Events: Started, status changes, completion, errors
• Real-time Streaming: See LLM responses as they stream
• Configuration View: Instructions, tools, middleware, model
• Messages View: Complete conversation history
• Duration Tracking: Execution time for each sub-agent

Sub-agent events are automatically broadcast through the parent agent's debug topic, requiring no additional configuration.

Getting insight into sub-agents is critically important. Sub-agents are launched by the main agent when it determines they are needed. They receive their instructions from the main agent and return their response back to the main agent. This visibility into sub-agents helps you confirm the system is working as expected, or reveals issues where something isn't configured correctly.

See what instructions a sub-agent received from the main agent and what its response was. This reveals the full picture of the delegation: what was asked and what was returned.

View the multi-turn conversation a sub-agent has as it uses tools and works towards an answer for its task. Follow the sub-agent's reasoning step by step.

See the tools a sub-agent has access to in order to do its work.

The debugger is designed as a self-contained plugin library:

• No JavaScript files to compile or bundle
• All CSS is inlined in the layout
• All JavaScript is inlined for timezone detection
• Zero configuration beyond adding to router

The debugger is entirely event-driven (no polling):

• Agent List: Built from presence metadata, updates via presence_diff events
• Agent Detail: Real-time updates via PubSub subscriptions
  • status_changed - Status updates
  • todos_updated - Todo list changes
  • llm_message - New messages
  • {:subagent, id, event} - Sub-agent events
• Sub-Agents: Events broadcast through parent agent's debug topic

AgentServer                    Debugger (LiveView)
    |                               |
    |-- presence track ------------>|  Agent appears in list
    |                               |
    |-- {:debug, event} ----------->|  Debug events stream
    |                               |
    |                               |
SubAgentServer                      |
    |                               |
    |-- via parent.publish_debug -->|  Sub-agent events
    |                               |

Automatic timezone detection for the event display uses Intl.DateTimeFormat().resolvedOptions().timeZone, which is supported in:

• Chrome/Edge 24+
• Firefox 52+
• Safari 10+

Older browsers will gracefully fall back to displaying timestamps in UTC.

The debugger uses dev-friendly defaults out of the box. For production deployments, add configuration to your application's config files:

Example production configuration:

# config/prod.exs in YOUR application (not the library)
config :sagents_live_debugger,
  auto_follow_default: false

With production settings, users must manually select agents to follow.

Apache-2.0 license - see LICENSE for details.