跳到內容
Hashee Docs

Artifact

Artifact 讓 Agent 透過 A2H Protocol（Agent-to-Human，版本 0.3）向使用者傳送結構化、互動式的內容。你可以直接傳送一個使用者可以填寫的表單，而非用文字描述表單。

傳送 Artifact

await agent.sendArtifact(conversationId, {
  artifact: {
    a2h: "0.3",
    subtype: "form",
    blocks: [
      {
        tag: "input",
        key: "name",
        variant: "text",
        label: "Project name",
        required: true,
      },
      {
        tag: "input",
        key: "description",
        variant: "textarea",
        label: "Description",
      },
      {
        tag: "action",
        key: "submit",
        label: "Create Project",
        variant: "primary",
      },
    ],
  },
  title: "New Project Form",
  summary: "Fill in the project details",
  forwardable: false,
});

更新 Artifact

更新先前傳送的 Artifact 以反映進度或新狀態：

await agent.updateArtifact(conversationId, {
  ref_artifact: "artifact_id",
  revision: 2,  // 必須大於當前修訂版號
  updates: {
    status_block_key: {
      state: "done",
      label: "Completed",
    },
  },
});

接收使用者回應

當使用者與 Artifact 互動（提交表單、點擊按鈕）時，回應透過 onEvent 到達：

agent.onEvent((event) => {
  if (event.type === "artifact_response") {
    const { conversation_id, ref_artifact, ref_action, values } = event.payload;
    // values 包含使用者提交的表單資料
  }
});

區塊類型

Artifact 由區塊組成。每個區塊有一個 tag 來決定其類型：

Tag說明使用範例
input文字輸入、文字區域、數字、日期表單欄位
select下拉選單或單選選項列表
checkbox布林切換確認項目
action按鈕（主要、次要、危險）提交、取消、批准/拒絕
text靜態顯示文字說明、描述
status進度指示器任務進度條
table表格式資料展示搜尋結果、資料表
code語法高亮程式碼程式碼片段
image嵌入式圖片圖表、圖示
divider視覺分隔線區段分隔

Artifact 子類型

子類型用途
form收集使用者輸入
status顯示任務進度
result顯示最終輸出
error顯示錯誤資訊
table結構化資料展示
code帶語法高亮的程式碼展示

限制

約束值
每個 Artifact 的最大區塊數16
A2H 載荷最大大小64KB
含封裝的最大載荷200KB
每個 Artifact 生命週期的最大更新次數100
預設可轉發否

SDK 處理的事項

  • 在傳送前加密 Artifact 載荷
  • 建構通知用的預覽文字
  • 透過 WebSocket 或 REST 回退路由
  • 驗證載荷結構

下一步