GitHub - ShreeshaBhat1004/Easy-Agent: Easy to implement multi-agentic framework

9 min read Original article ↗

Easy-Agent(beta)

Logo

Table of Contents

Overview

Easy-Agent is a multi-agent system designed to be easy-to-setup compared to crewAI or Autogen. Built with simplicity and extensible in mind, Easy-Agent allows developers to create, integrate, and manage custom agents effortlessly. Whether you need web browsing capabilities, data processing, reporting, or other functionalities, Easy-Agent provides a robust framework to meet your needs.

Features

  • Modular Architecture: Easily add or remove agents without affecting the overall system.
  • Custom Agent Support: Develop and integrate your own agents tailored to specific tasks.
  • API Integration: Seamlessly connect with external APIs like Google Custom Search and Groq for enhanced functionalities.
  • Environment Variable Management: Securely manage sensitive information using .env files.
  • Comprehensive Logging: Monitor system operations and debug with detailed logs.
  • Task Queue Management: Efficiently handle and assign tasks to appropriate agents.
  • Flexible Configuration: Customize agent behaviors and system settings through YAML configurations.

Prerequisites

Before setting up Easy-Agent, ensure you have the following installed on your system:

  • Python 3.7 or higher: Download Python
  • Git: Download Git
  • Virtual Environment (optional but recommended): While not mandatory, using a virtual environment helps manage dependencies effectively.

Installation

  1. Clone the Repository

    git clone https://github.com/ShreeshaBhat1004/Easy-Agent.git
cd Easy-Agent

  2. Set Up a Virtual Environment (Optional)

    • Activate the Virtual Environment:
      • On Windows:
      • On macOS/Linux:

  3. Install Dependencies

    pip install -r requirements.txt

Configuration

Easy-Agent utilizes environment variables to manage sensitive information like API keys. Follow the steps below to configure the system properly.

Setting Up API Keys

  1. Obtain API Keys

  2. Create a .env File

    In the root directory of the project (Easy-Agent/), create a file named .env and add your API keys as follows:

    # .env
GROQ_API_KEY=your_actual_groq_api_key_here
GOOGLE_API_KEY=your_actual_google_api_key_here
GOOGLE_CX=your_actual_google_cx_here

    Notes:

    • Security: Ensure that .env is included in your .gitignore to prevent accidental commits of sensitive information.
    • Format: Do not enclose values in quotes unless necessary. Avoid spaces around the = sign.

  3. Configure Agents

    The agent configurations are defined in config/agents_config.yaml. Ensure that the placeholders correspond to your .env variables.

    # config/agents_config.yaml
agents:
  - name: WebBrowsingAgent
    type: web_browsing
    params:
      api_key: "${GROQ_API_KEY}"
      search_api_key: "${GOOGLE_API_KEY}"
      search_engine_id: "${GOOGLE_CX}"

  - name: DataProcessingAgent1
    type: data_processing
    params: {}

  - name: ReportingAgent1
    type: reporting
    params: {}

    Customization:

    • Adding More Agents: You can add more agents by appending entries to the agents list.
    • Parameterization: Define specific parameters for each agent type as needed.

Running the System

To execute the multi-agent system, use the provided scripts. Here's how to run the main system:

  1. Navigate to the Project Root

    Ensure you're in the Easy-Agent/ directory.

  2. Run the Main Script

    python scripts/run_system.py

    What It Does:

    • Loads Configuration: Reads agents_config.yaml and initializes agents.
    • Loads Environment Variables: Reads API keys from the .env file.
    • Adds Tasks: Queues predefined tasks for agents to process.
    • Assigns and Executes Tasks: Delegates tasks to the appropriate agents.
    • Displays Results: Prints the final outcomes of each agent's operations.

  3. Example Output(upon running run_system.py) image

Creating Custom Agents

One of Easy-Agent's strengths is its ability to incorporate custom agents tailored to specific tasks. Follow the steps below to create and integrate your own agents seamlessly.

Agent Structure

Each agent should be a Python class inheriting from a base agent class (e.g., BaseAgent). The agent must implement necessary methods to handle tasks, process data, and communicate with other components.

Example Base Agent:

# agents/base_agent.py
import logging

