# AI-агенты и медицинские данные

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

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

**AI-агент — это программа, в которой языковая модель пошагово решает, какие действия предпринять — какие данные прочитать, какой инструмент вызвать, что записать — для выполнения задачи.** Когда задача включает медицинскую запись пациента, агенту требуется контролируемый доступ: он должен получать доступ только к тем записям, к которым ему разрешено, только к тем их частям, которые ему нужны, оставлять след того, что он прочитал, и помечать то, что он записал, как сгенерированное AI. 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
```

Модель предлагает действия; ваша среда выполнения выполняет их с учетными данными, которыми она обладает. Сама модель никогда не хранит ключ или токен 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/ru/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`) описывает каждый конечный пункт и может быть преобразована в определения инструментов; SDK для TypeScript и Dart могут быть обернуты непосредственно как инструменты.

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

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

**1. Согласие (OAuth 2.1 + PKCE, области SMART v2).** Ассистент направляет человека на страницу согласия с максимально узкими областями, которые все же позволяют получить контекст (наблюдения, состояния, лекарства и аллергии):

```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/ru/guides/webhooks)

## Рекомендации по проектированию, которых стоит придерживаться

1. Предоставляйте агенту максимально узкие области доступа (scopes), необходимые для выполнения задачи.
2. Начинайте с контекста, а не с необработанных массовых чтений; учитывайте `omitted` и `warnings`.
3. Отображайте источники данных пациента в ответе агента.
4. Никогда не позволяйте агенту самостоятельно ставить диагноз или менять лечение; передавайте такие результаты клиницисту.
5. Регистрируйте `manifest_id` каждого контекста рядом с ответом агента, чтобы человек мог впоследствии увидеть, на чем основывался ответ.

## Связанные материалы

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