google / google/adk-python

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

Open
#6,817 5 comments 0 reactions 1 assignee Claimed by @sanketpatil06 View on GitHub
needs review tools
Dominant language
Python
Stars
21.5k
Forks
4k
Avg merge
1d 14h
Merged PRs (30d)
37

Description

### 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](https://github.com/yuvaraj-97/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

```bash
# 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](https://github.com/yuvaraj-97/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!

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.