Skip to main content

建立 Generic Integration

在 Odin Studio 把你設計好的 Agent 透過 New Integration 對外發佈為一個 Generic 類型的整合 — 所有 Pattern(Hosted Embed / Direct Connect / Workflow Auth / Backend Relay)都從這裡取得 Endpoint 與 API Key 開始。

名詞對照: Generic Integration ↔ Bot Provider

你在 Odin UI 上建立的 Generic Integration, 就是 SDK / 架構文件中所稱的 Bot Provider — 它對外暴露為一個可呼叫的 AI Agent 端點。

  • UI 操作與本頁慣用 Generic Integration(對應畫面上的 New Integration → Generic)
  • 程式碼、API、SDK 文件慣用 Bot Provider(例如 SDK config 中的 botProviderEndpoint、環境變數 BOT_PROVIDER_API_KEY)

兩者指同一件事, 讀到後續 Pattern 與 SDK 文件時把它對應起來即可。

何時讀本頁

本頁是所有 Pattern 的共同前置作業。在 總覽與選型 選定 Pattern 後, 讀完本頁建立好 Integration, 再回到對應 Pattern 頁繼續。

如果你要整合 LINE / Discord / Slack / Telegram 等第三方平台, 請改看 第三方平台整合 — 那條路徑屬於另一種 Integration 類型, 跟本頁的 Generic 並列。

步驟 1: 進入 Apps​

從 Project 左側選單點擊 Apps 進入應用管理頁, 首次進入會是空的。點擊右上角 New Integration 開始建立。

Apps 入口

步驟 2: 填寫 Integration 設定​

依序填入基本資訊,應用類型選 Generic:

欄位說明
名稱自訂名稱, 日後在列表中辨識用
描述一句話寫清楚此 Bot 的用途
環境Workflows 預設建在 main, 若你有其他環境請對應選擇
工作流程集選擇要綁定的 Workflow Set(此 Integration 收到訊息會交給該 Workflow 處理)
應用類型選 Generic
API KeyGeneric 類型的存取憑證(pre-shared 密碼)
啟用預設啟用, 可暫時關閉而不刪除

建立 Generic Integration 表單

Debug Mode​

Debug Mode 控制 Integration 是否回傳額外的偵錯訊息到終端使用者裝置:

模式行為適用時機
Never(預設)不輸出任何偵錯訊息正式環境一律選此項, 確保效能與安全
Always持續輸出偵錯訊息開發期短期啟用, 排查訊息流問題
On-Demand僅當請求帶 is_debug=true 時輸出需要在不影響其他使用者下單獨除錯特定請求
偵錯訊息可能洩漏機敏資料

Always / On-Demand 都可能把 prompt、變數值、工具呼叫參數等內容回傳到使用者瀏覽器。只在開發或除錯需要時短期啟用, 正式環境務必切回 Never。

關於 API Key​

Generic 類型的 API Key 是一個 pre-shared 密碼 — 凡是知道這把 Key 的人都能存取此 Integration, 無法區分個別使用者身份。如果你需要 per-user 驗證或更細的存取控制, 在選擇整合模式的時候請務採用:

完整的存取控制策略見 Authentication & Access Control。

設定完成後儲存, Integration 就建立完成:

Integration 列表

步驟 3: 取得整合資訊​

在 Integration 卡片點擊右上角「⋯」更多選單, 選擇 檢視整合資訊, 即可看到後續 Pattern 會用到的兩項關鍵資訊:

  • Bot Provider Endpoint — Edge Server 上對應這個 Integration 的 URL(這也是「Bot Provider」第一次以技術名詞出現的地方 — 它就是你剛建立的 Generic Integration 對外暴露的端點)
  • API Key — 步驟 2 設定的存取憑證

檢視更多選單

整合資訊

管理你的 Integration​

同一個更多選單還提供以下動作:

  • View — 檢視 Integration 既有設定

    View

  • Edit — 修改設定(可隨時變更 Workflow Set、Debug Mode、API Key 等)

    Edit

  • Delete — 刪除 Integration(刪除後 Endpoint 立即失效, 使用該 Endpoint 的整合會中斷)

    Delete

下一步​

Generic Integration 建立完成、Bot Provider Endpoint 與 API Key 取得後, 回到 整合模式總覽 進入你選定的 Pattern: