如何為LLM智能體編寫工具？Anthropic官方教程來了

機(jī)器之心報(bào)道

機(jī)器之心編輯部

好工具，才有好智能體。

智能體（Agent）時(shí)代，工具已不再只是傳統(tǒng) API 或函數(shù)接口的簡單封裝，而是決定智能體能否高效完成任務(wù)的關(guān)鍵。

為了讓智能體真正釋放潛力，我們需要重新思考工具開發(fā)的方式。傳統(tǒng)軟件開發(fā)依賴確定性邏輯，而智能體是非確定性的，它們?cè)谙嗤斎胂驴赡墚a(chǎn)生不同輸出，這意味著為智能體設(shè)計(jì)工具需要新的范式。

而新的范式不僅僅是如何開發(fā)工具，更在于如何讓工具真正發(fā)揮最大效能。畢竟，AI 智能體的強(qiáng)大程度取決于我們?yōu)槠涮峁┑墓ぞ撸珕栴}是：如何讓這些工具發(fā)揮最大效能？

來自 Anthropic 的一篇文章為大家指出了一條可行路徑。

原文鏈接：https://www.anthropic.com/engineering/writing-tools-for-agents

以下是博客內(nèi)容：

在這篇文章中，Anthropic 介紹了一些在多種 agentic AI 系統(tǒng)中被證明最有效的性能提升技巧。

閱讀本文后，你可以做到：

• 構(gòu)建并測(cè)試工具原型；
• 如何創(chuàng)建并運(yùn)行全面的評(píng)估；
• 與智能體協(xié)作（如 Claude Code），自動(dòng)提升模型性能。

工具的定義

在計(jì)算機(jī)中，確定性系統(tǒng)在給定相同輸入時(shí)，每次都會(huì)產(chǎn)生相同的輸出；而非確定性系統(tǒng)，比如智能體，即便在相同的初始條件下，也可能生成不同的響應(yīng)。

在傳統(tǒng)的軟件開發(fā)中，我們是在確定性系統(tǒng)之間建立契約。例如，一個(gè)關(guān)于天氣的函數(shù)調(diào)用 getWeather ("NYC")，無論調(diào)用多少次，都將以完全相同的方式返回紐約的天氣。

而基于大模型的工具是一種全新的軟件形式，它體現(xiàn)的是確定性系統(tǒng)與非確定性智能體之間的契約。

舉個(gè)例子：當(dāng)用戶問「我今天要帶傘嗎？」時(shí)，智能體可能會(huì)調(diào)用天氣工具、也可能直接基于常識(shí)回答，甚至先提出一個(gè)澄清性問題（比如確認(rèn)具體地點(diǎn)）。有時(shí)，智能體還可能出現(xiàn)幻覺，或者根本沒弄明白該如何使用工具。

這意味著，我們?cè)跒橹悄荏w編寫軟件時(shí)，必須從根本上重新思考方法：不能再把工具和 MCP 服務(wù)器當(dāng)作普通函數(shù)或 API 來寫，而是需要專門為智能體設(shè)計(jì)。

那如何設(shè)計(jì)工具呢？

如何編寫工具？

首先，快速搭建工具原型并在本地進(jìn)行測(cè)試。

接著，進(jìn)行全面評(píng)估來衡量后續(xù)改動(dòng)帶來的影響。

在與智能體協(xié)作的過程中，你可以不斷重復(fù)評(píng)估與改進(jìn)這一循環(huán)，直到智能體能夠在現(xiàn)實(shí)任務(wù)中表現(xiàn)出強(qiáng)勁的性能。

構(gòu)建原型

在該教程中，我們以基于 Claude 的智能體構(gòu)建為例。

如果你使用 Claude Code 來編寫工具，最好向 Claude 提供相關(guān)的文檔，例如工具依賴的軟件庫、API 或 SDK（包括可能用到的 MCP SDK）。

另外，適合 LLM 閱讀的文檔通常可以在官方文檔網(wǎng)站上以 llms.txt 文件的形式找到，大家可以自行下載。

你也可以將工具封裝在本地 MCP 服務(wù)器或桌面擴(kuò)展程序 (DXT) 中，即可在 Claude Code 或 Claude Desktop 應(yīng)用中連接并測(cè)試這些工具。

值得一提的是，如果你要將本地 MCP 服務(wù)器連接到 Claude Code，請(qǐng)運(yùn)行 claude mcp add

[args...]。

此外，要將本地 MCP 服務(wù)器或 DXT 連接到 Claude Desktop 應(yīng)用，請(qǐng)分別前往「設(shè)置”>“開發(fā)者” 或 “設(shè)置”>“擴(kuò)展程序”」。你也可以將工具直接傳入 Anthropic API 調(diào)用進(jìn)行編程測(cè)試。

