Build Harness

Build an Agent Harness from first principles.

A hands-on engineering tutorial that starts with a simple CLI assistant and grows it into a controllable, observable, and extensible Agent Harness.

English · 中文 · 日本語

---

What This Is

Build Harness is a practical tutorial for developers who want to understand how modern coding agents actually work.

It does not begin with a giant framework. It begins with the smallest useful runtime around a model: a loop, tools, state, policy, and clear execution boundaries. From there, the project grows step by step into an Agent Harness: the control system outside the model.

By the end, you should be able to see an agent not as magic, but as an engineered runtime with explicit contracts, observable behavior, and understandable failure modes.

Why Read This

If you have used ChatGPT, Claude, Cursor, Claude Code, or other coding agents and wondered what the system outside the model is doing, this series is for you.

You will learn how the pieces fit together:

Layer	What You Build
Agent fundamentals	Model calls, loops, tools, state, and intent
Runtime control	Permissions, observations, context policy, and replay
Extension model	Providers, plugins, skills, and capability discovery
Diagnosis	Traces, memory governance, scoped retrieval, and evals
Productization	Profiles, hosted execution, automation, and durable runs

Choose Your Language

Language	Start Here
English	Building Agent and Harness from 0 to 1
中文	从 0 到 1 构建 Agent 与 Harness
日本語	0 から 1 へ Agent と Harness を構築する

Who It Is For

This tutorial is written for developers who can read Python or TypeScript and are comfortable with APIs, JSON, CLI tools, Git, and basic runtime concepts.

You do not need to be an AI researcher. You only need curiosity about how to wrap an LLM in a reliable engineering system that can do real work.

Learning Path

1. Understand the Agent

Start by separating an agent from a prompt. You will define the minimum useful parts of an agent and learn how chatbots, workflows, agents, and harnesses differ.

2. Build the Runtime

Add the loop, tool intent, execution boundaries, state, observations, and context policy that let the system move from one-shot answers to multi-step work.

3. Add Control Surfaces

Introduce permissions, traces, replay, memory governance, scoped retrieval, and capability discovery so the system becomes inspectable and recoverable.

4. Productize the Harness

Turn the prototype into something usable: profiles, extensions, multiple providers, hosted execution, durable state, and a shared terminology map.

Chapter Directory

Foundations

1. Agent Base Definition: Why It Is Not a Prompt
   Understand why an agent is a runtime system, not a clever instruction.

2. Agent Composition Model: Model, Loop, Tools, State
   Break an agent into the smallest useful parts and learn how they cooperate.

3. System Boundaries: The Difference Between ChatBot, Workflow, Agent, and Harness
   Map the boundary between scripted workflows, conversational bots, autonomous agents, and harnesses.

4. Harness Base Definition: The Control System Outside the Model
   See the harness as the layer that owns execution, permissions, recovery, audit, and product behavior.

5. Agent Evolution Path: Chat Agent -> Tool Agent -> Runtime Agent -> Managed Agent
   Follow the staged evolution from chat to tools, runtime control, and managed operation.

6. The Value of Hand-Writing an Agent
   Build intuition by writing the smallest useful agent yourself.

Runtime Core

7. LLM Provider Integration: Making the CLI Complete Its First Model Call
   Connect a real model provider to a CLI and normalize the first response.

8. Minimal Agent Loop: From One-Shot Answer to Multi-Step Action
   Turn a single model answer into an iterative action loop.

9. M0 Core Kernel: Bringing a Real Large Model Into the System
   Design the smallest core that can host a model without surrendering system control.

10. Intent / Execution Separation: The Model Proposes, the System Executes
    Separate model-generated intent from actual tool execution.

Extension Boundaries

11. Plugin Host: Why Should Core Learn to Be Extended?
    Add extension points for providers, tools, policies, and workflows.

12. Provider Runtime: Why Can a Provider Only Return Tool Intent?
    Keep model providers behind a clean runtime contract.

Execution and Field Control

13. Tool Runtime: From Tool Intent to Observation
    Build the runtime path from requested tool call to structured observation.

14. Local Tool Bundle: Files, Search, Terminal, and Permission Runtime
    Add practical local tools while keeping risk and permission boundaries visible.

15. Context Policy: What Should the Model See This Turn?
    Decide what enters the model input each turn.

16. Session Replay: Why Is the Event Log the Source of Truth for Long Tasks?
    Replace fragile chat history with an event log that can be replayed, audited, and resumed.

Capability, Collaboration, and Diagnosis

17. Capability Discovery: Skills, MCP, and Dynamic Tool Exposure
    Expose only the capabilities the agent needs right now.

18. Delegation Runtime: Handing Tasks Out Without Losing Control
    Add sub-agents and task delegation while keeping the parent harness in control.

19. Trace Analysis: Using Fact Logs to Locate Agent Failures
    Diagnose failures from traces instead of guesses.

20. Memory Governance: From Candidate Ledger to Governance Store
    Treat memory as governed data, not a dumping ground.

21. Scoped Retrieval: From Bounded Retrieval to Audit Snapshot
    Make retrieval explicit, bounded, and reviewable.

Productization and Hosting

22. Productized CLI: Profile, Extension, Multi-Provider
    Turn the prototype into a usable CLI with profiles, provider selection, and extensions.

23. Hosted Harness: Sandbox, Cron, Durable Execution, and Remote Deployment
    Move from local runs to hosted execution.

24. Agent Harness Terminology Map
    Close the series with a shared vocabulary for design, debugging, and discussion.

Star History