> Harness EngineeringHarness EngineeringHarness Engineering The engineering outside the model模型之外的工程模型之外的工程

1.2

Tool calling, and designing tools for an agentTool calling,和給 agent 設計工具Tool calling,以及怎么给 agent 设计工具

This chapter assumes you know that an AI coding agent can read files and run commands. You do not need to know how.

讀這一章,只需要知道 AI 寫程式 agent 能讀檔案、執行指令。怎麼做到的,不用知道。

读这一章,只需要知道写代码的 AI agent 能读文件、跑命令。不需要知道它是怎么做到的。

The Knowledge經驗分享经验分享

In one sentence

A model only asks for a tool call; the program around it runs the tool. So a tool is an interface for an unreliable user, and its description and error messages decide whether it is used well.

一句話

模型只是要求呼叫工具;執行工具的,是它周圍的程式。所以工具是給一個不可靠的使用者用的介面,它的描述和錯誤訊息,決定它能不能被用好。

一句话

模型只负责提出工具调用,运行工具的是它外面的程序。所以工具是给一个不可靠的用户用的接口,它的描述和报错信息,决定了它能不能被用好。

For leaders

  • The decision: treat the tools you give an agent as a product that needs a good description and good error messages, and decide which fixed steps go into a command, not a prompt.
  • The risk: the model only guesses from a tool's name and description, so a vague tool is used wrongly or never. A rule written in a prompt is a request; a step done by a command cannot be skipped on that path.
  • The cost of doing it right: rewriting descriptions and error messages is small. A command is code someone has to maintain. Anthropic suggests five real tasks are enough to start testing tools.
  • Ask the team: "If you read only the name and description of each tool, would you know when to use it? What does its error say?"

給主管

  • 要做的決定:把你給 agent 的工具當成產品,需要好的描述和好的錯誤訊息;並決定哪些固定的步驟,放進指令(command)裡,不放進 prompt 裡。
  • 風險:模型只能從工具的名字和描述去猜,所以含糊的工具會被用錯,或從來沒被用到。寫在 prompt 裡的規則是請求;由指令做的步驟,在那條路徑上沒辦法被跳過。
  • 做對的成本:重寫描述和錯誤訊息,成本很小。指令是程式碼,要有人維護。Anthropic 建議,五個真實的任務,就夠開始測試工具了。
  • 可以問團隊:「如果只讀每個工具的名字和描述,你知道什麼時候該用它嗎?它的錯誤訊息說了什麼?」

写给管理者

  • 要拍板的事:把你给 agent 的工具当成一个产品来对待,它需要好的描述和好的报错信息;并且决定哪些固定的步骤写进命令,而不是写进 prompt。
  • 风险:模型只能根据工具的名字和描述去猜,所以含糊的工具会被用错,或者根本没人用。写在 prompt 里的规则是请求;由命令完成的步骤,在这条路径上跳不过去。
  • 做对的代价:重写描述和报错信息,花费很小。命令是代码,得有人维护。Anthropic 建议,五个真实的任务就足够开始测试工具了。
  • 可以问团队:“如果只看每个工具的名字和描述,你能知道什么时候该用它吗?它的报错信息又是怎么说的?”

The problem

When you watch an agent edit a file, it looks as if the model did it. It did not. A language model is a program that takes in text and produces text. It cannot open a file, run a command or send a request. It has no hands.

What it can do is write a sentence that means "please call the tool read_file with the path src/app.py". That sentence is the tool call. The program around the model (the harness, in the first sense from chapter 0.1) reads the sentence, does the work, and puts the result back into the conversation as more text. The model then reads that result and decides what to do next.

This looks like a technical detail, but it changes how you should think about tools. Every action an agent takes passes through a call that the program could inspect, refuse or change. And the model is not a careful programmer calling a function: it is a reader guessing from a description. Treat it like a user who skims.

Three words first

  • A tool is one action the agent may ask for: read a file, search, edit a file, run a command, fetch a web page.
  • A tool call is the model's request to use one, with the arguments it chose.
  • A tool result is the text the program sends back after running it.

One round trip

the model the program around it the tool asks: read_file(src/app.py) runs the tool can allow, change or refuse here file contents the result, as text
  1. The model writes a request: which tool, which arguments. It does nothing else.
  2. The program around it runs the tool. This is the point where a rule can allow, change or refuse the call.
  3. The tool returns something: file contents, a command's output, or an error.
  4. The program puts the result into the conversation as text. The model reads it and decides what to do next.
One tool call. The model only asks; the program around it does the work, and can step in before and after.

