跳至主要内容
版本:PrivStation 4.0.0
Markdown 原文

Tool Calling 與 MCP 整合

在 PrivAI 中,/v1/chat/completions 除了支援一般對話生成外,也支援模型在回應過程中使用工具(Tool Calling),以擴展 AI Agent 的能力範圍。
透過工具呼叫機制,模型不再只能依賴自身參數知識進行回答,而可以根據任務需求呼叫外部功能,例如查詢外部資料、存取第三方系統、執行檢索流程,或串接其他應用服務。
在 PrivAI 中,Tool Calling 能力透過 MCP(Model Context Protocol)定義的工具整合方式提供。目前 Chat Completions API 僅支援以 MCP Tool 形式傳入工具,不支援直接傳入自定義的 Function Tool 定義。模型在推理過程中呼叫 MCP Tool 時,底層會以 function-calling 格式進行,並由 PrivAI 內部負責工具定義的轉換與呼叫路由。

Tool Calling 的目的​

Tool Calling 的核心目的,是讓模型在生成答案的同時,能根據上下文判斷是否需要借助額外工具完成任務。
這種設計特別適合建構 AI Agent、企業內部助手、流程自動化工具與多步驟任務系統。
常見使用情境包括:

  • 查詢外部 API 或企業內部服務

  • 存取外部知識來源或資料平台

  • 執行特定系統操作或業務流程

  • 讓模型具備更完整的 Agent tool-use 能力

在 PrivAI 中,開發者可於呼叫 Chat Completions API 時,透過 tools 欄位提供 MCP Tool 定義,讓模型在推理過程中選擇是否使用這些工具。MCP Tool 的欄位說明請參考 Chat Completions。


MCP 是什麼​

MCP(Model Context Protocol)是一種用於定義模型如何存取外部工具與資源的協定。
透過 MCP,開發者可以用一致的方式描述工具介面,使模型能在推理過程中理解有哪些工具可用、各工具需要哪些參數,以及工具執行後的結果如何回傳。
相較於單純手工定義 function schema,MCP 的優點在於:

  • 可用標準化方式整合外部工具

  • 有利於 Agent 系統擴充更多外部能力

  • 可與多種支援 MCP 的工具服務互通

  • 有助於建立可維護、可擴展的工具生態


MCP Tool 的執行方式​

  1. PrivAI 依 tools 中每個 MCP Tool 定義連線對應的 MCP server,取得工具清單;若有設定 allowed_tools,只暴露清單內的工具。

  2. 每個工具會以 {server_label}--{工具名稱} 的名稱提供給模型,例如 deepwiki--read_wiki_structure。若同一請求中有多個 MCP Tool 使用相同的 server_label,會依序加上 _1、_2 後綴(例如 deepwiki_1--read_wiki_structure)。在串流的 tool_calls 中看到的就是這個名稱。

  3. 模型決定呼叫工具時,PrivAI 會執行工具,並將結果交回模型,重複直到模型不再呼叫工具。Stream 模式下,每個工具呼叫會回傳一個 role = "tool" 的 chunk 表示工具輸出結果。

  4. 工具執行失敗或逾時時,PrivAI 會把 Tool error: ... 當作工具結果交回模型,由模型決定如何回覆,不會讓整個請求失敗。

💡

建議先用 探索 MCP 工具 確認 MCP server 提供哪些工具與其正確名稱,再填入 allowed_tools,避免一次把大量工具暴露給模型。

  • MCP server 無法連線或 server_url 不是 http:// / https:// 開頭時,整個請求會失敗。

  • MCP Tool 的 authorization 值會原樣放入 Authorization header,且不可與 headers 中的 Authorization 同時提供。


本階段支援範圍​

目前 PrivAI 在 Chat Completions API 中支援 MCP Tool,範圍如下:

  • 支援於 tools 欄位中傳入 MCP Tool 定義

  • 支援使用與 Responses API tools 欄位相容的 MCP Tool 格式

  • 僅支援 remote MCP / MCP connector

  • 僅支援透過 Streamable HTTP 連接的外部 MCP server

本階段 不支援 的範圍包括:

  • 直接傳入自定義的 Function Tool 定義

  • local MCP server

  • SSE 型態的 MCP server

  • 非 HTTP 型態的 MCP 連線方式


Tool Calling 與 Tenant Scope 的關係​

PrivAI 支援多租戶資料隔離機制,系統會依據呼叫 API 所使用的 API Key,自動套用對應的 Tenant Scope(見「Tenant Scope 與資料隔離」章節)。
即使在使用 Tool Calling 或 MCP Tool 的情境下,API 請求本身仍應遵守既有的租戶權限與資料範圍限制。