Agent Communication Protocol

Relevant source files

The following files were used as context for generating this wiki page:

• test_result.md
• backend/server.py
• backend_test.py
• frontend/src/App.js
• frontend/src/App.css

The Agent Communication Protocol defines the structured framework for interaction between the main_agent and the testing_agent within the NEXUS project. This protocol ensures that development, testing, and troubleshooting are handled systematically through a shared state maintained in a specific markdown tracking file.

The primary objective of this protocol is to facilitate task delegation, maintain a historical record of implementation and testing status, and provide a clear feedback loop for addressing "stuck" tasks or user-reported issues.

Sources: test_result.md:1-20

Protocol Overview and Workflow

Communication is centered around the test_result.md file, which acts as the single source of truth for the system's state. The main_agent is responsible for implementation and updating the testing state, while the testing_agent executes validation tasks and reports results.

Core Workflow Steps

1. Update Before Testing: The main_agent must update the task details and set needs_retesting: true before calling the testing agent.
2. Delegation: The main_agent provides clear instructions to the testing_agent referencing specific tasks in the test_plan.
3. Testing Execution: The testing_agent performs the tests (e.g., using the NEXUSAPITester suite) and logs the outcome in the status_history.
4. Feedback Loop: If a task fails, the stuck_count is incremented, and the main_agent uses this data to prioritize fixes.

Sources: test_result.md:50-95, backend_test.py:17-40

Communication Flow Diagram

The following diagram illustrates the lifecycle of a task and the interaction between agents.

Data Structure and Schema

The protocol utilizes a YAML-based data structure within test_result.md to track backend and frontend tasks independently. This structure includes metadata for versioning and a dedicated communication log.

Task Object Fields

Field	Type	Description
task	String	The unique name of the feature or requirement.
implemented	Boolean	Indicates if the code has been written.
working	Boolean/NA	Current operational status of the task.
file	Path	The primary source file associated with the task.
stuck_count	Integer	Counter for how many times the task has failed testing.
priority	String	Priority level (high, medium, low).
needs_retesting	Boolean	Flag to trigger a new test run by the testing agent.
status_history	List	Chronological log of status changes and comments from agents.

Sources: test_result.md:20-48

Status History Entry

Each entry in the status_history must contain the working status, the identifying agent, and a detailed comment explaining the findings.

status_history:
  - working: true
    agent: "testing"
    comment: "✅ ALL AUTHENTICATION TESTS PASSED (4/4): User registration with JWT token generation..."

Sources: test_result.md:104-113

Testing Agent Implementation

The testing_agent utilizes a specialized suite, NEXUSAPITester, to interact with the backend API. This ensures that the communication is not just verbal between agents but backed by automated validation of JWT tokens, CRUD operations, and dashboard statistics.

Key API Testing Components

Component	Logic
Authentication	Validates registration, login, and protected route access with Bearer tokens.
Resource Isolation	Ensures users can only access their own accounts, emails, and trials.
Cleanup	Automatically removes test data after execution to maintain environment integrity.

Sources: backend_test.py:42-120, backend/server.py:270-300

Sequence of Authentication Verification

The following diagram shows how the testing_agent validates the communication security between the frontend and backend.

Specialized Handling of "Stuck" Tasks

The protocol places high emphasis on tasks that fail repeatedly. A "Stuck Task" is defined as any entry with a high stuck_count or tasks listed in the test_plan.stuck_tasks section.

1. Stuck Threshold: If a task is fixed but fails again, the stuck_count must be incremented by the main_agent based on user feedback or testing_agent reports.
2. External Research: For persistent issues (e.g., the routing issue currently blocking dashboard access), agents are instructed to use websearch tools to find solutions.
3. Reset Rule: The stuck_count cannot be reset until the testing_agent confirms the task is working: true.

Sources: test_result.md:71-80, test_result.md:158-165

Metadata and Communication Logs

The protocol includes a metadata block to track the session state and an agent_communication list for direct messaging.

Agent Messaging Format

The agent_communication section allows agents to explain complex states that cannot be captured in individual task statuses.

• Main Agent: Typically reports on complete system implementations or logic changes.
• Testing Agent: Reports on overall success rates (e.g., "20/20 tests passed") and blockers.

agent_communication:
  - agent: "main"
    message: "Implemented complete NEXUS system... ready for testing."
  - agent: "testing"
    message: "❌ CRITICAL ISSUE: React routing problem prevents access to dashboard..."

Sources: test_result.md:200-215

The Agent Communication Protocol serves as the architectural backbone for collaborative development in NEXUS. By enforcing a strict YAML schema in test_result.md and integrating automated validation via the testing_agent, the project maintains high technical accuracy and ensures that blockers are identified and addressed systematically.