class BaseAgent:
    def __init__(self, name, manager, **kwargs):
        self.name = name
        self.manager = manager
        self.logger = logging.getLogger(self.__class__.__name__)
        self.logger.setLevel(logging.INFO)
        if not self.logger.handlers:
            ch = logging.StreamHandler()
            ch.setLevel(logging.INFO)
            formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
            ch.setFormatter(formatter)
            self.logger.addHandler(ch)
    
    def receive_task(self, task):
        """
        Handle incoming tasks.
        """
        raise NotImplementedError("Subclasses must implement this method.")
    
    def send_result(self, result):
        """
        Send results back to the manager.
        """
        self.manager.receive_result(self.name, result)

Implementing a New Agent

  1. Create the Agent File

    In the agents/ directory, create a new Python file for your agent. For example, image_processing_agent.py.

    # agents/image_processing_agent.py
from .base_agent import BaseAgent
import logging

class ImageProcessingAgent(BaseAgent):
    def __init__(self, name, manager, **kwargs):
        super().__init__(name, manager, **kwargs)
        # Initialize any additional parameters or resources here

    def receive_task(self, task):
        """
        Handle 'process_image' tasks.
        Task format: {'type': 'process_image', 'image_path': 'path/to/image.jpg'}
        """
        if task.get('type') == 'process_image':
            image_path = task.get('image_path')
            self.logger.info(f"Processing image: {image_path}")
            # Implement image processing logic here
            processed_data = f"Processed image at {image_path}"
            self.send_result({'task': task, 'processed_data': processed_data})
        else:
            error_msg = f"Unknown task type: {task.get('type')}"
            self.logger.error(error_msg)
            self.send_result({'error': error_msg})

  2. Register the New Agent

    Update config/agents_config.yaml to include your new agent.

    # config/agents_config.yaml
agents:
  - name: WebBrowsingAgent
    type: web_browsing
    params:
      api_key: "${GROQ_API_KEY}"
      search_api_key: "${GOOGLE_API_KEY}"
      search_engine_id: "${GOOGLE_CX}"

  - name: DataProcessingAgent1
    type: data_processing
    params: {}

  - name: ReportingAgent1
    type: reporting
    params: {}

  - name: ImageProcessingAgent1
    type: image_processing
    params:
      # Add any specific parameters your agent requires

  3. Update AgentManager to Support the New Agent Type

    Modify agents/agent_manager.py to recognize the new image_processing type.

    # agents/agent_manager.py
# Add the import for the new agent
from .image_processing_agent import ImageProcessingAgent

class AgentManager:
    # ... existing code ...

    def load_agents(self, config_path):
        # ... existing code ...

                if agent_type == 'web_browsing':
                    agent = WebBrowsingAgent(name, self, **params)
                elif agent_type == 'data_processing':
                    agent = DataProcessingAgent(name, self, **params)
                elif agent_type == 'reporting':
                    agent = ReportingAgent(name, self, **params)
                elif agent_type == 'image_processing':
                    agent = ImageProcessingAgent(name, self, **params)
                else:
                    logger.error(f"Unknown agent type: {agent_type}")
                    continue

        # ... existing code ...

    def get_supported_tasks(self, agent):
        if isinstance(agent, WebBrowsingAgent):
            return ['search']
        elif isinstance(agent, DataProcessingAgent):
            return ['process_data']
        elif isinstance(agent, ReportingAgent):
            return ['generate_report']
        elif isinstance(agent, ImageProcessingAgent):
            return ['process_image']
        else:
            return []

  4. Use the New Agent

    You can now add tasks for your new agent. For example, in run_system.py:

    # scripts/run_system.py
def main():
    # ... existing code ...

    # 4. Process an image
    image_task = {'type': 'process_image', 'image_path': 'path/to/image.jpg'}
    manager.add_task(image_task)

    # Assign and execute tasks
    manager.assign_tasks()

    # ... existing code ...

Registering the New Agent

Ensure that the AgentManager is aware of the new agent type by updating both the import statements and the conditional logic that instantiates agents based on their type. This ensures seamless integration and task assignment.

Project Structure

Understanding the project's directory structure is crucial for navigating and extending the system.

Easy-Agent/
├── agents/
│   ├── __init__.py
│   ├── agent_manager.py
│   ├── base_agent.py
│   ├── web_browsing_agent.py
│   ├── data_processing_agent.py
│   ├── reporting_agent.py
│   └── image_processing_agent.py
├── config/
│   └── agents_config.yaml
├── scripts/
│   ├── __init__.py
│   ├── run_system.py
│   └── interactive_run.py
├── requirements.txt
├── .env
└── README.md

