# AI agenti a lékařská data

> Řízený přístup pro AI agenty k záznamům pacientů: OAuth rozsahy, nástroje, které agent potřebuje, audit a původ toho, co čte a zapisuje, a událostmi řízení agenti.

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

**AI agent je program, ve kterém jazykový model krok za krokem rozhoduje, jaké akce provede — jaká data přečte, jaký nástroj zavolá, co zapíše — k dokončení úkolu.** Pokud úkol zahrnuje lékařský záznam pacienta, agent potřebuje řízený přístup: měl by dosáhnout pouze na záznamy, ke kterým má povolení, pouze na jejich části, které potřebuje, zanechat stopu toho, co přečetl a označit to, co zapsal, jako vygenerované AI. Anpheros poskytuje tento řízený přístup prostřednictvím svého API; framework agenta a model jsou vaše.

Anpheros nemá žádný vestavěný runtime agenta, žádný server Model Context Protocol (MCP) a žádnou oficiální integraci s žádným frameworkem agenta nebo poskytovatelem modelu. Agenti jej používají stejně jako jakákoli aplikace: prostřednictvím REST a FHIR API nebo SDK.

## Architektura

```
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
```

Model navrhuje akce; vaše runtime je provádí s přihlašovacími údaji, které drží. Samotný model nikdy nedrží klíč nebo token Anpheros.

## Řízený přístup

- **Čí záznamy.** S API klíčem agent vidí pacienty, které váš projekt vytvořil. Aby mohl jednat s existujícím záznamem někoho jiného, potřebuje OAuth grant od této osoby — pro jednoho pacienta, na 30 až 365 dní.
- **Která data.** Scopes omezují typy zdrojů a akce, volitelně na kategorii: `patient/Observation.rs?category=laboratory` umožňuje agentovi číst a vyhledávat laboratorní výsledky a nic jiného. Pro vytvoření kontextu musí grant umožňovat čtení pozorování, stavů, léků a alergií (například `patient/*.rs`).
- **Ve výchozím nastavení pouze pro čtení.** Udělujte scopes pro zápis pouze tehdy, když má agent zaznamenávat něco.
- **Odvolatelné.** Osoba může grant kdykoli odvolat; další volání agenta bude odmítnuto.

## Nástroje, které agent typicky potřebuje

