Troubleshooting

While using the Principles Framework, you might encounter some common issues. This section provides solutions to help you resolve these problems efficiently.

1. Circular Dependencies When Running Agents

Issue:

Errors related to circular dependencies occur when agents depend on each other, creating execution loops that prevent proper functioning.

What is a Circular Dependency?

A circular dependency happens when two or more agents depend on each other directly or indirectly, creating a loop. This can cause infinite loops or prevent agents from initializing correctly.

Solution:

Step 1: Identify the Circular Dependency

• Open the agentsConfig.ts file located in the config directory of your generated package.

  cd packages/<generated-agent-directory>/
  nano src/config/agentsConfig.ts

• Look for agents that list each other as dependencies. For example:

  export const agentsConfig = [
    {
      id: "agent-a",
      path: "agents/AgentA",
      name: "Agent A",
      dependencies: ["agent-b"],
    },
    {
      id: "agent-b",
      path: "agents/AgentB",
      name: "Agent B",
      dependencies: ["agent-a"],
    },
  ];

Step 2: Resolve the Dependency Loop

• Remove or adjust the dependencies to eliminate the circular reference. Ensure that each agent only depends on agents that are executed before it.

  export const agentsConfig = [
    {
      id: "agent-a",
      path: "agents/AgentA",
      name: "Agent A",
      dependencies: [],
    },
    {
      id: "agent-b",
      path: "agents/AgentB",
      name: "Agent B",
      dependencies: ["agent-a"],
    },
  ];

Step 3: Re-run the Agents

After resolving the dependencies, run the run-agents command again.

npm run run-agents
# or
yarn run-agents

Tip:

• Use LLM Assistance: If you're unsure how to fix the dependencies, you can copy the content of agentsConfig.ts and use a language model like ChatGPT to help identify and resolve the issue.

2. Importance of First Principles Thinking

Issue:

The effectiveness of the Principles Framework heavily relies on the proper application of first principles thinking. Without a clear and well-defined goal, the framework may not decompose the problem effectively, leading to suboptimal agent generation.

Solution:

Ensure a Singular, Well-Defined Goal

• Clarity: Clearly articulate your goal without ambiguity.
• Singularity: Focus on one objective to enable effective decomposition.
• Context: Provide necessary details that aid in breaking down the problem.

Example:

Instead of:

npm run generate-agents "I want to improve my company's customer service and increase sales."

Use:

npm run generate-agents "I want to enhance the customer support experience by reducing response times."

This allows Principles to deconstruct the goal into fundamental components like response time analysis, support ticket prioritization, and automated reply suggestions.

Best Practices:

• Be Specific and Clear: Avoid vague or broad goals.
• Focus on Fundamental Components: Think about the smallest elements that make up your problem.
• Avoid Assumptions: Base your decomposition on fundamental truths rather than conventional methods.

Additional Guidance:

• Iterate Your Goal Statement: Refine your goal to ensure it is specific and singular.
• Provide Comprehensive Context: Include relevant details that can aid in the decomposition process.

3. Agents Not Performing as Expected

Issue:

Agents are not delivering the expected results or are behaving unexpectedly.

Solution:

Step 1: Verify Agent Configurations

• Ensure that each agent is correctly configured in agentsConfig.ts.
• Check that dependencies are correctly set without circular references.

Step 2: Review Agent Code

• Inspect the code of each agent to ensure it aligns with its intended functionality.
• Look for any errors or misconfigurations in the agent's implementation.

Step 3: Test Agents Individually

• Run individual agents with test prompts to isolate and identify issues.

  npm run run-agent "Test prompt for Agent A."
  # or
  yarn run-agent "Test prompt for Agent A."

Step 4: Check Logs for Errors

• Review console logs for any error messages or warnings that can provide insights into what might be going wrong.

Tip:

• Use Detailed Prompts: Provide clear and specific prompts to help agents understand and process tasks effectively.
• Monitor Performance: Regularly monitor agent performance and adjust configurations as needed.

4. Installation Issues

Issue:

Encountering problems during the installation process, such as dependency errors or issues with setting up environment variables.

Solution:

Step 1: Verify Prerequisites

• Ensure that you have the correct versions of Node.js and npm/Yarn installed.

  node -v
  npm -v
  # or
  yarn -v

Step 2: Reinstall Dependencies

• Sometimes, reinstalling dependencies can resolve issues.

  rm -rf node_modules/
  rm package-lock.json # if using npm
  # or
  rm yarn.lock # if using Yarn
  npm install
  # or
  yarn install

Step 3: Check Environment Variables

• Ensure that the .env file is correctly set up with your OpenAI API key and that it is properly referenced in the code.

Step 4: Seek Community Support

• If issues persist, consider opening an issue on the repository or seeking assistance from the community.

5. Performance Issues

Issue:

Agents are running slower than expected or consuming excessive computational resources.

Solution:

Step 1: Optimize Agent Configurations

• Review the configurations to ensure that agents are not performing unnecessary tasks.
• Limit the number of agents running simultaneously to manage resource usage.

Step 2: Efficient Coding Practices

• Optimize the code within each agent to enhance performance.
• Avoid redundant computations and streamline agent workflows.

Step 3: Upgrade Hardware

• If possible, run the framework on machines with better computational resources to handle the demands of multiple agents.

Step 4: Monitor Resource Usage

• Use system monitoring tools to track CPU and memory usage, identifying any bottlenecks.

Tip:

• Scale Gradually: Start with a smaller number of agents and gradually scale up as needed, monitoring performance at each step.

Summary

By following the solutions outlined above, you can effectively troubleshoot and resolve common issues encountered while using the Principles Framework. Proper application of first principles thinking, careful configuration of agents, and adherence to best practices will ensure a smooth and productive experience.

For further assistance, refer to the Contributing page or open an issue on the repository.