事件與業務工具

事件是接入方告訴 AI 發生了什麼；工具是 AI 呼叫接入方查詢或執行能力。

事件

在控制台先建立、啟用事件，設定標識、描述、參數及 respond／record 處理方式，再透過私聊 API推送。一般文字訊息使用 type: message，不需要先建立自訂事件。

工具的三種執行方式

在控制台定義工具名稱、描述、輸入參數、呼叫條件與執行方式。送禮、查餘額等名稱只是業務示例，平台不會預置接入方的業務實作。

delivery	行為
["CALLBACK"]	模型呼叫時同步請求工具地址，拿到結果後再生成回覆；查詢工具只支援這種方式
["MESSAGE"]	本輪先登記計畫；回覆成功提交後，文字、素材、動作依序經訊息回呼投遞，由接入方執行
["CALLBACK","MESSAGE"]	同步回呼執行成功後，再發送展示用的動作訊息；展示不能再次執行

同步地址保存在工具配置，共用當前空間 TOOL 用途的簽章配置；須與已驗證地址同源（協議、域名、端口相同）。僅隨訊息投遞時不需要工具地址，但需要可用的訊息回呼。

同步工具請求

POST 至已配置的工具地址，事件類型為 tool.execute。OC-Event-Id 和 Idempotency-Key 為 callId。簽章方式見訊息回呼，但使用工具回呼金鑰。

{"type":"action","context":{"workspaceId":"1","conversationId":"456","personaId":"11","personaUid":"anchor-001","userId":"u-1001"},"action":{"callId":"stable-call-id","code":"send_gift","name":"送禮","mode":"EXECUTE","arguments":{"giftId":"rose","count":1}}}

動作欄位	說明
callId	穩定工具呼叫 ID；用於執行冪等
code / name	配置的工具標識／名稱
mode	EXECUTE 執行，NOTIFY 僅展示
arguments	按工具定義校驗的業務參數
result	展示訊息附帶已完成的同步執行結果

執行結果

在 HTTP 2xx 中返回頂層業務結果：

{"status":"SUCCEEDED","data":{"giftId":"rose","count":1}}

{"status":"FAILED","message":"餘額不足"}

結果不確定時返回 {"status":"UNKNOWN","message":"請核對原交易"}。接入方需自行校驗使用者權限、餘額等約束，並把冪等 ID 與業務結果一起持久化。

同步工具響應須在配置的 1–30 秒內完成，正文不超過 8000 UTF-8 位元組。非 2xx、非法狀態或超時都按未知處理。同步業務操作不會因未知結果直接自動再次執行；未知動作會限制同一會話繼續呼叫該工具，需核對。查詢工具可以重新查詢。

隨訊息投遞

使用訊息回呼、OC-Event-Type: chat.message：

{"actionId":"125","conversationId":"456","messageId":"791","type":"action","context":{"workspaceId":"1","conversationId":"456","personaId":"11","personaUid":"anchor-001","userId":"u-1001"},"action":{"callId":"stable-call-id","code":"send_gift","name":"送禮","mode":"EXECUTE","arguments":{"giftId":"rose","count":1}}}

EXECUTE 返回上述業務結果；重試規則遵循訊息回呼。NOTIFY 只需可靠接收並返回 2xx，action.result 是先前同步執行結果。

控制台測試收件箱的動作會返回 simulated: true 的模擬結果，並沒有真實執行。請用開放 API 與接入方系統驗證完整業務流程。