gorge-agent/1¶
gorge-agent/1 connects an out-of-process drafter, deck builder or player to
gorge's limited tools. gorge runs every draft and game and calls out to your
program with batches of questions; your program only answers. It is for training
and benchmark programs that want many games answered at once, so the wire is
batched from the start.
The transcripts below were produced on 2026-10-30 at commit 834ac7d9a by piping
the golden messages through cmd/extagent and examples/extagent/random_agent.py.
Choose this wire when your agent runs under cmd/labdemo or the draftlab library.
To sit at a table on a running server, use the
HTTP decision loop or SpellBench v2
instead. gorged itself does not speak gorge-agent/1.
Try it¶
examples/extagent/random_agent.py
is a complete agent of about 200 lines that uses only Python's standard library. It
answers at random on purpose, so it plays badly and some of its answers get refused.
Such a run prints lines like this one and carries on:
extern: ext:py-random@1 decide refused (choices 1 and 0 are mutually exclusive (group "blocker:12")): answered by fallback
Where agents plug in¶
labdemo's -player, -opponent-players, -drafter and -builder flags, and the
draftlab library through draft/draftlab/extern, accept these specs:
| Spec | Transport |
|---|---|
ext:exec:<path>[@<version>] |
gorge starts the program and talks over its stdin and stdout. The program's stderr is free-form logging. There is no way to pass arguments, so use a wrapper script to choose a checkpoint. |
ext:unix:<path>[@<version>] |
gorge connects to a Unix socket you already serve. |
@<version> pins a generation: the run refuses an agent whose model_version
differs. The agent is recorded as ext:<agent>@<model_version>, and the path or
socket never reaches a result or a manifest.
cmd/extagent is the reference agent as a binary:
go run ./cmd/extagent -listen unix:/tmp/gorge-agent.sock
go run ./cmd/labdemo -player ext:unix:/tmp/gorge-agent.sock -seed 1
Framing¶
- One JSON object per line, UTF-8, ending in
\n, at most 64 MiB. A longer line is a protocol violation, and the reader refuses it without buffering it whole. - Every message carries
"v": 1and a"type". - Both sides ignore unknown fields, so adding a field never bumps
v. An unknowntype, a wrongvor malformed JSON is a protocol violation, and the session ends. - gorge writes
hello,batch,stream_endandbye. The agent writeshello,resultanderror. gorge starts every exchange. - Seeds are integers below 2^53, so every JSON implementation reads them exactly.
A session¶
The lines marked > are what gorge sends; the rest is what cmd/extagent -policy
first -agent demo wrote back:
> {"v":1,"type":"hello","protocol":"gorge-agent/1","gorge_revision":"8ae5062a351078e5ec2725041bbae15e96d60c72","kinds":["pick","build","decide"]}
{"v":1,"type":"hello","protocol":"gorge-agent/1","agent":"demo","model_version":"1","kinds":["pick","build","decide"],"view_omit":["library","available","archetype","ability_costs","effective_cost","own_deck","potential","card_lists","derived_chars"]}
> {"v":1,"type":"batch","batch":17,"items":[{"id":41,"kind":"pick", ... }]}
{"v":1,"type":"result","batch":17,"answers":[{"id":41,"pick":"c1"}]}
> {"v":1,"type":"batch","batch":18,"items":[{"id":42,"kind":"build", ... }]}
{"v":1,"type":"result","batch":18,"answers":[{"id":42,"deck":{"main":["c1"],"basics":[19,0,20,0,0]}}]}
> {"v":1,"type":"batch","batch":19,"items":[{"id":43,"kind":"decide", ... }]}
{"v":1,"type":"result","batch":19,"answers":[{"id":43,"intent":{"seq":0,"player":0,"choices":[0]}}]}
> {"v":1,"type":"stream_end","stream":"g12.1"}
> {"v":1,"type":"bye"}
The exact bytes of each message type are golden files in
draft/draftlab/extern/wire/testdata/,
held by the tests of
draft/draftlab/extern/wire,
the package that defines the wire.
Handshake¶
gorge speaks first. gorge_revision is informational: a VCS revision, a module
version or devel. The agent answers with its own hello:
| Field | Rule |
|---|---|
protocol |
must be gorge-agent/1 |
agent |
your name, matching ^[a-z0-9][a-z0-9._-]{0,63}$ |
model_version |
identifies the weights, matching ^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$. It must change whenever the weights change |
kinds |
the roles served: a non-empty subset of pick, build, decide with no repeats. Using an agent in a role it did not declare is an error |
max_batch |
the most items you want per batch; 0 or absent means no preference. gorge's own default is 256 and its cap is 1024 |
skip_forced |
true: gorge answers a forced decision itself and never sends it. A decision is forced when it has one option, min and max of 1, and no payment choice |
payment_actions |
true: decisions carry payment_actions, and you may answer with intent.payment. False: casts pay through ordinary decisions |
target_hints |
true: priority options carry target_hints |
view_omit |
parts of the view you never read, so gorge need not project or send them: library, available, archetype, ability_costs, effective_cost, own_deck, potential, card_lists, derived_chars. An unknown name fails the handshake. The decision itself cannot be omitted |
A bad field fails the handshake with an error naming that field.
Batches¶
batch numbers start at 1 and increase within a session. Item ids are unique within a
session. One batch per session is in flight at a time, so a batch waits for your
result. Every item has id, kind and seed, and then:
kind |
Other fields | Question |
|---|---|---|
pick |
set, round, pick_no, pack, picks, seen |
which card to take from pack. picks is your own pool so far; seen is the packs this seat saw earlier |
build |
set, deck_size, pool |
which deck to play from pool. deck_size is at least 40 |
decide |
stream, view |
how to answer view.decision |
A card in pack, picks, seen or pool looks like this; mana_value, colors and
the other facts are absent when gorge's corpus does not know the card:
{"id":"c1","name":"Boreal Gravewalker","set":"FDN","number":"1","rarity":"C","mana_cost":"1W","mana_value":1,"colors":"B","type_line":"Creature — Zombie"}
A view is the same JSON a human seat reads from
GET …/view: the deciding seat's redacted projection, with view.decision
always present and view.viewer the seat. A decision lists its legal options:
{"seq":7,"player":1,"kind":"priority","prompt":"Your priority.","min":1,"max":1,"options":[
{"index":0,"kind":"pass","label":"Pass priority"},
{"index":1,"kind":"cast","label":"Cast Shock","obj":42},
{"index":2,"kind":"concede","label":"Concede"}]}
stream names one seat of one game, g<n>.<seat>, and stays the same for that game.
A seat used outside a draftlab game is u<n>.<seat>.
n depends on scheduling, so never let it change an answer. It exists so you can keep
per-game state and drop it on stream_end.
Answers¶
Answer every item id of the batch exactly once, in any order. Each answer has id and
exactly one of:
| Answer field | For | Shape |
|---|---|---|
pick |
pick |
a card id from pack |
deck |
build |
{"main":[ids from pool],"basics":[W,U,B,R,G]} |
intent |
decide |
{"choices":[option index values]}, plus optional rest, payment and announce. seq and player may be left out; gorge fills them in from the decision |
error |
any | {"code":"refused","message":"…"}: you decline this one item |
Refused and violating answers¶
A refusal costs one answer and the game goes on. These are refusals:
- an
erroranswer with coderefused; - a pick that is not in the pack;
- a deck that fails validation;
- an intent the decision does not accept.
gorge counts it, logs one line and answers for you: with the rating-colour drafter,
the best23 builder or the default bot's decision. The fallback is recorded like any
other answer. To debug a model, make refusals fatal with labdemo -ext-strict or
Options.StrictRefusals.
A violation ends the session: a wrong batch number, a missing, duplicate or unknown
id, an answer field that does not fit the item's kind, or more than one answer field.
After that, or after the agent exits, closes its connection or sends
{"v":1,"type":"error","code":"bad_request"|"unsupported"|"internal","message":"…"},
every pending request fails. The run fails too, unless you asked for
labdemo -ext-fail fallback (FailFallback), which answers all later requests with the
same fallbacks. Failing is the default because a run that silently changed policy would
mislabel its data.
No timeouts¶
gorge reads no clock here. A hung agent hangs its games until the program running gorge is cancelled, for example with Ctrl-C, so a deadline has to come from the caller's context.
Other messages¶
| Message | Direction | Meaning |
|---|---|---|
{"v":1,"type":"stream_end","stream":"g12.1"} |
gorge to agent, no reply | that seat's game ended |
{"v":1,"type":"bye"} |
gorge to agent, no reply | the session ends: exit, or close the connection |
The agent contract¶
An answer must be a pure function of its item and the model version. Batch
composition, batch order and stream numbers depend on scheduling, so none of them may
change an answer. Under this contract, a run's results do not depend on the number of
workers, the flush mode or the batch size. The simple way to keep it is to seed a fresh
generator from item["seed"] for each item, as the example does.
If you break the contract, the run is still recorded exactly and can be replayed from its logs and tapes, but a re-run may differ.
How batches form¶
Batches come from games waiting at the same time, so an agent that wants batches of 64
should run with about 64 workers (labdemo -workers, Options.Workers), whatever the
core count. There are two flush modes (labdemo -ext-flush, Options.Flush):
| Mode | A batch is sent when |
|---|---|
barrier (the default) |
every live game in the process is waiting on an external agent, or a queue holds max_batch items |
ready |
the session is idle and anything is queued |
Hidden information¶
An agent gets the deciding seat's own view, one seat's pack and picks, or one seat's pool. It never gets the engine, another seat's view or anything else. One process serving several seats receives each seat's redacted view on one connection and could combine them, just as one program running two built-in bots could. To keep seats isolated, use one endpoint per seat.
Replay without the model¶
Your answers are recorded. Picks and decks are in the event log, and a game's accepted
intents are in its tape (Options.RecordTape). event.ReplayLog, Lab.ReplayTape and
Lab.VerifyEventTapes replay them with the model gone; labdemo -verify-tapes does this
for every pod game.
Versioning¶
wire.Protocol is gorge-agent/1 and wire.Version is 1. The version bumps only on a
breaking change. Additive fields do not bump it, the same rule as
gorge's HTTP wire. The golden files named above
are the check that a change is additive.