adk-pixel-agents 0.6.0
Pixel art visualization for Google ADK agents — see your multi-agent workflows come alive!
Requires Python: >=3.10
Keywords: adk, agents, visualization, pixel-art, google-adk

# ADK Pixel Agents

Pixel art visualization for [Google ADK](https://github.com/google/adk-python) agents. See your multi-agent workflows come alive with animated pixel characters in an office environment!

## Features

- **One-line integration** -- just add `attach_visualizer(agent)`
- **Agent tree metadata** -- collects type, description, model, tools from your ADK agents
- **Tree-based layout** -- hierarchical visualization reflecting parent-child relationships
- **Office environment** -- desks, chairs, plants with agents that walk and interact
- **Agent-to-agent interactions** -- walking animations and document passing between agents
- **Supports all ADK agent types** -- LlmAgent, SequentialAgent, ParallelAgent, LoopAgent
- **Tree-aware document routing** -- documents flow correctly based on agent topology
- **Real-time call tracking** -- shows which agent triggered which via `triggered_by`
- **Role-based characters** -- distinct pixel art for Researcher, Writer, Coder, Reviewer
- **Custom sprites** -- bring your own pixel art via the sprites system
- **8-bit audio** -- chiptune sound effects via Web Audio API (muted by default)
- **Cloud Run ready** -- Dockerfile included for deployment

## Quick Start

```bash
pip install -e .
```

```python
from google.adk.agents import LlmAgent, SequentialAgent
from adk_pixel_agents import attach_visualizer

researcher = LlmAgent(
    name="Researcher",
    model="gemini-2.5-flash",
    description="Web search and information gathering specialist",
    instruction="...",
)
writer = LlmAgent(
    name="Writer",
    model="gemini-2.5-pro",
    description="Article writer and content creator",
    instruction="...",
)
team = SequentialAgent(
    name="Team",
    description="Sequential research and writing pipeline",
    sub_agents=[researcher, writer],
)

# One line to visualize!
viz = attach_visualizer(team, port=8080)

# Open http://localhost:8080 and type a query!
```

## Examples

Four examples are included to demonstrate different agent topologies:

### Basic (Sequential)

```bash
python examples/basic_example.py
```

Two agents in sequence: Researcher -> Writer.

### Parallel

```bash
python examples/parallel_example.py
```

Three analysts work in parallel, then an editor synthesizes their findings.

```
AnalysisPipeline (Sequential)
  +-- ResearchTeam (Parallel)
  |     +-- TechAnalyst
  |     +-- MarketAnalyst
  |     +-- SocialAnalyst
  +-- Editor
```

### Loop

```bash
python examples/loop_example.py
```

Coder and Reviewer iterate up to 3 times until code quality is satisfactory.

```
ReviewLoop (Loop, max_iterations=3)
  +-- Coder
  +-- Reviewer
```

### Complex (All combined)

```bash
python examples/complex_example.py
```

Full pipeline combining Sequential, Parallel, and Loop:

```
ContentPipeline (Sequential)
  +-- Researcher
  +-- CreationTeam (Parallel)
  |     +-- Writer
  |     +-- Designer
  +-- QualityLoop (Loop, max_iterations=2)
        +-- Editor
        +-- QAChecker
```

## Configuration

```python
viz = attach_visualizer(
    agent,
    port=8080,
    title="My Agent Team",      # Custom window title
    sprites={                    # Optional custom sprites
        "research": "/path/to/sprite.png",
        "writer": {
            "idle": "/path/to/idle.png",
            "active": "/path/to/active.png",
        },
    },
)
```

### Detaching

```python
from adk_pixel_agents import detach_visualizer
detach_visualizer(viz)
```

## What You See

### Agent Types

| Type | Badge | Visual |
|------|-------|--------|
| LlmAgent | `LLM` (teal) | Character at desk with monitor |
| SequentialAgent | `SEQ` (purple) | Dashed arrows between children |
| ParallelAgent | `PAR` (yellow) | Sync bar with flash effect |
| LoopAgent | `LOOP` (pink) | Return arc from last to first child |

### Office Environment

- Each LlmAgent gets a desk and chair placed nearby
- Decorative plants and water cooler
- Bookshelf with colorful books
- Whiteboard with sticky notes
- Coffee machine
- Night sky window in the background
- Floor tiles with ambient lighting

### Animations

- **Idle** -- breathing animation (4-frame spritesheet)
- **Walking** -- directional walk cycle (6-frame spritesheet, 4 directions)
- **Active** -- faster motion with glow
- **Thinking** -- spinning dots
- **Working** -- walk to desk, 4-frame walk cycle
- **Done** -- celebration jump + sparkles + document flies to next agent
- **Walking** -- agents walk toward each other during delegation
- **Document passing** -- paper arcs between agents on task completion

### Agent Interactions

- When an agent triggers a child, the parent walks partway toward the child
- When an agent completes, a document flies to the appropriate next agent:
  - **Sequential**: next sibling
  - **Parallel**: back to parent
  - **Loop**: last child loops back to first child
- Active connections glow brighter with pulsing dots
- Hover over any agent to see metadata panel (description, model, tools, state)

## Docker / Cloud Run

### Local Docker

```bash
docker build -t adk-pixel-agents .
docker run -p 8080:8080 -e GOOGLE_API_KEY=your-key adk-pixel-agents
```

### Cloud Run

```bash
gcloud builds submit --tag gcr.io/PROJECT_ID/adk-pixel-agents
gcloud run deploy adk-pixel-agents \
    --image gcr.io/PROJECT_ID/adk-pixel-agents \
    --port 8080 \
    --set-env-vars GOOGLE_API_KEY=your-key \
    --allow-unauthenticated
```

Health check endpoint: `GET /health`

## Architecture

```
attach_visualizer(agent)
    |-- Collects agent tree metadata (type, description, model, tools)
    |-- Walks agent tree, attaches lifecycle callbacks
    |-- Tracks call chain with triggered_by / parent_agent info
    |-- Starts FastAPI + WebSocket server (background thread)
    +-- Serves office environment frontend (single HTML file)

Agent runs -> callbacks fire -> WebSocket -> browser animates
```

## Roadmap

- [x] Agent tree metadata collection
- [x] Tree-based hierarchical layout
- [x] Office environment with furniture
- [x] Walking animations and document passing
- [x] Agent call chain tracking (triggered_by)
- [x] Tree-aware document routing
- [x] ParallelAgent / LoopAgent visual support
- [x] State-based sprite switching (idle/walk with spritesheets)
- [x] Spritesheet-based walk animation (6 frames, 4 directions)
- [x] Breathing idle animation
- [x] New office furniture (bookshelf, whiteboard, coffee machine)
- [x] PyPI publishing ready (LICENSE, tests, CHANGELOG)
- [ ] Timeline view (Gantt chart of agent execution)
- [ ] Click-to-inspect detail panel
- [ ] Transfer-to-agent event capture
- [ ] Theme system (light/dark/retro)

## License

Apache License 2.0 — see [LICENSE](LICENSE) for details.