Frontend · Backend · Agent

AI Agents Are Just a Brain and a Harness — Here's the Harness

By 不一样的少年_ · Jul 13, 2026

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Most developers use AI coding tools as black boxes. Building the harness by hand exposes exactly where the model's autonomy ends and the engineering begins — file I/O, tool dispatch, error recovery — which is the part that determines whether an agent is safe and useful in production.

Summary

The core of any AI coding agent — Cursor, Claude Code, or a custom tool — is a large model paired with a harness. The model supplies reasoning; the harness supplies file access, command execution, safety limits, and retry logic. Without the harness, the model can only chat. This series builds that harness from scratch in TypeScript, starting with the simplest possible pipeline: a Node.js CLI that reads a prompt, calls an OpenAI-compatible API, and prints the response.

The first installment sets up the project, configures TypeScript, and writes three single-responsibility modules: config loading, a chat client wrapper around the OpenAI SDK, and a CLI entry point that parses `-prompt` from `process.argv`. The result is a working command-line assistant that answers one question at a time.

It is not yet an agent — it cannot read files, run commands, or loop on failures. Those capabilities come next, when the harness gains a toolbox the model can invoke. The article frames the entire series as a deliberate demystification: agents are not magic, just a disciplined engineering loop around an API call.

Takeaways

— An AI agent is a large language model (the brain) plus a harness (the reins) that provides tools, constraints, and execution loops.

— Without a harness, a model can only chat; the harness gives it the ability to read files, run commands, and retry after failures.

— The minimum viable harness is a single-turn CLI that loads an OpenAI-compatible config, sends a prompt, and prints the response.

— OpenAI-compatible APIs are a universal interface: changing baseURL and apiKey switches between DeepSeek, GLM, Kimi, and most Chinese models without code changes.

— Node.js 21+, TypeScript with ES modules, and the openai npm package are the only dependencies for the initial build.

— The project enforces single-responsibility files from the start — config.ts, chat.ts, main.ts — so adding tools later does not create a monolith.

Conclusions

Demystifying agents as a model-plus-harness formula lowers the barrier to building custom coding tools; the harness is just structured I/O and control flow around an API call.

OpenAI's API format has become a de facto standard that domestic Chinese models follow, which means a single client abstraction works across providers — a practical detail often glossed over in agent discussions.

Starting with a single-turn CLI before adding tools is a deliberate pedagogical choice: it forces the builder to understand the request-response loop before introducing the complexity of tool-calling and multi-step reasoning.

Concepts & terms

Harness

In AI agent architecture, the harness is the engineering layer that wraps a large language model. It provides tool access (file I/O, terminal commands), safety constraints, and execution loops — everything the model needs to act beyond generating text.

OpenAI-compatible API

A de facto standard for LLM APIs where the request and response formats match OpenAI's chat completions endpoint. Many Chinese models (DeepSeek, GLM, Kimi) implement this protocol, allowing a single client to switch providers by changing only the base URL and API key.

process.argv

A Node.js built-in array containing the command-line arguments passed to a script. The first two elements are the Node binary path and the script path; actual user arguments start at index 2, commonly extracted with .slice(2).

Source: juejin.cn ↗ Google Translate ↗ Backup ↗