# ШІ-агенти та медичні дані

> Контрольований доступ для ШІ-агентів до записів пацієнтів: OAuth-області, інструменти, необхідні агенту, аудит та походження прочитаних і записаних даних, а також подійні агенти.

Source: https://developers.anpheros.com/uk/guides/ai-agents-medical-data

**ШІ-агент — це програма, в якій мовна модель крок за кроком вирішує, які дії вжити — які дані прочитати, який інструмент викликати, що записати — для виконання завдання.** Коли завдання стосується медичної картки пацієнта, агент потребує контрольованого доступу: він повинен отримувати доступ лише до тих записів, які йому дозволено, лише до тих їх частин, які йому потрібні, залишати слід того, що він прочитав, і позначати те, що він написав, як згенероване ШІ. Anpheros забезпечує такий контрольований доступ через свій API; фреймворк агента та модель належать вам.

Anpheros не має вбудованого середовища виконання агентів, сервера Model Context Protocol (MCP) та офіційної інтеграції з будь-яким фреймворком агентів чи постачальником моделей. Агенти використовують його так само, як будь-яка інша програма: через REST та FHIR API або SDK.

## Архітектура

```
Patient ── grants access (OAuth scopes, duration) ────────────────┐
                                                                  ▼
Agent runtime (your code, any framework) ── tools ──► Anpheros API ──► the patient's FHIR record
      │   ▲                                   │
      │   └── context, search results ◄───────┘      every call: scope checks + access log
      ▼
The model you choose (hosted or local) ── plans the next step
```

Модель пропонує дії; ваш runtime виконує їх з обліковими даними, які він має. Сама модель ніколи не зберігає ключ або токен Anpheros.

## Контрольований доступ

- **Чиї записи.** За допомогою API-ключа агент бачить пацієнтів, створених вашим проєктом. Щоб діяти щодо існуючого запису когось, йому потрібен OAuth-дозвіл від цієї особи — для одного пацієнта, на 30-365 днів.
- **Які дані.** Області дії (scopes) обмежують типи ресурсів та дії, опціонально за категорією: `patient/Observation.rs?category=laboratory` дозволяє агенту читати та шукати лабораторні результати і нічого більше. Щоб побудувати контекст, дозвіл повинен дозволяти читати спостереження (observations), стани (conditions), медикаменти (medications) та алергії (allergies) (наприклад, `patient/*.rs`).
- **Тільки для читання за замовчуванням.** Надавайте області дії для запису (write scopes) лише тоді, коли агент призначений для запису чогось.
- **Відкличний.** Особа може відкликати дозвіл у будь-який час; наступний виклик агента буде відхилено.

## Інструменти, які зазвичай потрібні агенту

