語言EN繁
首頁
文件

SDK 教學 · 1 / 10

建立第一個 Agent

先用 Heddle quickstart runner 驗證模型、憑證、對話狀態與串流輸出，再開始設計產品自己的操作介面。

客製化深度

層級 1 · 預設對話迴圈

託管深度

單一 Node.js 20+ process

文件狀態

可執行參考範例

前置假設

  • 你的專案使用 Node.js 20 以上版本，以及相容 ESM 的 TypeScript。
  • 你已安裝 @roackb2/heddle，並設定至少一組受支援的模型憑證。
  • 在第一個步驟中，可以讓 Heddle 負責互動式終端機 prompt 與純文字輸出。
Heddle 負責
  • 在開啟對話前解析 workspace、本機 state root、模型與憑證。
  • 建立並持久化對話 session、執行 turn，並呈現串流文字與狀態。
  • 把 trace 與 artifact 記錄到解析完成的本機 state root。
產品端負責
  • 選擇模型並提供憑證。
  • 提供產品專屬 system context，並決定何時替換終端機體驗。
  • 在把本機預設值視為正式環境儲存之前，選擇耐久的應用程式資料目錄。

你將建立什麼

你會從 TypeScript entrypoint 啟動一個可持久化的 conversational agent。這是 SDK 評估路徑，不是完整的 Heddle coding-agent CLI。它刻意先接管本機 prompt loop，讓你在加入產品 UI、tool、hosting 或自訂 storage 前，先確認 runtime 正常運作。

1. 安裝 runtime package

Shell
npm install @roackb2/heddle

Root package 是經過整理的 Node.js SDK。不要在 browser code 中匯入它；遠端 browser client 會在後續 hosting 路徑使用獨立的 @roackb2/heddle-remote package。

2. 設定模型

穩定的 OpenAI 路徑如下：

Shell
export OPENAI_API_KEY=your_key_here
export HEDDLE_MODEL=gpt-5.4

若使用 Anthropic，請設定 ANTHROPIC_API_KEY 並選擇 Claude model。本機與 OpenAI-compatible provider 使用文件指定的 provider prefix。憑證應留在 server environment 或 secret manager；不要把憑證放進 prompt、system context 或持久化的產品 record。

3. 建立 entrypoint

TypeScript
import { runQuickstartConversationCli } from '@roackb2/heddle'

await runQuickstartConversationCli()

如果專案尚未設定 TypeScript runner，可以安裝 tsx 並直接執行 entrypoint：

Shell
npm install --save-dev tsx
npx tsx src/agent.ts

在 Heddle repository 中，對應的可執行範例是：

Shell
yarn example:sdk:interactive

Quickstart 會解析哪些預設值

未傳入任何 options 時，runner 會使用：

  • 目前 working directory 作為 workspaceRoot；
  • workspace 內的 .heddle 作為 stateRoot；
  • 依序從 HEDDLE_MODEL、HEDDLE_EXAMPLE_MODEL、OPENAI_MODEL、ANTHROPIC_MODEL 找到第一個已設定模型，最後才使用 Heddle 內建的 OpenAI 預設值；
  • credential preflight；若所選模型無法驗證，會在建立 session 前失敗；
  • 不設定預設的 hard step budget；
  • 不自動執行 memory maintenance；
  • 可持久化的對話狀態與純文字 streaming host。

Runner 會印出所選模型與 credential source。當一台機器可能同時存在多種憑證路徑時，這是很重要的驗證資訊。

加入少量產品行為

只要終端機 loop 仍符合需求，就可以先留在 quickstart layer：

TypeScript
import { runQuickstartConversationCli } from '@roackb2/heddle'

await runQuickstartConversationCli({
  model: process.env.MY_PRODUCT_MODEL,
  systemContext: 'You help users understand their project workspace.',
  promptLabel: 'project> ',
  credentialPreflight: {
    missingCredentialHint: 'Configure a model credential for this product first.',
  },
})

只有當產品確實需要限制單一 turn 的步數時才設定 maxSteps。任意使用過小的值，可能讓正常的 tool workflow 在完成前就被停止。

驗證這個 checkpoint

繼續之前，請確認：

  1. credential preflight 能正確指出模型與 auth source；
  2. 送出 prompt 後會收到串流輸出與最終結果；
  3. process 會在設定的 stateRoot 下建立耐久狀態；
  4. 同一次執行中的下一個 prompt 會延續已持久化的對話。

當產品需要自己的 rendering、command、approval UI、session browser 或 lifecycle 時，下一步改用 conversation engine。

權威來源