Agent Communication Debugger

The Agent Communication Debugger is a comprehensive diagnostic toolkit designed for developers maintaining multi-agent systems, specifically those utilizing hub-and-spoke architectures like the A2A communication framework. This skill provides a structured, systematic approach to troubleshooting issues where agents fail to respond, messages are lost, or routing logic directs tasks to incorrect agents. It is intended for software engineers and systems architects who need to verify the health of distributed agent components, including orchestrators, coder agents, and tester agents, while ensuring the underlying transport layers like WebSockets or RAG-based storage are functioning correctly.

• Performs automated health checks on agent processes (orchestrator, coder, tester, and websocket_server) to identify hung or zombie instances.

• Validates agent configuration files (agent.json) to detect syntax errors, invalid capability definitions, or incorrect topic routing keys.

• Analyzes log files (logs/*.log) by filtering for specific patterns such as connection exceptions, JSON parsing errors, and routing decisions to pinpoint root causes.

• Verifies transport layer integrity by testing WebSocket ports (8765) and checking the availability and content of message board storage files.

• Includes a standalone test script for end-to-end message delivery validation, confirming that the orchestrator correctly receives and acknowledges requests.

• Provides deep-dive debugging for routing logic by inspecting priority keyword mappings, agent discovery logs, and fallback mechanisms within the orchestrator source code.

• Simplifies environment configuration verification by checking for essential variables such as OPENAI_API_KEY and specific model overrides (e.g., ORCHESTRATOR_MODEL, CODER_MODEL).

• Prerequisites include a Python 3.10+ environment and access to the a2a_communicating_agents/ directory structure.

• The tool is highly effective when troubleshooting 'agent not responding' or 'incorrect routing' scenarios in your local development environment.

• Always check the common_issues.md file for known pitfalls and resolution paths for specific transport connectivity problems.

• Ensure all relevant environment variables are set before initiating a full system restart, as misconfigured credentials often cause silent failures in LLM-based routing.