Primer · architecture · source tour
Agent Harnesses
This one is a bit recursive or self-referential. I used several agent harnesses to understand how agent harnesses are designed in general, and to dissect the inner workings of a couple whose source code is available in the open. It helped me understand the inner machinery of coding agents in a lot more depth. Hope you find it useful as a companion to the native docs for these harnesses.
The model proposes. The harness turns proposals into a working system: assembling context, exposing tools, enforcing policy, recording effects, and deciding whether the loop continues.
§0
Choose the depth you need
The foundational track stands alone. Read it first if “agent harness” still feels like a fuzzy label. The two extensions then trace the same concepts through real repositories, with source links pinned to the exact versions studied.
The agent-harness primer
Build a durable mental model of the loop, context, tools, authority, state, delegation, and failure boundaries.
9 chapters · 60–90 min Open-source extensionDeepSeek Harness
Follow a plugin-composed system from its Cordis kernel through the agent loop, policy pipeline, event log, and subagents.
6 chapters · 45–60 min Open-source extensionPi
Study a deliberately small three-layer stack: provider API, reusable agent core, and a practical coding-agent integration.
5 chapters · 35–50 min§1
The useful boundary
An LLM receives messages and produces a probabilistic continuation. An agent harness supplies the surrounding control system: it decides what messages the model sees, which capabilities appear as tools, how proposed calls become real effects, what enters durable state, and when another model call should happen. Interpretation
01 · Human
Intent and authority
Supplies the goal, constraints, approvals, and the environment in which actions matter.
02 · Harness
Control and memory
Builds context, validates calls, executes tools, records events, and schedules the next step.
03 · Model
Probabilistic proposal
Interprets the current context and emits text, structured tool requests, or a stopping answer.
04 · Environment
External reality
Files, shells, browsers, APIs, repositories, and people that can return evidence or be changed.
§2
What the primer will let you do
- Draw the complete control flow of one agent turn, including tool calls and results.
- Separate deterministic orchestration from nondeterministic model output without pretending either side is perfectly simple.
- Recognize the common subsystems in a new harness: model adapter, context builder, loop, tool runtime, policy gate, session store, compactor, and extension surface.
- Reason about capability versus permission: a tool may exist, be shown to the model, be callable, and still require approval before it may act.
- Inspect a codebase in an order that follows runtime control rather than directory names.
- Compare designs without collapsing product goals into a feature checklist.
No machine-learning mathematics is required. Familiarity with functions, JSON, files, and command-line programs will help in the source extensions, but the foundational path explains each term before using it.
§3
The evidence contract
“How the product behaves” and “how its internals are implemented” are different claims. DeepSeek Harness and Pi are open source, so their deep dives can point to repository documentation and code at pinned commits. Codex and Claude Code are bounded to what their current official documentation establishes. Their unexposed internals remain unknown here.
Pinned open-source code or repository documentation.
Current official product documentation or a first-party publication.
A reproducible public behavior, with version and conditions recorded.
A design reading made explicit so it is not confused with source fact.
Public evidence does not establish the implementation detail.
This boundary is deliberate: the source-code deep dives cover DeepSeek Harness and Pi; the Codex and Claude Code section compares their documented surfaces without reverse-engineering private implementations. Unknown internals
§4
The full route
| Track | Chapters | Best for |
|---|---|---|
| Foundation | Boundary · one turn · determinism · anatomy · context · trust · delegation · reading code · comparison | A complete mental model without repository detail. |
| DeepSeek | Plugin kernel · one turn · tool policy · state · extensions · lab | A composable, event-oriented architecture with explicit policy seams. |
| Pi | Three layers · one turn · context · extensions · lab | A smaller stack whose core loop and coding integration are easy to separate. |
Keep the glossary open if you meet an unfamiliar term. Every page works without JavaScript; the diagrams and context controls add a second way to inspect the same material.