# Plugins (https://www.agentenvframework.com/docs/plugins)

> Add env types, providers, task steps and stores to the framework from a package of your own

A plugin is a Python package you install next to the framework. Each of these pages covers one kind:

1. [Environment Plugins](https://www.agentenvframework.com/docs/plugins/environment-plugins.md): `openciv3_client`, an env type for the
   game with its real client on a GPU VM.
2. [Environment Provider Plugins](https://www.agentenvframework.com/docs/plugins/environment-provider-plugins.md): `openciv3_client_vm`,
   the topology that deploys that env onto a VM.
3. [Sandbox Provider Plugins](https://www.agentenvframework.com/docs/plugins/sandbox-provider-plugins.md): `gpu_vm`, the VMs it runs on.
4. [Task Step Plugins](https://www.agentenvframework.com/docs/plugins/task-step-plugins.md): `openciv3_match` and `save_env_recording`,
   to seat the agents in a game and store its recording.
5. [Registry Plugins](https://www.agentenvframework.com/docs/plugins/registry-plugins.md): a store for the recordings, chosen in
   `config.toml`.

## Example: OpenCiv3

[`agentenv-openciv-plugin`](https://github.com/earakely-scale/agentenv-openciv-plugin) is a complete
plugin you can install and run today. AI agents play [OpenCiv3](https://github.com/C7-Game/OpenCiv3),
the open-source Civilization III remake, against each other, the game's own AI or you in the browser,
and message each other in public as they play.

[![The showmatch as it streams: America's public greeting to Rome and China under the caster's welcome, the real OpenCiv3 client's view of America with a caption, and the final standings as Ada signs off](https://www.agentenvframework.com/plugins/openciv3-showmatch-poster.jpg)](https://www.agentenvframework.com/plugins/openciv3-showmatch.mp4)

The OpenCiv3 match is an AgentEnv Framework task:

1. `deploy_env` starts the OpenCiv3 env: one container that serves the game’s 15 MCP tools.
2. Three `deploy_agent` steps start together: Opus and Kimi on Claude Code, Sol on Codex, each picked by `a2a_agent_id`.
3. The plugin’s `openciv3_match` step starts one 50-turn game, a seat per agent, paced for the stream and cast by two AI casters.
4. Three `prompt_agent` steps, each with its own model and prompt, play the same game at once and message each other in public.
5. The verifier names the victor, Opus 5.5, while `save_env_recording` stores the game’s video.

Parts of the scene:

- **The showmatch task**: One of the tasks in the plugin’s bundle, which it registers under `agent_env.bundles`, so `agent-env run openciv3 --task showmatch` finds it once the plugin is installed. Every run is graded, recorded and stored.
- **tasks/showmatch.json**: The match is plain JSON: 10 steps, each an `id`, a `type`, that type’s fields and `depends_on`. To add a player, add its `deploy_agent` and `prompt_agent` steps and its civilization; no code changes.
- **The run**: Each run is a task instance with its own id. The 50-turn game took 16 minutes; `showmatch-quick` is the same match in 10 turns. `agent-env openciv3 watch --open` shows it live, and `agent-env openciv3 stream` sends it to Twitch as it plays.
- **depends_on**: Each line is a `depends_on` edge. The three `deploy_agent` steps run at once, the match waits for all three, and grading and recording wait for every player to finish its game.
- **deploy_env**: Starts the env registered as `openciv3` (by `agent-env openciv3 setup`): one container that runs the game headless, serves its MCP tools and the live viewer. `ttl_seconds` keeps it up for the whole game.
- **deploy_agent, one per player**: `agent_name` names the player and its seat. `a2a_agent_id` picks its CLI: `openciv3-claude`, `openciv3-codex` or `openciv3-gemini`. Add or remove one to change who plays.
- **openciv3_match**: A task step from the plugin (`agent_env.task_steps`). Once every agent is up it starts the game, a seat per agent: `civs`, `turns` and the map’s `seed`, `size`, `difficulty` and `barbarians`. `min_turn_seconds` paces it for viewers, `broadcast` names the stream and its two AI casters, and `humans` seats people who play in the browser.
- **prompt_agent, one per player**: Each player has its own `model` and `prompt`, which tells it the game is broadcast and to message the other leaders all game. All three play at once, a whole game each, and the turn advances once every seat has ended it.
- **env_outcome_verifier**: Runs the bundle’s `victor-verifier` against the env’s final summary: who won, and each agent’s rank, score and share of the world. Grade 1 for a valid match with one victor, 0.5 for a tie.
- **save_env_recording**: Another task step from the plugin. It renders the game’s MP4 and the viewer as one self-contained HTML file, and stores them with the run, alongside grading.
- **The step’s JSON**: The running step’s entry in tasks/showmatch.json, trimmed. Of each three, one is shown: Sol, GPT-6 Sol on Codex. With it, the three seats and the civilization `civs` gives each; when the run ends, the verifier’s result and the scores at T50.

To install it and play a match yourself, follow the plugin's
[quickstart](https://github.com/earakely-scale/agentenv-openciv-plugin#run-it-yourself).