adk-pixel-agents

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

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.