這些做完之后，還要自行測(cè)試以發(fā)現(xiàn)不足之處。

運(yùn)行評(píng)估

接下來，你需要通過評(píng)估來衡量工具的效果。

評(píng)估可以分為幾個(gè)部分進(jìn)行，首先是生成評(píng)估任務(wù)。

在你完成早期原型后，Claude Code 可以檢驗(yàn)?zāi)愕墓ぞ撸⑸蓴?shù)十組提示與響應(yīng)對(duì)。

這些提示應(yīng)當(dāng)源自真實(shí)的使用場景，并基于真實(shí)的數(shù)據(jù)源和服務(wù)（例如內(nèi)部知識(shí)庫和微服務(wù)）。

• 本文建議避免使用過于簡單或太過于表面的沙盒環(huán)境，因?yàn)槟菢訜o法在足夠復(fù)雜的條件下對(duì)工具進(jìn)行壓力測(cè)試。
• 那些高質(zhì)量的評(píng)估任務(wù)往往需要多次工具調(diào)用，甚至可能多達(dá)數(shù)十次。

那什么是好的任務(wù)評(píng)估呢？大家可以參考如下示例：

• 安排下周與 Jane 會(huì)面，討論我們最新的 Acme Corp 項(xiàng)目。附上我們上次項(xiàng)目規(guī)劃會(huì)議的記錄，并預(yù)訂會(huì)議室。
• 客戶 ID 9182 報(bào)告稱，他們單次購買被扣款三次。查找所有相關(guān)日志條目，并確定是否有其他客戶受到同一問題的影響。
• 客戶 Sarah Chen 剛剛提交了取消訂單的申請(qǐng)。準(zhǔn)備一份留任方案。確定：(1) 他們離開的原因；(2) 哪種留任方案最具吸引力；以及 (3) 在提出方案之前我們應(yīng)該注意的風(fēng)險(xiǎn)因素。

還有一些較弱的任務(wù)：

• 安排下周與 jane@acme.corp 的會(huì)議。
• 在付款日志中搜索 purchase_complete 和 customer_id=9182。
• 查找客戶 ID 為 45892 的取消請(qǐng)求。

每個(gè)評(píng)估 prompt 都應(yīng)與可驗(yàn)證的響應(yīng)或結(jié)果配對(duì)。你設(shè)置的驗(yàn)證器可以簡單到只是在基本事實(shí)和采樣響應(yīng)之間進(jìn)行精確的字符串比較，也可以高級(jí)到請(qǐng)大模型來判斷響應(yīng)。避免使用過于嚴(yán)格的驗(yàn)證器，因?yàn)檫@些驗(yàn)證器會(huì)因?yàn)楦袷健?biāo)點(diǎn)符號(hào)或有效的替代措辭等虛假差異而拒絕正確的響應(yīng)。

對(duì)于每個(gè)提示 - 響應(yīng)對(duì)，你還可以選擇指定智能體在解決任務(wù)時(shí)調(diào)用的工具，以衡量智能體在評(píng)估過程中是否成功掌握了每個(gè)工具的用途。但是，由于正確解決任務(wù)可能存在多種有效途徑，因此請(qǐng)盡量避免過度指定或過度擬合策略。

接著是運(yùn)行評(píng)估。

本文建議通過直接調(diào)用 LLM API 以編程方式運(yùn)行評(píng)估。

還可以采用簡單的智能體循環(huán)（例如用 while 循環(huán)交替包裝 LLM API 與工具調(diào)用）：每個(gè)評(píng)估任務(wù)對(duì)應(yīng)一個(gè)循環(huán)。每個(gè)評(píng)估智能體應(yīng)被分配一個(gè)任務(wù)提示和相關(guān)工具。

如果你使用 Claude 運(yùn)行評(píng)估，可以直接啟用 interleaved thinking（交錯(cuò)思維）。這樣一來你就能探究智能體為何調(diào)用或不調(diào)用某些工具。

在評(píng)估過程中，除了準(zhǔn)確率，本文還建議收集智能體的其他指標(biāo)，例如：

• 單次工具調(diào)用和任務(wù)的總運(yùn)行時(shí)間；
• 工具調(diào)用總次數(shù)；
• 總 token 消耗；
• 工具錯(cuò)誤情況。

接下來是結(jié)果分析。

通常來講，有時(shí)智能體在反饋和回答中遺漏的內(nèi)容，往往比它們提到的內(nèi)容更重要。LLM 并不總是準(zhǔn)確表達(dá)出它們的真實(shí)含義。