The provider's own documentation describes the same round trip: the model answers with a stop reason of tool_use and a block that names the tool and its arguments; your code runs it and sends back a tool_result. (Tool use overview) One exception is worth knowing: some server tools, such as web search, run on the provider's side, so you never handle the call yourself. Most of what an agent in your editor does are client tools, run on your machine. The difference matters for this chapter: for a server tool, you cannot step in before or after it runs, because the program never sees the call.

問題

看 agent 改檔案的時候,好像是模型做的。其實不是。語言模型是一個吃進文字、吐出文字的程式。它不能打開檔案、執行指令或送出請求。它沒有手。

它能做的,是寫出一句話,意思是「請用路徑 src/app.py 呼叫工具 read_file」。這句話就是工具呼叫。模型周圍的程式(harness,用的是 差距在模型外面 裡的第一個意思)讀這句話,做事,再把結果當成更多文字放回對話裡。然後模型讀這個結果,決定下一步。

這看起來是個技術細節,但它改變了你該怎麼想工具。agent 做的每個動作,都經過一次呼叫,而程式可以檢查、拒絕或修改這次呼叫。而且模型不是在呼叫函式的謹慎程式設計師:它是根據描述去猜的讀者。把它當成一個只會快速瀏覽的使用者。

先講三個詞

  • 工具是 agent 可以要求的一個動作:讀檔案、搜尋、改檔案、執行指令、抓一個網頁。
  • 工具呼叫是模型要求用其中一個,附上它選的參數。
  • 工具結果是程式執行之後送回來的文字。

一次來回

模型 外面的程式 工具 read_file(src/app.py) 執行工具 這裡可以放行、修改 或拒絕 檔案內容 結果,以文字形式
  1. 模型寫出一個請求:用哪個工具、什麼參數。它不做別的。
  2. 外面的程式去執行工具。規則可以在這一步放行、修改或拒絕這次呼叫。
  3. 工具回傳東西:檔案內容、指令的輸出,或一個錯誤。
  4. 程式把結果當成文字放進對話。模型讀完,決定下一步。
一次工具呼叫。模型只提出請求;外面的程式做事,並且在前後都能插手。

供應商自己的文件也描述了同樣的來回:模型回答時帶著停止原因 tool_use,以及一個寫出工具名和參數的區塊;你的程式執行它,再送回 tool_result。(Tool use overview)有一個例外值得知道:有些 server tool(例如網頁搜尋)是在供應商那邊執行的,所以你自己永遠碰不到那次呼叫。你編輯器裡的 agent 做的大部分事,是 client tool,在你的機器上執行。這個差別對這一章很重要:對 server tool,你沒辦法在它執行之前或之後插手,因為程式從來看不到那次呼叫。

问题

看着 agent 改文件,会觉得是模型干的。其实不是。语言模型是一个读入文本、产出文本的程序。它打不开文件,运行不了命令,也发不出请求。它没有手。

它能做的,是写一句话,意思是“请调用工具 read_file,路径是 src/app.py”。这句话就是工具调用。模型外面的程序(差距在模型外面里第一种意思的 harness)读到这句话,把事情做完,再把结果作为更多文本放回对话里。然后模型读这个结果,决定下一步做什么。

这看起来像个技术细节,却改变了你该怎么看待工具。agent 的每个动作,都要经过一次调用,而程序可以检查、拒绝或修改这次调用。而且模型也不是一个认真的程序员在调用函数:它是一个靠描述来猜的读者。把它当成一个只会扫一眼的用户。

先说三个词

  • 工具是 agent 可以要求做的一个动作:读文件、搜索、改文件、运行命令、抓取网页。
  • 工具调用是模型请求使用一个工具,带着它选的参数。
  • 工具结果是程序运行完工具之后送回来的文本。

一次来回

模型 外面的程序 工具 read_file(src/app.py) 运行工具 这里可以放行、修改 或拒绝 文件内容 结果,以文本形式
  1. 模型写出一个请求:用哪个工具、什么参数。它不做别的。
  2. 外面的程序去运行工具。规则可以在这一步放行、修改或拒绝这次调用。
  3. 工具返回东西:文件内容、命令的输出,或一个错误。
  4. 程序把结果当成文本放进对话。模型读完,决定下一步。
一次工具调用。模型只提出请求;外面的程序做事,并且在前后都能插手。

