語言EN繁
首頁
文件

Heddle 文件

使用 Heddle 建立 Agentic Experience

先建立可運作的對話，再只採用產品真正需要的執行環境、能力、託管與客戶端層級。

客製化深度

選擇最小且實用的執行環境邊界

託管深度

行程內、託管、遠端或產品 UI

文件狀態

支援的 SDK 邊界

Heddle 負責
  • 持久對話與回合語意
  • 模型與工具執行、核准、追蹤紀錄與產物
  • 有序的 active run、重播、取消與終結結果
產品端負責
  • 身分、租戶、授權與產品資料關係
  • 領域工具、模型憑證、儲存政策與對外 schema
  • Server framework、傳輸、部署、UI 與結果套用方式

整合證據

看看真實產品如何壓力測試 Heddle 的邊界。

SlideX 驗證嵌入式 Product Agent 整合；Lucid 驗證使用者離開後的排程與隔離執行。透過兩個案例選擇產品真正需要的 Heddle 層級。

產品整合回顧

SlideX

歷史部署 · 首次第三方整合

曾整合對話式 Agent，讓使用者建立與修改真正簡報的瀏覽器工作區。

SlideX 如何促使 Heddle 從自用 Agent 引擎走向產品 SDK。

2026 年 7 月，SlideX 曾部署由 Heddle 驅動的對話式簡報 Agent。之後 SlideX 結束公開託管版本並轉回本機運作方向，但這次整合成為一場重要的壓力測試，促使 Heddle 演進成可重用的產品 SDK。

  • 整合真正的簡報工具
  • 驗證可持久化的多輪對話
  • 塑造 Heddle 公開 SDK 邊界
閱讀產品整合回顧
SlideX 編輯器中，簡報與多輪 SlideX Agent 對話並排顯示
攝於 2026 年 7 月部署期間：真正的 SlideX 對話要求 Agent 調整投影片風格、加入 SDK 內容，並插入章節頁。
查看所有實際案例

把 Heddle 想成一間工作坊

用工作坊來理解，會更容易記住每個元件的責任：

工作坊角色元件責任
前台你的產品 backend認識使用者、授權 request、選擇產品 ID 與政策，並擁有 database 與 UI
安全工單與追蹤Heddle adopter contract 與 lifecycle攜帶簽署過的 scope、提交工作，並讓 requested、accepted、interrupted 與 terminal 狀態保持真實
工作坊建築Compatible Execution Host把 execution 與產品 database 隔離，並提供 workstation 執行空間
機具與工作人員Heddle runtime執行 conversation、model、tool、approval、trace、artifact 與 workspace operation
受控服務窗口產品的 scoped MCP endpoint只讓 Agent 使用本次 invocation 已授權的產品能力
產品帳本你的產品 database透過產品自有的 atomic adapter、schema、migration 與 retention policy 儲存記錄
Text
產品使用者
     |
你的產品（前台 + identity + policy + ledger + UI）
     |
HEDDLE ADOPTER CONTRACT（安全工單 + durable tracking）
     |
COMPATIBLE EXECUTION HOST（隔離的工作坊建築）
     |
HEDDLE RUNTIME（機具、工作人員、tool、workspace）
     |
SCOPED MCP 窗口 ----------> 你的產品 API 與資料

在 embedded 形態中，TypeScript／Node backend 同時是前台與工作坊：它直接 import @heddleagent/runtime。只有當同一個 process 需要可定址 run、replay、cancellation 或 reconnect 時，才加入 @heddleagent/runtime/runs。Run service 仍在你營運的 infrastructure 中，並不是 Heddle cloud service。

在 獨立 host 形態中，只有 compatible Execution Host 會 import Heddle runtime。Python、Go、Java、TypeScript 或其他 backend 透過 versioned OpenAPI、JSON Schema、JWT、SSE 與選用的 durable-lifecycle profile 整合。TypeScript 團隊可使用 @heddleagent/execution-host-client 的受支援 helper；每個 adopter 仍提供自己的 database adapter 與產品政策。

產品擁有一筆記錄，不代表產品程式碼應重做通用 state machine。Heddle 定義 lifecycle transition 的意義與 commit 時機；產品 adapter 定義如何 atomic 儲存；產品則決定使用者可以查詢哪些記錄，以及 UI 如何呈現。

