Introduction: AgentVerse

🤖 AgentVerse 🪐
Think of it as a universe for LLM agents.
It is designed to facilitate the deployment of multiple LLM-based agents in various applications, which primarily provides two frameworks: task-solving and simulation Introduce how to run an example successfully in CLI mode and in GUI mode

The codebase contained facilitates the creation and simulation of multi-agent systems, potentially incorporating language models for agent interactions.

Requirements

This documentation assumes you have the following:

  • AgentVerse github repo
  • A Python virtual environment setup
  • A working OpenAI API key
  • Good working knowledge of Python
  • Some experience of web development
  • Knowledge and understanding of yaml
  • Interest or a general understanding of LLM's
  • Knoweldge of github

Installation

This section of the README has details on how you can get up and running with installing this project. The steps below were used to install it on Windows 10 using the recommended manually: Make sure you have Python >= 3.9
  • Clone the AgentVerse github repo git clone https://github.com/OpenBMB/AgentVerse.git --depth 1
  • Navigate into the folder cd AgentVerse
  • Install pip install -e .
  • Optional: If you want to use AgentVerse with local models such as LLaMA, you need to additionally install some other dependencies: pip install -r requirements_local.txt

Another alternative to install is: pip install -U agentverse

This guide shows how to export environment variables. On windows, the screenshot below gives as example on how it can be done.



Simulations: Graphical User Interface


Simulations can either have a Graphical User Interface (GUI) or a Command Line Interface (CLI), some simulations have both interfaces. Here are some showcases, examples of cli simulations can be found here and GUI simulations can be found here.

The simulation agent located inside the agents folder which is inside the agentverse folder defines a BaseAgent which is a Python class that serves as the foundation for other agent classes in the AgentVerse framework. The class includes attributes such as name, llm, output_parser, and methods like step, reset, etc. The agent can interact with an environment and has methods for performing steps, asynchronous steps, and memory management. It provides functionality for managing prompts, receivers, spending, and memory-related operations.
As part of the agent registry module in the AgentVerse framework there is an initialization file that imports classes from various modules, including simulation agents (ConversationAgent, ToolAgent, etc.) and task-solving agents (RoleAssignerAgent, CriticAgent, etc.). The Registry class from agentverse.registry is used to manage and register agents.The file initializes an instance of Registry named AgentRegistry for agent registration. These files shown below collectively contribute to the structure and functionality of the AgentVerse framework, providing a foundation for creating and managing different types of agents in both simulation and task-solving scenarios.




1. Prisoner's dilema


This class defines a PrisonerDilemaAgent within the AgentVerse framework. This agent class is designed for simulating interactions in a Prisoner's Dilema scenario. Additionally, subclasses PoliceAgent and PrisonerAgent inherit from PrisonerDilemaAgent, each representing a specific role with additional role-specific information.
Imports and Type Checking : The from __future__ import annotations statement is used for postponed evaluation of type annotations. The class also uses type hints, and there's a conditional import based on type checking to avoid circular dependencies.
Class Structure: The class PrisonerDilemaAgent inherits from BaseAgent and serves as a base for agents involved in a Prisoner's Dilemma scenario.
Methods: step Represents a step in the agent's decision-making process within the environment. astep An asynchronous version of step. _fill_prompt_template A helper method to fill placeholders in the prompt template, including agent name, environment description, role description, and chat history. add_message_to_memory Adds messages to the agent's memory. reset Resets the agent.
Role-specific Subclasses The PoliceAgent and PrisonerAgent subclasses introduce role-specific behavior and template filling.


Task solving agent - Command Line Interface


The base.py file located inside the task-solving agent folder, defines an abstract base class named BaseAgent within the AgentVerse framework. This class represents the foundation for creating agents in a multi-agent system. Agents are entities capable of interacting with an environment, processing messages, and maintaining memory.

