# Agenci AI i dane medyczne

> Kontrolowany dostęp dla agentów AI do dokumentacji pacjenta: zakresy OAuth, narzędzia potrzebne agentowi, audyt i pochodzenie tego, co odczytuje i zapisuje, oraz agenci sterowani zdarzeniami.

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

**Agent AI to program, w którym model językowy krok po kroku decyduje, jakie działania podjąć — jakie dane odczytać, jakie narzędzie wywołać, co zapisać — aby wykonać zadanie.** Gdy zadanie dotyczy dokumentacji medycznej pacjenta, agent potrzebuje kontrolowanego dostępu: powinien docierać tylko do tych rekordów, do których ma pozwolenie, tylko do tych ich części, których potrzebuje, pozostawiać ślad tego, co odczytał i oznaczać to, co zapisał, jako wygenerowane przez AI. Anpheros zapewnia taki kontrolowany dostęp za pośrednictwem swojego API; framework agenta i model są Twoje.

Anpheros nie posiada wbudowanego środowiska uruchomieniowego agentów, serwera Model Context Protocol (MCP) ani oficjalnej integracji z żadnym frameworkiem agentów ani dostawcą modeli. Agenci korzystają z niego w taki sam sposób, jak każda inna aplikacja: za pośrednictwem API REST i FHIR lub 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 proponuje akcje; środowisko uruchomieniowe wykonuje je z posiadanym poświadczeniem. Sam model nigdy nie przechowuje klucza ani tokenu Anpheros.

## Kontrolowany dostęp

- **Czyje rekordy.** Za pomocą klucza API agent widzi pacjentów utworzonych przez Twój projekt. Aby działać na istniejącym rekordzie kogoś, potrzebuje zgody OAuth od tej osoby — dla jednego pacjenta, na okres od 30 do 365 dni.
- **Jakie dane.** Zakresy (scopes) ograniczają typy zasobów i akcje, opcjonalnie do kategorii: `patient/Observation.rs?category=laboratory` pozwala agentowi na odczyt i wyszukiwanie wyników badań laboratoryjnych i niczego więcej. Aby zbudować kontekst, zgoda musi zezwalać na odczyt obserwacji, schorzeń, leków i alergii (na przykład `patient/*.rs`).
- **Domyślnie tylko do odczytu.** Nadawaj zakresy zapisu (write scopes) tylko wtedy, gdy agent ma coś zapisać.
- **Możliwość cofnięcia.** Osoba może cofnąć zgodę w dowolnym momencie; następne wywołanie agenta zostanie odrzucone.

## Narzędzia zazwyczaj potrzebne agentowi

