語言EN繁
首頁
文件

從這裡開始 · 責任邊界

重用執行環境，保留你的產品

Heddle 負責可重用的 Agent mechanics；你的產品仍然掌控使用者、資料、政策、部署、傳輸與體驗。

客製化深度

適用於所有客製化層級

託管深度

適用於所有託管層級

文件狀態

權威參考

Heddle 負責
  • 訊息、回合、延續、compaction、lease 與 session 持久化行為
  • 模型／工具執行、核准生命週期、追蹤、semantic activity 與 artifact
  • 選用的 run identity、ordered sequence、replay、cancel、terminal 與遠端 envelope validation
產品端負責
  • 經驗證的身分、tenant scope、access rules 與產品資料關係
  • 領域工具、system context、憑證、對外 schema、retention、encryption 與 backup
  • API framework、transport、routing、rate limit、部署、UI state 與結果套用

依賴方向

Text
你的產品
  UI state 與結果套用
          |
  remote consumer + optional HTTP/SSE client
          |
  你的 transport、authentication 與 public schemas
          |
  你的 application service 與 composition root
======================= HEDDLE SDK =======================
  ConversationRunService
  run identity、ordered activity、replay、cancel、approvals
          |
  ConversationEngine
  sessions、turns、compaction、traces、artifacts
          |
  models、tools、host extensions、MCP

依賴方向必須向下。Transport-neutral application service 不應讀取 HTTP request，Heddle core 也不應知道結果由哪個 frontend 呈現。

完整責任切分

關注點Heddle 負責產品端負責
對話訊息、回合、延續、compaction、lease、持久化行為Stable product conversation ID、資料關係、access rules
執行Model/tool loop、registration、host extensions、traces、artifacts領域工具、context、model choice、credentials、capability policy
核准Request 與 resolution lifecycle是否允許、經驗證的 approver、policy 與 UI
Active runsRun ID、ordered sequence、bounded replay、cancel、terminal settlementAddress scope、process lifetime、routing、draining、distributed delivery
遠端 clientEnvelope validation、cursor rules、duplicate/gap handling、terminal detectionPublic fields、timers、UI state、retry UX、notifications、result presentation
持久化本機 defaults 與可注入的 session/artifact portsProduction adapters、tenant binding、retention、encryption、backup
API 與 UI選用的 transport mechanicsFramework、routes、authorization、CORS、limits、errors 與所有視覺決定

避免重複實作執行環境行為

不要再次實作 Heddle 已經負責的 mechanics：

  • 不要在每個新 prompt 前重播完整產品聊天歷史；請重用同一個 Heddle session ID。
  • 不要為同一個 active Heddle run 再建立第二個 host-side run ID。
  • 不要在 ConversationRunService 上方再加一套 in-process event bus。
  • 不要把單一 subscriber disconnect 當成取消 underlying run。
  • 不要解析渲染後的 assistant text 來還原 structured failure 或 tool result。
  • 未經明確 public projection，不要把 internal trace、tool input、path 或 provider error 暴露出去。

實作前先回答

  1. 既有 server framework 與 transport 是什麼？
  2. 身分與 tenant scope 如何驗證？
  3. 哪一個 stable product ID 對應 Heddle conversation？
  4. 哪個 UI/state layer 會使用 run events？
  5. 一個 process 能否負責 active run 的完整生命週期？
  6. 正式環境需要哪些 repository、approval policy、tools 與 telemetry？

接著選擇最低且相符的層級，只複製假設與產品一致的 example stages。

接著閱讀建立第一個 Agent；如果產品已經有 conversation UI，也可以直接前往託管總覽。

權威來源