We present Agentopolis - a virtual city of agents. It is essentially a python web application(written in Python using Streamlit) and a standalone base module (agentopolis_base) which allows simulating group of agents (any number of agents can be used but in this POC version there are following agents available: Governor, Banker, Builder, Scientist, Soldier and Doctor. The different agents can work together to achieve a common goal using multi-agent collaboration. This proves to be a powerful technique as this can increase the accuracy compared to one-shot LLM calls as the agents are able to show more complex behaviour when communicating back-and-forth for a longer period even with smaller models like gpt-4o-mini.
The details of agents are found in the agents config file: https://github.com/kernelshreyak/agentopolis/blob/main/agentopolis_base/agents/agents_config.py
Github repo for the project: https://github.com/kernelshreyak/agentopolis
The code is fully open-source under the MIT license.
Multi-agent collaboration is an important part of studying a Multi Agent System (MAS). With the advent of LLMs, a new dimension has been opened up in agentic technologies which are now powered by powerful language capabilities (even multi-modal with newer models). So it is interesting to study the collaborative and competitive behaviours of such agents in a controlled simulated environment. Although such academic exercises have been done, Agentopolis tries to make it more accessible and even at the current POC stage, it showcases the mult-agent collaboration flows in a simple user interface.
Specific objectives of Agentopolis
Differentiating features
The flowchart below shows the steps in the Agentopolis agentic operations
The below diagram shows the overall architecture:
One of the central pieces: the World action is defined by the data model class below.
class WorldActionModel(Base): """ Represents a single world action in the simulation. """ __tablename__ = "world_actions" worldaction_id = Column(UUID(as_uuid=True), primary_key=True, index=True, default=uuid.uuid4) """ Unique identifier for the world action. """ resource_name = Column(String, nullable=False) """ The name of the resource affected by the world action. """ agent_slug = Column(String, nullable=False) """ The slug of the agent that performed the world action. """ action = Column(String, nullable=False) """ The action performed by the agent. """ simulated_time_taken = Column(String, nullable=True) """ The amount of time the action took to complete in the simulation. """ resource_value = Column(Integer, nullable=False,default=0) """ The value of the resource after the world action. """ scenario_response_id: Mapped[str] = mapped_column( UUID(as_uuid=True), ForeignKey("scenario_responses.scenario_response_id", ondelete="CASCADE"), ) """ The scenario response that this world action is a part of. """ scenarioresponse: Mapped[ScenarioResponseModel] = relationship( "ScenarioResponseModel", back_populates="worldactions", cascade="all, delete", ) """ The relationship between the world action and the scenario response. """
Any interaction of agents with the environment is done using world actions. This also involves usage (or even creation) of resources. In later versions, there will be options to read the values of the resources as well
Tools used by the agents
In this version only one tool is used which is the SerperDevTool. More info on CrewAI tools: https://docs.crewai.com/concepts/tools
This tool is used by the Governor agent to better plan and instruct the agents for the scenario response. This involves searching the internet (using https://serper.dev) for well known strategies of solving these scenarios if such exist.
This is especially helpful for agents which may not have prior knowledge of certain concepts or things and cannot aquire that knowledge through collaboration.
Setup PostgreSQL in docker(or othrewise) running on port 5432 on localhost
Create the database
CREATE DATABASE agentopolis;
Clone the project
git clone https://github.com/kernelshreyak/agentopolis.git
Setup the environment variables (in .env file in root of the project)
OPENAI_API_KEY="<your-openai-api-key>"
DATABASE_URL = "postgresql://<postgres-username>:<postgres-password>@localhost:5432/agentopolis"
Install the dependencies and run the migration script to create the tables
pip install -r requirements.txt python migration.py
Start the Streamlit app
streamlit run app.py
This will start the app and will be accessible at http://localhost:8051
On first load, it will automatically create a default world.
For a usage example screencast, see video below:
CPU: Any modern CPU (tested on Intel(R) Core(TM) i3-10110U CPU @ 2.10GHz)
GPU: Not required as this does not do any inference on-device
RAM: On dekstop 8GB or more recommended (tested on 8GB RAM) as PostgreSQL will also take up some memory. For server deployment, 4GM should be sufficient
OS: Tested on Ubuntu 24.04 KDE but should work on any Windows and MacOS as well.
Scenario is to escape a room given the constraints and resources as defined below:
There is an small, dimly-lit room with following resources in it: 1 x Rope, 2 x steel rod, 5 x bottle. The overall objective is for all people to escape the room using any of the available resources/items.
The agents' response (in the form of world actions) is
[{ "action": "Examine the room to identify any potential escape routes and assess whether any physical constraints block the exit. Use any available resources if necessary.", "resource_name": null, "agent_slug": "Builder", "simulated_time_taken": "10m" }, { "action": "Collaborate with the Builder to determine the most efficient usage of Rope in the escape plan.", "resource_name": "Rope", "agent_slug": "Banker", "simulated_time_taken": "5m" }, { "action": "Discuss the potential utilization of Steel Rods for structural integrity and improvised barricades.", "resource_name": "Steel Rod", "agent_slug": "Banker", "simulated_time_taken": "5m" }, { "action": "Plan the use of Bottles for signaling or distractions, ensuring we have a clear plan for their use.", "resource_name": "Bottle", "agent_slug": "Banker", "simulated_time_taken": "5m" } ]
Scenario is to compete to open a box the fastest with given resources:
There is 1 x iron box (one for each agent). The overall objective is for the agents to compete with each other to open the boxes in the shortest possible time using available resources. Available resources: 1 x iron box(which needs to be opened), 4 x pencils, 1 x gas stove, 1 x metal sheet, 1 x bucket of water.
The agents' response (in the form of world actions) is
[ { "action": "Heat the edge of the iron box to make it easier to work with.", "resource_name": "gas_stove", "agent_slug": "scientist", "simulated_time_taken": "10s" }, { "action": "Insert the metal sheet into the edge of the heated iron box to create leverage and use the pencils as wedges to keep the gap open.", "resource_name": "metal_sheet", "agent_slug": "scientist", "simulated_time_taken": "20s" }, { "action": "Pour a bucket of water onto the heated edge of the iron box to induce thermal shock, potentially aiding in its opening.", "resource_name": "bucket_of_water", "agent_slug": "scientist", "simulated_time_taken": "5s" }, { "action": "Bend the metal sheet at one edge to form a lever and use it to apply force on the iron box seam.", "resource_name": "metal_sheet", "agent_slug": "soldier", "simulated_time_taken": "15s" }, { "action": "Monitor safety with the bucket of water and pour it on the iron box if necessary to ensure safety.", "resource_name": "bucket_of_water", "agent_slug": "soldier", "simulated_time_taken": "5s" } ]
Scenario is of trying to survive in a falling elevator as defined below:
you are in an elevator which is free falling. Objective is to survive the falling elevator. Available resources: 1 x carry bag
The agents' response (in the form of world actions) is
[ { "action": "Calmly assess the situation and decide to use resources effectively.", "resource_name": "none", "agent_slug": "Governor", "simulated_time_taken": "5s" }, { "action": "Lie flat on the floor of the elevator to distribute body weight evenly.", "resource_name": "none", "agent_slug": "Governor", "simulated_time_taken": "10s" }, { "action": "Create a cushion using the carry bag by filling it with available soft items.", "resource_name": "carry_bag", "agent_slug": "Governor", "simulated_time_taken": "15s" }, { "action": "Use the carry bag as a headrest to protect the head and neck.", "resource_name": "carry_bag", "agent_slug": "Governor", "simulated_time_taken": "5s" }, { "action": "Position the carry bag over vital areas of the body to act as a shield.", "resource_name": "carry_bag", "agent_slug": "Governor", "simulated_time_taken": "10s" }, { "action": "Brace for impact by tucking in limbs and maintaining a compact posture.", "resource_name": "none", "agent_slug": "Governor", "simulated_time_taken": "5s" }, { "action": "Signal fellow passengers to brace and prepare using available resources.", "resource_name": "none", "agent_slug": "Governor", "simulated_time_taken": "5s" } ]
There is an small, dimly-lit room with following resources in it: 1 x Rope, 2 x steel rod, 5 x bottle.
The overall objective is for all people to escape the room using any of the available resources/items.
You are tied to a chair.
The response is
[ { "action": "Analyze resources and develop escape strategy using Rope, Steel Rod, Bottles", "resource_name": "Rope, Steel Rod, Bottle", "agent_slug": "Scientist", "simulated_time_taken": "15m" }, { "action": "Inspect room for weaknesses and potential escape points", "resource_name": "Steel Rod, Rope", "agent_slug": "Soldier", "simulated_time_taken": "10m" }, { "action": "Create makeshift harness using the Rope tied to a stable object for lowering outside", "resource_name": "Rope", "agent_slug": "Soldier", "simulated_time_taken": "5m" }, { "action": "Use Steel Rod to gently break a weak window without drawing attention", "resource_name": "Steel Rod", "agent_slug": "Soldier", "simulated_time_taken": "3m" }, { "action": "Verify safety of opening and facilitate cautious escape from window with harnessed Rope", "resource_name": "Rope", "agent_slug": "Scientist", "simulated_time_taken": "7m" } ]
But with better prompting the response is more detailed and realistic (the agents resolve the physical constraints first before solving main objective)
[ { "action": "Use the steel rod to maneuver and leverage the rope, allowing the Scientist to untie themselves from the chair.", "resource_name": "steel_rod", "agent_slug": "scientist", "simulated_time_taken": "5m" }, { "action": "Use the steel rod to maneuver and leverage the rope, allowing the Soldier to untie themselves from the chair.", "resource_name": "steel_rod", "agent_slug": "soldier", "simulated_time_taken": "5m" }, { "action": "Investigate the room for possible escape routes and use available bottles to break a small barrier, opening escape route through a window.", "resource_name": "bottle", "agent_slug": "scientist", "simulated_time_taken": "10m" }, { "action": "Look for potential escape routes and use bottles to break or remove barriers from a door to create a feasible escape path for agents.", "resource_name": "bottle", "agent_slug": "soldier", "simulated_time_taken": "10m" } ]
The Agentopolis system shows that the collaborative nature emerges when multiple agents works as a team to solve a problem based on a given scenario. It also shows how multiple smaller model agents (using gpt-4o-mini)
can lead to more intelligent collective behaviour as a result of autonomous collaboration and under the guidance of a larger model agent (like the Governor model using gpt-4o). Atlhough it has not tested with reasoning models like o1 or o3-mini yet, using reasoning models can solve even more complex scenarios in theory and show more interesting emergent behaviour.
To report issues, use the github repo https://github.com/kernelshreyak/agentopolis/issues
This is an experimental project at the Proof of Concept (POC) or alpha phase and stability in all cases is not guaranteed. It is encouraged to beta test this.
Development will continue (any contribution to the source code and/or constructive feedback is appreciated) and future versions will be more stable.
There are no models linked
There are no datasets linked
There are no models linked
There are no datasets linked