ADK Pixel Agents

Pixel art visualization for Google ADK 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

pip install -e .

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)

python examples/basic_example.py

Two agents in sequence: Researcher -> Writer.

Parallel

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

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)

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

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

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

docker build -t adk-pixel-agents .
docker run -p 8080:8080 -e GOOGLE_API_KEY=your-key adk-pixel-agents

Cloud Run

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

• Agent tree metadata collection
• Tree-based hierarchical layout
• Office environment with furniture
• Walking animations and document passing
• Agent call chain tracking (triggered_by)
• Tree-aware document routing
• ParallelAgent / LoopAgent visual support
• State-based sprite switching (idle/walk with spritesheets)
• Spritesheet-based walk animation (6 frames, 4 directions)
• Breathing idle animation
• New office furniture (bookshelf, whiteboard, coffee machine)
• 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 for details.