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 的執行方式
-
PrivAI 依
tools中每個 MCP Tool 定義連線對應的 MCP server,取得工具清單;若有設定allowed_tools,只暴露清單內的工具。 -
每個工具會以
{server_label}--{工具名稱}的名稱提供給模型,例如deepwiki--read_wiki_structure。若同一請求中有多個 MCP Tool 使用相同的server_label,會依序加上_1、_2後綴(例如deepwiki_1--read_wiki_structure)。在串流的tool_calls中看到的就是這個名稱。 -
模型決定呼叫工具時,PrivAI 會執行工具,並將結果交回模型,重複直到模型不再呼叫工具。Stream 模式下,每個工具呼叫會回傳一個
role = "tool"的 chunk 表示工具輸出結果。 -
工具執行失敗或逾時時,PrivAI 會把
Tool error: ...當作工具結果交回模型,由模型決定如何回覆,不會讓整個請求失敗。
建議先用 探索 MCP 工具 確認 MCP server 提供哪些工具與其正確名稱,再填入 allowed_tools,避免一次把大量工具暴露給模型。
-
MCP server 無法連線或
server_url不是http:///https://開頭時,整個請求會失敗。 -
MCP Tool 的
authorization值會原樣放入Authorizationheader,且不可與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 請求本身仍應遵守既有的租戶權限與資料範圍限制。