先分清楚每個 package

Package用途不要把它誤認為
@heddleagent/runtime受支援的 TypeScript／Node Agent runtime 與 SDKBrowser library 或 language-neutral runtime
@heddleagent/cli可安裝的 heddle coding-agent command、TUI、daemon 與本機 browser control planeEmbeddable SDK
@heddleagent/runtime/runs長駐 Node process 內的可定址 run另外部署的 Execution Host
@heddleagent/run-client在 browser-safe 邊界消費 hosted-run eventExecution backend
@heddleagent/execution-host-client對獨立 compatible host 提供 TypeScript helper 與 canonical v1 artifactHeddle runtime 或公開 hosted service
@heddleagent/postgres/execution-host/conversations為通用 Execution Host turn lifecycle 提供官方 PostgreSQL adapterProduct conversation history、通用 storage layer 或 pool ownership
@heddleagent/postgres/heartbeat為 durable Heddle heartbeat task 提供官方 PostgreSQL authorityScheduler、product database 或通用 storage layer

受維護的 embedded runtime 是 TypeScript／Node；獨立 host 的 network 與 durable-lifecycle boundary 則是 language-neutral。公開 npm artifact 包含 canonical wire specification；permissioned canonical source 內的 Python 實作提供 clean-room conformance proof，但不是已發布或受支援的 Python SDK，也不保證同步每一個 TypeScript convenience。現有 compatible Execution Host 仍採 permissioned access；Heddle 目前沒有提供公開 managed hosting service。

舊的 @roackb2/* coordinate 已 deprecated，只為了讓既有 application 繼續運作而保留安裝能力。新的 integration 應使用 @heddleagent/* package family；durable heartbeat task authority 使用 @heddleagent/postgres/heartbeat。

選擇符合產品現況的路徑

你想完成的事情從這裡開始你需要負責的部分
在 TypeScript 行程中評估 Heddle建立第一個 Agent設定與 prompts
把 Heddle 加進既有 backend選擇整合層級產品組裝與既有邊界
加入領域工具或 MCP server加入原生工具 或 連接 MCP領域行為與能力政策
在自有應用程式中呈現 Agent接管輸出與活動呈現、UI state 與結果處理
讓一次執行超過單一 request 的生命週期託管總覽身分、address scope、行程生命週期與傳輸
建立瀏覽器產品遠端客戶端對外 schema、重新連線 UX 與產品 UI state
從任意 backend 語言呼叫獨立 compatible Execution Host選擇整合層級Product admission、database adapter、MCP policy、結果套用與部署
先在本機體驗完整參考產品本機快速開始一個工作區與模型存取

從兩個維度逐步學習

Heddle 不會強迫產品採用單一技術棧。請分開決定兩件事：

  1. **客製化深度：**從完整 prompt loop 開始，再逐步接管能力、輸出、生命週期、政策與持久化。
  2. **託管深度：**留在單一行程、加入可定址 run、公開傳輸層，或連接遠端產品 UI。

整合層級選擇器會把這兩個決定對應到最小且合適的 public package surface。

建議的第一條學習路徑

第一次學習 Heddle 時，請依序閱讀 使用 SDK 建立 Agent：

  1. 執行一個可持久化的 conversational agent。
  2. 建立穩定 session，並送出第二個回合。
  3. 加入一個產品自有工具。
  4. 只有在能力已存在 MCP server 後方時，才加入 MCP。
  5. 把能力專屬的 system context 放在該能力旁邊。
  6. 用自有應用程式介面取代預設文字輸出。
  7. 先處理結構化結果；當 capability 需要決策時，再連接核准政策。
  8. 只有產品需要時，才加入 artifact 與 storage adapter。

你可以停在任何已經有用的層級；託管與瀏覽器層都是選用的。

本機 Coding Agent 是參考宿主

Heddle 的 terminal UI 與 browser control plane 使用 SDK 所公開的同一套對話、活動、核准、追蹤與 run 基礎。你可以先用它們理解 Heddle，再只採用產品需要的層級來打造自己的體驗。

權威來源