| Інструмент | Виклик Anpheros | Примітки |
|---|---|---|
| Отримати контекст для завдання | `POST /v1/context` | перший виклик для більшості завдань; бюджетується та маркується за джерелом ([LLM applications and healthcare data](https://developers.anpheros.com/uk/guides/llm-healthcare-data)) |
| Переглянути останні результати | `GET /v1/patients/{id}/observations?category=laboratory&from=…` | фільтри: `category`, `code`, `from`, `to` |
| Активні медикаменти | `GET /v1/patients/{id}/medications?status=active` | |
| Що сталося | `GET /v1/patients/{id}/timeline?from=…` | один хронологічний список за типами |
| Повні деталі FHIR | `GET /fhir/R4/{type}?patient=…` | коли резюме недостатньо |
| Стандартне резюме | `GET /fhir/R4/Patient/{id}/$summary` | пакет International Patient Summary |
| Знайти код | `GET /v1/terminology/loinc?q=…` | пакетний піднабір LOINC; ліки через `GET /v1/search` |
| Записати примітку | `POST /v1/patients/{id}/observations` з `author_type: "ai"` | тільки з write scope |

Специфікація OpenAPI (`https://developers.anpheros.com/openapi.json`) описує кожен endpoint і може бути перетворена на визначення інструментів; TypeScript та Dart SDK можна обгорнути як інструменти безпосередньо.

## Приклад: агент для підготовки до візиту за згодою пацієнта

Пацієнт, який вже веде запис в Anpheros, просить стороннього помічника підготувати запитання для кардіологічного візиту. Агенту потрібен доступ на читання до запису на обмежений час — нічого більше.

**1. Згода (OAuth 2.1 + PKCE, SMART v2 scopes).** Помічник перенаправляє особу на сторінку згоди з найвужчими областями дії, які все ще дозволяють отримати контекст (спостереження, стани, ліки та алергії):

```ts
import { Anpheros, OAuthAuth, OAuthFlow, generatePkce } from '@anpheros/sdk';

const flow = new OAuthFlow({ baseUrl: 'https://platform.anpheros.com', clientId: CLIENT_ID, redirectUri: REDIRECT_URI });
const pkce = await generatePkce();
const url = flow.authorizeUrl({
  scopes: ['patient/Observation.rs', 'patient/Condition.rs', 'patient/MedicationStatement.rs',
           'patient/AllergyIntolerance.rs', 'offline_access'],
  state, pkce, purpose: 'treatment',
});
// … the person chooses the record and the duration (30–365 days) and allows; on the callback:
const tokens = await flow.exchange(code, pkce);
const anpheros = new Anpheros({ auth: new OAuthAuth({ tokens, onRefresh: flow.refresh }) });
const patient = tokens.patient!;   // this application's own (pairwise) id for the person
```

**2. Інструменти.** Середовище виконання агента надає моделі кілька функцій; кожна з них є реальною API-запиткою, виконаною з токеном доступу:

```ts
const tools = {
  // POST /v1/context — relevant sections, within a budget, labelled with author type and source
  get_context: (a: { question: string }) =>
    anpheros.context.build({ patient, task: 'prepare a cardiology visit', question: a.question, budget_tokens: 2000, format: 'text' }),
  // GET /v1/patients/{id}/observations?category=laboratory&code=…&from=…
  list_lab_results: (a: { code?: string; from?: string }) =>
    anpheros.observations.list(patient, { category: 'laboratory', code: a.code, from: a.from, limit: 20 }),
  // GET /v1/patients/{id}/timeline?from=…
  get_timeline: (a: { from: string }) => anpheros.timeline.list(patient, { from: a.from, limit: 50 }),
};
```

Опишіть їх моделі у будь-якому форматі інструментів або викликів функцій, який використовує ваш API моделі; модель пропонує виклик, ваше середовище виконання виконує його та повертає JSON. Модель ніколи не бачить токен.

**3. Що забезпечує платформа.** Токен досягає лише запису цієї особи та лише визначених областей дії; будь-що інше повертає `403` (тип поза областями дії) або `404` (інший пацієнт). Кожен виклик — включаючи кожен запит контексту з його `manifest_id` — з'являється в журналі доступу особи для цієї програми. Якщо особа відкликає доступ, наступний виклик повертає `401`, і агент повинен зупинитися; токен оновлення не може його відновити.

**4. Результат.** Агент повертає запитання для лікаря з використаними джерелами. Він нічого не записує назад, оскільки йому не було надано область дії для запису.

## Аудит та походження даних

- Кожен виклик, який робить агент, є доступом до запису і відображається в журналі доступу пацієнта для вашого застосунку — включно з кожним запитом контексту, який також зберігає маніфест використаних розділів та джерел.
- Усе, що записує агент, реєструється як створене ШІ в `Provenance`. Коли контекст будується пізніше, значення, написані ШІ, перелічуються під `ai_notes`, окремо від клінічних фактів, щоб агент не посилався на власний попередній вивід як на доказ.

## Запуск агентів за подіями

Вебхуки дозволяють агенту запускатися, коли щось змінюється — новий результат лабораторного дослідження (`resource.created`), нова згода (`consent.granted`) — замість опитування. Події несуть лише ідентифікатори; потім агент читає те, що дозволяють його області дії. [Вебхуки](https://developers.anpheros.com/uk/guides/webhooks)

## Правила проєктування, яких варто дотримуватися

1. Надавайте агенту найвужчі області (scopes), які необхідні для виконання завдання.
2. Починайте з контексту, а не з необроблених масових зчитувань; дотримуйтесь `omitted` та `warnings`.
3. Відображайте джерела даних пацієнта у відповіді агента.
4. Ніколи не дозволяйте агенту самостійно ставити діагноз або змінювати лікування; передавайте такі результати клініцисту.
5. Логуйте `manifest_id` кожного контексту поруч із відповіддю агента, щоб людина могла пізніше побачити, на чому ґрунтувалася відповідь.

## Пов'язані матеріали

- [Як надати ШІ-агенту доступ до медичних записів](https://developers.anpheros.com/uk/guides/ai-agent-access-medical-records): покроковий посібник на Python
- [Сервер FHIR MCP для ШІ-агентів](https://developers.anpheros.com/uk/guides/mcp)
- [Застосунки ШІ в охороні здоров'я](https://developers.anpheros.com/uk/guides/ai-healthcare)
- [Застосунки LLM та медичні дані](https://developers.anpheros.com/uk/guides/llm-healthcare-data)
- [Як створити медичний чат-бот зі структурованими даними](https://developers.anpheros.com/uk/guides/ai-medical-assistant)
- [Модель згоди та доступу](https://developers.anpheros.com/uk/guides/consent)
- [Автентифікація та OAuth](https://developers.anpheros.com/uk/guides/authentication)
- [Дані про ліки для медичних застосунків та ШІ-агентів](https://developers.anpheros.com/uk/guides/medication-data-ai-agents): список пацієнта проти джерел знань про ліки