Sagents Live Debugger

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.

Features

Installation

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

def deps do
  [
    {:sagents_live_debugger, "~> 0.4.0-rc"}
  ]
end

Note: the 0.4.0-rc.x line depends on sagents 0.8.0-rc.x and introduces a required :pubsub router option (see Setup). The 0.3.x line tracks the previous sagents dependency.

Setup

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,
    pubsub: MyApp.PubSub,
    presence_module: MyAppWeb.Presence
end

The :pubsub option is the Phoenix.PubSub instance your application uses to broadcast agent and presence events — the same name you give your Phoenix.PubSub child spec in your supervision tree (typically MyApp.PubSub). The debugger subscribes to agent presence and per-conversation viewer topics on this PubSub.

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!

AgentsDemo example application showing active TODO items

Configuration Options

The sagents_live_debugger macro accepts the following options:

Required

Optional

Example with All Options

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

Content Security Policy

If your host application enforces a strict CSP that disallows inline/unsafe sources, pass :csp_nonce_assign_key so the debugger can stamp the correct nonce onto the bundled <link rel="stylesheet"> and <script> tags it emits in the root layout.

The option accepts either a single atom (used as the nonce for both style and script tags) or a map with :script and :style keys when you want to use distinct nonces per directive:

# Single nonce for both style and script
sagents_live_debugger "/debug/agents",
  coordinator: AgentsDemo.Agents.Coordinator,
  pubsub: AgentsDemo.PubSub,
  presence_module: AgentsDemoWeb.Presence,
  csp_nonce_assign_key: :csp_nonce

# Distinct nonces per directive
sagents_live_debugger "/debug/agents",
  csp_nonce_assign_key: %{
    style: :style_src_nonce,
    script: :script_src_nonce
  },
  coordinator: AgentsDemo.Agents.Coordinator,
  pubsub: AgentsDemo.PubSub,
  presence_module: AgentsDemoWeb.Presence

Your browser pipeline (or a plug earlier in the stack) is responsible for generating the nonce values and placing them on conn.assigns under the keys you supply — the debugger only reads them:

# Example plug in your browser pipeline
defmodule MyAppWeb.CSPNonce do
  import Plug.Conn

  def init(_), do: nil

  def call(conn, _) do
    conn
    |> assign(:style_src_nonce, generate_nonce())
    |> assign(:script_src_nonce, generate_nonce())
    |> put_resp_header("content-security-policy",
      "style-src &#39;nonce-#{conn.assigns.style_src_nonce}&#39;; " <>
      "script-src &#39;nonce-#{conn.assigns.script_src_nonce}&#39;")
  end

  defp generate_nonce, do: 18 |> :crypto.strong_rand_bytes() |> Base.url_encode64(padding: false)
end

The debugger serves its CSS and JS from cache-busted Plug routes (/css-<md5> and /js-<md5>), so with nonces wired through there are no inline assets to whitelist separately.

Key Features

Presence-Based Agent Discovery

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:

Presence detection reveals agents immediately

Auto-Follow First

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.

Agent Messages

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.

Agent messages showing system prompt and conversation history

Middleware Config

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.

Middleware configuration showing composable agent capabilities

Tool Insights

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

Tool configuration and instructions overview

Event Stream

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.

Live event stream showing agent activity

Sub-Agents Tab

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

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.

Sub-Agent Config

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.

Sub-agent config showing instructions and response

Sub-Agent Messages

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.

Sub-agent multi-turn message history

Sub-Agent Tools

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

Sub-agent available tools

Architecture Notes

Plugin Design

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

Event-Driven Architecture

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

Debug Event Flow

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

Browser Compatibility

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

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

Environment Configuration

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

Setting Default Description
auto_follow_defaulttrue Auto-follow first agent that appears

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.

License

Apache-2.0 license - see LICENSE for details.