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

機器之心報道

機器之心編輯部

好工具，才有好智能體。

智能體（Agent）時代，工具已不再只是傳統 API 或函數接口的簡單封裝，而是決定智能體能否高效完成任務的關鍵。

為了讓智能體真正釋放潛力，我們需要重新思考工具開發的方式。傳統軟件開發依賴確定性邏輯，而智能體是非確定性的，它們在相同輸入下可能產生不同輸出，這意味著為智能體設計工具需要新的范式。

而新的范式不僅僅是如何開發工具，更在于如何讓工具真正發揮最大效能。畢竟，AI 智能體的強大程度取決于我們為其提供的工具，但問題是：如何讓這些工具發揮最大效能？

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

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

以下是博客內容：

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

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

• 構建并測試工具原型；
• 如何創建并運行全面的評估；
• 與智能體協作（如 Claude Code），自動提升模型性能。

工具的定義

在計算機中，確定性系統在給定相同輸入時，每次都會產生相同的輸出；而非確定性系統，比如智能體，即便在相同的初始條件下，也可能生成不同的響應。

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

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

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

這意味著，我們在為智能體編寫軟件時，必須從根本上重新思考方法：不能再把工具和 MCP 服務器當作普通函數或 API 來寫，而是需要專門為智能體設計。

那如何設計工具呢？

如何編寫工具？

首先，快速搭建工具原型并在本地進行測試。

接著，進行全面評估來衡量后續改動帶來的影響。

在與智能體協作的過程中，你可以不斷重復評估與改進這一循環，直到智能體能夠在現實任務中表現出強勁的性能。

構建原型

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

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

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

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

值得一提的是，如果你要將本地 MCP 服務器連接到 Claude Code，請運行 claude mcp add

[args...]。

此外，要將本地 MCP 服務器或 DXT 連接到 Claude Desktop 應用，請分別前往「設置”>“開發者” 或 “設置”>“擴展程序”」。你也可以將工具直接傳入 Anthropic API 調用進行編程測試。

這些做完之后，還要自行測試以發現不足之處。

運行評估

接下來，你需要通過評估來衡量工具的效果。

評估可以分為幾個部分進行，首先是生成評估任務。

在你完成早期原型后，Claude Code 可以檢驗你的工具，并生成數十組提示與響應對。

這些提示應當源自真實的使用場景，并基于真實的數據源和服務（例如內部知識庫和微服務）。

• 本文建議避免使用過于簡單或太過于表面的沙盒環境，因為那樣無法在足夠復雜的條件下對工具進行壓力測試。
• 那些高質量的評估任務往往需要多次工具調用，甚至可能多達數十次。

那什么是好的任務評估呢？大家可以參考如下示例：

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

還有一些較弱的任務：

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

每個評估 prompt 都應與可驗證的響應或結果配對。你設置的驗證器可以簡單到只是在基本事實和采樣響應之間進行精確的字符串比較，也可以高級到請大模型來判斷響應。避免使用過于嚴格的驗證器，因為這些驗證器會因為格式、標點符號或有效的替代措辭等虛假差異而拒絕正確的響應。

對于每個提示 - 響應對，你還可以選擇指定智能體在解決任務時調用的工具，以衡量智能體在評估過程中是否成功掌握了每個工具的用途。但是，由于正確解決任務可能存在多種有效途徑，因此請盡量避免過度指定或過度擬合策略。

接著是運行評估。

本文建議通過直接調用 LLM API 以編程方式運行評估。

還可以采用簡單的智能體循環（例如用 while 循環交替包裝 LLM API 與工具調用）：每個評估任務對應一個循環。每個評估智能體應被分配一個任務提示和相關工具。

如果你使用 Claude 運行評估，可以直接啟用 interleaved thinking（交錯思維）。這樣一來你就能探究智能體為何調用或不調用某些工具。

在評估過程中，除了準確率，本文還建議收集智能體的其他指標，例如：

• 單次工具調用和任務的總運行時間；
• 工具調用總次數；
• 總 token 消耗；
• 工具錯誤情況。

接下來是結果分析。

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

你需要觀察智能體在什么地方會卡住或感到困惑。我們需要根據反饋，定位工具的薄弱環節。

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

另外，還需要分析你的工具調用指標：

• 冗余調用過多 → 可能說明需要重新設計分頁或 token 限制參數；
• 無效參數導致的錯誤過多 → 可能說明工具需要更清晰的描述或更好的使用示例。

用戶還可以與智能體協作。

你甚至可以讓智能體直接幫你分析結果并改進工具。

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

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

選擇合適的工具

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

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