Attributes:

  • name (str): A unique identifier for the agent.
  • llm (BaseLLM): An instance of a language model that the agent uses for generating responses.
  • output_parser (OutputParser): An output parser that interprets the responses generated by the agent.
  • prepend_prompt_template (str): Template for the prompt to be prepended before generating a response.
  • append_prompt_template (str): Template for the prompt to be appended before generating a response.
  • prompt_template (str): Combined template for the entire prompt used in generating a response.
  • role_description (str): A description of the role of the agent.
  • memory (BaseMemory): Memory for storing chat history and other relevant information.
  • memory_manipulator (BaseMemoryManipulator): Manipulator for interacting with the agent's memory.
  • max_retry (int): The maximum number of retry attempts if an error occurs during response generation.
  • receiver (Set[str]): A set of identifiers representing the entities that can receive messages from the agent.
  • async_mode (bool): A flag indicating whether the agent operates in asynchronous mode.

    • Abstract Methods:
  • step(self, env_description: str = "") -> Message: Abstract method to get one-step response.
  • astep(self, env_description: str = "") -> Message: Abstract asynchronous version of step.
  • reset(self) -> None: Abstract method to reset the agent.
  • add_message_to_memory(self, messages: List[Message]) -> None: Abstract method to add a message to the agent's memory.

    • Methods: get_spend(self) -> float: Gets the spending of the agent (associated with language model usage). get_spend_formatted(self) -> str: Gets the formatted spending of the agent. get_all_prompts(self, **kwargs): Gets both prepend and append prompts along with the total number of tokens. get_receiver(self) -> Set[str]: Gets the set of entities that can receive messages from the agent. set_receiver(self, receiver: Union[Set[str], str]) -> None: Sets the receiver entities. add_receiver(self, receiver: Union[Set[str], str]) -> None: Adds receiver entities. remove_receiver(self, receiver: Union[Set[str], str]) -> None: Removes receiver entities.

    This base class provides a blueprint for creating agents in a multi-agent system. It encapsulates common attributes and methods that agents might use to interact with the environment, generate responses, and manage their memory. The abstract methods enforce the implementation of core functionalities in derived agent classes. The class is designed to be extended to create specialized agents tailored for specific tasks or environments within the AgentVerse framework.



    Simulation environment


    The simulation environments are defined in a class named BasicEnvironment within the AgentVerse framework. This environment, labeled as "sim-basic" in the EnvironmentRegistry, serves as a foundational simulation environment implementing the logic of conversation. It is designed to facilitate interactions between multiple agents based on a set of rules.

    Purpose: This class represents a basic simulation environment within the AgentVerse framework, implementing the logic of conversation between agents.
    Inheritance: Inherits from BaseEnvironment, providing a base class for custom environment implementations.
    Registration: Registered in the EnvironmentRegistry under the name "sim-basic."
    Attributes:
  • agents: List of agents participating in the environment.
  • rule: Rule defining the logic of agent interactions.
  • max_turns: Maximum number of turns in the environment.
  • cnt_turn: Current turn number in the environment.
  • last_messages: Messages from the last turn.
  • rule_params: Variables set by the rule.

    • Initialization: The class initializes with a rule, and additional configurations for order, visibility, selector, updater, and describer aspects of the rule are extracted from the rule configuration.
    Methods: step Asynchronously runs one step of the environment, involving obtaining the next agent index, generating the current environment description, generating the next message from each agent, selecting certain messages based on rules, updating agent memory, updating the set of visible agents, and incrementing the turn count. print_messages Logs the content of selected messages. reset Resets the environment, setting the turn count to 0, resetting the rule, and calling the reset method for each agent. is_done Checks if the environment is done based on the current turn count. This class provides a flexible and extensible foundation for creating various simulation environments within the AgentVerse framework. It encapsulates the common logic for agent interactions, allowing for easy customization and extension based on specific simulation requirements.

    The code snippet below shows an example of it's usage:
    # Creating an instance of the BasicEnvironment basic_env = BasicEnvironment(rule=custom_rule, agents=[agent1, agent2]) # Running a step in the environment resulting_messages = await basic_env.step()


    Pokemon environment


    Pokemon enviroment defines a class named PokemonEnvironment within the AgentVerse framework. This environment, labeled as "pokemon" in the EnvironmentRegistry and is designed for simulating a Pokémon-themed scenario. It involves multiple agents located in different places, and the environment allows for interactions and responses to a player's messages.
    Initialization: The class initializes with information about agents, their initial locations, a rule governing the environment, and additional parameters.
    Environment Steps: The step method simulates one step of the environment, allowing either routine agent actions or responses to a player's input.
    Internal Methods _routine_step Simulates routine steps for non-player agents. _respond_to_playerProcesses the player's input and triggers agent responses. update_state Updates the state of agents based on their locations. print_messagesLogs messages for debugging or information. resetResets the environment to its initial state. is_done Checks if the environment simulation is completed. get_test_messages Returns a set of test messages for demonstration.


    Prisoner's dilema


    PrisonerDilemmaEnvironment, which is a specific environment implementation within the AgentVerse framework. This environment is designed for simulating a scenario related to the prisoner's dilemma. The class inherits from BasicEnvironment and is registered in the EnvironmentRegistry with the label "prisoner_dilemma." The purpose of this class is to represent an environment for simulating the prisoner's dilemma, a classic problem in game theory.
    -It inherits from BasicEnvironment, providing a foundation for custom environment implementations.
    -It is registered in the EnvironmentRegistry under the label "prisoner_dilemma."
    -It asynchronously runs one step of the environment simulation. It involves obtaining the next agent index, generating the current environment description, generating the next message from each agent, selecting certain messages based on rules, updating agent memory, updating the set of visible agents, and incrementing the turn count.
    -It inherits attributes and methods from BasicEnvironment.and it utilizes a specific rule (SimulationRule) for governing agent interactions in the environment.
    -For asynchronous execution it utilizes asynchronous programming with asyncio.gather to concurrently execute agent steps. This class is registered in the EnvironmentRegistry under the name "prisoner_dilemma," facilitating easy retrieval and instantiation.

    The screenshot below shows the location of the Prisoner's dilema's class



    Software Development Environment Team


    This file defines a class named SdeTeamEnvironment within the AgentVerse framework. This environment class is designed for simulating interactions in a software development environment where a team collaborates to craft code. It extends the BaseEnvironment class and includes specific rules and behaviors for the given context.
    Imports The class includes necessary imports for asynchronous operations, logging, typing, and JSON handling.
    Class Structure: The class SdeTeamEnvironment is registered in the EnvironmentRegistry as the environment for simulating software development teams.
    Attributes: agents: List of BaseAgent instances representing team members.
  • rule
    • - Rule for the environment.
  • max_turns
    • - Maximum number of turns for the simulation.
  • cnt_turn
    • - Current turn number.
  • last_messages
    • - Messages from the last turn.
  • rule_params
    • - Variables set by the rule.
  • task_name
    • - A string representing the name of the task or project (default is "test").
    Methods Constructor (__init__) Initializes the environment with a specified rule and other optional parameters. It configures the rule based on provided configurations for order, visibility, selector, updater, and describer.
    step Method Purpose: Runs one step of the environment simulation. Steps
  • Gets the next agent index based on the order rule.
  • Generates the next message asynchronously for each agent.
  • Selects certain messages based on the selector rule.
  • Updates memory of the agents using the updater rule.
  • Updates the set of visible agents for each agent.
  • Increments the turn count.
  • Returns the selected messages.

    • print_messages Method
    Purpose: Prints the sender and content of messages to the logging system.
    Parameters:
  • messages: List of Message instances.
  • Output: Logs the sender and content of each message.
  • reset Method:Resets the environment, including the turn count, rule, and agent states.
  • Output: Resets the environment state.
  • is_done Method: Checks if the environment is done, either reaching the maximum turns or an end flag.
  • Output: Returns True if the environment is done, False otherwise.
  • Rule Initialization and Configuration: Initializes and configures the rule for order, visibility, selector, updater, and describer based on provided configurations.

    • The SdeTeamEnvironment class is specifically designed to model interactions within a software development environment where a team collaborates to craft code. The environment includes rules for order, visibility, selector, updater, and describer, which are tailored to simulate the dynamics of a software development team. The asynchronous step method and other functionalities allow for the simulation of turns, messages, and interactions among team members.
    Tool Loading The environment loads a tool named "code_interpreter" as part of the initialization process. This tool, along with others, is loaded using the load_tools function from agentverse.initialization. The tools are used to interact with specific functionalities related to the software development context.


    Task solving Enviroment


    TasksolvingRule class defined within the AgentVerse framework represents a rule set for a task-solving environment where agents collaborate to perform tasks. The rule set includes components for role assignment, decision-making, execution, and evaluation. It extends the BaseRule class and is designed to be used in the context of multi-agent systems where agents need to work together to solve complex tasks.

    Components:
  • Role Assigner (BaseRoleAssigner): Assigns roles to agents based on the task description and advice.
  • Decision Maker (BaseDecisionMaker): Determines the plan or decision for solving the task. It takes into account the task description, previous plans, and advice.
  • Executor (BaseExecutor): Executes the task using the provided final solution from the decision-making stage.
  • Evaluator (BaseEvaluator): Evaluates the solution and execution result to provide a score and advice.

    • Attributes:
  • role_assigner: Instance of the role assigner component.
  • decision_maker: Instance of the decision maker component.
  • executor: Instance of the executor component.
  • evaluator: Instance of the evaluator component.
  • role_assign_only_once: Boolean indicating whether role assignment should occur only once.
  • add_execution_result_to_critic: Boolean indicating whether to add execution results to critic agents.
  • add_execution_result_to_solver: Boolean indicating whether to add execution results to the solver agent.

    • Methods: __init__ Method Initializes the rule set with components configured using provided configurations for role assigner, decision maker, executor, and evaluator. role_assign Method Assigns roles to agents based on the task description, advice, and turn count. Handles scenarios where role assignment occurs only once. decision_making Method Determines the plan or decision for solving the task. Handles dynamic decision-making scenarios. Takes into account task description, previous plans, and advice. execute Method Executes the task using the executor component. Adds execution results to critic and solver agents based on configuration. evaluate Method Evaluates the solution and execution result using the evaluator component. Handles human evaluation scenarios by collecting scores and advice. reset Method Resets the state of the rule set by resetting each component.

    The TasksolvingRule class is designed for a task-solving environment where multiple agents collaborate to perform tasks. It integrates components for role assignment, decision-making, execution, and evaluation. The file incorporates dynamic decision-making scenarios, human evaluation, and configuration options for controlling the behavior of the rule set. Below is a screenshot showing codebase for this class.



    Contributing


    To contribute or if you are interested in joining the agent verse and a become core AgentVerse team member - don't hesitate to reach out to the leaders, their details are on the repo's README file.