# AI_Diplomacy: LLM agents playing Diplomacy with memory and betrayal detection

> AI_Diplomacy extends the open source Diplomacy project with agents driven by large language models, one per power, each keeping a structured private diary, a relationship scale, and evolving goals. The interesting engineering is the context pipeline: only the last 40 diary entries reach the model, and old entries are consolidated every two in-game years to keep the prompt from overflowing. The repository is a research artifact with a custom licence and no releases.

**GoodStartLabs/AI_Diplomacy** — Frontier Models playing the board game Diplomacy.

- Repository: https://github.com/GoodStartLabs/AI_Diplomacy
- Stars: 710 · Forks: 99
- Language: Python
- License: NOASSERTION
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/goodstartlabs-ai-diplomacy

## One agent per power, and what each agent actually holds

The project extends the original Diplomacy project with AI agents powered by large language models, and each power in the game is controlled by an autonomous agent that maintains state, forms relationships, conducts negotiations and makes strategic decisions.

The agent is a DiplomacyAgent, and the README describes its four components. Dynamic goals are strategic objectives that evolve based on game events. Relationship tracking maintains a position on a scale from Enemy through Unfriendly and Neutral to Friendly and Ally. A memory system uses a dual layer of structured diary entries and consolidation. And a personality is expressed through power-specific system prompts that shape each agent's diplomatic style.

That last element is what makes the result legible as Diplomacy rather than as a generic multi-agent demo. Each power speaks in a way that reflects who it is, and the relationships are not a log of past messages but a standing opinion that the agent carries into its next decision.

The authors are Alex Duffy and Tyler Marques, the project is written in Python, and the licence is a custom one that GitHub cannot classify, with the terms in a LICENSE file at the root. The last push to the repository was on 2026-06-01 and there are no GitHub releases.

## The five decision points where the model is called

The information flow diagram in the README makes the agent loop explicit, and the useful part is the list of decision points where a language model is actually consulted.

At initialization the model sets initial goals and relationships. At negotiation it generates messages and updates relationships. At planning it produces high-level strategic directives. At order generation it chooses specific moves. At state update it revises goals and relationships based on the outcome. Five calls, and they are not interchangeable, because each one has a different prompt template and a different piece of state feeding it.

The ordering matters too. The state summary of the phase goes into the state update call rather than into the next negotiation, which is a sensible separation: the agent first forms a view of what just happened, then carries that view into how it talks to other powers.

The same diagram shows the write path. Negotiation output feeds the negotiation diary, order output feeds the order diary, and the phase result feeds the phase result diary. All three write into the single private diary, and it is the private diary, not the raw transcripts, that becomes the agent's long-term memory. A separate private journal holds debug logs only and is explicitly not used by the LLMs.

## Three diary types, and why they are separate

The diary is the core of the design, and the README divides it into three specialised entry types, each capturing a different aspect of gameplay.

The negotiation diary holds message analysis, trust assessment and relationship changes. The order diary holds strategic reasoning and risk and reward analysis. The phase result diary holds outcome analysis, betrayal detection and success evaluation. Each is phase-prefixed, so an entry can be traced back to the turn it belongs to.

The split is what makes the memory queryable. If a single unstructured log held everything, a prompt would have to include text that might be relevant rather than text that is relevant, and the relevance of a note from six turns ago depends on whether you are writing a message or choosing a move. Three types means the context builder can pull the right slice.

Betrayal detection is also worth naming on its own, because it comes out of a comparison rather than a model call: the README describes it as operating through order and negotiation comparison, and the phase result diary records it. The question of whether a power broke a promise it made in a message is answered by looking at what it actually did, which is exactly the kind of check that is hard to do well with a language model alone and easy to do with a diff.

## Consolidation every two in-game years, and a 40 entry context window

This is the part of the system that makes the whole thing fit in a context window, and it is the most transferable idea in the repository.

Yearly consolidation automatically summarises old entries to prevent context overflow, and the diagram shows the diary flowing into consolidation on a trigger of every 2 years, with the summary flowing back into the diary. The README also names the model used for that step, summarisation via Gemini Flash, which is a sensible choice for a cheap frequent summarisation task.

The recent context is bounded too. The context construction block lists the last 40 diary entries, the current relationships and the active goals, and only relevant history is provided to LLMs.

So at any moment the model receives a bounded window of recent history plus a compacted summary of everything older. That is a deliberate design rather than a limitation worked around, and it has a consequence worth understanding: an agent's memory of a promise made in turn three is preserved only as far as the summariser carried it. A detail the summariser drops is gone from that agent's point of view, and no later negotiation can recover it.

The smart context building also filters by relevance rather than by recency alone, so the 40 entries are selected, not simply the last 40.

## Orders come from pathfinding context, with a fallback

Order generation is the one place where a language model has to reason about a board rather than about words, and the mechanism for that is spelled out.

BFS pathfinding for movement analysis identifies the nearest enemies, uncontrolled supply centres and adjacent territories, and that analysis is combined with the relationships and goals to build a possible order context. The model then selects from that context, with context-aware order selection with nearest threats and opportunities, and there is fallback logic for when the model cannot produce a usable order.

The BFS step is what makes this different from asking a model to pick a province. The model is not imagining a route, it is choosing among moves that pathfinding has already established are reachable, and the candidate set is filtered by who is a threat and who holds a supply centre that nobody controls. The fallback matters more than it might sound: in a game with a strict order deadline, an agent that fails to produce a valid order loses its turn, and a language model that returns malformed output would do that routinely.

