Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card

Agenti AI e dati medici

Accesso controllato per agenti AI ai record paziente: scope OAuth, gli strumenti necessari a un agente, audit e provenienza di ciò che legge e scrive, e agenti basati su eventi.

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

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):

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:

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

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: tutorial passo-passo in Python
• Server FHIR MCP per agenti AI
• Applicazioni AI nel settore sanitario
• Applicazioni LLM e dati sanitari
• Come creare un chatbot medico con dati strutturati
• Modello di consenso e accesso
• Autenticazione e OAuth
• Dati sui farmaci per app sanitarie e agenti AI: l'elenco del paziente rispetto alle fonti di conoscenza sui farmaci

Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card