語言EN繁
首頁
文件

SDK 教學 · 5 / 10

自訂 Agent 行為

把耐久的產品指引放在 system context，把 capability instruction 放在對應 host extension，並把 user-prompt formatting 保留給 request-specific framing。

客製化深度

層級 3 · 輸入與能力政策

託管深度

Quickstart 或 conversation engine

文件狀態

支援的 SDK 邊界

前置假設

  • 產品有跨 turn 都應套用的穩定行為指引。
  • 部分指引屬於特定 capability，而不是整個 agent。
  • 憑證與使用者私密資料不會進入 prompt 或 system context。
Heddle 負責
  • 在 turn 前，以確定性順序組合 engine 與 host-extension context。
  • 套用選定的 tool profile 與 Heddle runtime 所擁有的 domain context。
  • 持久化 conversation behavior，不要求 host 重建歷史。
產品端負責
  • 撰寫產品專屬目標、邊界、術語與 capability instruction。
  • 選擇模型、reasoning effort、visible tools 與 memory-maintenance policy。
  • 讓 request data、secret 與 authorization decision 留在適當的產品 layer。

用 system context 保存穩定的產品指引

TypeScript
import {
  createConversationEngine,
  defineHostExtension,
} from '@roackb2/heddle'

const recordsExtension = defineHostExtension({
  id: 'records',
  tools: [findRecord, updateRecord],
  systemContext: [
    'Use record tools only when the request concerns a product record.',
    'After a mutation, report the record ID and validation status.',
  ].join('\n'),
})

const engine = createConversationEngine({
  workspaceRoot,
  stateRoot,
  model,
  systemContext: [
    'You are an assistant embedded in the Acme product.',
    'Use concise product terminology and state uncertainty explicitly.',
  ].join('\n'),
  hostExtensions: [recordsExtension],
})

Engine-level systemContext 是穩定的 host guidance。它會補充 Heddle runtime-owned context，而不是取代整個 runtime system prompt。

Host-extension context 應說明何時以及如何使用該 extension。多個 extensions 會依宣告順序接在 engine context 後方。每個 extension 都應保持聚焦，讓它可以獨立加入或移除，而不需要改寫一份巨大的 global prompt。

只有 quickstart 擁有 loop 時才格式化 user prompt

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

await runQuickstartConversationCli({
  formatPrompt: (prompt) => [
    prompt,
    '',
    'Response requirements:',
    '- Mention validation status.',
    '- Link every saved artifact by ID.',
  ].join('\n'),
})

formatPrompt 會轉換每個送進 quickstart 的 prompt。它不是 system context，也不是 engine.turns.submit 的 option。產品開始自行掌控 engine 後，請在 application layer 建立 user message，並把穩定指引留在 engine 或 extension context。

控制模型可以看見哪些 tools

TypeScript
const engine = createConversationEngine({
  workspaceRoot,
  stateRoot,
  model,
  toolProfile: {
    preset: 'default',
    memoryMode: 'none',
  },
})

toolProfile 控制 model-visible tool policy，與 memoryMaintenanceMode 是不同設定：

  • toolProfile.memoryMode 控制模型是否看得到 memory tools。
  • memoryMaintenanceMode 控制 post-turn memory-maintenance scheduling。

若某個 turn 選擇 coding-agent profile，該 profile 的 tool policy 可以在那個 turn 覆蓋 engine default。產品 authorization 仍必須由 tool 與 host policy 執行。

用解析完成的預設值準備 extensions

若 extension 在 startup 前需要 quickstart 解析後的 stateRoot 或 model，請呼叫 resolveQuickstartConversationCliDefaults，準備 extension，再把兩者傳給 runner。不要在產品 code 中複製 Heddle 的 fallback order。

Prompt 安全與衛生

  • 不要讓 credential、access token、private key 或 raw provider error 進入任何 prompt layer。
  • 優先使用短而可測試的行為規則，不要放入整份產品手冊。
  • 把 authoritative domain data 放在 tools 後方，不要凍結在 system context。
  • 用實際 tool 與 failure cases 驗證行為；prompt prose 本身不是 policy boundary。

權威來源