你需要觀察智能體在什么地方會(huì)卡住或感到困惑。我們需要根據(jù)反饋，定位工具的薄弱環(huán)節(jié)。

與此同時(shí)，我們需要回顧原始對(duì)話記錄（包括工具調(diào)用和工具響應(yīng)），以捕捉那些沒有明確出現(xiàn)在智能體 CoT 中的行為。記住評(píng)估智能體并不一定真正知道正確答案或最佳策略。

另外，還需要分析你的工具調(diào)用指標(biāo)：

• 冗余調(diào)用過多 → 可能說明需要重新設(shè)計(jì)分頁或 token 限制參數(shù)；
• 無效參數(shù)導(dǎo)致的錯(cuò)誤過多 → 可能說明工具需要更清晰的描述或更好的使用示例。

用戶還可以與智能體協(xié)作。

你甚至可以讓智能體直接幫你分析結(jié)果并改進(jìn)工具。

只需將評(píng)估智能體的對(duì)話記錄拼接起來，然后粘貼到 Claude Code 中即可。Claude 擅長分析對(duì)話記錄，并能一次性重構(gòu)大量工具。

如何編寫高效工具？有哪些原則

選擇合適的工具

并不是說工具越多，結(jié)果就越好。我們觀察到一個(gè)現(xiàn)象：工具只是簡單封裝了現(xiàn)有軟件功能或 API 接口，而很多時(shí)候調(diào)用這些工具是否真正適合智能體還未知。

原因在于，智能體與傳統(tǒng)軟件有著不同的可供性（affordances），也就是說，它們感知并使用工具的方式與傳統(tǒng)軟件截然不同

• 舉個(gè)例子：LLM 智能體的上下文有限（即一次能處理的信息量有限），而計(jì)算機(jī)內(nèi)存廉價(jià)且?guī)缀鯚o限。
• 在地址簿中查找聯(lián)系人這個(gè)任務(wù)上，傳統(tǒng)軟件可以高效地逐個(gè)存儲(chǔ)并處理聯(lián)系人，檢查完一個(gè)再檢查下一個(gè)。

然而，如果一個(gè) LLM 智能體使用的工具返回了所有聯(lián)系人，并且必須逐個(gè) token 地讀完，那么它就會(huì)把有限的上下文空間浪費(fèi)在無關(guān)信息上。（想象一下，在地址簿里找聯(lián)系人時(shí)，你得從頭到尾一頁一頁翻閱，這其實(shí)就是一種暴力搜索。）

更好、更自然的方式（無論對(duì)智能體還是對(duì)人類而言）都是直接跳到相關(guān)頁面（比如按字母順序定位）。

因此，本文建議先構(gòu)建少量經(jīng)過深思熟慮的工具，針對(duì)高價(jià)值的工作流，并與評(píng)估任務(wù)保持一致，然后再逐步擴(kuò)展。在地址簿的例子中，你可以實(shí)現(xiàn)一個(gè) search_contacts 或 message_contact 工具，而不是簡單地提供一個(gè) list_contacts 工具。

此外，工具還有整合能力，能在底層同時(shí)處理多個(gè)離散操作（或 API 調(diào)用）。

例如，工具可以：

• 在返回結(jié)果時(shí)附加相關(guān)元數(shù)據(jù)；
• 或者在一次調(diào)用中完成經(jīng)常需要串聯(lián)的多步任務(wù)。

以下是整合功能的一些示例：

• 與其分別實(shí)現(xiàn) list_users、list_events 和 create_event 工具，不如實(shí)現(xiàn)一個(gè) schedule_event 工具，它可以查找空閑時(shí)間并能直接安排其他任務(wù)。
• 與其實(shí)現(xiàn)一個(gè) read_logs 工具，不如實(shí)現(xiàn)一個(gè) search_logs 工具，它只返回相關(guān)的日志行以及必要的上下文。
• 與其實(shí)現(xiàn) get_customer_by_id、list_transactions 和 list_notes 工具，不如實(shí)現(xiàn)一個(gè) get_customer_context 工具，它能一次性匯總某個(gè)客戶的所有近期且相關(guān)的信息。

所以說，你構(gòu)建的每個(gè)工具都應(yīng)當(dāng)具有清晰且獨(dú)立的目標(biāo)。工具應(yīng)當(dāng)使智能體能夠像人類一樣，在獲取相同底層資源的情況下，去分解并解決任務(wù)，同時(shí)還能減少原本會(huì)被中間結(jié)果消耗掉的上下文空間。

