[Feature Proposal]: adk graph - Visual Agent Inspector, Bi-directional Code Generator, & Live Debugger

[yuvaraj-97]

Summary

As agentic workflows scale, inspecting and debugging multi-agent delegation topology (SequentialAgent, ParallelAgent, LoopAgent, tools, memory) via terminal logs or raw Python code becomes challenging.

We propose adding a built-in CLI tool adk graph (and Web UI interface) that provides:

1. Reverse Inspection / AST Parser (Python → Graph): Reads existing ADK Python agent files and renders their multi-agent topology visually.
2. Visual Builder & Code Generator (Graph → Python): Drag-and-drop agent visual editor (integrating concepts from ADKGraph).
3. Live Execution & Debugging Visualizer: Highlights active agents and tools on the visual graph in real time as events stream over SSE/WebSockets during runner execution.

---

User Experience / Proposed CLI

# 1. Inspect & debug an existing agent script
adk graph path/to/agent.py

# 2. Launch the visual agent editor to construct a new agent system
adk graph --new

When run, adk graph will:

1. Spin up a lightweight local inspection server.
2. Open an interactive web UI in the browser showing the agent topology.
3. Allow real-time step execution with visual active-node highlighting.

---

Key Features

• Bi-directional Editing: Changes made in code update the graph visual; canvas edits compile directly back to production-ready adk-python code.
• Hierarchical Orchestrator Containers: Support nested visual group containers for SequentialAgent, ParallelAgent, and LoopAgent.
• Live Event Debugger: Visual node glow/state animation during active agent execution, tool calls, and LLM reasoning steps.

---

Proposed Architectural Changes

• CLI extension: Add graph subcommand in google.adk.cli.
• Inspector engine (google.adk.cli.graph): Dynamic agent object visitor & Python AST static analysis module.
• Web UI bundle: Embedded lightweight React visual canvas server.

---

Additional Context

This proposal is based on the open-source ADKGraph visual IDE built specifically for Google ADK. We are willing to contribute and maintain this feature via a Pull Request.

Is this feature aligned with the ADK roadmap? We welcome maintainer feedback before submitting our PR implementation!

[SHAI-shivansh-sharma]

Hi @sanketpatil06 and @yuvaraj-97 , I’m also interested in contributing to this feature. To avoid duplicating work, I’d be happy to take ownership of a focused part of the implementation — particularly the graph representation + Python/AST inspection layer and its unit/integration tests.

I’d like to build it with comprehensive coverage for nested SequentialAgent, ParallelAgent, LoopAgent, tools, invalid/unsupported source patterns, deterministic graph serialization, and round-trip behavior where applicable.

If you’re already working on a particular architecture, I’m happy to coordinate and take a separate sub-part.

[yuvaraj-97]

Hi @sanketpatil06, thank you for reaching out and offering to help! I wanted to clarify that I have already completed the full implementation and changes locally, so I will be handling the PR submission for this feature directly. I appreciate your interest, but I will be managing this effort independently. I'll unassign this issue for now. Thanks!

[yuvaraj-97]

Self-assignment update: I am taking ownership of this issue as the author and lead implementer.

[yuvaraj-97]

Pull request has been created: #6825

[sanketpatil06]

Hi @yuvaraj-97 , Thanks for bringing this and taking time to raise a PR. Your request is currently being reviewed, and we will let you know if anything further is needed. We appreciate your contribution.