# AI agenti a lekárske dáta

> Kontrolovaný prístup pre AI agentov k záznamom pacienta: OAuth scopes, nástroje, ktoré agent potrebuje, audit a pôvod toho, čo číta a zapisuje, a udalostne riadení agenti.

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

**AI agent je program, v ktorom jazykový model krok za krokom rozhoduje, aké akcie vykoná — aké dáta prečíta, aký nástroj zavolá, čo zapíše — na dokončenie úlohy.** Keď úloha zahŕňa lekársky záznam pacienta, agent potrebuje kontrolovaný prístup: mal by dosiahnuť iba tie záznamy, ku ktorým má povolený prístup, iba tie časti z nich, ktoré potrebuje, zanechať stopu toho, čo prečítal a označiť to, čo zapísal, ako vygenerované AI. Anpheros poskytuje tento kontrolovaný prístup prostredníctvom svojho API; framework agenta a model sú vaše.

Anpheros nemá žiadny vstavaný runtime agenta, žiadny server Model Context Protocol (MCP) a žiadnu oficiálnu integráciu s akýmkoľvek frameworkom agenta alebo poskytovateľom modelu. Agenti ho používajú tak, ako akákoľvek aplikácia: prostredníctvom REST a FHIR API alebo SDK.

## Architektúra

