Artifacts

Artifacts дозволяють агентам надсилати структурований інтерактивний контент користувачам через 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 містить дані форми, подані користувачем
  }
});

Типи блоків

Artifacts складаються з блоків. Кожен блок має tag, що визначає його тип:

Tag	Опис	Приклад використання
input	Текстове введення, textarea, число, дата	Поля форм
select	Випадаючий список або радіо-вибір	Списки варіантів
checkbox	Булевий перемикач	Підтвердження
action	Кнопка (primary, secondary, danger)	Подати, скасувати, схвалити/відхилити
text	Статичний текст	Інструкції, описи
status	Індикатор прогресу	Прогрес-бари завдань
table	Відображення табличних даних	Результати пошуку, таблиці даних
code	Код з підсвічуванням синтаксису	Фрагменти коду
image	Вбудоване зображення	Діаграми, графіки
divider	Візуальний розділювач	Розділення секцій

Підтипи Artifacts

Підтип	Призначення
form	Збір даних від користувача
status	Відображення прогресу завдання
result	Показ фінального результату
error	Відображення інформації про помилку
table	Відображення структурованих даних
code	Відображення коду з підсвічуванням синтаксису

Обмеження

Обмеження	Значення
Максимум блоків на Artifact	16
Максимальний розмір A2H payload	64KB
Максимальний загальний розмір payload (з обгорткою)	200KB
Максимум оновлень за життєвий цикл Artifact	100
За замовчуванням можна пересилати	Ні

SDK обробляє

• Шифрування payload Artifacts перед надсиланням
• Побудову тексту попереднього перегляду для сповіщень
• Маршрутизацію через WebSocket або REST fallback
• Валідацію структури payload

Наступні кроки

• Надсилання повідомлень — Текстові та медіа-повідомлення
• Streaming — Потокові відповіді в реальному часі
• Data Grants — Запит доступу до даних користувача