| Nástroj | Volání Anpheros | Poznámky |
|---|---|---|
| Získat kontext pro úkol | `POST /v1/context` | první volání pro většinu úkolů; rozpočtované a označené zdrojem ([LLM applications and healthcare data](https://developers.anpheros.com/cs/guides/llm-healthcare-data)) |
| Seznam posledních výsledků | `GET /v1/patients/{id}/observations?category=laboratory&from=…` | filtry: `category`, `code`, `from`, `to` |
| Aktivní léky | `GET /v1/patients/{id}/medications?status=active` | |
| Co se stalo kdy | `GET /v1/patients/{id}/timeline?from=…` | jeden chronologický seznam napříč typy |
| Plné FHIR detaily | `GET /fhir/R4/{type}?patient=…` | když souhrn nestačí |
| Standardní souhrn | `GET /fhir/R4/Patient/{id}/$summary` | balíček International Patient Summary |
| Vyhledat kód | `GET /v1/terminology/loinc?q=…` | přiložená podmnožina LOINC; léky přes `GET /v1/search` |
| Zaznamenat poznámku | `POST /v1/patients/{id}/observations` s `author_type: "ai"` | pouze s rozsahem zápisu |

Specifikace OpenAPI (`https://developers.anpheros.com/openapi.json`) popisuje každý koncový bod a lze ji převést na definice nástrojů; TypeScript a Dart SDK lze zabalit přímo jako nástroje.

## Příklad: Agent pro přípravu návštěvy se souhlasem pacienta

Pacient, který již vede záznam v Anpheros, požádá externího asistenta o přípravu otázek pro kardiologickou návštěvu. Agent potřebuje přístup ke čtení záznamu po omezenou dobu – nic víc.

**1. Souhlas (OAuth 2.1 + PKCE, rozsahy SMART v2).** Asistent přesměruje osobu na stránku souhlasu s nejužšími rozsahy, které stále umožňují kontext (pozorování, stavy, léky a alergie):

```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. Nástroje.** Runtime agenta zpřístupňuje modelu několik funkcí; každá z nich je skutečným voláním API provedeným s přístupovým tokenem:

```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 }),
};
```

Popište je modelu v jakémkoli formátu nástrojů nebo volání funkcí, který vaše API modelu používá; model navrhne volání, váš runtime jej spustí a vrátí JSON. Model nikdy nevidí token.

**3. Co platforma vynucuje.** Token se dostane pouze k záznamu dané osoby a pouze k typům v rozsahu; cokoli jiného odpoví `403` (typ mimo rozsahy) nebo `404` (jiný pacient). Každé volání – včetně každého požadavku na kontext s jeho `manifest_id` – se objeví v přístupovém logu dané osoby pro tuto aplikaci. Pokud osoba odvolá přístup, další volání odpoví `401` a agent musí přestat; obnovovací token jej nemůže vrátit zpět.

**4. Výstup.** Agent vrátí otázky pro lékaře se zdroji, které použil. Nic nezapisuje zpět, protože mu nebyl udělen rozsah zápisu.

## Audit a původ

- Každý požadavek, který agent provede, je přístupem k záznamu a objeví se v logu přístupů pacienta pro vaši aplikaci – včetně každého požadavku na kontext, který také ukládá manifest použitých sekcí a zdrojů.
- Vše, co agent zapíše, je zaznamenáno jako vytvořené AI v `Provenance`. Když je kontext sestaven později, hodnoty napsané AI jsou uvedeny pod `ai_notes`, odděleně od klinických faktů, takže agent nakonec necituje svůj vlastní dřívější výstup jako důkaz.

## Spouštění agentů na základě událostí

Webhooks umožňují agentovi spustit se, když dojde ke změně — nový laboratorní výsledek (`resource.created`), nový souhlas (`consent.granted`) — místo pravidelného dotazování. Události nesou pouze ID; agent si pak přečte, co mu jeho rozsahy dovolují. [Webhooks](https://developers.anpheros.com/cs/guides/webhooks)

## Pravidla návrhu, která stojí za to dodržovat

1. Udělte agentovi nejužší možné rozsahy oprávnění, které splňují požadavky úkolu.
2. Začínejte s kontextem, nikoli s nefiltrovanými hromadnými čteními; respektujte `omitted` a `warnings`.
3. V odpovědi agenta uveďte zdroje dat pacienta.
4. Nikdy nenechte agenta samostatně prezentovat diagnózu nebo měnit léčbu; takové výstupy směřujte na klinického lékaře.
5. Zaznamenejte `manifest_id` každého kontextu vedle odpovědi agenta, aby osoba mohla později vidět, na čem byla odpověď založena.

## Související

- [Jak povolit přístup AI agenta k lékařským záznamům](https://developers.anpheros.com/cs/guides/ai-agent-access-medical-records): podrobný návod v Pythonu
- [FHIR MCP server pro AI agenty](https://developers.anpheros.com/cs/guides/mcp)
- [Aplikace AI ve zdravotnictví](https://developers.anpheros.com/cs/guides/ai-healthcare)
- [Aplikace LLM a zdravotnická data](https://developers.anpheros.com/cs/guides/llm-healthcare-data)
- [Jak vytvořit lékařského chatbota se strukturovanými daty](https://developers.anpheros.com/cs/guides/ai-medical-assistant)
- [Model souhlasu a přístupu](https://developers.anpheros.com/cs/guides/consent)
- [Autentizace a OAuth](https://developers.anpheros.com/cs/guides/authentication)
- [Data o lécích pro zdravotnické aplikace a AI agenty](https://developers.anpheros.com/cs/guides/medication-data-ai-agents): seznam pacienta vs. zdroje znalostí o lécích