The README lists support for multiple LLM providers, OpenAI, Claude, Gemini, DeepSeek and OpenRouter, and the dependency list confirms it, with the openai, anthropic, google-genai, google-generativeai and together packages all present.

## What it takes to run the thing

The project needs Python 3.13 or newer, and the dependency list in pyproject.toml is long, covering the model providers plus the analysis stack: anthropic, openai, google-genai, google-generativeai and together for the providers, matplotlib, seaborn and scipy for analysis, statsmodels at a pinned 0.14.4, pydantic-settings, pytest with pytest-xdist, and a Sphinx documentation toolchain with the rtd theme.

Configuration is through environment variables, and the repository ships .env.example with the keys the system expects:

```
DEEPSEEK_API_KEY=
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GEMINI_API_KEY=
OPENROUTER_API_KEY=
VITE_WEBHOOK_URL=
```

The file also carries a VITE_ELEVENLABS_API_KEY and a separate ELEVENLABS_API_KEY, plus a STREAM_KEY, which belong to the broadcasting side of the project rather than to the agent loop. The docker-compose file shows how that side is wired: a twitch-streamer service that gets SYS_ADMIN capability, a DISPLAY set to :99, port 9222 published, host IPC and 2gb of shared memory, which is a browser running under Xvfb driven by a debugging port. A separate diplomacy service builds from the ai_animation directory and publishes port 4173, and a diplomacy-dev service publishes 5173 for the development server.

The repository layout shows the scope of the work: ai_diplomacy/ and diplomacy/ for the game itself, experiment_runner.py and experiment_runner/ for running games, analysis/ and the analysis scripts for post-game evaluation, ai_animation/ and twitch-streamer/ for the streaming visuals, plus benchmark_results.ipynb and support_explanation_ablations_csa.ipynb, which are the notebook side of the experimental record.

## Where this is useful, and where it is not

The value of this repository is pedagogical and comparative, and it is worth being clear about the boundary.

It is useful if you want to see a full LLM agent loop built around a stateful game rather than a single prompt, and specifically if you want to study memory compaction. The diary, the three entry types, the yearly consolidation trigger and the bounded recent window are a working answer to the question of how you keep an agent's memory inside a context limit, and the code is short enough to read.

The betrayal detection is the second thing worth stealing, because comparing what an agent said against what it did is a check you can implement without asking a model to judge itself.

It is not a library, though, and it should not be treated as one. There is no package to install and no releases, the module name in the manifest is ai-diplomacy at version 0.1.0 with the description field still reading Add your description here, and the top-level layout is a research tree with notebooks, analysis scripts and a streaming setup alongside the agent code. Running a game costs money in model API calls, at five calls per decision point per power across a seven-power game.

There is also an evaluation question the repository raises but does not fully answer. The benchmark_results.ipynb file and the support_explanation_ablations_csa.ipynb name suggest the intent, and a rules.pdf and DIPLOMACY_ANALYSIS_DOCUMENTATION.md are present, but the README does not describe what the ablations measure or what the results were, so the numbers in those notebooks have to be read directly rather than taken from a summary.

## Conclusion

Adopt AI_Diplomacy if you are studying how language model agents handle negotiation, memory compaction and betrayal, since the repository exposes the whole agent loop in one place and the diary design is the reusable idea. Do not adopt it as a library to import, because it is a research project with no releases, a custom licence and a hard Python 3.13 floor, and it needs paid model API keys to run at all. Before you try it, copy .env.example to .env and fill in the provider keys you want to use, since the agent loop calls an LLM at five distinct decision points, and read the LICENSE file, because the terms are not one of the standard open source licences GitHub can classify.

## FAQ

### What is AI_Diplomacy?

It extends the original Diplomacy project with AI agents powered by large language models, where each power in the game is controlled by an autonomous agent that maintains state, forms relationships, conducts negotiations and makes strategic decisions. It was created by Alex Duffy and Tyler Marques.

### How does the AI_Diplomacy agent remember things?

Through a dual layer memory system built on a private diary of phase-prefixed entries in three types, a negotiation diary for message analysis and trust assessment, an order diary for strategic reasoning, and a phase result diary for outcome analysis and betrayal detection. Old entries are consolidated into yearly summaries every two in-game years to prevent context overflow, and only the last 40 diary entries plus current relationships and active goals are given to the model.

### Which LLM providers does AI_Diplomacy support?

The README lists support for multiple providers, OpenAI, Claude, Gemini, DeepSeek and OpenRouter, and the pyproject dependencies include the openai, anthropic, google-genai, google-generativeai and together packages. The .env.example file lists DEEPSEEK_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY and OPENROUTER_API_KEY.

### How does AI_Diplomacy decide which moves to make?

BFS pathfinding produces a possible order context by identifying the nearest enemies, uncontrolled supply centres and adjacent territories. The model then selects among those options with context-aware order selection, using current relationships and goals, and fallback logic covers the case where the model does not return a usable order.

### What are the requirements to run AI_Diplomacy?

The project requires Python 3.13 or newer, and you configure it by copying .env.example to .env and filling in the provider keys you want to use. The docker-compose file also wires up a twitch-streamer service with SYS_ADMIN capability, DISPLAY set to :99, port 9222 published and 2gb of shared memory for the streaming side.

## Sources

- [GoodStartLabs/AI_Diplomacy on GitHub](https://github.com/GoodStartLabs/AI_Diplomacy)
- [Issues](https://github.com/GoodStartLabs/AI_Diplomacy/issues)
- [README](https://github.com/GoodStartLabs/AI_Diplomacy/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/goodstartlabs-ai-diplomacy