• 舉個例子：LLM 智能體的上下文有限（即一次能處理的信息量有限），而計算機內存廉價且幾乎無限。
• 在地址簿中查找聯系人這個任務上，傳統軟件可以高效地逐個存儲并處理聯系人，檢查完一個再檢查下一個。

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

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

因此，本文建議先構建少量經過深思熟慮的工具，針對高價值的工作流，并與評估任務保持一致，然后再逐步擴展。在地址簿的例子中，你可以實現一個 search_contacts 或 message_contact 工具，而不是簡單地提供一個 list_contacts 工具。

此外，工具還有整合能力，能在底層同時處理多個離散操作（或 API 調用）。

例如，工具可以：

• 在返回結果時附加相關元數據；
• 或者在一次調用中完成經常需要串聯的多步任務。

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

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

所以說，你構建的每個工具都應當具有清晰且獨立的目標。工具應當使智能體能夠像人類一樣，在獲取相同底層資源的情況下，去分解并解決任務，同時還能減少原本會被中間結果消耗掉的上下文空間。

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

因此，謹慎且有選擇性地規劃哪些工具需要構建（或不需要構建），往往會帶來更大的回報。

為工具設置命名空間

AI 智能體可能會接入數十個 MCP 服務器和數百個不同的工具，其中還包括其他開發者編寫的工具。

當工具在功能上出現重疊，或者用途模糊不清時，智能體就可能會混淆該用哪個工具。

命名空間（即給相關工具加上統一前綴分組）可以劃清不同工具之間的邊界；有些 MCP 客戶端會默認采用這種方式。

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

本文發現，前綴式命名和后綴式命名在工具使用評估中的效果并不相同。本文建議根據你的評估結果來選擇合適的命名方式。

假如不這樣做的話，智能體可能會：

• 調用錯誤的工具；
• 或者用錯誤的參數調用正確的工具；
• 又或者調用的工具太少；
• 甚至錯誤地處理了工具響應。

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

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

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

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

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

enum ResponseFormat {

DETAILED = "detailed",

CONCISE = "concise"

以下是詳細工具響應的示例（206 個 token）：

以下是一個簡潔工具響應（72 個 token）的示例：

Slack 線程和線程回復由唯一的 thread_ts 標識，這些 thread_ts 是獲取線程回復所必需的。thread_ts 和其他 ID（channel_id、user_id）可以從「詳細」工具響應中檢索，以便后續需要這些 ID 的工具調用。「簡潔」工具響應僅返回線程內容，不包含 ID。本例中使用約 1/3 個 token 作為「簡潔」工具響應。

你的工具響應結構（例如 XML、JSON 或 Markdown）也會對評估性能產生影響：沒有一刀切的解決方案。這是因為 LLM 是基于下一個 token 預測進行訓練的，并且往往在使用與其訓練數據匹配的格式時表現更佳。最佳響應結構會因任務和智能體而異，建議根據自身的評估選擇最佳響應結構。

優化工具響應以提高 token 效率

優化上下文質量至關重要。但優化工具響應中返回給智能體的上下文數量也同樣重要。

Anthropic 建議，對于任何可能消耗大量上下文的工具響應，結合分頁、范圍選擇、過濾和 / 或截斷功能，并設置合理的默認參數值。對于 Claude Code 來說，工具響應限制默認是 25000 個 token。未來智能體的有效上下文長度會隨著時間的推移而增長，但對上下文高效工具的需求會始終存在。

如果你選擇截斷響應，請務必為智能體提供實用的指導。你可以直接鼓勵智能體采用更高效的 token 策略，例如，在知識檢索任務中進行多次小規模、有針對性的搜索，而不是進行單一、廣泛的搜索。同樣，如果工具調用引發錯誤（例如，在輸入驗證期間），你可以對錯誤響應進行提示式設計，以清晰地傳達具體且可操作的改進措施，而不是使用晦澀難懂的錯誤代碼或回溯。

以下是截斷工具響應的示例：

以下是一個無用的錯誤響應示例：

以下是一個有用的錯誤響應示例：

快速構建工具描述

現在來談談改進工具的最有效方法之一：快速構建工具描述和規范。由于這些內容會加載到智能體的上下文中，因此它們可以共同引導智能體實現有效的工具調用行為。

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

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

展望未來

為了構建高效的智能體工具，我們需要重新調整軟件開發實踐，從可預測的確定性模式轉向非確定性模式。

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

Anthropic 預計，智能體與世界交互的具體機制將不斷演變 —— 從 MCP 協議的更新到底層 LLM 本身的升級。通過系統化的、評估驅動的方法來改進智能體工具，我們可以確保隨著智能體能力的提升，它們所使用的工具也能隨之發展。