語言EN繁
首頁
文件

SDK 教學 · 3 / 10

加入原生工具

Native tool 是讓 agent 呼叫產品邏輯的最小邊界，同時讓 authorization、transaction 與 domain semantics 留在你的應用程式內。

客製化深度

層級 2 · 產品能力

託管深度

Quickstart 或 conversation engine

文件狀態

可執行參考範例

前置假設

  • 產品有一個 domain action 或資料查詢需要讓模型看見。
  • Tool 可以回傳 JSON-safe 的 Heddle ToolResult。
  • Host 會在變更產品狀態前驗證模型提供的輸入。
Heddle 負責
  • 註冊 tool、把 schema 提供給模型、執行 tool，並記錄 trace activity。
  • 在執行前套用設定好的 tool profile 與 approval policy。
  • 在 turn result 回傳已完成的 tool-call details。
產品端負責
  • 負責 input validation、authenticated identity、authorization、idempotency、transaction 與 domain error。
  • 選擇穩定的 public tool name、有用的 model-facing description 與最小 JSON Schema。
  • 決定哪些 capabilities 需要 approval，或不應讓特定 agent 看見。

定義最小且有用的 capability

ToolDefinition 是公開 contract。下列範例沒有模型提供的欄位，因此 runtime input 刻意保持為空：

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

const currentTime: ToolDefinition = {
  name: 'current_time',
  description: 'Return the current time as an ISO-8601 timestamp.',
  parameters: {
    type: 'object',
    properties: {},
    additionalProperties: false,
  },
  execute: async () => ({
    ok: true,
    output: new Date().toISOString(),
  }),
}

const productExtension = defineHostExtension({
  id: 'product-operations',
  tools: [currentTime],
  systemContext: 'Use current_time when the user asks for the current time.',
})

parameters 是提供給模型的 JSON Schema。Runtime 中的 execute 仍接收不可信任的 unknown input。Tool 若含有欄位，請在讀取或修改產品資料前，再用應用程式既有的 schema library 驗證一次。

你可以把 product.read 這類 application-defined 字串當成 metadata，但 Heddle 內建的 tool selection 與 read-only profile 不會推斷其語意。只有在語意確實相符時才使用文件列出的 built-in capability；否則請提供明確理解產品自訂標籤的 policy。

把 extension 加入 engine

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

const engine = createConversationEngine({
  workspaceRoot,
  stateRoot,
  model,
  hostExtensions: [productExtension],
})

若只是小型終端機評估，quickstart 也接受 tools: [currentTime]。新的 embedded engine 應優先使用 hostExtensions；直接傳入 ConversationEngineConfig.tools 只為相容性保留。

為下一個模型步驟設計 tool result

請回傳下列其中一種 shape：

TypeScript
{ ok: true, output: { recordId: 'rec_123', status: 'created' } }
{ ok: false, error: 'The requested record does not exist.' }

回傳精簡、結構化，而且能幫助模型決定下一步的資料。不要回傳憑證、內部 exception object 或無上限的 database rows。大型 generated body 應成為 artifact，而不是在每次 tool result 中重複傳遞。

Approval 與 capability metadata

  • 當 default policy 應在執行前請求 host decision 時，設定 requiresApproval: true。
  • 使用 capabilities 進行 tool-profile 與 approval-policy 分類。
  • Capability 不是 authorization。Tool implementation 仍必須驗證 authenticated product user 的權限。

組合規則

Host extensions 依宣告順序組合。Extension ID、tool name 與 toolkit ID 必須唯一；Heddle 會在第一個 turn 前拒絕重複值。Prompt、trace、policy 與 result handling 都可能引用這些名稱，因此應把它們視為穩定的 public API。

驗證

執行一個明確需要該 tool 的 prompt，確認 activity stream 顯示 call，且 turn result 的 toolResults 包含它。也請測試 invalid input 與 denied product authorization path，不要依賴模型永遠正確。

權威來源