#怎麼把產品做成「AI agent 也能操控」— 一份實作清單

前兩篇講的是取捨與架構。這篇動手 —— 給開發者一份具體清單：如果你相信未來幫人辦事的會是 AI agent，你的產品該怎麼做，才能讓 agent 不只「看得到」、還「用得了」。

我們在 UD House 上實際這樣做了。下面講的三個對外零件（REST API、OpenAPI、llms.txt）跟 Web 後台都已經 live；MCP server 跟 Pin 入口還在內測 —— 我會在相關段落標明，不混為一談。

#為什麼要為 agent 做

先講賭注：未來很多事，不是人親手點按鈕完成的，而是一個 agent 幫你跑 —— 你的 agent，或是別人的。

如果這成真，那「只給人看的網站」就不夠了。你的產品要同時是程式讀得懂的介面。這不是加分項，我認為會變成基本門檻。

具體要做三件事。

#零件一：開放 REST API（action 層）

最底層，是把產品的能力做成一組乾淨、可程式呼叫的動作 —— 不是只藏在前端按鈕後面。

UD House 的 /api/v1 就是這層：建物件、傳相生成草稿、改狀態、生成文案、查 lead，每個都是一個 endpoint，用一把 API key（Bearer udh_…）認證。

關鍵心法：前端按鈕能做的事，API 都要能做。 如果一個功能只活在 UI 裡，agent 就碰不到它。把「動作」跟「介面」分開，動作才能被人用、也被 agent 用。

#零件二：公開 OpenAPI spec（機器可讀的契約）

光有 API 不夠 —— agent 怎麼知道有哪些 endpoint、要傳什麼參數？

答案是公開一份 OpenAPI spec（我們放在 /api/v1/openapi.json）。它是一份機器可讀的契約：列清楚每個 endpoint、方法、參數、回傳格式。任何 agent 或工具 import 進去，就「知道」整個 API 怎麼用，不用你寫一頁頁文件給它讀。

#零件三：llms.txt（給 LLM 自我引導）

OpenAPI 是給「已經知道要用你 API」的工具。但一個 agent / 爬蟲第一次碰到你的網站，怎麼知道你是誰、能幹嘛？

這就是 llms.txt —— 放在網站根目錄的一份純文字說明，專門寫給 LLM 看：這個平台是什麼、有哪些能力、API 在哪、怎麼開始。它之於 AI agent，就像 robots.txt 之於搜尋引擎爬蟲 —— 一個約定俗成的入口。

UD House 的 social.8338.hk/llms.txt 就是這樣：一個 agent 讀完，就知道這是個房仲平台、有 Agent API、規格在哪。

#把三塊接起來：一份 SKILL.md 當源頭

API + OpenAPI + llms.txt 是「對外」的三個面。它們背後最好有單一真相，不然三份東西會各自漂走、對不上。

我們用一份 SKILL.md：宣告這個產品有哪些 entities、能做哪些 actions。OpenAPI、llms.txt、給人的後台、給 agent 的 MCP，理想上都從這一份長出來 —— 改一次，四面同步。

（誠實說明：UD House 的 API、OpenAPI、llms.txt、Web 後台都已 live；MCP server 跟 Pin 入口目前還在內測。但它們吃的是同一份 SKILL.md，這個源頭已經成形。）

#實例：一個 agent 怎麼自己跑完

把上面接起來，一個 agent 的流程長這樣：

1. 讀 social.8338.hk/llms.txt        → 知道這是房仲平台 + 有 Agent API
2. 讀 /api/v1/openapi.json            → 知道每個 endpoint 怎麼呼叫
3. 用一把 udh_ key：
   POST /api/v1/listings/from-photo   → 傳一張相，AI 回傳抽好的草稿欄位
   POST /api/v1/listings              → 用草稿建物件，拿到 share_url
   POST /api/v1/listings/{id}/promo   → 生成多語文案
   GET  /api/v1/leads                 → 查 AI 客服收到的 lead

全程沒有人手點任何一個按鈕。一個房仲（或他的 agent）可以在對話裡說「幫我把這張相出盤、寫文、看有沒有客」，agent 讀完文件就自己跑完。

#收束：agent-ready 不是「加個 API」

最後一個觀念上的提醒：讓產品 agent-ready，不是事後補一個 API 上去，而是從設計時就把「給 agent 操控」當成第一公民。

它意味著：動作跟介面分開、契約公開可讀、入口（llms.txt）寫給機器看、所有面共用一份源頭。

人從 UI 進來，agent 從 API 進來，走的是同一條路 —— 這就是我說的「人和 AI 都讀得懂」。趁現在做，等 agent 真的普及那天，你已經在門裡面。