Visual debugger for multi-agent systems built on Google's A2A protocol

A2A Trace intercepts and visualizes Agent-to-Agent (A2A) protocol communications, helping you debug complex multi-agent systems with ease.

• 🚀 One-command setup - Just prefix your command with a2a-trace --
• 📊 Real-time visualization - Watch agent interactions as they happen
• 🔍 Message inspection - Drill down into request/response payloads
• 🤖 Agent discovery - Automatically detect and display agent info
• ⚡ Insights & analysis - Detect slow responses, errors, and retry loops
• 📦 Single binary - No dependencies, works everywhere
• 🌐 Language agnostic - Works with any A2A agent implementation

go install github.com/harry-kp/a2a-trace/cmd/a2a-trace@latest

brew install harry-kp/tap/a2a-trace

Download from Releases:

# macOS (Apple Silicon)
curl -L https://github.com/harry-kp/a2a-trace/releases/latest/download/a2a-trace-darwin-arm64.tar.gz | tar xz
sudo mv a2a-trace-darwin-arm64 /usr/local/bin/a2a-trace

# Linux (x86_64)
curl -L https://github.com/harry-kp/a2a-trace/releases/latest/download/a2a-trace-linux-amd64.tar.gz | tar xz
sudo mv a2a-trace-linux-amd64 /usr/local/bin/a2a-trace

Wrap your A2A agent command with a2a-trace --:

# Node.js agent
a2a-trace -- node my-agent.js

# Python agent
a2a-trace -- python agent.py

# Go agent
a2a-trace -- ./my-go-agent

# With custom port
a2a-trace --port 9000 -- npm start

Then open http://localhost:8080/ui in your browser to see the trace UI.

┌──────────────────────────────────────────────────────────────────┐
│                                                                  │
│   $ a2a-trace -- node my-agent.js                                │
│                                                                  │
│   ┌─────────────┐      ┌─────────────┐      ┌─────────────┐     │
│   │   Your      │      │  A2A Trace  │      │  External   │     │
│   │   Agent     │─────▶│   (proxy)   │─────▶│   Agents    │     │
│   │             │◀─────│             │◀─────│             │     │
│   └─────────────┘      └──────┬──────┘      └─────────────┘     │
│                               │                                  │
│                               ▼                                  │
│                        ┌─────────────┐                          │
│                        │  Browser UI │                          │
│                        │ (real-time) │                          │
│                        └─────────────┘                          │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

1. A2A Trace spawns your agent as a child process
2. Sets HTTP_PROXY environment variable automatically
3. All A2A HTTP traffic flows through the trace proxy
4. Messages are logged to SQLite and broadcast via WebSocket
5. The web UI displays everything in real-time

Usage:
  a2a-trace [flags] -- <command> [args...]

Flags:
  -p, --port int      Proxy port (default 8080)
      --ui-port int   UI port (default: same as proxy)
      --db string     SQLite database path (default: in-memory)
  -v, --verbose       Verbose output
      --no-ui         Don't serve the web UI
  -h, --help          Help for a2a-trace
      --version       Version info

# Basic usage
a2a-trace -- node agent.js

# Custom proxy port
a2a-trace --port 9000 -- python agent.py

# Persist traces to file
a2a-trace --db ./traces.db -- ./agent

# Verbose mode (see all requests in terminal)
a2a-trace --verbose -- npm run agent

# Without UI (CLI only)
a2a-trace --no-ui -- ./agent

A realistic enterprise workflow with 4 agents processing expense reports:

# Start the agent network
cd examples/expense_workflow && ./run_demo.sh

# In another terminal - trace the workflow
./bin/a2a-trace -- python3 examples/expense_workflow/run_client.py

Open http://localhost:8080/ui to see 13+ request/response pairs across:

• Receipt Analyzer - OCR and data extraction
• Policy Checker - Compliance validation
• Approval Workflow - Routing and status tracking
• Expense Orchestrator - Workflow coordination

📖 See examples/expense_workflow/README.md

A2A Trace works with Google's official Agent Development Kit:

# Install Google ADK
pip install google-adk

# Start the A2A sample agents
adk api_server --a2a --port 8001 contributing/samples/a2a_basic/remote_a2a

# In another terminal, trace your root agent
a2a-trace -- adk web contributing/samples/a2a_basic

Supports any ADK sample:

• a2a_basic - Dice rolling + prime checking
• a2a_human_in_loop - Human approval workflows
• a2a_auth - Authenticated agent communication

The trace server exposes REST endpoints:

• Go 1.22+
• Node.js 20+
• npm

git clone https://github.com/harry-kp/a2a-trace.git
cd a2a-trace

# Build everything
./scripts/build.sh

# Or manually:
cd ui && npm install && npm run build && cd ..
mkdir -p cmd/a2a-trace/ui && cp -r ui/out cmd/a2a-trace/ui/
go build -o bin/a2a-trace ./cmd/a2a-trace

# Go tests
go test ./...

# UI type check
cd ui && npm run build

• HAR export - Export traces in HTTP Archive format
• Replay - Replay captured requests
• Diff mode - Compare two trace sessions
• OpenTelemetry - Export traces to OTEL backends
• Streaming support - Better SSE/streaming visualization
• VSCode extension - Integrated debugging experience

Contributions are welcome! Please read our Contributing Guide first.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

MIT License - see LICENSE for details.

• Google A2A Protocol - The protocol this tool debugs
• Cobra - CLI framework
• Gorilla WebSocket - WebSocket implementation
• modernc.org/sqlite - Pure Go SQLite driver

Made with ❤️ by Harshit Chaudhary