Artifact

Artifact cho phép agent gửi nội dung có cấu trúc, tương tác cho người dùng qua A2H Protocol (Agent-to-Human, phiên bản 0.3). Thay vì mô tả biểu mẫu bằng văn bản, bạn gửi biểu mẫu thực mà người dùng có thể điền.

Gửi 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,
});

Cập Nhật Artifact

Cập nhật artifact đã gửi trước đó để phản ánh tiến độ hoặc trạng thái mới:

await agent.updateArtifact(conversationId, {
  ref_artifact: "artifact_id",
  revision: 2,  // Phải lớn hơn revision hiện tại
  updates: {
    status_block_key: {
      state: "done",
      label: "Completed",
    },
  },
});

Nhận Phản Hồi Người Dùng

Khi người dùng tương tác với artifact (gửi biểu mẫu, nhấn nút), phản hồi đến qua onEvent:

agent.onEvent((event) => {
  if (event.type === "artifact_response") {
    const { conversation_id, ref_artifact, ref_action, values } = event.payload;
    // values chứa dữ liệu biểu mẫu người dùng gửi
  }
});

Loại Block

Artifact được tạo từ các block. Mỗi block có tag xác định loại:

Tag	Mô tả	Ví dụ sử dụng
input	Nhập văn bản, textarea, số, ngày	Trường biểu mẫu
select	Dropdown hoặc lựa chọn radio	Danh sách tùy chọn
checkbox	Toggle boolean	Xác nhận
action	Nút (primary, secondary, danger)	Gửi, hủy, phê duyệt/từ chối
text	Văn bản hiển thị tĩnh	Hướng dẫn, mô tả
status	Chỉ báo tiến độ	Thanh tiến độ nhiệm vụ
table	Hiển thị dữ liệu dạng bảng	Kết quả tìm kiếm, bảng dữ liệu
code	Code với syntax highlighting	Đoạn code
image	Hình ảnh nhúng	Biểu đồ, sơ đồ
divider	Phân cách trực quan	Ngắt phần

Artifact Subtype

Subtype	Mục đích
form	Thu thập đầu vào người dùng
status	Hiển thị tiến độ nhiệm vụ
result	Hiển thị kết quả cuối
error	Hiển thị thông tin lỗi
table	Hiển thị dữ liệu có cấu trúc
code	Hiển thị code với syntax highlighting

Giới Hạn

Ràng buộc	Giá trị
Block tối đa mỗi artifact	16
Kích thước payload A2H tối đa	64KB
Tổng payload tối đa (bao gồm bọc)	200KB
Cập nhật tối đa mỗi vòng đời artifact	100
Mặc định cho phép chuyển tiếp	Không

SDK Xử Lý

• Mã hóa payload artifact trước khi gửi
• Tạo văn bản xem trước cho thông báo
• Định tuyến qua WebSocket hoặc REST fallback
• Kiểm tra cấu trúc payload

Bước Tiếp Theo

• Gửi Tin Nhắn — Tin nhắn văn bản và media
• Streaming — Truyền phản hồi thời gian thực
• Data Grant — Yêu cầu truy cập dữ liệu người dùng