跳到正文
DEV Community· Roi Dayan·· 10 小時前AI 評分51

Agent harness 是甚麼?日常例子入門指南

What is an agent harness? A plain-English guide, with everyday examples

AI 導讀

文章解釋,Agent harness 是包圍模型的程式,透過工具及 agent loop 讓模型輸出轉化為實際操作。Harness 亦負責處理權限、指令檔和上下文管理。作者指出,Moontors 並非 harness,而是可同時運行多個供應商原生 harness 的 agentic development environment(ADE)。

正文

If you read about AI coding tools, you keep meeting the word harness. "Claude Code's harness." "A better harness beats a better model." "Build your own harness." It sounds technical, but the idea is simple, and once you have it, a lot of AI news makes more sense.

Here's the short version: a model can only write text. The harness is the program around it that lets that text do things. Claude Code, Codex, Gemini CLI, Grok Build and OpenCode are harnesses.

The rest of this post explains that with everyday examples first, then a small technical one.

Where the word comes from

A horse is strong, but a horse in a field doesn't move your cart. A harness is the straps, collar and reins that connect the horse to the cart and let the driver steer it.

AI works the same way. The model (Claude, GPT, Gemini, Grok) is the horse: lots of power, no direction, no way to touch anything. The harness connects that power to your work, and gives you the reins.

What a model alone can do

On its own, a model does one thing: you give it text, it gives you text back.

Ask it "what's in my package.json?" and it can't tell you. It can't see your computer. It can only guess, or say it doesn't know. It can't run your tests, open a file, or save a change. It writes words, and that's all.

So how does Claude Code fix a bug in your project? Not with a smarter model. With a harness.

You've already been a harness

Remember helping a relative fix their Wi-Fi over the phone?

You know routers, but you can't see theirs. So the call goes like this:

  1. You: "What lights are on?"
  2. Your aunt looks and reads them out: "The red one's blinking."
  3. You: "Unplug it, count to ten, plug it back in."
  4. Your aunt: "Wait, will that delete anything?" You say it won't. She does it.
  5. You: "What lights now?" "All green." "Great, you're done."

You're the model: you know what to do, but you can't touch anything. Your aunt is the harness: she does what you ask, tells you what happened, and checks before anything scary. Neither of you fixes the Wi-Fi alone. Together you do.

That back-and-forth is called the agent loop, and running it is the harness's main job.

The harness's five jobs

1. Hands: tools

The harness gives the model tools: read a file, edit a file, run a command, search the web. The model can't use them directly. It writes a request ("run npm test"), and the harness runs it.

Everyday version: your aunt's hands.

2. The loop

The harness runs the request, hands the result back to the model, and asks for its next step. It repeats until the model stops asking for tools and just answers.

Everyday version: "What lights now?"

3. Rules: permissions

The harness decides what the model may do without asking. Claude Code, for example, asks you before it runs a command or edits a file you haven't allowed. You say Allow or Deny.

Everyday version: "Wait, will that delete anything?"

4. Notes: instruction files

Every time a model starts, it knows nothing about your project. So the harness reads it a note first: CLAUDE.md for Claude Code, AGENTS.md for Codex, GEMINI.md for Gemini CLI. That's where you write "we use pnpm" or "never touch the legacy/ folder".

Everyday version: the note on the fridge for the babysitter. Bedtime is 8, no sweets, the cat bites.

5. Memory: the context

A model can only hold so much text at once, called its context. In a long session, the harness decides what stays in. When it fills up, the harness has the model summarise the conversation so far and carries on from the summary. Claude Code and Codex call this /compact.

Everyday version: meeting minutes. Nobody remembers the whole three-hour meeting, but everyone can read the one page of notes.

The technical version, in fifteen lines

Here's the shape every harness shares. This isn't any real SDK, just the idea, in Python-like code:

messages = [your_task]

while True:
    reply = model(messages, tools=TOOLS)   # the model only writes text
    messages.append(reply)

    if not reply.tool_calls:               # no tool asked for: it's done
        break

    for call in reply.tool_calls:
        if needs_permission(call) and not ask_you(call):
            result = "The user said no."
        else:
            result = run(call)              # read a file, run a command...
        messages.append(result)

print(reply.text)

And here's one real-looking trip around that loop, for "the tests fail, fix them":

  1. Model: run npm test. Harness runs it, hands back: expected 3, got 4 in sum.test.js.
  2. Model: read sum.js. Harness hands back the file.
  3. Model: change a + b + 1 to a + b. Harness asks you, you click Allow, it saves the edit.
  4. Model: run npm test. Harness hands back: all tests pass.
  5. Model: "Fixed: sum added 1 by mistake." No tool asked for, so the loop ends.

The model wrote five short messages. The harness did all the actual work.

A real harness does much more around that loop: dozens of tools, subagents, hooks, plugins, skills, and sessions you can resume. Anthropic even offers Claude Code's as a library: its Agent SDK gives you "the same tools, agent loop, and context management that power Claude Code". That's the harness.

Why people say the harness matters as much as the model

Put the same model in two harnesses and you get two different tools. One reads your project's notes, the other doesn't. One has a good file-editing tool, the other rewrites whole files. One asks before rm -rf, the other doesn't. Same horse, different harness, different ride.

That's why each vendor builds its own and tunes it for its own models: Anthropic's is Claude Code, OpenAI's is Codex, Google's is Gemini CLI, xAI's is Grok Build. Others are built for any model: OpenCode is an open-source harness that connects models from 200+ providers, Claude, GPT and Gemini among them.

So where does Moontors fit?

Moontors is the tool I build, and it isn't a harness. It doesn't replace any of the above. It runs each vendor's own harness, as the vendor ships it: Claude Code's own command-line agent on your Claude subscription, Codex on your ChatGPT sign-in, Gemini CLI, Grok Build and OpenCode, each with your own settings, skills and MCP servers.

What Moontors adds is the place to run many of them at once, which is called an agentic development environment (ADE). Back to the phone call: if every agent is a helper on a call, Moontors is the switchboard.

  • Every session on one board. Each agent is a live card, its work streaming as it goes, with the ones waiting for you counted at the top. See Sessions and the board.
  • Calls that don't drop. Sessions keep working when you close the window. See Keep agents running.
  • Helpers who talk to each other. A Claude Code session can hand work to a Codex session and hear back. See Sessions messaging each other.
  • Their own desks. Each session can work in its own git worktree, so two agents don't trip over each other's changes.
  • Take a call from anywhere. The phone app follows your sessions and lets you answer them away from your desk. It's on Google Play now, and the iPhone app is coming soon.

It's free, with no Moontors account, on macOS, Windows and Linux.

Cheat sheet

Word Everyday version In coding agents
Model The horse; the expert on the phone Claude, GPT, Gemini, Grok
Harness The straps and reins; your aunt with the router Claude Code, Codex, Gemini CLI, Grok Build, OpenCode
Tool Her hands Read a file, edit a file, run a command
Agent loop "What lights now?" Ask for a tool, get the result, ask again
Permission "Will that delete anything?" Allow or Deny
Instruction file The note on the fridge CLAUDE.md, AGENTS.md, GEMINI.md
Context and compaction Meeting minutes /compact
ADE The switchboard Moontors

Next time someone says "it's the harness, not the model", you'll know what they mean: the model knows what to do, and the harness is how it gets done. And once you're running more than one, that's what Moontors is for: every agent, as its vendor ships it, on one board.


AI did the writing, I did the reading, and we both took credit.

來源:DEV Community · dev.to