feat(beta): set up a debug server to visualize memory streams

[jsun-m]

Summary

• Decoupled debugger from agent core: Removed all debug logic (AG2_DEBUG_SERVER_URL check, session creation, attach/close) from Agent.ask(). The debugger is now a standalone middleware users pass explicitly via middleware=[DebugMiddleware].
• Middleware-driven event recording: DebugMiddleware intercepts events through middleware hooks (on_turn, on_llm_call, on_tool_execution) instead of subscribing to the stream. This fixes event ordering issues where the user's message appeared after the reply.
• Auto-session support: When AG2_DEBUG_SERVER_URL is set, DebugMiddleware auto-creates a DebugSession and closes it after the turn. Without the env var (and no pre-existing session), it's a silent pass-through.
• Lazy stream registration: DebugSession._ensure_stream() registers new streams with the server on first event, correctly handling multi-agent sessions that span multiple streams.
• Import guards: autogen.beta.debug.__init__ wraps imports in try/except ImportError with helpful messages pointing to pip install "ag2[beta-debug]".
• importlib.resources: Replaced Path(__file__).parent / "ui.html" with importlib.resources.files() for proper package data access.

Usage

Quick start (env var)

import os
os.environ["AG2_DEBUG_SERVER_URL"] = "http://localhost:8765"

from autogen.beta.debug import DebugMiddleware

reply = await agent.ask("Hello", middleware=[DebugMiddleware])

Explicit session (multi-call)

from autogen.beta.debug import DebugMiddleware, DebugSession

async with DebugSession(name="my-run") as session:
    # session is stored in context variables automatically
    await agent.ask("Hello", middleware=[DebugMiddleware])
    await agent.ask("Follow up", middleware=[DebugMiddleware])

[Lancetnik]

@jsun-m it's great initiative! But, what to you think about smth simpler? Like regular https://docs.python.org/3/library/pdb.html integration

It seems like we can just introduce interceptors for all stream events?

stream = MemoryStream()

@stream.subscriber(intercept=True)
async def debug_subscriber(event):
    breakpoint()
    return event

agent = Agent(...)

await agent.ask(..., stream=stream)

[jsun-m]

breakpoint()

hey nikita, I think i want less on the breakpointing and more and the visualization of the memory state. I remove breakpointing for now.

[jsun-m]

this is non-critical for a locally running server

[Lancetnik]

Prefer https://docs.python.org/3/library/importlib.resources.html for libraries

[jsun-m]

take another look

[jsun-m]

@Lancetnik addressed feedback. removed changes to agent.py
Added examples in the description and I will follow up with a PR to add a doc page for this

[codecov]

Codecov Report

❌ Patch coverage is 93.41317% with 22 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
autogen/beta/debug/__init__.py	56.00%	11 Missing ⚠️
autogen/beta/debug/server.py	95.30%	5 Missing and 2 partials ⚠️
autogen/beta/debug/__main__.py	81.81%	1 Missing and 1 partial ⚠️
autogen/beta/debug/session.py	95.55%	1 Missing and 1 partial ⚠️

Files with missing lines	Coverage Δ
autogen/beta/debug/client.py	100.00% <100.00%> (ø)
autogen/beta/debug/middleware.py	100.00% <100.00%> (ø)
autogen/beta/debug/models.py	100.00% <100.00%> (ø)
autogen/beta/debug/__main__.py	81.81% <81.81%> (ø)
autogen/beta/debug/session.py	95.55% <95.55%> (ø)
autogen/beta/debug/server.py	95.30% <95.30%> (ø)
autogen/beta/debug/__init__.py	56.00% <56.00%> (ø)

... and 13 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Lancetnik]

Hi @jsun-m — this PR now has merge conflicts with main and has been moved to status:changes-requested.

Please rebase onto the current main and resolve the conflicts. Once you push the updated branch, the PR will return to the review queue automatically.

⏳ If there's no update within 30 days, this PR will be marked stale and closed 7 days after that.