SashegDev
874b6f20c2
Основа — Horizon (MIT). История апстрима не переносится: этот репозиторий ведёт свою.
56 lines
2.9 KiB
Markdown
56 lines
2.9 KiB
Markdown
# Agent control API
|
|
|
|
How a program drives a running game: an AI agent through MCP, a script through `horizon-ctl`, a test through the
|
|
control socket. Design and inventory: [agent-control.md](../agent-control.md); for players:
|
|
[playhorizon.dev/docs/agents](https://playhorizon.dev/docs/agents).
|
|
|
|
## Overview
|
|
|
|
The game listens on a local control socket (a Unix socket, or localhost TCP with a token on Windows), takes one
|
|
command per text line and answers one JSON line. `horizon-ctl` wraps it: it starts the game, sends commands and
|
|
serves the same commands as MCP tools. The launcher's MCP server offers them too, as `game_<tool>`.
|
|
|
|
| | Count |
|
|
| --- | --- |
|
|
| `horizon-ctl` commands | 96, in 8 groups (session, observe, move and look, act, screens and chat, multiplayer, world and cheats, scripting and benchmarks) |
|
|
| MCP tools | 88 (8 commands are CLI only) |
|
|
| Destructive commands (need `--confirm`) | 3 |
|
|
| Command names the game's socket answers | about 160, test hooks included (`horizon-ctl help --game`) |
|
|
|
|
## Guide
|
|
|
|
1. Build `horizon-ctl` (`cargo build --profile fast -p horizon-client`), then
|
|
`horizon-ctl --socket $PWD/ctl.sock launch --world W --creative --wait --resources <prepared files>`.
|
|
2. `horizon-ctl --socket … state`, `keys`, `turn`, `command`, `screenshot`, `quit`.
|
|
3. For an agent: `horizon-ctl mcp`, or the launcher's `horizon-launcher mcp` with `agent-config` to connect a client
|
|
([launcher-commands.md](../launcher-commands.md)).
|
|
|
|
## Reference
|
|
|
|
[horizon-ctl-commands.md](../horizon-ctl-commands.md), generated from the command table in
|
|
`crates/horizon-client/src/bin/horizon-ctl/commands.rs`: every command, its MCP tool and its arguments.
|
|
|
|
## Examples
|
|
|
|
- `tools/agent_control_e2e.py`: starts a game and drives it end to end through `horizon-ctl` and MCP.
|
|
- `tools/lan_e2e.py`: two games over LAN, both driven through their sockets.
|
|
|
|
## Stability
|
|
|
|
Preview ([stability.md](stability.md)). The commands in `horizon-ctl`'s table and their MCP tool names are what the
|
|
API offers; the other commands the game's socket answers are test hooks and experimental.
|
|
|
|
## Not there yet
|
|
|
|
- **A version.** A `hello` command that answers the protocol version, the game's release and the features it has;
|
|
MCP `serverInfo` carries the same version; `horizon-ctl` refuses a game whose major it doesn't speak.
|
|
- **Reply schemas.** Each command's reply described in the table (fields, types, units), so the reference documents
|
|
replies as well as arguments and MCP tools declare an output schema.
|
|
- **Events as a stream.** `events --since` polls today; a subscription that pushes events as they happen.
|
|
- **Test hooks apart.** The hooks only harnesses use move under their own prefix, out of the agent's tool list.
|
|
- **Compatibility tests.** A transcript per protocol version: commands and the reply keys each must keep.
|
|
|
|
## Changelog
|
|
|
|
- Unversioned so far: the command table and the generated reference are the contract.
|