Doc 0001 / Project thesis / Accepted 2026-10-30
Compile the agent program and the model together.
AgentForge is an open-source compiler and runtime, written in Rust, for AI inference silicon. It plans KV-cache residency, prefetch, prefill/decode placement and kernels from what the agent already knows, instead of guessing one HTTP request at a time.
- Simulator working
- Hardware backend none yet
- Crates 7
- Milestone M0 of M6
01 / Problem
The serving layer guesses what the agent already knows.
Source: design doc §1, research report
Today's compilers stop at the kernel or at one model iteration. The KV cache, batching, prefill/decode placement and prefix reuse belong to a serving scheduler, in Python, over hand-written per-vendor kernels. Agentic workloads make that split expensive.
- 01.1Workloads
Agentic workloads dominate inference growth
A median coding-agent step carries about 119k prefix tokens, appends 875 and generates 214. Prefix-cache hit rates are 95 to 96 percent, and each miss, caused by a long tool wait, costs seconds of recompute.
Source: TraceLab, June 2026
- 01.2Silicon
Hardware split along the prefill/decode axis
Vera Rubin with Groq 3 LPX racks, Trainium with Cerebras: heterogeneous prefill and decode devices shipped in 2026. Placement across device classes is still configured by hand.
Source: research notes 01 to 03
- 01.3Software
Tile IRs converged, and nobody sees the agent
Tile-level IRs are vendor-owned, the neutral layers changed owners (Modular to Qualcomm, Groq to NVIDIA), and NVFP4 versus OCP MX numerics diverge. No compiler looks past one model iteration.
Source: research note 05
02 / Thesis
Two inputs. One plan.
Source: design doc §2
Input A
Agent Program IR
- Which prompt blocks are stable
- When the session comes back
- What it will append
- Which branches are likely
Input B
Machine model
- Where bytes can live
- How fast they move
- What each device class computes per precision
- Which tiers and links exist
agentforge-compile
Compiler
Liveness, residency, placement and kernel selection decided before the first token is served.
Output
- 01KV residency
- 02Prefetch
- 03Prefill / decode placement
- 04Kernels
KV block liveness is derived from the agent program the way register liveness is derived from a control-flow graph. The same machine files drive the cost model, the simulator and the compiler, so every policy is testable before silicon.
03 / Architecture
Eight layers, top to bottom.
Source: design doc §3
- L1
Agent Program IR
agentforge-ir::agent
Steps are LLM calls with structured prompt blocks marked stable or not; transitions are tool calls with latency models, probabilistic branches, or end. KV block liveness is derived from it.
Baseline - L2
Model graph IR
agentforge-ir::model
Attention and MoE variants as structured descriptions (dense, grouped-query, latent, sliding-window, compressed); numerics as first-class types, including block-scaled formats.
Baseline - L3
Tile IR
agentforge-ir::tile
Tiles with explicit memory spaces (global, shared, register, tensor memory), async copies and MMA operations. Async protocols are to be encoded in Rust types so misuse fails to compile.
Skeleton - L4
Machine model
agentforge-machine
TOML descriptions: devices with class, compute per precision, memory capacity and bandwidth, on-chip SRAM; memory tiers with capacity, bandwidth and latency; links.
Baseline - L5
Cost model and simulator
agentforge-cost · agentforge-sim
Roofline-style phase costs for prefill, decode and transfers, and a discrete-event replay of agent sessions over the machine description.
Baseline - L6
Compiler passes
agentforge-compile
KV liveness, residency planning (Belady-style cost comparison over tiers), prefill/decode placement. E-graph rewrites of the model graph and tile programs come next.
Baseline - L7
Backends
PTX · CUDA Tile IR · LLVM AMDGPU · SPIR-V · MSL · tt-metal · Cranelift
Emit public, stable low-level formats. No MLIR dependency in the baseline.
Planned - L8
Runtime
agentforge-runtime
Executor, KV block store with lifetimes from the plan, transports between tiers and devices; memory-safe by construction.
Traits
Workspace crates
- agentforge-ir
- agentforge-machine
- agentforge-cost
- agentforge-compile
- agentforge-sim
- agentforge-runtime
- agentforge-cli
04 / Results
First simulation results.
M0 · synthetic traces · source: design doc, first simulation results
Setup · regime D
- Model
- llama-3.1-70b · FP8 weights · FP8 KV
- Machine
- h200-sxm ×8 · 945 GB KV budget · 2 TB host tier
- Trace
- 80 synthetic coding-agent sessions · 1719 steps · seed 11
- Policies
- lru (reactive, device until pressure) vs plan (program-aware)
The plan policy uses the per-tool latency model from the Agent Program IR: it keeps KV across short waits, spills it during long waits and prefetches before the predicted return. lru keeps everything on the device until pressure forces an eviction whose write lands on the arriving session's critical path.
Figure 1
LRU baseline against the program-aware plan
Each metric indexed to its LRU value. Lower is better.
- lru
- plan
Seed sweep (1, 11, 23, 42): pressure evictions fall 30 to 40 percent in every seed; foreground KV waits fall in three of four; p90 TTFT improves in two of four.
Table view · full regime D report
| Metric | lru | plan |
|---|---|---|
| TTFT mean (s) | 8.398 | 8.298 |
| TTFT p50 (s) | 0.063 | 0.063 |
| TTFT p90 (s) | 33.224 | 22.960 |
| TTFT p99 (s) | 112.230 | 113.058 |
| Step latency p50 (s) | 1.71 | 1.73 |
| Step latency p90 (s) | 36.35 | 27.82 |
| Step latency p99 (s) | 113.82 | 115.43 |
| Foreground KV wait (s) | 20.4 | 16.5 |
| Fetched in foreground (GB) | 3726 | 3681 |
| Prefetched (GB) | 0 | 3777 |
| Spilled during waits (GB) | 0 | 5229 |
| Pressure evictions | 188 | 114 |
| Capacity waits | 1954 | 2107 |
| Device busy (s) | 1716.2 | 1710.5 |
| Makespan (s) | 5725.7 | 5727.1 |
01 Where it holds
With a fast, large host tier the plan cuts pressure evictions by 30 to 40 percent in every seed and lowers foreground KV waits in three of four. The information doing the work is which tool the agent called: a policy that only saw the blended wait distribution lost to LRU.
02 What it does not fix
Mean TTFT barely moves in any pressured regime, because the dominant cost is queueing for device memory. No residency policy changes how much KV the active sessions need; admission control, smaller KV and placement onto bigger devices do.
03 Where it loses
With scarce, slow tiers (a 128 GB host tier, NVMe writing at 24 GB/s) every extra transfer competes for one channel. The plan saturates it and loses to LRU, which is why channel-aware planning is the first M1 item.
Figure 2
Why a miss matters: first-order arithmetic
70B grouped-query model, 119k-token prefix, FP16 KV ≈ 38 GB. Seconds, one axis.
With a 4 to 5 percent miss rate, misses dominate tail latency. Moving KV between tiers costs tenths of a second to seconds; recomputing it costs 6 to 30 s depending on GPU and precision.
05 / Machines
Machines are data.
crates/agentforge-machine/machines/*.toml
A machine is a TOML file: devices with class, compute per precision, memory capacity and bandwidth, on-chip SRAM; memory tiers with capacity, read and write bandwidth and latency; links. Five ship with the baseline. Closed silicon is a modelling target through the same files.
- gpu01 / 05
h200
NVIDIA H200 SXM ×8
- Memory
- 141 GB HBM3e
- Bandwidth
- 4.8 TB/s
- SRAM
- 50 MB
- FP8
- 1979 TFLOPS
- Link
- NVLink 4 · 900 GB/s
- Tiers
- host 2 TB · NVMe 30 TB
No FP4 tensor cores; FP4 weights run through the FP8 path.
h200.toml - gpu02 / 05
b200
NVIDIA HGX B200 ×8
- Memory
- 180 GB HBM3e
- Bandwidth
- 8.0 TB/s
- SRAM
- 164 MB
- FP8
- 4500 TFLOPS
- Link
- NVLink 5 · 1800 GB/s
- Tiers
- host 2 TB · NVMe 30 TB
NVFP4 at 9000 TFLOPS; E4M3 scales per 16 elements.
b200.toml - gpu03 / 05
mi355x
AMD Instinct MI355X ×8
- Memory
- 288 GB HBM3e
- Bandwidth
- 8.0 TB/s
- SRAM
- 296 MB
- FP8
- 5000 TFLOPS
- Link
- Infinity Fabric · 1000 GB/s
- Tiers
- host 2 TB · NVMe 30 TB
OCP MX block scaling only; NVFP4 falls back to the MXFP4 rate.
mi355x.toml - gpu04 / 05
blackhole-p150
Tenstorrent Blackhole p150 ×1
- Memory
- 32 GB GDDR6
- Bandwidth
- 0.512 TB/s
- SRAM
- 210 MB
- FP8
- 774 TFLOPS
- Link
- 800G ×4 · 400 GB/s
- Tiers
- host 512 GB
140 Tensix cores with 1.5 MB SRAM each. The only fully open accelerator stack.
blackhole-p150.toml - sram_lpu05 / 05
lpx-tier
SRAM decode tier · Groq 3 LPX shape ×256
- Memory
- 0.5 GB SRAM per LPU
- Bandwidth
- 150 TB/s
- SRAM
- 500 MB
- FP8
- 1230 TFLOPS
- Link
- Rack fabric · 2500 GB/s
- Tiers
- DDR5 pool 12 TB
Modelling target only; the hardware is closed.
lpx-tier.toml
Excerpt
h200.toml
Vendor dense peaks, per-GPU host link share and one NVMe drive per GPU. The cost model reads the same fields the simulator and the compiler read.
All machine filesname = "h200"
description = "NVIDIA H200 SXM node: eight GPUs on NVLink 4, PCIe Gen5 host links, host DRAM and NVMe tiers"
[[devices]]
name = "h200-sxm"
class = "gpu"
count = 8
memory_gb = 141
memory_bw_tbps = 4.8
on_chip_sram_mb = 50
[devices.compute_tflops]
fp16 = 989
fp8 = 1979
[[tiers]]
name = "host_dram"
capacity_gb = 2000
read_bw_gbps = 50
write_bw_gbps = 50
latency_us = 20
[[links]]
name = "nvlink4"
bw_gbps = 900
latency_us = 206 / Quickstart
Build it. Run the simulator.
Rust 1.90 is pinned in rust-toolchain.toml; rustup installs it on the first build. The CLI lists machines and model presets, costs prefill and decode, runs the planning passes, and replays synthetic or recorded traces under both residency policies.
# build every crate
$ cargo build --workspace
# run the test suite
$ cargo test --workspace
# list the bundled machine descriptions
$ cargo run -p agentforge-cli -- machines list
# cost a 119k-token prefill on eight H200s
$ cargo run -p agentforge-cli -- cost prefill --model llama-3.1-70b --machine h200 --tp 8 --tokens 119000 --prefix 0
# decide residency for a prefix across a 45 s median tool wait
$ cargo run -p agentforge-cli -- plan residency --machine h200 --tp 8 --prefix-tokens 119000 --wait-median 45
# replay 64 synthetic sessions and compare both policies
$ cargo run -p agentforge-cli -- sim run --model llama-3.1-70b --machine h200 --tp 8 --sessions 64 --steps 20 --policy both --seed 1
07 / Roadmap
M0 to M6.
Source: docs/ROADMAP.md
- M0
Baseline
2026-10Research notes and report, design doc, Cargo workspace with IR, machine model, cost model, compiler passes, trace simulator, runtime traits, CLI.
cargo test, clippy and fmt pass; sim run compares LRU and program-aware residency.
current - M1
Simulator validation
nextFreeInference and TraceLab trace loaders, calibration against GenZ and LLMCompass, TP interference, channel-aware residency, write-through baseline, admission control.
Simulated TTFT and throughput within 15 percent of published measurements for Llama 3.1 70B on H200 and B200.
planned - M2
CPU backend
plannedTile IR to Cranelift for a tiny transformer; reference numerics for FP8, MXFP4, NVFP4.
A 2-layer model runs end to end, bit-exact against the reference.
planned - M3
NVIDIA backend
plannedPTX emission and cutile-rs kernels; KV block store with planned lifetimes; agent-aware runtime on one GPU.
An agentic trace replays on real hardware with the simulator’s predicted ordering of policies confirmed.
planned - M4
Tenstorrent backend
plannedtt-metal programs through the host API; Blackhole machine file validated on hardware.
The same tiny model and trace replay on a Blackhole card.
planned - M5
Heterogeneous placement
plannedPrefill-class and decode-class devices in one plan; KV transfer scheduling over links.
Simulation, and measurement where hardware allows, of a two-class deployment.
planned - M6
Numerics verification
plannedBlock formats as verified IR types; e-graph rewrites with checked equivalence; batch-invariant kernel mode.
Rewrite rules proven or property-tested; deterministic mode passes a 1,000-run identity test.
planned