Mastering the T20 Multi-Agent System

Appendix B: Common Error Codes and Solutions

This appendix lists potential errors users might encounter when working with the T20 Multi-Agent System and provides practical solutions or troubleshooting steps.

Installation and Setup Errors

• Error: No module named 'venv'
  
  • Cause: Python installation might be incomplete or missing the built-in venv module.
  • Solution: Ensure you have a standard Python 3.3+ installation. If issues persist, try reinstalling Python, making sure to check the option to "Add Python to PATH" during installation.
• Error: pip install -e . fails with dependency errors
  
  • Cause: Missing system dependencies (e.g., build tools) or conflicts with existing packages.
  • Solution: Ensure you are in an activated virtual environment. Check the error messages for specific missing libraries (e.g., C++ compiler errors might require installing build tools like Visual C++ Build Tools on Windows or build-essential on Debian/Ubuntu).

Environment Variable Errors

• Error: GOOGLE_API_KEY not found or similar authentication errors
  
  • Cause: The .env file is missing, incorrectly named, not in the root directory, or the API key is missing/invalid.
  • Solution:
    • Verify that a file named exactly .env exists in the root directory of your T20 project.
    • Ensure the file contains the line GOOGLE_API_KEY="YOUR_API_KEY_HERE" with your valid key replacing the placeholder.
    • Check that your API key is active and has the necessary permissions.

CLI Execution Errors

• Error: command not found: t20-cli
  
  • Cause: The T20 package was not installed correctly, or the virtual environment is not activated.
  • Solution:
    • Ensure your virtual environment is activated (check terminal prompt).
    • Re-run pip install -e . in the project root.
    • Try running the script directly: python runtime/executor.py --goal "Your Goal"
• Error: Orchestrator fails to generate a plan (e.g., initial_plan.json is empty or invalid)
  
  • Cause: The high-level goal might be too ambiguous, overly complex for the planning LLM, or the LLM API request failed.
  • Solution:
    • Simplify the goal or provide more specific details and constraints.
    • Check the Orchestrator's logs (usually in the session directory) for specific error messages from the LLM API call.
    • Ensure your API key is valid and has quota available.
• Error: Specific agent fails during execution (e.g., Kodax produces syntax errors)
  
  • Cause: Issues with the agent's prompt, limitations of the underlying model, incorrect input received from a previous step, or bugs in the agent's logic.
  • Solution:
    • Examine the session directory for the specific agent's output file and logs. Look for error messages or clues about the failure point.
    • Review the initial_plan.json to understand the task delegated to the failing agent.
    • If the issue seems consistent, consider refining the agent's definition (e.g., its default prompt in the YAML file) or the prompts generated by Lyra.

Session and Artifact Management Errors

• Error: Session directory not created or incomplete
  
  • Cause: File system permissions issues, disk space limitations, or an early crash before session initialization.
  • Solution: Check write permissions for the sessions/ directory. Ensure sufficient disk space is available. Review logs for the earliest errors.

By understanding these common issues and systematically checking logs and configurations, most problems encountered during the use of the T20 system can be resolved.