語言EN繁
首頁
文件

SDK 教學 · 9 / 10

擷取與讀取產物

Artifact 是具有 metadata 與 content addressing 的耐久 generated value，讓模型與產品可以引用結果，而不必在每次 tool response 與 turn 中複製整份大型文件。

客製化深度

層級 4 · 耐久的 generated result

託管深度

本機檔案或注入 artifact repository

文件狀態

支援的 SDK 邊界

前置假設

  • MCP server 可能產生 source、HTML、JSON、document 或其他大型文字。
  • 產品需要在 producing turn 結束後檢查或重用 generated content。
  • Artifact metadata 與 content 仍受產品 conversation authorization 保護。
Heddle 負責
  • 建立 artifact ID 與 metadata、追蹤 current artifact pointer，並向 agent 提供 artifact tools。
  • 自動擷取已設定的大型 MCP result fields，並用精簡 reference 取代 mirror。
  • 透過 engine 已解析的 repository 與 root 讀取及列出 artifacts。
產品端負責
  • 決定哪些 output 應成為 artifact，以及 authorized user 如何下載或套用。
  • 在正式環境提供 retention、encryption、content validation，以及與 Heddle 目前同步 artifact port 相容的 storage；或回傳產品自己的 remote reference。
  • 投影安全的 metadata，不公開 internal content key 或 filesystem path。

從自動擷取 MCP result 開始

若 MCP extension 會回傳 generated text、HTML、JSON 或 document body：

TypeScript
const prepared = await prepareMcpHostExtension({
  id: 'document-operations',
  workspaceRoot,
  stateRoot,
  serverId: 'documents',
  server,
  resultArtifacts: true,
})

Automatic capture 會遍歷 MCP result、儲存達到大小門檻的字串、推斷常見 kind，並用同一個 compact artifact reference 取代重複的 text/structured mirror。它也會處理 text field 重複 serialized structured content 的常見 MCP shape。

請先使用 boolean option。觀察真實輸出後才調整：

TypeScript
resultArtifacts: {
  auto: {
    minChars: 1200,
    domain: 'document',
    maxPreviewChars: 800,
  },
}

Path hint 與 manual rule 是給穩定 server-specific result shape 的進階 override。第一次 integration 不要與猜測的 nested path 緊密耦合。

從 engine boundary 讀取 artifacts

TypeScript
const artifacts = engine.artifacts.list({ sessionId })
const readResult = engine.artifacts.read(artifactId)

if (readResult) {
  console.log(readResult.artifact)
  console.log(readResult.content)
}

請使用 engine.artifacts，不要自行用 stateRoot/artifacts 建立另一個 ArtifactService。Host extension 或 injected repository 可能改變 resolved location。

理解 turn-result artifact scope

result.artifacts 是目前與該 session 關聯的 artifact list，不只包含本次 turn 新建立的 artifact。請使用 artifact ID、timestamp、domain、kind 或產品自己的 record，區分新產物與先前累積的產物。

result.toolResults 則只包含本次 turn 完成的 tool calls。

精簡 replacement shape

Automatic capture 取代大型 value 後，tool result 會包含等同下列內容的 metadata：

TypeScript
{
  artifact,
  contentPath,
  preview,
  omittedCharacters,
}

完整內容仍可透過 Heddle artifact reader/tool path 取得。Preview 讓模型可以理解 value，而不需要再次載入全文。

原生工具行為

resultArtifacts 是 MCP host-extension capture，不會自動轉換任意 native-tool output。若 native tool 使用產品自己的非同步 document store，請先把 value 存到該處，再回傳精簡且經授權的 reference：

TypeScript
execute: async (input) => {
  const document = await productDocuments.create(input)
  return {
    ok: true,
    output: { documentId: document.id, preview: document.preview },
  }
}

若 value 必須成為 Heddle artifact，請在 host boundary 明確使用同步的 engine.artifacts.saveText(...)，並納入使用自有儲存層所說明的 storage 限制。

正式環境注意事項

  • 依據所屬 product conversation 或 record，授權每次 artifact read；
  • 套用到 user-visible product object 前，驗證 generated content；
  • 為 metadata 與 content 設定 retention 和 deletion policy；
  • 不要在 public response schema 暴露 repository content key 或 local path。

權威來源