agent-communication-debugger

Agent Communication Debugger

Debug and diagnose issues with the A2A (Agent-to-Agent) communication system, including the orchestrator, coder-agent, tester-agent, and message transport layers.

Prerequisites

• A2A agent system located in a2a_communicating_agents/
• Python 3.10+ environment
• Access to agent logs in logs/ directory
• Agent configurations in respective agent.json files

Instructions

1. Check Agent Status

First, determine which agents are running:

# Check all agent processes
ps aux | grep -E "(orchestrator|coder|tester|websocket)_agent|main.py" | grep -v grep

Look for:

• orchestrator_agent/main.py
• coder_agent/main.py
• tester_agent/main.py
• websocket_server.py

Common issues:

• Agent process not found → Agent isn't running, needs to be started
• Multiple instances → Duplicate processes causing conflicts

2. Inspect Agent Configurations

Read the agent configuration files to verify capabilities and topics:

# View orchestrator config
cat a2a_communicating_agents/orchestrator_agent/agent.json

# View coder agent config
cat a2a_communicating_agents/coder_agent/agent.json

# View tester agent config (if exists)
cat a2a_communicating_agents/tester_agent/agent.json

Verify:

• Agent names match expected values
• Topics are correctly defined
• Capabilities describe what the agent does
• No JSON syntax errors

3. Check Agent Logs

Examine logs for errors and message flow:

# View orchestrator logs (last 50 lines)
tail -50 logs/orchestrator.log

# View all logs with timestamps
tail -f logs/*.log

# Search for specific errors
grep -i "error\|exception\|failed" logs/*.log

# Check for routing decisions
grep -i "routing to\|routed to" logs/orchestrator.log

Look for:

• Connection errors
• Routing decisions showing wrong agent selection
• JSON parsing errors
• Message processing failures

4. Verify Message Transport

Check if the message transport (WebSocket or RAG board) is working:

# Check if WebSocket server is running
ps aux | grep websocket_server | grep -v grep
netstat -tlnp 2>/dev/null | grep 8765 || ss -tlnp 2>/dev/null | grep 8765

# Check RAG board storage
ls -lh a2a_communicating_agents/storage/
ls -lh storage/

# Check recent messages in message board
tail -20 storage/message_board.jsonl 2>/dev/null || echo "Message board not found"

Expected:

• WebSocket server on port 8765 (if using WebSocket transport)
• Recent messages in storage/message_board.jsonl (if using RAG transport)
• No permission errors accessing storage

5. Test Message Sending

Use the provided test script to send a message and verify delivery:

# Send a test message to orchestrator
python .claude/skills/agent-debug/scripts/test_message.py

This script will:

1. Send a test message to the orchestrator topic
2. Wait for response
3. Show message delivery status
4. Display any responses received

6. Diagnose Routing Issues

If messages reach orchestrator but route to wrong agent:

Check orchestrator's routing logic:

# View the decide_route method
grep -A 50 "def decide_route" a2a_communicating_agents/orchestrator_agent/main.py

Check priority keyword mappings:

# View fallback routing keywords
grep -A 20 "priority_mappings = {" a2a_communicating_agents/orchestrator_agent/main.py

Verify agent discovery:

# Check discovered agents in logs
grep "Discovered.*agents" logs/orchestrator.log | tail -5

Common routing issues:

• Agent not discovered → Check agent.json exists and is valid
• Wrong agent selected → Keywords don't match, update priority_mappings
• Null target → No suitable agent found, check agent topics/capabilities

7. Check Environment Variables

Verify API keys and configuration:

# Check if OPENAI_API_KEY is set (don't display value)
env | grep -E "(OPENAI|API_KEY)" | sed 's/=.*/=***HIDDEN***/'

# Check model configuration
grep -E "(model|MODEL)" .env 2>/dev/null | sed 's/=.*/=***HIDDEN***/' || echo "No .env file"

Required environment variables:

