語言EN繁
首頁
文件

架構指南

選擇 Heddle 在產品中的整合方式

任務執行多久，並不能決定整合方式。嵌入式 Heddle Runtime 可以工作幾秒，也可以工作幾小時；真正的問題是執行應該放在哪裡，以及誰要負責它的生命週期。

客製化深度

Runtime 與生命週期責任

託管深度

嵌入式或獨立 Host

文件狀態

架構指南

前置假設

  • 你的產品擁有使用者身分、授權、Canonical Data、政策、外部效果與 UI。
  • 你想重用 Heddle，但不想讓 Heddle 變成產品的 Application Framework。
  • 你會分開選擇隔離需求與生命週期深度，而不是用任務時間長短代替架構判斷。
Heddle 負責
  • 可重用的模型、工具、對話、核准、產物與活動 Runtime。
  • 選用的 Agent Run 管理，提供穩定 Run Identity、串流、重播、取消、核准、重新連線與 Terminal Settlement。
  • 呼叫獨立部署之相容 Execution Host 的公開 Adopter Contract。
產品端負責
  • 把已登入使用者可信地映射到租戶、對話、專案與 Capability Scope。
  • Heddle 採嵌入式執行時的 Process 與部署拓樸，或是否引入獨立 Host 的架構決策。
  • Canonical Product Transaction、歷史查詢、保留政策、使用者可見狀態，以及成功的產品定義。

不要用任務時間長短選擇架構

嵌入式 Heddle Runtime 就是一般 Application Code。Backend 可以在 HTTP Request 內等待一個 Turn，也可以從 Queue Worker 啟動，或讓它在原始 Request 回應後繼續執行。@heddleagent/runtime 並沒有要求 Execution 必須和原始 Request 同時結束。

兩個選用層解決的是不同問題：

  • Agent Run 管理標準化產品如何辨識、觀察、控制與結算一次 Execution。
  • 獨立 Execution Host改變 Runtime 的執行位置，並新增一個部署與信任邊界。

兩者彼此相關，但不是同一條架構軸線。

兩個獨立決策

1. Runtime 在哪裡執行？

部署位置意義
嵌入式@heddleagent/runtime 直接執行在產品營運的 TypeScript 或 Node.js Backend、Server、Worker 或 Desktop Process 中。
獨立 Host相容 Execution Host 匯入 Heddle，並在獨立部署的環境中執行；Adopter Backend 透過公開 Network Contract 呼叫它。

2. 誰負責一次 Execution 周圍的生命週期？

生命週期方式意義
直接執行產品直接呼叫 Conversation Engine；需要 Run ID、事件傳遞、取消 Route、核准 Route 或 Reconnect 時，由產品自行實作。
Agent Run 管理@heddleagent/runtime/runs 提供穩定 Run Identity，以及事件排序、重播、取消、核准、重新連線、產品結果投影與單一 Terminal Outcome 的可重用生命週期。

常見的漸進路徑是：

Text
嵌入式 Runtime
  在 Backend 中直接呼叫 Heddle
            |
            | 需要時加入可重用的 Execution Lifecycle
            v
Agent Run 管理
  Heddle 仍執行在你的 Server 或 Worker
            |
            | 需要時再新增獨立部署與信任邊界
            v
獨立 Execution Host
  同一套 Runtime 改在隔離環境中執行

這是漸進式採用路徑，不是三個互斥產品。獨立 Host 本身也可以提供受管理的 Run Workflow；Agent Run 管理仍是生命週期概念，而 Execution Host 是部署位置與 Authority Boundary。

選擇能解決實際問題的最小整合方式

你的需求建議起點
從 Node Backend 呼叫模型與工具，並由產品自行處理輸出嵌入式 Runtime
在 Queue 或背景 Worker 執行，而產品已經擁有完整控制與傳遞語意嵌入式 Runtime
讓多個 Request 或 Client 找到、訂閱、重播、取消、核准或重連同一次 Execution嵌入式 Runtime + Agent Run 管理
讓 Agent Workstation 遠離 Application Process 與產品資料庫 Credential獨立 Execution Host
從 Python、Go、Java 或其他非 Node Backend 呼叫 Heddle Runtime獨立 Execution Host Contract
獨立部署、隔離、替換或擴展 Execution Environment獨立 Execution Host
只是讓任務執行很久單靠時間長短，不需要任何選用層

產品始終是權威來源

不論採用哪種方式，產品責任都不會移進 Heddle。產品仍負責驗證使用者、推導租戶與專案 Scope、決定可用 Capability、擁有 Canonical Data 與外部效果，並呈現結果。Heddle 負責可重用的執行機制；產品決定這份工作代表什麼。

公開狀態

嵌入式 Runtime 與 Agent Run 管理套件均已公開並開源。獨立 Host 的 Adopter Contract、語言中立 Artifact 與整合 Helper 也已公開。目前相容 Execution Host 的完整實作與 AgentCore 受管部署仍是私有研究；Heddle 現在沒有營運公開的 Managed Execution Host 或 Cloud Service。

當 Client 需要穩定的 Execution Lifecycle 時，繼續閱讀 Agent Run 管理；當 Execution 需要新的部署位置、Authority 或隔離邊界時，閱讀獨立 Execution Host。

權威來源