```
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 akcie; vaše runtime prostredie ich vykonáva s poverením, ktoré drží. Samotný model nikdy nedrží Anpheros kľúč ani token.

## Riadený prístup

- **Čie záznamy.** S API kľúčom agent vidí pacientov, ktorých váš projekt vytvoril. Aby mohol konať na existujúcom zázname niekoho, potrebuje OAuth súhlas od danej osoby – pre jedného pacienta, na 30 až 365 dní.
- **Aké údaje.** Scopes obmedzujú typy zdrojov a akcie, voliteľne na kategóriu: `patient/Observation.rs?category=laboratory` umožňuje agentovi čítať a vyhľadávať laboratórne výsledky a nič iné. Na vytvorenie kontextu musí súhlas umožňovať čítanie pozorovaní, stavov, liekov a alergií (napríklad `patient/*.rs`).
- **Predvolene iba na čítanie.** Povoľte write scopes iba vtedy, keď má agent zaznamenávať niečo.
- **Odvolateľné.** Osoba môže súhlas kedykoľvek odvolať; ďalší hovor agenta bude odmietnutý.

## Nástroje, ktoré agent typicky potrebuje

| Nástroj | Anpheros volanie | Poznámky |
|---|---|---|
| Získať kontext pre úlohu | `POST /v1/context` | prvé volanie pre väčšinu úloh; rozpočtované a označené zdrojom ([LLM applications and healthcare data](https://developers.anpheros.com/sk/guides/llm-healthcare-data)) |
| Vypísať posledné výsledky | `GET /v1/patients/{id}/observations?category=laboratory&from=…` | filtre: `category`, `code`, `from`, `to` |
| Aktuálne lieky | `GET /v1/patients/{id}/medications?status=active` | |
| Čo sa stalo kedy | `GET /v1/patients/{id}/timeline?from=…` | jeden chronologický zoznam naprieč typmi |
| Plné FHIR detaily | `GET /fhir/R4/{type}?patient=…` | keď súhrn nestačí |
| Štandardný súhrn | `GET /fhir/R4/Patient/{id}/$summary` | International Patient Summary bundle |
| Vyhľadať kód | `GET /v1/terminology/loinc?q=…` | pribalená podmnožina LOINC; lieky cez `GET /v1/search` |
| Zaznamenať poznámku | `POST /v1/patients/{id}/observations` s `author_type: "ai"` | iba s oprávnením na zápis |

OpenAPI špecifikácia (`https://developers.anpheros.com/openapi.json`) popisuje každý endpoint a môže byť premenená na definície nástrojov; TypeScript a Dart SDK môžu byť priamo zabalené ako nástroje.

## Príklad: agent na prípravu návštevy so súhlasom pacienta

Pacient, ktorý si už vedie záznam v Anpheros, požiada externého asistenta o prípravu otázok na kardiologickú návštevu. Agent potrebuje prístup na čítanie k záznamu na obmedzený čas – nič viac.

**1. Súhlas (OAuth 2.1 + PKCE, SMART v2 scopes).** Asistent presmeruje osobu na stránku súhlasu s najužšími scopes, ktoré stále umožňujú kontext (pozorovania, diagnózy, lieky 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 sprístupňuje modelu niekoľko funkcií; každá z nich je skutočným API volaním vykonaným s prístupovým tokenom:

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

Opíšte ich modelu v akomkoľvek formáte nástrojov alebo volaní funkcií, ktorý používa API vášho modelu; model navrhne volanie, váš runtime ho vykoná a vráti JSON. Model nikdy nevidí token.

**3. Čo platforma vynucuje.** Token sa dostane iba k záznamu danej osoby a iba k typom v rámci scopes; čokoľvek iné odpovie `403` (typ mimo scopes) alebo `404` (iný pacient). Každé volanie – vrátane každej žiadosti o kontext s jej `manifest_id` – sa objaví v prístupovom logu osoby pre túto aplikáciu. Ak osoba odvolá prístup, ďalšie volanie odpovie `401` a agent sa musí zastaviť; refresh token ho nemôže obnoviť.

**4. Výstup.** Agent vráti otázky pre lekára so zdrojmi, ktoré použil. Nič nezapisuje späť, pretože mu nebol udelený write scope.

## Audit a pôvod

- Každé volanie, ktoré agent vykoná, je prístupom k záznamu a objaví sa v denníku prístupov pacienta pre vašu aplikáciu – vrátane každej žiadosti o kontext, ktorá tiež ukladá manifest použitých sekcií a zdrojov.
- Všetko, čo agent zapíše, je zaznamenané ako vytvorené AI v `Provenance`. Keď sa neskôr zostaví kontext, hodnoty napísané AI sú uvedené pod `ai_notes`, oddelene od klinických faktov, takže agent nakoniec nebude citovať svoj vlastný predchádzajúci výstup ako dôkaz.

## Spustenie agentov na základe udalostí

Webhooks umožňujú agentovi spustiť sa pri zmene – nový výsledok laboratórneho vyšetrenia (`resource.created`), nový súhlas (`consent.granted`) – namiesto neustáleho dopytovania. Udalosti nesú iba ID; agent si potom prečíta to, čo mu jeho rozsahy (scopes) umožňujú. [Webhooks](https://developers.anpheros.com/sk/guides/webhooks)

## Pravidlá návrhu, ktoré sa oplatí dodržiavať

1. Priraďte agentovi čo najužšie rozsahy (scopes), ktoré dokončia úlohu.
2. Začnite s kontextom, nie s priamym čítaním veľkého objemu dát; rešpektujte `omitted` a `warnings`.
3. V odpovedi agenta zobrazte zdroje dát pacienta.
4. Nikdy nedovoľte agentovi samostatne prezentovať diagnózu alebo meniť liečbu; takéto výstupy smerujte na klinického lekára.
5. Zaznamenajte `manifest_id` každého kontextu vedľa odpovede agenta, aby si osoba mohla neskôr pozrieť, na základe čoho bola odpoveď vytvorená.

## Súvisiace

- [Ako udeliť prístup k lekárskym záznamom AI agentovi](https://developers.anpheros.com/sk/guides/ai-agent-access-medical-records): podrobný návod v Pythone
- [FHIR MCP server pre AI agentov](https://developers.anpheros.com/sk/guides/mcp)
- [AI zdravotnícke aplikácie](https://developers.anpheros.com/sk/guides/ai-healthcare)
- [LLM aplikácie a zdravotnícke dáta](https://developers.anpheros.com/sk/guides/llm-healthcare-data)
- [Ako vytvoriť zdravotnícky chatbot so štruktúrovanými údajmi](https://developers.anpheros.com/sk/guides/ai-medical-assistant)
- [Model súhlasu a prístupu](https://developers.anpheros.com/sk/guides/consent)
- [Autentifikácia a OAuth](https://developers.anpheros.com/sk/guides/authentication)
- [Dáta o liekoch pre zdravotnícke aplikácie a AI agentov](https://developers.anpheros.com/sk/guides/medication-data-ai-agents): zoznam pacienta vs. zdroje znalostí o liekoch