將工具新增至 Azure AI 代理程式
Tip
有關更多詳細信息，請參閱 文本和圖像 選項卡！
工具是讓你的客服人員能夠採取行動的工具——呼叫 API、執行程式碼、搜尋檔案，或與外部服務互動。 沒有工具，代理只能根據已知資訊產生文字。 有了工具，它就能對世界採取行動。
Microsoft 代理框架支援兩大類工具：由提供者託管和管理的服務提供工具，以及由您自行撰寫並在代理註冊的自訂函式工具。
服務提供的工具
使用 Foundry 服務時，可提供多種託管工具，無需額外實作。 你可以透過在代理設定中包含它們來啟用它們——提供者負責實際執行。
最常用的服務提供工具包括：
| Tool | 其功能是什麼 |
|---|---|
| 程式碼解譯器 | 在沙盒環境中執行 Python 程式碼進行計算與資料分析 |
| 檔案搜尋 | 搜尋並檢索上傳文件中的資訊 |
| 網路搜尋 | 從網際網路取得最新資訊 |
| 託管 MCP 工具 | 由提供者執行階段直接叫用的 MCP（模型上下文協定）伺服器 |
| Azure AI 搜尋服務 | 透過 Foundry 連線查詢 Azure AI 搜尋服務 索引 |
| Foundry 工具箱 | 在 Foundry 專案中管理的具名、版本化託管工具設定套件 |
Note
部分工具——包括 Azure AI 搜尋服務、Bing Grounding、SharePoint 等——目前仍處於預覽或實驗階段。 這些服務對 Foundry 代理有提供，但其他供應商的支援可能有限。
自訂功能工具
自訂函式工具讓你能擴充代理所需的任何邏輯——呼叫內部 API、查詢資料庫、執行計算，或是 Python 函式能做的任何事。
要將函式註冊為工具，你在建立時直接將它傳給代理。 框架會檢查函式的簽名，並產生一個結構，告訴模型函式的功能、預期參數及回傳內容。
要讓模型可靠地呼叫工具，你的功能必須被清楚描述。 代理框架支援兩種方法：
-
附有描述的型別註解—使用 Python 的
Annotated型別，並為每個參數加上欄位描述。 函式的說明字串即為工具說明。 -
@tool裝飾器——明確指定工具名稱和描述作為裝飾器參數，讓你完全掌控模型所見。 如果你需要精確控制輸入結構，也可以用 Pydantic 模型提供明確的結構模式。
無論哪種情況，框架都能自動處理結構產生與工具調用。 當模型決定應呼叫某工具時，框架會執行該函式，並在最終回應產生前將結果回傳給模型。
新增多種工具
你可以用同一個代理人註冊多個工具。 建立代理時傳遞函數清單，模型會自動為對話的每個部分選擇最合適的工具。 你不需要寫任何路由邏輯——框架會根據對話上下文和你提供的工具描述來處理工具協調。
工具核准
對於需要人工審查才能執行的工具調用，代理框架支援 工具審核 模式。 當工具啟用批准模式時，代理會在呼叫該函式前暫停並請求確認。 這對於不可逆、昂貴或涉及敏感資料的行動非常有用。 可使用 @tool 裝飾器上的 approval_mode 參數，針對每個工具設定核准行為。
使用代理人作為工具
代理人可以透過將一個代理人作為另一個代理人的工具來組合而成。 你將內部代理轉換為函式工具，並將其傳遞給外部代理，外部代理之後即可將特定任務委派給該工具。 這使得模組化設計成為可能，專門代理處理特定領域，並由協調代理在這些領域間路由請求——這一模式在多代理模組中有更深入探討。
自訂工具的最佳實務
- 寫出清楚的描述——模型能否選擇合適的工具，完全取決於你提供的描述。 要具體說明這個函數的作用以及何時使用。
- 註解每個參數——描述每個輸入，讓模型能構建有效的呼叫，尤其當參數名稱本身不易理解時。
- 回傳有意義的資料——工具應回傳結構化且可解釋的輸出。 模型在形成回應時直接使用回傳值。
- 讓工具各司其職——每個工具都應該把一件事做好。 將多項責任合併成一個函式，會讓模型更難正確調用它。
- 優雅地處理錯誤——若工具遇到意外輸入或外部服務失敗，應回傳一個有資訊的錯誤訊息，而非提出例外，讓模型能有幫助地回應。