過多的工具或功能重疊的工具，反而會(huì)分散智能體的注意力，阻礙其選擇高效的策略。

因此，謹(jǐn)慎且有選擇性地規(guī)劃哪些工具需要構(gòu)建（或不需要構(gòu)建），往往會(huì)帶來更大的回報(bào)。

為工具設(shè)置命名空間

AI 智能體可能會(huì)接入數(shù)十個(gè) MCP 服務(wù)器和數(shù)百個(gè)不同的工具，其中還包括其他開發(fā)者編寫的工具。

當(dāng)工具在功能上出現(xiàn)重疊，或者用途模糊不清時(shí)，智能體就可能會(huì)混淆該用哪個(gè)工具。

命名空間（即給相關(guān)工具加上統(tǒng)一前綴分組）可以劃清不同工具之間的邊界；有些 MCP 客戶端會(huì)默認(rèn)采用這種方式。

例如，可以按服務(wù)進(jìn)行命名空間劃分（如 asana_search、jira_search），也可以按資源劃分（如 asana_projects_search、asana_users_search），這樣能夠幫助智能體在合適的時(shí)機(jī)選擇正確的工具。

本文發(fā)現(xiàn)，前綴式命名和后綴式命名在工具使用評(píng)估中的效果并不相同。本文建議根據(jù)你的評(píng)估結(jié)果來選擇合適的命名方式。

假如不這樣做的話，智能體可能會(huì)：

• 調(diào)用錯(cuò)誤的工具；
• 或者用錯(cuò)誤的參數(shù)調(diào)用正確的工具；
• 又或者調(diào)用的工具太少；
• 甚至錯(cuò)誤地處理了工具響應(yīng)。

從工具中返回有意義的上下文

同樣，工具實(shí)現(xiàn)應(yīng)注意僅向智能體返回高信號(hào)信息。它們應(yīng)優(yōu)先考慮上下文相關(guān)性而非靈活性，并避免使用低級(jí)技術(shù)標(biāo)識(shí)符（例如：uuid、256px_image_url、mime_type）。諸如 name、image_url 和 file_type 之類的字段更有可能直接影響智能體的下游操作和響應(yīng)。

智能體處理自然語言名稱、術(shù)語或標(biāo)識(shí)符的能力也顯著優(yōu)于處理隱晦的標(biāo)識(shí)符。實(shí)踐發(fā)現(xiàn)，僅僅將任意字母數(shù)字 UUID 解析為語義上更有意義且更易于解釋的語言（甚至是 0 索引的 ID 方案）就能顯著提高 Claude 在檢索任務(wù)中的準(zhǔn)確率，從而減少幻覺。

在某些情況下，智能體可能需要靈活地與自然語言和技術(shù)標(biāo)識(shí)符輸出進(jìn)行交互，哪怕只是為了觸發(fā)下游工具調(diào)用（例如，search_user (name=’jane’) → send_message (id=12345)）。你可以通過在工具中公開一個(gè)簡單的 response_format 枚舉參數(shù)來啟用這兩種功能，從而允許智能體控制工具返回「簡潔」還是「詳細(xì)」的響應(yīng)（如下圖所示）。

你可以添加更多格式以獲得更大的靈活性，類似于 GraphQL，也可以精確選擇要接收的信息。以下是一個(gè)用于控制工具響應(yīng)詳細(xì)程度的 ResponseFormat 枚舉示例：

enum ResponseFormat {

DETAILED = "detailed",

CONCISE = "concise"

以下是詳細(xì)工具響應(yīng)的示例（206 個(gè) token）：

以下是一個(gè)簡潔工具響應(yīng)（72 個(gè) token）的示例：

Slack 線程和線程回復(fù)由唯一的 thread_ts 標(biāo)識(shí)，這些 thread_ts 是獲取線程回復(fù)所必需的。thread_ts 和其他 ID（channel_id、user_id）可以從「詳細(xì)」工具響應(yīng)中檢索，以便后續(xù)需要這些 ID 的工具調(diào)用。「簡潔」工具響應(yīng)僅返回線程內(nèi)容，不包含 ID。本例中使用約 1/3 個(gè) token 作為「簡潔」工具響應(yīng)。

你的工具響應(yīng)結(jié)構(gòu)（例如 XML、JSON 或 Markdown）也會(huì)對(duì)評(píng)估性能產(chǎn)生影響：沒有一刀切的解決方案。這是因?yàn)?LLM 是基于下一個(gè) token 預(yù)測(cè)進(jìn)行訓(xùn)練的，并且往往在使用與其訓(xùn)練數(shù)據(jù)匹配的格式時(shí)表現(xiàn)更佳。最佳響應(yīng)結(jié)構(gòu)會(huì)因任務(wù)和智能體而異，建議根據(jù)自身的評(píng)估選擇最佳響應(yīng)結(jié)構(gòu)。

