語言EN繁
首頁
文件

選用的生命週期層

不移動 Runtime，也能加入 Agent Run 管理

Agent Run 管理不會讓 Heddle 突然變得能執行更久；它讓一次 Execution 可以被一致地辨識、觀察、控制、重新連線與真實結算。

客製化深度

Execution Lifecycle

託管深度

你的 Server 或 Worker

文件狀態

支援的 SDK 邊界

前置假設

  • Heddle 已執行在你營運的長駐 TypeScript 或 Node.js Process 中。
  • Client、Route、Worker 或 Operator 可能需要不只一次指向同一個 Execution。
  • 產品會對每次 Start、Subscribe、Cancel、Approval 與保留 Run 查詢進行驗證與授權。
Heddle 負責
  • 穩定 Run Identity、每個 Host-defined Address 一個 Active Run、事件排序、有限重播、取消、核准處理與單一 Terminal Outcome。
  • Success 顯示前的安全產品結果投影，以及對 Subscriber 的安全公開錯誤投影。
  • Transport-neutral Run Handle，以及選用的 Node HTTP/SSE 與 Browser Client Helper。
產品端負責
  • Server 或 Worker Process、Routing、驗證、租戶授權、工具、Credential、Storage Adapter 與 Approval Policy。
  • Product Conversation 與 Heddle Session 的映射，以及所有 Public API 與 UI 決策。
  • 需要時的跨 Process 傳遞、Restart Recovery、Durable Active-work Orchestration 與容量政策。

直接執行與受管理執行都可以在背景繼續

只要 Host 在 Worker 中啟動，或持續保有執行中的 Promise，直接嵌入的呼叫也可以在 HTTP Response 結束後繼續。差別不在於執行時間，而在於產品是否要自行發明並維護周圍的生命週期。

直接呼叫 Conversation Engine 時：

Text
產品程式碼 -> submit turn -> model 與 tools -> result

產品自行決定是否需要另一個 Execution ID、Event Buffer、Reconnect Cursor、Cancel Route、Approval Route、Retained Handle 與 Terminal State Machine。

加入 Agent Run 管理後：

Text
產品程式碼 -> start managed run -> runId
                                  |
                                  +-> ordered event stream
                                  +-> replay from sequence
                                  +-> cancel exact run
                                  +-> resolve exact approval
                                  +-> one terminal outcome

Heddle Runtime 仍然執行在同一個 Adopter-operated Server 或 Worker。@heddleagent/runtime/runs 只是在外圍加入可重用的 Application Lifecycle；它不是另一個 Cloud Service 或部署目標。

這一層提供什麼

  • 每次確切 Execution 都有穩定 runId；
  • 每個 Host-defined Conversation Address 同時只有一個 Active Run；
  • 單調遞增且排序明確的活動與 Terminal Event；
  • 讓斷線後回來的 Client 使用有限重播；
  • 取消綁定確切 Run，而不是影響稍後碰巧成為 Current 的另一個 Execution；
  • 核准綁定確切 Run 與 Approval Request；
  • 成功 Terminal 發布前，先等待產品結果投影完成；
  • 一個明確的 result、cancelled 或 error Terminal；以及
  • 透過選用套件提供 Browser-safe Client Validation 與 Reconnect Helper。

較底層的架構文件有時會把具有穩定身分的 Run 稱為 addressable。對產品而言，意義很簡單：之後仍然可以可靠地指向同一次 Execution。

這一層刻意不提供什麼

Agent Run 管理是 Process-local。保留的 Handle 與 Replay Buffer 不會在 Process Crash 後復原，也不會自動跨多個 Instance Routing。它不是 Queue、Scheduler、Distributed Broker、Durable Active-work Database、隔離工作站或 Managed Cloud Service。

需要 Restart Recovery 或 Multi-worker Ownership 的產品，仍要加入合適的 Durable Work System。需要獨立 Process 或信任邊界時，應評估獨立 Execution Host。

什麼時候值得加入

只要以下任一項屬於產品 Contract，就適合加入 Agent Run 管理：

  • 初始 Request 在 Execution 結算前就會回應；
  • 另一個 Request 或 Client 必須找到同一個 Active Execution；
  • 使用者可能斷線，之後再恢復排序進度；
  • 取消或核准會從稍後的 Interaction 抵達；
  • 產品必須區分 accepted、active、cancelled、failed 與 successful execution；或
  • 產品狀態必須在 Success 對外可見前完成 Commit。

如果一次 Application Call 只要等待 Turn Result，而且沒有其他 Actor 需要觀察或控制該 Execution，就可以先不加入。之後仍能加入這一層，不必把 Runtime 移到另一個 Deployment。

前往 API 教學

這個概念層由 @heddleagent/runtime/runs 的 ConversationRunService 實作。接著閱讀 ConversationRunService API 指南，了解 Construction、Start、Subscribe、Replay、Cancel、Approval、Projection 與限制。只有當該 Transport 符合你的 Server 時才加入 Node HTTP/SSE；只有 Event 會跨越不可信 Client Boundary 時才加入遠端客戶端。

權威來源