# Agenti AI e dati medici

> Accesso controllato per agenti AI ai record dei pazienti: ambiti OAuth, gli strumenti di cui un agente ha bisogno, audit e provenienza di ciò che legge e scrive, e agenti basati su eventi.

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

**Un agente AI è un programma in cui un modello linguistico decide, passo dopo passo, quali azioni intraprendere — quali dati leggere, quale strumento chiamare, cosa scrivere — per completare un'attività.** Quando l'attività coinvolge la cartella clinica di un paziente, l'agente necessita di un accesso controllato: dovrebbe raggiungere solo i record a cui è autorizzato ad accedere, solo le parti di essi di cui ha bisogno, lasciare una traccia di ciò che ha letto e contrassegnare ciò che ha scritto come generato dall'AI. Anpheros fornisce tale accesso controllato tramite la sua API; il framework dell'agente e il modello sono tuoi.

Anpheros non dispone di un runtime di agenti integrato, di un server Model Context Protocol (MCP) né di un'integrazione ufficiale con alcun framework di agenti o provider di modelli. Gli agenti lo utilizzano come qualsiasi altra applicazione: tramite l'API REST e FHIR o gli SDK.

## L'architettura

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

Il modello propone azioni; il tuo runtime le esegue con le credenziali che possiede. Il modello stesso non detiene mai una chiave o un token Anpheros.

## Accesso controllato

- **Di chi sono i record.** Con una chiave API l'agente vede i pazienti creati dal tuo progetto. Per agire sul record esistente di qualcuno, necessita di una concessione OAuth da parte di quella persona — per un paziente, per 30-365 giorni.
- **Quali dati.** Gli scope limitano i tipi di risorse e le azioni, opzionalmente a una categoria: `patient/Observation.rs?category=laboratory` consente a un agente di leggere e cercare risultati di laboratorio e nient'altro. Per costruire un contesto, la concessione deve consentire la lettura di osservazioni, condizioni, farmaci e allergie (ad esempio `patient/*.rs`).
- **Sola lettura per impostazione predefinita.** Concedi scope di scrittura solo quando l'agente è destinato a registrare qualcosa.
- **Revocabile.** La persona può revocare la concessione in qualsiasi momento; la chiamata successiva dell'agente viene rifiutata.

## Strumenti di cui un agente ha tipicamente bisogno

| Strumento | Chiamata Anpheros | Note |
|---|---|---|
| Ottieni contesto per un'attività | `POST /v1/context` | la prima chiamata per la maggior parte delle attività; con budget e etichettato per origine ([LLM applications and healthcare data](https://developers.anpheros.com/it/guides/llm-healthcare-data)) |
| Elenca risultati recenti | `GET /v1/patients/{id}/observations?category=laboratory&from=…` | filtri: `category`, `code`, `from`, `to` |
| Farmaci attivi | `GET /v1/patients/{id}/medications?status=active` | |
| Cosa è successo | `GET /v1/patients/{id}/timeline?from=…` | un elenco cronologico tra i tipi |
| Dettaglio FHIR completo | `GET /fhir/R4/{type}?patient=…` | quando un riepilogo non è sufficiente |
| Un riepilogo standard | `GET /fhir/R4/Patient/{id}/$summary` | bundle International Patient Summary |
| Cerca un codice | `GET /v1/terminology/loinc?q=…` | sottoinsieme LOINC in bundle; farmaci tramite `GET /v1/search` |
| Registra una nota | `POST /v1/patients/{id}/observations` con `author_type: "ai"` | solo con uno scope di scrittura |

La specifica OpenAPI (`https://developers.anpheros.com/openapi.json`) descrive ogni endpoint e può essere trasformata in definizioni di strumenti; gli SDK TypeScript e Dart possono essere incapsulati direttamente come strumenti.

## Esempio: un agente di preparazione visita con il consenso del paziente

Un paziente che ha già una cartella in Anpheros chiede a un assistente di terze parti di preparare domande per una visita cardiologica. L'agente necessita di accesso in lettura alla cartella per un tempo limitato, niente di più.