優(yōu)化工具響應(yīng)以提高 token 效率

優(yōu)化上下文質(zhì)量至關(guān)重要。但優(yōu)化工具響應(yīng)中返回給智能體的上下文數(shù)量也同樣重要。

Anthropic 建議，對(duì)于任何可能消耗大量上下文的工具響應(yīng)，結(jié)合分頁、范圍選擇、過濾和 / 或截?cái)喙δ埽⒃O(shè)置合理的默認(rèn)參數(shù)值。對(duì)于 Claude Code 來說，工具響應(yīng)限制默認(rèn)是 25000 個(gè) token。未來智能體的有效上下文長度會(huì)隨著時(shí)間的推移而增長，但對(duì)上下文高效工具的需求會(huì)始終存在。

如果你選擇截?cái)囗憫?yīng)，請(qǐng)務(wù)必為智能體提供實(shí)用的指導(dǎo)。你可以直接鼓勵(lì)智能體采用更高效的 token 策略，例如，在知識(shí)檢索任務(wù)中進(jìn)行多次小規(guī)模、有針對(duì)性的搜索，而不是進(jìn)行單一、廣泛的搜索。同樣，如果工具調(diào)用引發(fā)錯(cuò)誤（例如，在輸入驗(yàn)證期間），你可以對(duì)錯(cuò)誤響應(yīng)進(jìn)行提示式設(shè)計(jì)，以清晰地傳達(dá)具體且可操作的改進(jìn)措施，而不是使用晦澀難懂的錯(cuò)誤代碼或回溯。

以下是截?cái)喙ぞ唔憫?yīng)的示例：

以下是一個(gè)無用的錯(cuò)誤響應(yīng)示例：

以下是一個(gè)有用的錯(cuò)誤響應(yīng)示例：

快速構(gòu)建工具描述

現(xiàn)在來談?wù)劯倪M(jìn)工具的最有效方法之一：快速構(gòu)建工具描述和規(guī)范。由于這些內(nèi)容會(huì)加載到智能體的上下文中，因此它們可以共同引導(dǎo)智能體實(shí)現(xiàn)有效的工具調(diào)用行為。

在編寫工具描述和規(guī)范時(shí)，請(qǐng)思考如何向團(tuán)隊(duì)中的新成員描述你的工具。考慮到可能隱式引入的上下文 —— 專用查詢格式、專業(yè)術(shù)語的定義、底層資源之間的關(guān)系 —— 并將其明確化。通過清晰描述（并使用嚴(yán)格的數(shù)據(jù)模型強(qiáng)制執(zhí)行）預(yù)期的輸入和輸出，避免歧義。特別是，輸入?yún)?shù)的命名應(yīng)清晰明確：不要使用名為 user 的參數(shù)，而應(yīng)嘗試使用名為 user_id 的參數(shù)。

通過評(píng)估，你可以更有信心地衡量快速構(gòu)建的影響。即使對(duì)工具描述進(jìn)行微小的改進(jìn)，也能帶來顯著的提升。在對(duì)工具描述進(jìn)行精準(zhǔn)改進(jìn)后，Claude Sonnet 3.5 在 SWE-bench Verified 評(píng)估中取得了最佳性能，大幅降低了錯(cuò)誤率，并提高了任務(wù)完成率。

展望未來

為了構(gòu)建高效的智能體工具，我們需要重新調(diào)整軟件開發(fā)實(shí)踐，從可預(yù)測(cè)的確定性模式轉(zhuǎn)向非確定性模式。

通過本文中描述的迭代式、評(píng)估驅(qū)動(dòng)的流程，現(xiàn)在已經(jīng)出現(xiàn)了使工具成功的一致模式：高效的工具應(yīng)具有清晰明確的定義，能夠合理地利用智能體上下文，能夠在不同的工作流程中組合使用，并支持智能體直觀地解決現(xiàn)實(shí)世界中的任務(wù)。

Anthropic 預(yù)計(jì)，智能體與世界交互的具體機(jī)制將不斷演變 —— 從 MCP 協(xié)議的更新到底層 LLM 本身的升級(jí)。通過系統(tǒng)化的、評(píng)估驅(qū)動(dòng)的方法來改進(jìn)智能體工具，我們可以確保隨著智能體能力的提升，它們所使用的工具也能隨之發(fā)展。