FactVerse AI Agent 快速開始

本指南面向實施工程師、合作夥伴和客戶技術團隊，用於第一次把 AI 客戶端連接到 FactVerse AI Agent。

FactVerse AI Agent 使用受治理的 MCP endpoint。客戶端連接到一個 endpoint，發送 API key，列出該 key 可用的工具，然後在平台解析出的租戶和 scope 範圍內呼叫讀取或計算工具。

AI client -> /mcp/<slice>/ -> API key 解析租戶和 scope -> 可用工具

前置條件

連接客戶端前，需要準備以下內容：

要求	說明
FactVerse 主機	使用該客戶或專案環境提供的主機。範例中使用 `https://your-factverse-host`。
MCP endpoint	使用客戶已啟用的 slice endpoint，例如 `/mcp/base/` 或 `/mcp/pdm/`。
API key	Key 由管理員簽發，僅顯示一次，透過 `X-API-Key` 發送。
Scope	Key 必須具備目標工具所需的 scope。
來源資料	Agent 推理前，需要已有資產記錄、營運訊號、文件、場景或工單記錄。
MCP 相容客戶端	Claude Desktop、Cursor、自建 MCP client 或企業 Agent runtime。

選擇 endpoint

從匹配工作流的 endpoint 開始。目前工具和 scope 以本網站生成的 scope 參考為準。

Endpoint	典型用途	常見 scope
`/mcp/base/`	通用資產讀取、知識、文件、資料品質、模擬、最佳化和受控寫操作	`base.read`, `base.compute.run`, `base.action.write`
`/mcp/pdm/`	預測性維護健康度、摘要、異常和元件智能	`pdm.read`
`/mcp/trafficops/`	人流、車流、檢查點和交通營運工具	`trafficops.read`
`/mcp/telcoops/`	網路營運和容量分析工具	`telcoops.read`
`/mcp/semiops/`	潔淨室、廠務、utility、SMT 和環境工具	`semiops.read`
`/mcp/aviation/`	航空可靠性分析工具	`aviation.analysis.read`

已退役的 /mcp/physical/ endpoint 僅保留遷移提示。新的 Physical AI 工作流應使用目前 base 和模組 endpoint，並結合 Designer 場景、SimReady asset 和模擬流程。

設定客戶端

每個請求都使用 X-API-Key。不要把租戶標識作為 header 傳入來替代 key 授權。

{
  "mcpServers": {
    "factverse-base": {
      "url": "https://your-factverse-host/mcp/base/",
      "headers": {
        "X-API-Key": "fvk_your_scoped_key"
      }
    }
  }
}

如果整合需要多個 slice，為每個 endpoint 設定獨立 server entry。若部署策略允許，同一個 key 可以具備多個 scope。

驗證接入

正式設計工作流前，先完成這些檢查：

透過 HTTPS 連接 endpoint。
初始化 MCP session。
執行時列出工具。
確認可見工具符合預期。
先呼叫唯讀工具。
記錄回應、來源引用和缺失資料提示。

Python 客戶端範例：

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client(
        "https://your-factverse-host/mcp/base/",
        headers={"X-API-Key": "fvk_your_scoped_key"},
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            tools = await session.list_tools()
            for tool in tools.tools:
                print(tool.name)

            result = await session.call_tool(
                "get_equipment_status",
                {"equipment_id": "EQ-001"},
            )
            print(result)

如果工具沒有出現在列表裡，不要硬編碼呼叫。先檢查 endpoint、key、scope 和模組啟用狀態。

第一個工作流檢查

工作流	從這裡開始	驗證內容
設施營運	`/mcp/base/` 與 `base.read`	資產身份、位置、狀態、來源系統新鮮度和相關文件。
預測性維護	`/mcp/pdm/` 與 `pdm.read`	設備健康度、異常可見性、維護歷史和訊號品質。
Physical AI	`/mcp/base/` 與 `base.compute.run`，並結合 Designer 場景上下文	場景版本、資產版本、模擬假設和驗證記錄。

工單建立等寫操作需要明確的寫 scope，例如 base.action.write。這類動作應保留人工審批和稽核控制。

常見啟動失敗

現象	可能原因	檢查方式
閘道返回 `403`	沒有發送 API key	確認存在 `X-API-Key` header。
`401`	Key 無效、已撤銷或屬於其他環境	向管理員申請新的 key。
`missing required scope`	Key 不具備目標工具 scope	對照可見工具和 scope 參考。
工具不在列表中	endpoint 錯誤、模組未啟用或 scope 不足	使用執行時 `tools/list` 並檢查 endpoint 路徑。
回答為空或品質弱	來源資料缺失、過期或未映射到資產	檢查 DFS pipeline、Platform 資產記錄、Inspector 記錄和文件。
寫操作被阻止	缺少寫 scope 或審批策略	將動作保留為草稿，並交給具備權限的操作者審批。

下一步

設計工作流前閱讀核心概念。
使用 MCP 接入指南查看客戶端設定。
使用工具參考和 Scope 參考查看目前生成的工具與權限細節。

前置條件​

選擇 endpoint​

設定客戶端​

驗證接入​

第一個工作流檢查​

常見啟動失敗​

下一步​