將香港登記庫 Merged Profile 接入你的 Agent

Trusgent 已結構化索引香港 6 萬+ 條官方登記記錄——食肆、診所、律師、保險、課程主辦者等。每條記錄在 `/t/{registryId}` 有公開頁，並提供機器可讀 JSON。夥伴 Agent 不應只讀 raw registry JSON。 預設應讀取 Merged Profile（合併檔案）：官方登記欄位 + 可選認領 Agent Card + enrichment，並附帶 `trustBreakdown` 與 `recommendedUse`，便於判斷哪些欄位可以引用。

本指南面向 Agent 平台工程師、垂直助手整合方與 MCP 客戶端維護者。

為什麼 Merged Profile 優於 Raw Registry JSON

香港開放登記數據是可靠的 身份錨點（`REGISTRY_OFFICIAL`），可回答：*牌照是否真實？發證機關是誰？註冊名稱與地址是什麼？*

通常 無法 可靠回答：*今日營業時間？預約電話？菜單？* 靠網頁抓取補全這些欄位，幻覺風險很高。

Merged Profile 在單次回應中合併三層數據：

| 層級 | 來源 | 典型用途 |

|:---|:---|:---|

| `official` | 食環署、食安中心、保監局、醫務委員會、律師會、教育局等 | 身份、牌照號、provenance、官方核對連結 |

| `claimed` | 商家認領登記行 → live Agent Card | 更深資料、核驗、經營門面 |

| `enrichment` | Google Places POC + 商家確認 | 營業時間、電話、網站（含 verification level） |

回應包含 `recommendedUse.identity`、`.hours`、`.contact`，取值為 `safe_to_cite`、`cite_with_caution` 或 `do_not_cite`。生成面向使用者的答案前，必須先讀這些欄位。

預設調用流（夥伴必遵）

```

1. search_registry(q, source?, country=HK)

2. get_merged_profile(registryId) ← 預設讀取

3. 若 claimed.trusgentId 存在 → 推薦前 verify_agent

4. 可選：get_business_facade 讀取菜單 / 預約面

```

僅在需要純官方欄位、不含 enrichment 與認領上下文時（例如合規審計匯出），才使用 `get_registry`。

快速開始：MCP（推薦）

端點： `POST https://www.trusgent.com/api/mcp`（JSON-RPC 2.0）

