GPTeam: Running Collaborative GPT-4 Agents in a Shared World

What GPTeam Explores and Who It Is For

GPTeam addresses a specific research question: can multiple GPT-4 agents, each with their own memory and goals, coordinate effectively through natural-language communication alone? The project is not designed to automate real workflows. It is designed for engineers and researchers who want to observe how agents form plans, share information, and divide work when given a predefined objective.

The primary audience is ML engineers exploring agent architectures and software developers curious about emergent multi-agent behavior. If your goal is to build a reliable pipeline that completes a business task every time, GPTeam is not the right starting point. If your goal is to watch agents debate, delegate, and revise strategies in a simulated office or town, it is purpose-built for that.

Memory, Reflection, and Location: How the Simulation Runs

GPTeam implements agent memory and reflection based on the architecture described in the generative agents research paper (arXiv 2304.03442). Each agent maintains a memory store that accumulates observations and interactions over time. Reflection is the mechanism by which an agent periodically synthesizes recent memories into higher-level insights, which then influence future decisions.

Agents are not static chat participants. They move between named locations defined in config.json, choosing where to be based on their current tasks and where other agents are. This spatial dimension adds a coordination cost that forces agents to communicate about meeting points and divide work by location. The world runs agent steps in parallel, so multiple agents act simultaneously rather than in a fixed turn order.

The state of each agent is written as a human-readable summary to a text file inside the agents/ folder while the world runs. Opening one of those files gives you a current snapshot of what that agent believes, what it intends to do, and where it thinks it is.

Installing GPTeam and Launching a World

GPTeam uses Poetry for dependency management and Python between 3.9 and 3.11 (Python 3.12 is not supported). The setup script handles Poetry installation and initial database seeding.

Clone the repository and run the setup script:

git clone <repo-url>
cd gpteam
python setup.py

The setup script copies .env.example to .env and seeds the database. Open .env and fill in at minimum:

OPENAI_API_KEY=
DATABASE_PROVIDER=sqlite

SQLite works without additional infrastructure. If you prefer Supabase, set DATABASE_PROVIDER=supabase and provide SUPABASE_URL and SUPABASE_KEY.

Once the environment is configured, start the simulation:

poetry run world

Expect several GPT-4 calls per agent per step. To reduce cost during experiments, use the turbo flag, which switches all LLM calls to gpt-3.5-turbo:

poetry run world --turbo

The README notes that turbo mode produces noticeably weaker results. If you are running GPTeam to evaluate agent coordination quality rather than just verify that it runs, use the default GPT-4 mode.

Reshaping the World: Agents, Locations, and Database Resets

The simulated world is defined entirely in config.json at the repository root. You can add agents with new names, personalities, and goals, and define the locations they can occupy. Changes take effect after a database reset, which clears the previous simulation state.

The reset command is:

poetry run db-reset

After the reset, run `poetry run world` to start a fresh simulation with the updated configuration. There is no hot-reload; every structural change to the world requires a reset and a restart.

The repository also includes a seed command that populates the database with the default set of agents and locations, and a small-seed variant for lightweight testing:

poetry run db-seed-small

For teams that want agents to communicate through a live Discord server, the project ships a Discord integration. Each agent can be assigned a Discord token so it posts messages to a channel that represents its current location. The DISCORD.md file in the repository root documents the complete setup.

Model Alternatives: Anthropic Claude and Window Support

GPTeam ships with optional support for two alternatives to OpenAI. The first is Anthropic Claude: set ANTHROPIC_API_KEY in .env and pass the --claude flag to use claude-v1 for some calls and claude-v1-instant for others.

poetry run world --claude

The second alternative is Window, a browser extension that routes LLM calls to locally available models. Pass --window after installing the extension. The README notes that some models may respond slowly because the prompts sent per agent step are long.

The dependency pinning is worth noting here: the installed anthropic package is 0.2.10, an early SDK version. The claude-v1 model identifier it references is no longer a current Anthropic model name. Anyone using the Anthropic integration today should verify whether the library version is compatible with current API behavior.

Where GPTeam Is the Wrong Tool

GPTeam's architecture makes it unsuitable for several common agent use cases.

First, it has no retry or error-recovery mechanism documented in the README. If an API call fails mid-step, the simulation's behavior is not specified. Second, there is no support for agents that call external tools beyond those enabled through optional API keys (SerpAPI for search, Wolfram Alpha for computation). Agents in GPTeam communicate with each other, but they do not browse the web or write code unless those capabilities are explicitly wired in.

Third, the framework is Python 3.9 to 3.11 only. Projects on Python 3.12 or later cannot install it without modifications. Fourth, the openai package is pinned to ^0.27.4, which is the pre-1.0 SDK. If your project already uses openai >= 1.0, running GPTeam in the same environment will cause dependency conflicts.

Finally, cost is a real constraint. Running the default simulation with GPT-4 makes multiple concurrent API calls per agent step. A long-running simulation with several agents and many steps can become expensive quickly, and the README provides no estimate of typical cost.

Maintenance Status and License

The last push to the repository was on 2026-09-08, which is recent. The project has no formal GitHub releases, meaning there are no versioned tags to pin to. Dependency updates are handled through renovate.json, which is present in the repository.

The listed dependencies show specific version windows: langchain 0.0.144, openai 0.27.x, anthropic 0.2.10. These are all significantly behind the current versions of each library. LangChain in particular has undergone major API changes since 0.0.144. Anyone building on top of GPTeam should treat these as pinned historical snapshots, not current library versions.

The project is licensed under MIT. There are no stated restrictions on commercial use, but the primary dependency on OpenAI's API means API terms of service apply to any deployment.

Editorial conclusion

GPTeam suits researchers and engineers who want to observe emergent agent coordination in a controlled sandbox and are comfortable managing OpenAI API costs. Anyone looking for a production-ready task orchestration system should look elsewhere: the framework is built for exploration, not reliability guarantees. Before running it, verify that your OpenAI API budget covers the cost of multiple concurrent LLM calls per agent step, and check whether the pinned dependency versions (openai 0.27.x, langchain 0.0.144) are compatible with your existing project.

Frequently asked questions

Official sources

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