[AlonMalach]

What this adds

A race page, docs/agent_race.html: agents that switch adapters as they work, on one GPU, served two ways and replayed side by side. Like the ALORA-vs-LoRA race (docs/race_live.html), it opens straight from disk: its five races are embedded in it.

Lane	Serving	At an adapter switch
gs-sr-vllm	granite-switch Shadow Residual: 64 SR adapters composed into one checkpoint	nothing: its K/V come from the base model, so one generation runs until a tool call
lora-vllm	stock vLLM serving the same 64 adapters as LoRAs	ends the request, waits the round trip to the agent (2–10 ms), and prefills the agent's whole context again

The page opens on the demo race: the paper's ReAct agents (above), 64 per lane, 16 at a time, 128 to 1,024 tokens each. It shows the outcome, three numbers on why, the race's settings, a track per lane, and the race:

	SR	stock vLLM
All agents done	90.4 s	282.4 s
Prompt tokens computed again	957	3.05M
Requests	170	892
Context already cached	99.8%	16.6%

SR finished 3.1× sooner. Everything else is behind buttons: how it works (the experiment, its diagrams, what an adapter switching (rtt) takes), the models (each lane's base model, adapters, rank and modules), the metrics, and four more races.

The five races

Granite 4.1 3B at b7e5421, one A100-80GB, vLLM 0.26.0:

Agents	Per lane	At a time	Tokens per agent	SR	stock vLLM	SR sooner by
ReAct, classic5	64	16	128–1,024, 16 each	90.4 s	282.4 s	3.1×
fixed steps	16	8	512	28.4 s	91.8 s	3.2×
fixed steps	64	8	512	114.4 s	365.0 s	3.2×
fixed steps	64	16	1,024	129.1 s	747.7 s	5.8×
fixed steps	64	16	128–1,024, 16 each	89.4 s	335.9 s	3.8×

The fixed-steps agents are the adapter benchmark's switching workload: 32-token steps, a new adapter at each, a tool call after every 256 tokens.

What the page shows that the runs do not do: SR is shown switching on the same schedule as stock vLLM. The switch itself is not implemented yet, so the runs kept one adapter per agent; on the GPU, SR costs the same either way, because its K/V come from the base model. The page says so.

What is and isn't in this PR

• In: the page, its three diagrams as images (docs/media/agent_race_*.svg), their generator (docs/generation/generate_race_diagram.py, which reproduces them byte for byte), and docs/AGENT_RACE.md.
• Not in: the code that runs and records races. It runs on the adapter benchmark's harness and jobs, so it stays on feature/adapter-benchmark (PR Agent race: granite-switch SR against stock vLLM LoRA, agents switching adapters #145); docs/AGENT_RACE.md says where it lives.
• Not live on the site: GitHub Pages serves the benchmark branch's docs/, so this page is opened from a clone.
• .pre-commit-config.yaml: the page is exempt from the 500 KB file-size check, as uv.lock is: it is about 7 MB because its races are embedded.
• CLAUDE.md: docs/AGENT_RACE.md in the documentation list.

Testing

• All pre-commit hooks pass on the changed files, and the size and link checks pass over the whole repo.
• The page plays all five races to their results in a browser, with no console errors.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!