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

Agentes de IA e dados médicos

Acesso controlado para agentes de IA a registos de pacientes: âmbitos OAuth, as ferramentas de que um agente necessita, auditoria e proveniência do que lê e escreve, e agentes orientados por eventos.

Um agente de IA é um programa no qual um modelo de linguagem decide, passo a passo, que ações tomar — que dados ler, que ferramenta chamar, o que escrever — para completar uma tarefa. Quando a tarefa envolve o registo médico de um paciente, o agente necessita de acesso controlado: deve aceder apenas aos registos que lhe são permitidos, apenas às partes de que necessita, deixar um rasto do que leu e marcar o que escreveu como gerado por IA. A Anpheros fornece esse acesso controlado através da sua API; o framework do agente e o modelo são seus.

A Anpheros não tem um runtime de agente integrado, um servidor Model Context Protocol (MCP) nem integração oficial com qualquer framework de agente ou fornecedor de modelos. Os agentes utilizam-na da mesma forma que qualquer aplicação: através da API REST e FHIR ou dos SDKs.

A arquitetura

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

O modelo propõe ações; o seu runtime executa-as com a credencial que detém. O modelo em si nunca detém uma chave ou token Anpheros.

Acesso Controlado

• Registos de quem. Com uma API key, o agente vê os pacientes que o seu projeto criou. Para atuar sobre um registo existente de alguém, necessita de uma autorização OAuth dessa pessoa — para um paciente, por 30 a 365 dias.
• Que dados. Os escopos limitam os tipos de recursos e ações, opcionalmente a uma categoria: patient/Observation.rs?category=laboratory permite que um agente leia e pesquise resultados de laboratório e mais nada. Para construir um contexto, a autorização deve permitir a leitura de observações, condições, medicamentos e alergias (por exemplo, patient/*.rs).
• Apenas leitura por defeito. Conceda escopos de escrita apenas quando o agente se destina a registar algo.
• Revogável. A pessoa pode revogar a autorização a qualquer momento; a próxima chamada do agente é recusada.

Ferramentas que um agente necessita tipicamente

A especificação OpenAPI (https://developers.anpheros.com/openapi.json) descreve todos os endpoints e pode ser transformada em definições de ferramentas; os SDKs TypeScript e Dart podem ser encapsulados diretamente como ferramentas.

Exemplo: um agente de preparação de consulta com o consentimento do paciente

Um paciente que já mantém um registo no Anpheros pede a um assistente de terceiros para preparar questões para uma consulta de cardiologia. O agente necessita de acesso de leitura ao registo por um tempo limitado — nada mais.

1. Consentimento (OAuth 2.1 + PKCE, âmbitos SMART v2). O assistente envia a pessoa para a página de consentimento com os âmbitos mais restritos que ainda permitem um contexto (observações, condições, medicamentos e alergias):

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. Ferramentas. O runtime do agente expõe algumas funções ao modelo; cada uma é uma chamada de API real feita com o token de acesso:

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

Descreva-as ao modelo no formato de chamada de ferramenta ou função que a API do seu modelo utiliza; o modelo propõe uma chamada, o seu runtime executa-a e devolve o JSON. O modelo nunca vê o token.

3. O que a plataforma impõe. O token alcança apenas o registo dessa pessoa e apenas os tipos com âmbito; qualquer outra coisa responde 403 (um tipo fora dos âmbitos) ou 404 (outro paciente). Cada chamada — incluindo cada pedido de contexto, com o seu manifest_id — aparece no registo de acesso da pessoa para esta aplicação. Se a pessoa revogar o acesso, a próxima chamada responde 401 e o agente deve parar; o token de atualização não pode trazê-lo de volta.

4. Saída. O agente devolve questões para o médico com as fontes que utilizou. Não escreve nada de volta, pois não lhe foi concedido um âmbito de escrita.

Auditoria e proveniência

• Cada chamada que o agente faz é um acesso ao registo e aparece no registo de acessos do paciente para a sua aplicação — incluindo cada pedido de contexto, que também armazena um manifesto das secções e fontes utilizadas.
• Tudo o que o agente escreve é registado como "escrito por IA" em Provenance. Quando um contexto é construído posteriormente, os valores escritos por IA são listados em ai_notes, para além dos factos clínicos, para que um agente não acabe por citar a sua própria saída anterior como prova.

Iniciar agentes a partir de eventos

Webhooks permitem que um agente seja executado quando algo muda — um novo resultado de laboratório (resource.created), um novo consentimento (consent.granted) — em vez de fazer polling. Os eventos transportam apenas IDs; o agente lê então o que os seus escopos permitem. Webhooks

Regras de design a manter

1. Conceda ao agente os âmbitos mais restritos que completem a tarefa.
2. Comece a partir de um contexto, não de leituras brutas em massa; respeite omitted e warnings.
3. Apresente as fontes de dados do paciente na resposta do agente.
4. Nunca permita que o agente apresente um diagnóstico ou altere um tratamento por si só; encaminhe tais resultados para um clínico.
5. Registe o manifest_id de cada contexto ao lado da resposta do agente, para que uma pessoa possa ver posteriormente em que se baseou a resposta.

Relacionado

• Como dar acesso de um agente de IA a registos médicos: tutorial passo a passo em Python
• Servidor FHIR MCP para agentes de IA
• Aplicações de IA na área da saúde
• Aplicações LLM e dados de saúde
• Como construir um chatbot médico com dados estruturados
• Modelo de consentimento e acesso
• Autenticação e OAuth
• Dados de medicação para aplicações de saúde e agentes de IA: a lista do paciente vs fontes de conhecimento de medicamentos

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