**1. Consenso (OAuth 2.1 + PKCE, ambiti SMART v2).** L'assistente invia la persona alla pagina di consenso con gli ambiti più ristretti che consentono comunque un contesto (osservazioni, condizioni, farmaci e allergie):

```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. Strumenti.** Il runtime dell'agente espone alcune funzioni al modello; ognuna è una vera chiamata API effettuata con il token di accesso:

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

Descrivili al modello nel formato di strumento o chiamata di funzione che la tua API del modello utilizza; il modello propone una chiamata, il tuo runtime la esegue e restituisce il JSON. Il modello non vede mai il token.

**3. Cosa applica la piattaforma.** Il token raggiunge solo la cartella di quella persona e solo i tipi specificati negli ambiti; qualsiasi altra cosa risponde `403` (un tipo al di fuori degli ambiti) o `404` (un altro paziente). Ogni chiamata, inclusa ogni richiesta di contesto con il suo `manifest_id`, appare nel log di accesso della persona per questa applicazione. Se la persona revoca l'accesso, la chiamata successiva risponde `401` e l'agente deve interrompersi; il token di aggiornamento non può ripristinarlo.

**4. Output.** L'agente restituisce domande per il medico con le fonti utilizzate. Non scrive nulla indietro, perché non gli è stato concesso un ambito di scrittura.

## Audit e provenienza

- Ogni chiamata effettuata dall'agente costituisce un accesso al record e compare nel log di accesso del paziente per la tua applicazione, inclusa ogni richiesta di contesto, che memorizza anche un manifest delle sezioni e delle sorgenti utilizzate.
- Tutto ciò che l'agente scrive viene registrato come generato dall'IA in `Provenance`. Quando un contesto viene costruito successivamente, i valori scritti dall'IA sono elencati sotto `ai_notes`, separati dai fatti clinici, in modo che un agente non finisca per citare il proprio output precedente come prova.

## Avvio di agenti da eventi

I webhook consentono a un agente di essere eseguito quando qualcosa cambia — un nuovo risultato di laboratorio (`resource.created`), un nuovo consenso (`consent.granted`) — invece di effettuare il polling. Gli eventi trasportano solo ID; l'agente legge quindi ciò che i suoi scope consentono. [Webhook](https://developers.anpheros.com/it/guides/webhooks)

## Regole di progettazione da rispettare

1. Concedere all'agente gli ambiti più ristretti che completano l'attività.
2. Partire da un contesto, non da letture grezze di massa; rispettare `omitted` e `warnings`.
3. Mostrare le origini dei dati del paziente nella risposta dell'agente.
4. Non consentire mai all'agente di presentare una diagnosi o di modificare un trattamento autonomamente; instradare tali output a un clinico.
5. Registrare il `manifest_id` di ciascun contesto accanto alla risposta dell'agente, in modo che una persona possa in seguito vedere su cosa si basava la risposta.

## Correlati

- [Come concedere a un agente AI l'accesso alle cartelle cliniche](https://developers.anpheros.com/it/guides/ai-agent-access-medical-records): tutorial passo-passo in Python
- [Server FHIR MCP per agenti AI](https://developers.anpheros.com/it/guides/mcp)
- [Applicazioni AI nel settore sanitario](https://developers.anpheros.com/it/guides/ai-healthcare)
- [Applicazioni LLM e dati sanitari](https://developers.anpheros.com/it/guides/llm-healthcare-data)
- [Come creare un chatbot medico con dati strutturati](https://developers.anpheros.com/it/guides/ai-medical-assistant)
- [Modello di consenso e accesso](https://developers.anpheros.com/it/guides/consent)
- [Autenticazione e OAuth](https://developers.anpheros.com/it/guides/authentication)
- [Dati sui farmaci per app sanitarie e agenti AI](https://developers.anpheros.com/it/guides/medication-data-ai-agents): l'elenco del paziente rispetto alle fonti di conoscenza sui farmaci