Data Grants

Data Grants — це система дозволів Hashee для доступу агентів до даних користувачів. Вони забезпечують контроль користувачів над тим, до якої інформації агенти можуть мати доступ.

Як це працює

Агент запитує доступ — Ваш агент надсилає запит data grant, вказуючи, які дані йому потрібні та чому.
Користувач переглядає — Додаток Hashee представляє запит користувачу з чітким описом обсягу.
Користувач вирішує — Користувач явно схвалює або відхиляє запит.
Доступ надано — Якщо схвалено, агент може отримати доступ до вказаних даних у межах наданого обсягу.

Принципи проєктування

Data Grants відповідають моделі суверенітету даних Hashee:

Ініційовані користувачем — Користувач повинен явно схвалити кожен грант. Без прихованого збору даних.
Обмежені за обсягом — Кожен грант точно вказує, до яких даних надається доступ. Без загальних дозволів.
Відкличні — Користувачі можуть відкликати будь-який грант у будь-який час з налаштувань.
Прозорі — Користувачі можуть бачити всі активні гранти та до яких даних має доступ кожен агент.
Аудитовані — Усі запити грантів та рішення логуються.

Запит гранта

Запити data grant доставляються як Artifact взаємодії. Ваш агент надсилає Artifact з деталями запиту, і користувач відповідає через A2H Protocol:

await agent.sendArtifact(conversationId, {
  artifact: {
    a2h: "0.3",
    subtype: "form",
    blocks: [
      {
        tag: "text",
        key: "explanation",
        content: "I need access to your knowledge base to provide personalized recommendations.",
      },
      {
        tag: "action",
        key: "approve",
        label: "Grant Access",
        variant: "primary",
      },
      {
        tag: "action",
        key: "deny",
        label: "Deny",
        variant: "secondary",
      },
    ],
  },
  title: "Data Access Request",
  summary: "Requesting access to your knowledge base",
  forwardable: false,
});

Обсяги

Обсяг	Опис
`knowledge:read`	Читання елементів з бази знань користувача
`profile:read`	Читання інформації профілю користувача
`conversations:read`	Читання історії розмов (в межах H2A відносин)

Найкращі практики

Запитуйте мінімальні обсяги — Просіть лише ті дані, які вам дійсно потрібні.
Поясніть чому — Додайте чітке пояснення, як будуть використовуватися дані.
Обробляйте відмови коректно — Агент повинен працювати зі зниженою функціональністю, якщо грант відхилено.
Поважайте відкликання — Якщо користувач відкликає грант, негайно припиніть використання цих даних.

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

Artifacts — A2H Protocol для інтерактивних запитів
Webhooks — Отримання сповіщень про зміни грантів
Автентифікація — Довідник потоку автентифікації