模型提供方自己的文档讲的是同一个来回:模型回复时,停止原因是 tool_use,并带着一个写明工具名和参数的块;你的代码运行它,再送回一个 tool_result。(Tool use overview)有一个例外值得知道:有些服务端工具,比如网页搜索,是在提供方那边运行的,所以你从头到尾碰不到这次调用。你编辑器里的 agent 做的大部分事,是客户端工具,在你的机器上运行。这个区别对本章很要紧:对服务端工具,你没法在它运行之前或之后插手,因为程序根本看不到这次调用。

How it works

Where you can step in

Because the program sits between the request and the action, there are two places to step in:

  • Before the tool runs. The program can let the call through, refuse it, or change it. A hook (chapter 2.2) is the usual way to do that, and a refusal comes with a reason that goes back to the agent.
  • After it runs. The program can shorten, filter or add to the result before the model reads it.

That is the main reason it is possible to enforce rules on an agent at all. A rule that lives in the program is code that runs; a rule in a prompt is a request (chapter 4.1).

The rest of this chapter is about the middle of that trip: what the model sees and what it gets back. Both are text you write.

A tool is an interface for an unreliable user

A person using a command line can read documentation, ask a colleague, and notice that something looks wrong. The model has the tool's name, a short description, and the list of parameters. That is all. It can guess wrongly, and the provider's documentation says so: given a tool that needs a location and a request that does not give one, a model might make one up. (Tool use overview)

So designing a tool for an agent is designing for someone who:

  • reads only the name and description to decide when to use it,
  • fills the arguments by guessing from context,
  • does not know what the tool does not tell it,
  • reads the result as text, with whatever room it takes in the context window.

Anthropic's advice on writing tools for agents says the same in other words: "Even small refinements to tool descriptions can yield dramatic improvements." (Writing tools for agents) The five rules below follow from it.

1. Write the description like a brief for a new hire

Say what the tool does, when to use it, and when not to. Make names unambiguous: a parameter called user can mean a name, an ID or an email; user_email cannot. If two tools look alike, say in each one how it differs. The description is the only place the model learns this, so a vague one means the tool is used wrongly or never.

2. Write errors for the agent to read

A person can look at a stack trace and think. A model gets the text and goes on. If the error is Error 400, the model guesses, often the same thing again. If the error says what was wrong and what to try next, it fixes the call.

The same goes for a refusal: say what to do instead (chapter 4.2).

3. Keep the output short, and let it be paged

Everything a tool returns is put in the context window (chapter 3.1), and it is read again on every later turn (chapter 1.1). A tool that returns a whole large file when the agent wanted one line wastes tokens, and it can crowd useful things out of the window.

