GPTeam: running a multi-agent simulation with GPT-4 and a local SQLite world

What GPTeam actually simulates, and who it is for

GPTeam is a simulation, not a library you import into an application. The README states its main objective plainly: to explore the potential of GPT models in enhancing multi-agent productivity and effective communication. The unit of work is a world containing named agents and named locations, and the point is to watch what happens when those agents pursue goals in the same space.

That places it closer to a research instrument than to a product. The README links a LangChain blog post on the architecture and a YouTube demo, and the repository ships a config.json that defines the available agents and locations. If you want to see whether two language models will coordinate, stall, or talk past each other, this is the shape of tool you want. If you want an agent runtime to embed in a service, the design will fight you, because the world owns the loop and the state.

The audience is narrow but real: researchers, people writing about multi-agent behaviour, and engineers who want a concrete reference implementation of agent memory and reflection. The README credits that memory and reflection design to a research paper, so the project is explicitly positioned as an implementation of published ideas rather than an invention of its own.

Agents, memory, and communication as a tool

The mechanism described in the README is straightforward. Each agent has its own memory. Agents interact with one another by using communication as a tool, which means talking is not a side channel but an action an agent can choose to take, sitting alongside whatever other tools are available. Agents move between locations depending on what they are doing and where the other agents are, so the map is not decoration: position constrains who can talk to whom.

Because agents run in parallel toward common goals, the interesting behaviour is emergent rather than scripted. The README does not describe a central planner that assigns turns. It describes agents that decide, move and speak, with memory carrying context forward.

Observability is handled in a deliberately low-tech way. While the world runs, the agents/ folder holds one txt file per agent containing a summary of that agent's current state. That is the debugging surface. There is no dashboard described in the README, and no metrics endpoint. For a simulation you leave running in a terminal, tailing a text file per agent is often enough, and it avoids building an interface for a project whose value is in the transcripts.

Installing GPTeam and running the world once

The README gives a five-step path. Clone the repository, move into it, run python setup.py, fill in .env, then launch with Poetry. The setup script is not a build step in the usual sense: it checks whether Poetry is installed, offers to install it via the official installer script, copies .env.example to .env if no .env exists, runs poetry install, and then seeds the database.

Start by cloning and entering the repository, then run the environment check. The script prompts before installing Poetry when it does not find it.

The setup script prompts before it installs anything

Running the check is the first real command. It will print that Poetry is already installed, or ask whether to install it. In CI it skips the prompt when the CI environment variable is true.

Filling in the environment file

The setup script copies .env.example to .env. Only OPENAI_API_KEY is required; everything else is optional, including the Anthropic key, the SerpAPI key, the Wolfram Alpha app id, and the Discord tokens. DATABASE_PROVIDER selects between sqlite and supabase, and the Supabase URL and key are only needed for the latter.

Launching the simulation

The world is started through the Poetry script entry point defined in pyproject.toml. The README notes that poetry run world --turbo swaps in gpt3.5-turbo for all LLM calls, which it describes as a lot cheaper with worse results. Note the wording: all calls, not a subset, so turbo is a global quality setting rather than a per-agent one.

Changing the world means resetting the database

Editing config.json to add or remove agents and locations is not enough on its own. The README is explicit that you must reset the database and run the world again, otherwise the new configuration and the stored state disagree. The reset is a Poetry script that maps to a module in src/utils/database.

Swapping the model provider and the Python version ceiling

GPTeam is not locked to OpenAI. An ANTHROPIC_API_KEY enables poetry run world --claude, which the README says uses claude-v1 for some calls and claude-v1-instant for others, and the Window browser extension enables poetry run world --window. The README warns that Window models may respond slowly because the prompts are very long.

The tighter constraint is the interpreter. The pyproject.toml dependency block pins python to >=3.9,<3.12. Python 3.12 and newer are outside that range, and the pinned langchain version, 0.0.144, is old enough that a modern interpreter will not be a drop-in. If your team standardises on 3.12, this project is not for you without forking the dependency set.

Where GPTeam is the wrong tool

The cost profile is the first limitation and it is structural. Every agent turn is an LLM call, agents run in parallel, and the prompts are long enough that the README flags slow responses under the Window provider. There is no documented budget cap, no dry-run mode, and no way to replay a run without paying for it again. The turbo flag lowers the bill by degrading every call, which is a blunt instrument.

State management is the second. The world depends on a seeded database, and changing the configuration invalidates it. There is no documented migration path between world definitions, and no rollback described for a run that goes badly. The README does not document rollback.

The third is that this is a simulation harness, not an integration surface. There is no documented public API for driving agents from your own code, no plugin contract for adding tools beyond what the environment variables enable, and no release history to pin against: the repository has no releases retrieved, so the only version you can install is whatever main points at.

Finally, the Discord integration is a separate setup path with its own document, and the .env.example shows it needs a token per agent plus a channel id per location. That is a lot of configuration surface for a feature that only matters if you want agents posting into chat channels.

AutoGPT and LangChain as the other two doors

The nearest comparison is AutoGPT, and the repository's own topics list includes autogpt alongside agents, ai and gpt-4. The difference in approach is what the agents share. AutoGPT centres on a single agent decomposing a goal into tasks for itself. GPTeam centres on several agents that occupy locations, hold separate memories and treat communication as a tool, so the interesting output is the interaction rather than the task list.

The second comparison is LangChain, and it is a comparison the project invites: the architecture write-up lives on the LangChain blog, and langchain is a direct dependency. LangChain gives you the building blocks to assemble your own agent loop. GPTeam gives you an assembled world with a map, seeded state and a config file, at the cost of flexibility and a pinned, dated LangChain version. If you want to control the loop, use the library. If you want a working simulation to modify, use GPTeam.

Editorial conclusion

GPTeam fits people who want to watch a small team of GPT-4 agents coordinate in a shared map and are willing to run Poetry, seed a database and supply an OpenAI key. It does not fit anyone who needs a stable API, a production agent framework, or a guaranteed cost per run: the turbo flag changes the model for every call, not a subset. Before adopting it, check the Python version bound in pyproject.toml against your interpreter, decide whether DATABASE_PROVIDER is sqlite or supabase, and read DISCORD.md only if you actually want the Discord integration.

Frequently asked questions

Official sources

1. 101dotxyz/GPTeam on GitHub
2. Issues
3. License: MIT
4. Project website
5. README