• OPENAI_API_KEY - For LLM-based routing and code generation
• ORCHESTRATOR_MODEL or OPENAI_MODEL - Model to use (default: gpt-5-mini)
• CODER_MODEL - Model for coder agent (optional, defaults to OPENAI_MODEL)

8. Restart Agents (if needed)

If agents are stuck or not responding:

# Stop all agents
pkill -f "orchestrator_agent/main.py"
pkill -f "coder_agent/main.py"
pkill -f "tester_agent/main.py"
pkill -f "websocket_server.py"

# Wait a moment
sleep 2

# Start WebSocket server (if using)
cd a2a_communicating_agents
nohup python agent_messaging/websocket_server.py > ../logs/websocket.log 2>&1 &

# Start orchestrator
nohup python orchestrator_agent/main.py > ../logs/orchestrator.log 2>&1 &

# Start coder agent
nohup python coder_agent/main.py > ../logs/coder.log 2>&1 &

# Verify they started
sleep 3
ps aux | grep -E "(orchestrator|coder|websocket)" | grep -v grep

9. Common Issues and Solutions

See [common_issues.md](common_issues.md) for a detailed troubleshooting guide covering:

• Messages not being delivered
• Routing to wrong agent
• Agent not generating responses
• Duplicate message processing
• Transport connectivity problems

Quick Diagnostic Checklist

Run through this checklist systematically:

• [ ] All required agents are running (orchestrator, coder, tester)
• [ ] WebSocket server is running (if using WebSocket transport)
• [ ] Agent configuration files are valid JSON
• [ ] Orchestrator discovered all agents (check logs)
• [ ] OPENAI_API_KEY is set in environment
• [ ] Recent log entries show activity
• [ ] No Python exceptions in logs
• [ ] Test message sends and receives successfully
• [ ] Routing decisions select correct agent

Examples

Example 1: Agent Not Responding to Messages

User problem:

I'm sending messages to the orchestrator but getting no response

Debug workflow:

1. Check if orchestrator is running:

``bash ps aux | grep orchestrator_agent | grep -v grep `` Result: No process found → Orchestrator isn't running

1. Check logs for crash:

``bash tail -50 logs/orchestrator.log `` Result: ImportError for OpenAI package

1. Solution: Install missing dependency

``bash pip install openai ``

1. Restart orchestrator:

``bash cd a2a_communicating_agents nohup python orchestrator_agent/main.py > ../logs/orchestrator.log 2>&1 & ``

1. Verify it's running:

``bash ps aux | grep orchestrator_agent | grep -v grep tail -10 logs/orchestrator.log ``

Example 2: Messages Routing to Wrong Agent

User problem:

I asked for code but it routed to dashboard-agent instead of coder-agent

Debug workflow:

1. Check orchestrator discovered coder-agent:

``bash grep "Discovered.*agents" logs/orchestrator.log | tail -1 `` Result: Shows coder-agent in list ✓

1. Check routing decision in logs:

``bash grep -A 5 "please write.*code" logs/orchestrator.log `` Result: Shows routing to dashboard-agent

1. Check routing logic:

``bash grep -A 30 "priority_mappings = {" a2a_communicating_agents/orchestrator_agent/main.py `` Result: Keywords look correct

1. Check LLM routing decision:

``bash grep "Error in decision making" logs/orchestrator.log `` Result: LLM routing failed, falling back to heuristic

1. Check API key:

``bash env | grep OPENAI_API_KEY | sed 's/=./=HIDDEN*/' `` Result: Variable not set

1. Solution: Set API key and restart orchestrator:

``bash export OPENAI_API_KEY="your-key-here" # Or add to .env file echo "OPENAI_API_KEY=your-key-here" >> .env ``

1. Restart orchestrator to pick up new environment

Example 3: Coder Agent Acknowledges But Doesn't Generate Code

User problem:

Coder agent receives the message but only acknowledges, doesn't generate code

Debug workflow:

1. Check coder agent logs:

`