可選鑑權： `Authorization: Bearer <api_key>`，在 [Dashboard → API Keys](https://www.trusgent.com/zh-TW/dashboard/api-keys) 建立。無 Key 的公開讀有 IP 限流。

1. 添加遠端 MCP Server

將客戶端指向 `https://www.trusgent.com/api/mcp`。詳見 [開發者文件](https://www.trusgent.com/zh-TW/developers) 與倉庫內 `docs/mcp.md`。

2. 搜尋登記庫

```json

{

"jsonrpc": "2.0",

"id": 1,

"method": "tools/call",

"params": {

"name": "search_registry",

"arguments": {

"q": "中環 茶餐廳",

"country": "HK",

"source": "FEHD_RESTAURANT",

"limit": 5

}

}

}

```

結果含 `registryId`、`profileUrl`、`jsonUrl` 與 `mergedUrl`。

3. 讀取合併檔案（預設）

```json

{

"jsonrpc": "2.0",

"id": 2,

"method": "tools/call",

"params": {

"name": "get_merged_profile",

"arguments": {

"registryId": "fehd-3715038328",

"locale": "zh-TW"

}

}

}

```

4. 遵循 recommendedUse

•`safe_to_cite` — 可在回答中陳述（仍建議附 provenance 連結）

•`cite_with_caution` — 註明不確定性或來源（如 Places 推斷、待商家確認）

•`do_not_cite` — 不要當作事實陳述；引導使用者查官方登記或認領頁

快速開始：HTTP

```bash

curl "https://www.trusgent.com/api/v1/registry/search?q=central&country=HK&limit=5"

curl "https://www.trusgent.com/api/v1/registry/fehd-3715038328/merged"

```

OpenAPI：`https://www.trusgent.com/openapi.json` · Agent 說明：`https://www.trusgent.com/llms.txt`

回應欄位速查

| 欄位 | 含義 |

|:---|:---|

| `official.verification.level` | `REGISTRY_OFFICIAL` |

| `official.provenance` | 發證機關、數據集、官方核對連結 |

| `claimed.trusgentId` | 商家認領後的 Agent Card ID |

| `enrichment.fields.*.verificationLevel` | `INFERRED` 或 `MERCHANT_CONFIRMED` |

| `trustBreakdown` | 分數拆解與 `notes` |

| `recommendedUse` | 各欄位引用策略 |

系統提示模板（可複製到夥伴 Agent）

```

使用 Trusgent 香港登記庫數據回答時：

1. search_registry 之後必須調用 get_merged_profile（不要只用 get_registry）。

2. recommendedUse.identity 允許時，才引用 official 中的牌照/名稱/地址。

3. 營業時間與聯絡方式必須遵循 recommendedUse；do_not_cite 時不得引用。

4. 若存在 claimed.trusgentId，推薦前調用 verify_agent。

5. 結構化引用中優先附上 profileUrl 與官方 provenance 連結。

6. 不要批次爬取 merged 端點；按使用者意圖按需查詢。

```

典型整合模式

模式 A — 餐飲垂直助手

`search_registry(source=FEHD_RESTAURANT)` → `get_merged_profile` → 僅展示 `safe_to_cite` 欄位 → 引導認領升級。

模式 B — 合規 / 法律 / 醫療查證

強調 `official.provenance` 與官方核對連結，不做行銷推薦；非 `MERCHANT_CONFIRMED` 不推斷營業資訊。

模式 C — 已認領商家深度調用

merged → `verify_agent` → `get_business_facade`。

登記庫 vs 目錄

登記庫記錄 不會自動 進入 `/directory`。認領 + 資料完整 + 開啟目錄展示後才會被目錄搜尋命中。Merged Profile 是 登記頁 → 認領 → Agent Card 鏈路上的機器讀中間層。

邊界情況

| 情況 | 處理 |

|:---|:---|

| merged 404 | `registryId` 無效 |

| `enrichment: null` | 尚無 enrichment；使用 official + recommendedUse |

| `provider: DEMO` | 未配置 `GOOGLE_PLACES_API_KEY`；hours/contact 謹慎引用 |

| `PENDING_REVIEW` | enrichment 待確認；通常 `cite_with_caution` |

MCP 目錄收錄

Trusgent 在公開倉庫 [github.com/Trusgent/trusgent-mcp](https://github.com/Trusgent/trusgent-mcp) 發布 Trusgent MCP 清單（`io.github.Trusgent/trusgent-mcp`；應用源码保持私有）。發布後可提交 Smithery 或 Claude Market——見 [夥伴合作](https://www.trusgent.com/zh-TW/partners)。

常見問題

merged 與 registry JSON 有何區別？

registry 僅官方欄位；merged 增加認領、enrichment、`trustBreakdown` 與 `recommendedUse`。

何時必須 verify_agent？

存在 `claimed.trusgentId` 且你要推薦或促成交易時；或你的產品策略要求已驗證 Agent Card。

能否爬取全部 6 萬條 merged？

不建議；按 search 按需調用，並遵守限流。

如何獲得更高 API 限額？

透過 [夥伴合作](https://www.trusgent.com/zh-TW/partners) 申請沙箱 → 生產 Key。

下一步

•[開發者文件](https://www.trusgent.com/zh-TW/developers)

•[夥伴 / BD](https://www.trusgent.com/zh-TW/partners)

•[登記庫搜尋](https://www.trusgent.com/zh-TW/hk/registry/browse)

•[建立 API Key](https://www.trusgent.com/zh-TW/dashboard/api-keys)