| Narzędzie | Wywołanie Anpheros | Uwagi |
|---|---|---|
| Pobierz kontekst dla zadania | `POST /v1/context` | pierwsze wywołanie dla większości zadań; budżetowane i oznaczone źródłem ([Aplikacje LLM i dane medyczne](https://developers.anpheros.com/pl/guides/llm-healthcare-data)) |
| Wymień ostatnie wyniki | `GET /v1/patients/{id}/observations?category=laboratory&from=…` | filtry: `category`, `code`, `from`, `to` |
| Aktywne leki | `GET /v1/patients/{id}/medications?status=active` | |
| Co się wydarzyło | `GET /v1/patients/{id}/timeline?from=…` | jedna chronologiczna lista obejmująca różne typy |
| Pełne szczegóły FHIR | `GET /fhir/R4/{type}?patient=…` | gdy podsumowanie nie wystarcza |
| Standardowe podsumowanie | `GET /fhir/R4/Patient/{id}/$summary` | pakiet International Patient Summary |
| Wyszukaj kod | `GET /v1/terminology/loinc?q=…` | pakiet podzbioru LOINC; leki przez `GET /v1/search` |
| Zapisz notatkę | `POST /v1/patients/{id}/observations` z `author_type: "ai"` | tylko z zakresem zapisu |

Specyfikacja OpenAPI (`https://developers.anpheros.com/openapi.json`) opisuje każdy punkt końcowy i może zostać przekształcona w definicje narzędzi; pakiety SDK TypeScript i Dart mogą być bezpośrednio opakowane jako narzędzia.

## Przykład: agent przygotowujący wizytę za zgodą pacjenta

Pacjent, który już prowadzi dokumentację w Anpheros, prosi zewnętrznego asystenta o przygotowanie pytań na wizytę kardiologiczną. Agent potrzebuje dostępu do odczytu dokumentacji przez ograniczony czas — nic więcej.

**1. Zgoda (OAuth 2.1 + PKCE, zakresy SMART v2).** Asystent kieruje osobę na stronę zgody z najwęższymi zakresami, które nadal pozwalają na kontekst (obserwacje, schorzenia, leki i 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. Narzędzia.** Środowisko wykonawcze agenta udostępnia modelowi kilka funkcji; każda z nich to rzeczywiste wywołanie API wykonane z tokenem dostępu:

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

Opisz je modelowi w dowolnym formacie narzędzi lub wywołań funkcji, którego używa API Twojego modelu; model proponuje wywołanie, Twoje środowisko wykonawcze je uruchamia i zwraca JSON. Model nigdy nie widzi tokenu.

**3. Co egzekwuje platforma.** Token dociera tylko do dokumentacji tej osoby i tylko do typów objętych zakresem; wszystko inne zwraca `403` (typ spoza zakresów) lub `404` (inny pacjent). Każde wywołanie — w tym każde żądanie kontekstu, wraz z jego `manifest_id` — pojawia się w dzienniku dostępu osoby dla tej aplikacji. Jeśli osoba cofnie dostęp, następne wywołanie zwróci `401`, a agent musi się zatrzymać; token odświeżający nie może go przywrócić.

**4. Wynik.** Agent zwraca pytania dla lekarza wraz z używanymi źródłami. Nic nie zapisuje z powrotem, ponieważ nie otrzymał zakresu zapisu.

## Audyt i pochodzenie

- Każde wywołanie przez agenta jest dostępem do rekordu i pojawia się w dzienniku dostępu pacjenta dla Twojej aplikacji — w tym każde żądanie kontekstu, które również przechowuje manifest użytych sekcji i źródeł.
- Wszystko, co agent zapisuje, jest rejestrowane jako napisane przez AI w `Provenance`. Kiedy kontekst jest później budowany, wartości napisane przez AI są wymienione w `ai_notes`, oprócz faktów klinicznych, dzięki czemu agent nie cytuje własnych wcześniejszych wyników jako dowodu.

## Uruchamianie agentów na podstawie zdarzeń

Webhooki pozwalają agentowi na uruchomienie w momencie zmiany — nowego wyniku badania laboratoryjnego (`resource.created`), nowej zgody (`consent.granted`) — zamiast cyklicznego sprawdzania. Zdarzenia zawierają tylko identyfikatory; agent następnie odczytuje dane w zakresie swoich uprawnień. [Webhooks](https://developers.anpheros.com/pl/guides/webhooks)

## Zasady projektowania, których warto przestrzegać

1. Nadaj agentowi najwęższe zakresy uprawnień, które są niezbędne do wykonania zadania.
2. Rozpocznij od kontekstu, a nie od surowego odczytu dużych ilości danych; przestrzegaj zasad `omitted` i `warnings`.
3. W odpowiedzi agenta przedstaw źródła danych pacjenta.
4. Nigdy nie pozwól agentowi samodzielnie stawiać diagnozy ani zmieniać leczenia; przekieruj takie wyniki do lekarza.
5. Zapisz `manifest_id` każdego kontekstu obok odpowiedzi agenta, aby osoba mogła później zobaczyć, na czym opierała się odpowiedź.

## Powiązane

- [Jak nadać agentowi AI dostęp do dokumentacji medycznej](https://developers.anpheros.com/pl/guides/ai-agent-access-medical-records): samouczek krok po kroku w Pythonie
- [Serwer FHIR MCP dla agentów AI](https://developers.anpheros.com/pl/guides/mcp)
- [Aplikacje AI w opiece zdrowotnej](https://developers.anpheros.com/pl/guides/ai-healthcare)
- [Aplikacje LLM i dane dotyczące opieki zdrowotnej](https://developers.anpheros.com/pl/guides/llm-healthcare-data)
- [Jak zbudować medyczny chatbot z danymi strukturalnymi](https://developers.anpheros.com/pl/guides/ai-medical-assistant)
- [Model zgody i dostępu](https://developers.anpheros.com/pl/guides/consent)
- [Uwierzytelnianie i OAuth](https://developers.anpheros.com/pl/guides/authentication)
- [Dane dotyczące leków dla aplikacji opieki zdrowotnej i agentów AI](https://developers.anpheros.com/pl/guides/medication-data-ai-agents): lista pacjenta a źródła wiedzy o lekach