Descriptions:

  • agents/: Contains all agent classes and related modules.

    • __init__.py: Makes the directory a Python package.
    • agent_manager.py: Manages agents, task assignment, and result collection.
    • base_agent.py: Defines the base class for all agents.
    • web_browsing_agent.py: Agent for performing web searches.
    • data_processing_agent.py: Agent for processing data.
    • reporting_agent.py: Agent for generating reports.
    • image_processing_agent.py: (Example) Agent for processing images.

  • config/: Holds configuration files.

    • agents_config.yaml: Defines agents and their parameters.

  • scripts/: Contains executable scripts.

    • __init__.py: Makes the directory a Python package.
    • run_system.py: Main script to run the multi-agent system.
    • interactive_run.py: (Optional) Script for interactive task management.

  • requirements.txt: Lists all Python dependencies.

  • .env: Stores environment variables and API keys.

  • README.md: Project documentation (this file).

Troubleshooting

Encountering issues is a natural part of development. Here are some common problems and their solutions.

1. ModuleNotFoundError: No module named 'agents'

Cause: Python cannot locate the agents module due to incorrect project structure or import statements.

Solution:

  • Ensure __init__.py Exists:

    • Verify that the agents/ directory contains an __init__.py file.

  • Correct Import Paths:

    • Use absolute imports in your scripts.
    • Add the project root to sys.path if necessary.

  • Run Scripts from Project Root:

    • Navigate to the Easy-Agent/ directory before executing scripts.

  • Use the -m Flag:

    • Run scripts as modules to help Python resolve imports. 
      python -m scripts.run_system

2. AttributeError: 'AgentManager' object has no attribute 'add_task'

Cause: The AgentManager class lacks the add_task method or there is a typo in the method name.

Solution:

  • Verify Method Definition:

    • Ensure add_task is defined in agent_manager.py.

  • Check for Typos:

    • Confirm consistent naming (add_task vs. addTasks).

  • Review Class Instantiation:

    • Make sure you're instantiating the correct AgentManager class.

3. API Errors (e.g., 400 Bad Request)

Cause: Malformed API requests due to incorrect API keys, CSE ID, or misconfigurations.

Solution:

  • Verify .env File:

    • Ensure API keys are correctly set without typos.

  • Check CSE Configuration:

    • Confirm that your Custom Search Engine is set to search the entire web.

  • Test APIs Independently:

    • Use separate scripts to validate API functionality.

  • Monitor API Quotas and Billing:

    • Ensure you haven't exceeded usage limits and billing is enabled.

4. No Results Found

Cause: The search query might be too specific, or the API isn't returning results due to configuration issues.

Solution:

  • Use General Queries:

    • Test with broader search terms to verify functionality.

  • Inspect API Responses:

    • Enable detailed logging to view API response content.

  • Ensure Proper API Configuration:

    • Double-check that the API keys and CSE ID are correct and active.

Contributing

Contributions are welcome! If you'd like to enhance Easy-Agent, please follow these guidelines:

  1. Fork the Repository

    Click the "Fork" button at the top-right corner of this page.

  2. Create a New Branch

    git checkout -b feature/your-feature-name

  3. Make Your Changes

    Implement your feature, fix bugs, or improve documentation.

  4. Commit Your Changes

    git commit -m "Add feature: your feature description"

  5. Push to Your Fork

    git push origin feature/your-feature-name

  6. Submit a Pull Request

    Navigate to the original repository and click "New pull request".

Please ensure your contributions adhere to the project's coding standards and include relevant tests.

License

This project is licensed under the MIT License.

Contact Information:

For any questions, suggestions, or support, feel free to reach out:

Happy Coding! 🚀

Low-Rank Factorization of (\Delta_{l}^{l+i})

[ \mathbf{W}_{l+i} = \mathbf{W}l + \Delta{l}^{l+i} ]

where ( \Delta_{l}^{l+i} ) is factorized into low-rank matrices ( \mathbf{A} ) and ( \mathbf{B} ):

[ \Delta_{l}^{l+i} = \mathbf{A}{d \times r} \cdot \mathbf{B}{r \times d}, \quad r \ll d ]