So give results sensible limits: a default cap, a way to ask for a range or the next page, a filter. Anthropic also describes letting the agent choose between a concise and a detailed response. And when you have many tools, grouping related ones under a common name prefix helps the agent tell them apart. (Writing tools for agents) Claude Code caps tool responses at 25,000 tokens by default (Anthropic's figure at the time of writing). When you cut the output, say so, and tell the agent how to narrow its query. (Writing tools for agents)

4. Fewer tools choose better

Every tool's name, description and parameters are sent to the model on every call. More tools cost more tokens and give more chances to pick the wrong one, especially when they overlap. Prefer a small set that is clearly different, and merge related operations into one where you can. (Writing tools for agents)

5. Do the fixed steps in a command, not in a prompt

This is the one I would stress most. Sometimes a job has steps that always go the same way and where there is a right and wrong: make the folder for a new task, copy the files, compute a hash, write the record, check that everything is ready before writing back. You can describe those steps in the instructions and ask the agent to follow them. It will, most of the time.

Or you can write them once as a command: a small program the agent runs as a tool. The command does the steps, checks the preconditions itself, and returns a short result. On the path through the command, the agent cannot skip a step and cannot write a wrong state, because it never writes it.

In the prompt 1. check folder is clean 2. copy the files 3. write the record May skip or reorder steps In a command agent runs one command checks preconditions copies the files writes the record Same steps every time A short result comes back
The same job, two ways. Asking the model to follow steps is a request; a command that does them is code.

The fit is for steps that need no judgment. If a step needs the agent to decide something, leave that part to the agent and let the command do only what is fixed around it. This is what my harness does. A command line creates a task folder (the unit of work in Manage tasks, not chats), fetches files, works out diffs and counts checks, and the model only runs the command and reads the answer. Progress is a good example: the task list reads a data file that commands write, and not the Markdown notes an agent wrote by hand, because hand-written progress misses ticks and goes wrong. The result is the same every time, and the model does not have to get the steps right.

Two details make a command friendly to an agent:

  • A result that says what comes next. The command's output tells the agent what to do next, so it does not have to guess.
  • Text for people, JSON for scripts. The same command prints aligned text in a terminal and JSON when it is piped. The fields are the same.

A command only helps if the agent actually uses it, and it only guards what goes through it. If the agent can do the same thing another way (edit the file by hand), the command is a convenience, not a limit. Chapter 4.1 takes that further.

Test your own setup

Three questions for any tool you give an agent:

  1. If you read only its name and description, would you know when to use it and when not to?
  2. When it fails, does the message tell the agent what to do next?
  3. How big can its output be, and what happens to the context if it is large?

A zero-install experiment. Ask the agent to call one of your tools in a way that you know is wrong, and read what comes back. Is it clear enough that you would know what to do if you were the agent? If not, that is the message to rewrite.

A bigger loop, if you build tools. Anthropic's method is the same idea at scale: write tasks drawn from real use, run them, read the raw transcripts (the calls and the results, not only the final answer), and fix the descriptions and errors where the agent went wrong. Five tasks are enough to start. (Writing tools for agents)

原理

你能在哪裡插手

因為程式站在請求和動作之間,有兩個地方可以插手:

  • 工具執行之前。程式可以放行、拒絕或修改這次呼叫。通常的辦法是用 hook(Hooks:每次呼叫都會經過的執行點),而拒絕會附上一個原因,回到 agent 那裡。
  • 執行之後。程式可以在模型讀到結果之前,縮短、過濾或補充它。

這是能對 agent 執行規則的主要原因。放在程式裡的規則,是會執行的程式碼;寫在 prompt 裡的規則,是請求(提示裡的規則只是請求)。

這一章其餘的部分,講這趟來回的中間:模型看到什麼,拿回什麼。兩者都是你寫的文字。

工具是給不可靠使用者的介面

人在用命令列時,可以讀文件、問同事,也會注意到哪裡看起來不對。模型有的只是工具的名字、一段簡短的描述,和參數清單。就這樣。它可能猜錯,供應商的文件也這麼說:給它一個需要地點的工具,而請求裡沒有地點,模型可能會編一個。(Tool use overview)

所以替 agent 設計工具,是在為這樣的人設計:

  • 只讀名字和描述,來決定什麼時候用,
  • 靠從上下文猜來填參數,
  • 不知道工具沒告訴它的事,
  • 把結果當文字讀,結果占多少上下文視窗的空間,就占多少。

Anthropic 寫給 agent 的工具的建議,用別的話說了一樣的事:「就算只是把工具描述稍微改好,也能帶來很大的進步。」(Writing tools for agents)下面的五條規則由此而來。

1. 描述要寫得像給新同事的交辦單

寫清楚這個工具做什麼、什麼時候用、什麼時候不用。名字不要有歧義:叫 user 的參數,可能是名字、ID 或 email;叫 user_email 就不會。如果兩個工具看起來很像,在每一個裡都說明它哪裡不同。模型只能在描述裡學到這些,所以含糊的描述,就是工具被用錯,或從來沒被用到。

2. 錯誤訊息要寫給 agent 讀

人看到堆疊追蹤會思考。模型拿到文字就繼續。如果錯誤訊息是 Error 400,模型就會猜,常常又猜同一件事。如果錯誤訊息寫了哪裡錯、接著可以試什麼,它就會修好這次呼叫。

拒絕也一樣:寫明該改做什麼(詢問不是限制)。

3. 輸出要短,而且能分頁

工具回傳的所有東西,都會放進上下文視窗(上下文是一份預算),而且之後每一輪都會再讀一遍(選模型:算的是每次成功的成本)。agent 只想要一行,工具卻回傳整個大檔案,就浪費 token,還可能把有用的東西擠出視窗。

所以結果要有合理的限制:預設的上限、要求某個範圍或下一頁的辦法、一個過濾條件。Anthropic 也描述過,讓 agent 在簡潔和詳細的回應之間選。而且工具很多的時候,把相關的工具用共同的名字前綴分組,能幫 agent 分辨它們。(Writing tools for agents)Claude Code 預設把工具回應限制在 25,000 個 token(這是我寫作時 Anthropic 的數字)。你截掉輸出的時候,要說出來,並告訴 agent 怎麼把查詢範圍縮小。(Writing tools for agents)

4. 工具少,選得更準

每個工具的名字、描述和參數,每次呼叫都會送給模型。工具越多,花的 token 越多,選錯的機會也越多,尤其是它們功能重疊的時候。偏好一小組明顯不同的工具,能合併的相關操作就合併成一個。(Writing tools for agents)

5. 固定的步驟,放進指令裡,不放進 prompt 裡

這是我最想強調的一條。有時一件工作,有些步驟永遠是同一個走法,而且有對有錯:為新任務建資料夾、複製檔案、算雜湊值、寫紀錄、寫回去之前檢查一切就緒。你可以在指令裡描述這些步驟,請 agent 照做。它大多數時候會照做。

或者你可以把它們寫成一次的指令:一個 agent 當工具執行的小程式。指令做這些步驟,自己檢查前置條件,回傳一個簡短的結果。在經過這個指令的路徑上,agent 沒辦法跳過一步,也寫不出錯的狀態,因為它根本沒有寫。

寫在提示裡 1. 確認資料夾是乾淨的 2. 複製檔案 3. 寫下紀錄 agent 可能跳步或換順序 寫成命令 agent 跑一條命令 檢查前置條件 複製檔案 寫下紀錄 每次步驟都一樣 回來一個很短的結果
同一件事的兩種做法。叫模型照步驟做是請求;由命令來做是程式碼。

這適合不需要判斷的步驟。如果某一步需要 agent 決定什麼,就把那部分留給 agent,讓指令只做周圍固定的部分。我的 harness 就是這樣。一條命令列指令建立任務資料夾(工作的單位,見 管任務,不管對話)、抓檔案、算 diff、數檢查的次數,而模型只執行指令、讀答案。進度是個好例子:任務清單讀的是指令寫入的資料檔,不是 agent 手寫的 Markdown 筆記,因為手寫的進度會漏打勾、會出錯。結果每次都一樣,模型也不用把步驟做對。

兩個細節讓指令對 agent 友善:

  • 結果要說明接下來是什麼。指令的輸出告訴 agent 下一步做什麼,它就不用猜。
  • 給人的是文字,給腳本的是 JSON。同一個指令,在終端機裡印出對齊的文字,透過管線接出去時印出 JSON。欄位是一樣的。

指令只有在 agent 真的用它的時候才有幫助,而且它只守得住經過它的東西。如果 agent 能用別的辦法做同一件事(手動改檔案),指令就只是方便,不是限制。提示裡的規則只是請求 把這一點講得更深。

測你自己的設定

對你給 agent 的任何工具,問三個問題:

  1. 如果只讀它的名字和描述,你知道什麼時候該用、什麼時候不該用嗎?
  2. 它失敗的時候,訊息有沒有告訴 agent 接下來做什麼?
  3. 它的輸出最大可以多大?大的時候,上下文會怎樣?

一個不用安裝任何東西的實驗。請 agent 用一個你知道是錯的方式,呼叫你的某個工具,讀回來的是什麼。如果你是 agent,這個訊息夠不夠清楚,讓你知道該做什麼?如果不夠,那就是要重寫的訊息。

更大的迴圈,如果你自己做工具。Anthropic 的方法是同一個想法放大:寫出取材自真實使用的任務,執行它們,讀原始的紀錄(呼叫和結果,不只是最後的答案),並在 agent 出錯的地方修好描述和錯誤訊息。五個任務就夠開始。(Writing tools for agents)

原理

你能在哪里插手

程序夹在请求和动作之间,所以有两个地方可以插手:

  • 工具运行之前。程序可以放行这次调用,拒绝它,或者修改它。常用的办法是 hook(Hook:每次调用都会经过的执行点),拒绝时会带上一个原因,送回给 agent。
  • 运行之后。程序可以在模型读到结果之前,对结果做精简、过滤或补充。

这是能对 agent 强制执行规则的主要原因。放在程序里的规则是会运行的代码;放在 prompt 里的规则是请求(提示里的规则只是请求)。

这一章其余的部分,讲的是这趟来回的中间:模型看到什么,又拿回什么。这两样都是你写的文本。

工具是给不可靠用户的接口

人用命令行,可以看文档,可以问同事,还能注意到哪里看着不对。模型有的只是工具的名字、一段简短的描述和参数列表。仅此而已。它可能猜错,提供方的文档也这么说:给一个需要位置的工具,而请求里没给位置,模型可能会编一个。(Tool use overview)

所以给 agent 设计工具,是在给这样的人设计:

  • 只看名字和描述,来决定什么时候用,
  • 靠上下文猜着填参数,
  • 不知道工具没告诉它的事,
  • 把结果当文本来读,结果占多少上下文窗口,就占多少。

Anthropic 关于给 agent 写工具的建议,换了个说法讲的是同一件事:“哪怕对工具描述做很小的改进,也能带来显著的提升。”(Writing tools for agents)下面的五条规则都由此而来。

1. 把描述写得像给新员工的交接说明

说清楚这个工具做什么、什么时候用、什么时候不用。名字要无歧义:叫 user 的参数,可能是名字、ID 或邮箱;user_email 就不会。如果两个工具看起来很像,就在各自的描述里说明它们哪里不同。描述是模型了解这些的唯一地方,所以含糊的描述,意味着工具会被用错,或者没人用。

2. 报错信息要写给 agent 看

人看到堆栈,会停下来想。模型拿到的是文本,然后继续往下走。如果报错是 Error 400,模型就会猜,往往又猜出同样的东西。如果报错说明了哪里不对、接下来该试什么,它就会把调用改对。

拒绝也一样:要说明应该改做什么(询问不是限制)。

3. 输出要短,还要能分页

工具返回的所有东西,都会放进上下文窗口(上下文是一份预算),而且之后每一轮都要再读一遍(选模型:看每次成功的成本)。agent 只想要一行,工具却把一个很大的文件整个返回,既浪费 token,还可能把有用的东西挤出窗口。

所以要给结果设合理的限制:默认的上限、取某个范围或下一页的办法、过滤器。Anthropic 还提到,可以让 agent 在简洁回复和详细回复之间选。工具很多的时候,把相关的工具用同一个名字前缀归在一起,有助于 agent 区分它们。(Writing tools for agents)Claude Code 默认把工具的响应限制在 25,000 个 token 以内(这是 Anthropic 写这篇文章时给出的数字)。你截短输出时,要说明这一点,并告诉 agent 怎么缩小查询范围。(Writing tools for agents)

4. 工具少,选得更准

每个工具的名字、描述和参数,每次调用都要发给模型。工具越多,花的 token 越多,选错的机会也越多,尤其是功能重叠的时候。优先用一小组明显不同的工具,能把相关的操作合并成一个就合并。(Writing tools for agents)

5. 固定的步骤写进命令,不写进 prompt

这一条是我最想强调的。有时候,一件事里有些步骤每次都一样,而且有对错之分:给新任务建文件夹、复制文件、算一个哈希、写入记录、写回之前检查一切就绪。你可以在指令里描述这些步骤,让 agent 照着做。它大多数时候会照做。

或者,你可以把它们一次性写成一个命令:一个 agent 当作工具来运行的小程序。命令自己完成这些步骤,自己检查前置条件,返回一个简短的结果。走命令这条路径时,agent 跳不过任何一步,也写不出错误的状态,因为状态不是它写的。

写在 prompt 里 1. 确认文件夹是干净的 2. 复制文件 3. 写入记录 agent 可能跳步或换顺序 写成命令 agent 运行一条命令 检查前置条件 复制文件 写入记录 每次步骤都一样 返回一个很短的结果
同一件事的两种做法。叫模型照步骤做是请求;由命令来做是代码。

这适合不需要判断的步骤。如果某一步需要 agent 做决定,就把那部分留给 agent,让命令只做它周围固定的部分。我的 harness 就是这么做的。一个命令行工具建任务文件夹(任务是管任务,不管对话里的工作单元)、取文件、算 diff、统计检查,模型只要运行命令、读结果。进度是个好例子:任务清单读的是命令写入的数据文件,而不是 agent 手写的 Markdown 笔记,因为手写的进度会漏打勾,也会出错。结果每次都一样,模型也不必保证每一步都做对。

有两个细节,让命令对 agent 更友好:

  • 结果里说明下一步。命令的输出告诉 agent 接下来做什么,它不用去猜。
  • 给人看文本,给脚本用 JSON。同一个命令,在终端里打印对齐的文本,通过管道输出时打印 JSON。字段是一样的。

命令只有 agent 真去用才有帮助,而且它只守得住经过它的东西。如果 agent 能用另一种办法做同样的事(手动改文件),这个命令就只是个方便,不是限制。提示里的规则只是请求会往下讲这一点。

测一测你自己的配置

给 agent 的任何工具,都问三个问题:

  1. 只看它的名字和描述,你知道什么时候该用、什么时候不该用吗?
  2. 它失败的时候,信息有没有告诉 agent 接下来做什么?
  3. 它的输出最大能有多大?如果很大,上下文会怎么样?

一个不用安装任何东西的实验。让 agent 用一种你知道是错的方式调用你的某个工具,然后看返回了什么。它够不够清楚,让你如果是 agent 也知道该怎么办?如果不够,就是这条信息该重写。

更大的循环,如果你在做工具。Anthropic 的方法是同一个想法的放大版:根据真实使用写出任务,运行它们,读原始的记录(调用和结果,不只是最终答案),然后在 agent 出错的地方修描述和报错信息。五个任务就够开始了。(Writing tools for agents)

Costs and traps

Good descriptions cost tokens, too. A long description is sent on every call. Write what the model needs to choose and use the tool, and put the long manual in a file the agent reads when needed.

A command is code to maintain. If your project changes, the command can be wrong in a way a prompt cannot. Keep each one small, and give it a test.

A tool call is not a trusted act. The model chose the arguments, after reading text that may have come from anywhere. Do not treat a call as the user's wish. Chapter 4.6 explains why.

Tool names change between versions. If your rules or hooks match on tool names, keep the mapping in one place so a rename means one change.

代價和陷阱

好的描述也要花 token。長的描述每次呼叫都會送出去。寫模型選工具和用工具需要的就好,長的手冊放在 agent 需要時才讀的檔案裡。

指令是要維護的程式碼。專案變了,指令可能出錯,而 prompt 不會這樣。每個指令都保持小,並給它一個測試。

工具呼叫不是可信的行為。參數是模型選的,而且是讀了可能來自任何地方的文字之後選的。別把一次呼叫當成使用者的意願。agent 讀到的文字可能在指揮它 說明了原因。

工具名稱會隨版本改變。如果你的規則或 hook 靠工具名稱比對,把對應關係放在一個地方,改名時就只要改一處。

代价和坑

好的描述也要花 token。长描述每次调用都要发一遍。只写模型选择和使用这个工具所需要的内容,长的说明书放在文件里,让 agent 需要时再读。

命令是要维护的代码。项目变了,命令可能出错,而且是 prompt 不会有的那种错。每个命令都保持小,并且给它写测试。

一次工具调用不是一个可信的行为。参数是模型选的,而它读到的文本可能来自任何地方。别把一次调用当成用户的意愿。agent 读到的文字可能在指挥它解释了为什么。

工具名在不同版本之间会变。如果你的规则或 hook 按工具名来匹配,就把这个映射放在一个地方,这样改名只需改一处。

What the industry says Industry practice

  • Anthropic: tool design is part of the work, and descriptions and error messages deserve testing like code. (Writing tools for agents)
  • Tool use documentation: the application runs client tools and sends back results; the model "might guess values you didn't supply". (Tool use overview)

They agree with the argument here: the tool is an interface, and its text is part of the interface.

業界怎麼說 業界做法

  • Anthropic:工具設計是工作的一部分,描述和錯誤訊息值得像程式碼一樣測試。(Writing tools for agents)
  • Tool use 文件:應用程式執行 client tool 並送回結果;模型「可能會猜出你沒有提供的值」。(Tool use overview)

它們和這裡的論點一致:工具是介面,它的文字是介面的一部分。

业界怎么说 业界做法

  • Anthropic:工具设计是工作的一部分,描述和报错信息值得像代码一样测试。(Writing tools for agents)
  • 工具使用文档:客户端工具由应用运行,并把结果送回去;模型“可能会猜出你没提供的值”。(Tool use overview)

它们和这里的论点一致:工具是一个接口,它的文本是接口的一部分。

When to delete it Industry practice

A command that checks preconditions is scaffolding around the model's weak spots. If models become reliable enough at following multi-step instructions, a command may no longer beat a good prompt, but I would still keep commands for anything that has to be exactly the same every time, or that needs a record. The reasoning on descriptions and errors stays as long as the model reads text.

什麼時候可以刪掉 業界做法

檢查前置條件的指令,是圍繞模型弱點搭的鷹架。如果模型在照著多步驟的指令做事上變得夠可靠,指令可能不再勝過一個好的 prompt,但凡是每次都必須完全一樣、或需要留紀錄的事,我仍然會保留指令。只要模型還是讀文字,關於描述和錯誤訊息的道理就還在。

什么时候可以删掉 业界做法

检查前置条件的命令,是围着模型弱点搭的脚手架。如果模型在遵循多步指令上变得足够可靠,命令也许就不再比好的 prompt 强,但对那些每次都必须完全一样、或者需要留记录的事,我还是会保留命令。关于描述和报错信息的道理,只要模型还在读文本,就一直成立。

Try it on your own setup

No harness needed. Open your agent in your own repository and paste:

Find every tool, command or script in this repository that an agent is meant to run (look in agent files, scripts, task runners and instruction files). For each, judge four things: is its name and description clear about when to use it and when not to; does its error message say what to do next; how large can its output get; does a fixed multi-step procedure described in the instructions belong in a command instead. List the three worst and say how to fix each. Do not change any files.

在你自己的環境試試

不用裝 harness。在你自己的倉庫裡打開 agent,貼上:

找出這個倉庫裡,每一個預期由 agent 執行的工具、指令或腳本(看 agent 檔、腳本、任務執行器和指令檔)。每一個都判斷四件事:它的名字和描述,有沒有清楚說明什麼時候用、什麼時候不用;它的錯誤訊息有沒有說明接下來做什麼;它的輸出最大可以多大;指令檔裡描述的固定多步驟流程,是不是該改放進一個指令。列出最差的三個,並說明各自怎麼修。不要改任何檔案。

在你自己的环境里试试

不用装 harness。在你自己的仓库里打开 agent,粘贴:

找出这个仓库里每一个预期由 agent 运行的工具、命令或脚本(看 agent 文件、脚本、任务运行器和指令文件)。每一个从四方面判断:名字和描述是否说清了什么时候该用、什么时候不该用;报错信息有没有说明接下来做什么;输出最大能有多大;指令里描述的某个固定的多步流程,是否应该改成命令。列出最差的三个,并说明各自怎么修。不要修改任何文件。

Go deeper

延伸閱讀

延伸阅读

You can stop here: that is the whole idea. The next part shows where it runs, so you can look inside.讀到這裡就夠了,這就是整個想法。下一部分告訴你它在哪裡運行,可以進去看看。读到这里就够了,核心思路就是这些。下一部分告诉你它在哪里跑,可以进去看看。

In my practice (Copilot Harness)實作实战

Copilot Harness is my open-source harness for VS Code Copilot.

Repository: https://github.com/Smars-Bin-Hu/copilot-agentic-harness

Get started: clone it, open it in VS Code, and type /harness-rookie-get-me-ready in Copilot Chat. You need Python 3.9 or later and git.

Copilot Harness 是我開源的 VS Code Copilot harness。

倉庫: https://github.com/Smars-Bin-Hu/copilot-agentic-harness

開始:clone 下來,用 VS Code 打開,在 Copilot Chat 裡輸入 /harness-rookie-get-me-ready。需要 Python 3.9 以上和 git。

Copilot Harness 是我开源的 VS Code Copilot harness。

仓库: https://github.com/Smars-Bin-Hu/copilot-agentic-harness

上手:把仓库 clone 下来,用 VS Code 打开,在 Copilot Chat 里输入 /harness-rookie-get-me-ready。需要 Python 3.9 及以上版本和 git。

Explore it in the harness

My harness gives the agent a command line for the steps that must be certain, and a hook that stands at the door of every tool call. The harness can show you both from the inside, with the real files. After the setup above, type:

/harness-rookie-wondering I have read the chapter "Tool calling, and designing tools for an agent". Teach me what tools this harness gives the agent: the built-in ones, and its command line. Open the real files with me, show me a refusal and its reason, and draw how one tool call travels.

It teaches one small piece at a time, stops to ask if you are following, and opens the files with you.

在 harness 裡探索

我的 harness 給 agent 一個命令列,處理那些必須確定的步驟;還有一個 hook,站在每次工具呼叫的門口。harness 可以從裡面把兩者都展示給你看,帶著真實的檔案。照上面的說明準備好之後,輸入:

/harness-rookie-wondering 我讀完了「Tool calling,和給 agent 設計工具」這一章。請教我這個 harness 給 agent 哪些工具:內建的,和它的命令列。帶我打開真實的檔案,讓我看一次拒絕和它的原因,並畫出一次工具呼叫是怎麼走的。

它一次教一小塊,停下來確認你跟得上,然後和你一起打開檔案。

在 harness 里探索

我的 harness 给 agent 一个命令行工具,用来做必须确定的步骤,还有一个守在每次工具调用门口的 hook。harness 可以从内部带你看这两样,配上真实的文件。按上面的说明准备好之后,输入:

/harness-rookie-wondering 我读完了“Tool calling,以及怎么给 agent 设计工具”这一章。请教我这个 harness 给了 agent 哪些工具:内置的,和它自己的命令行工具。带我打开真实的文件,让我看一次拒绝和它的原因,并画出一次工具调用是怎么走的。

它一次只教一小块,停下来确认你跟上了,再和你一起打开文件。