# 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.

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

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

| Ferramenta | Chamada Anpheros | Notas |
|---|---|---|
| Obter contexto para uma tarefa | `POST /v1/context` | a primeira chamada para a maioria das tarefas; orçamentada e com etiqueta de origem ([LLM applications and healthcare data](https://developers.anpheros.com/pt/guides/llm-healthcare-data)) |
| Listar resultados recentes | `GET /v1/patients/{id}/observations?category=laboratory&from=…` | filtros: `category`, `code`, `from`, `to` |
| Medicamentos ativos | `GET /v1/patients/{id}/medications?status=active` | |
| O que aconteceu quando | `GET /v1/patients/{id}/timeline?from=…` | uma lista cronológica entre tipos |
| Detalhe FHIR completo | `GET /fhir/R4/{type}?patient=…` | quando um resumo não é suficiente |
| Um resumo padrão | `GET /fhir/R4/Patient/{id}/$summary` | pacote International Patient Summary |
| Procurar um código | `GET /v1/terminology/loinc?q=…` | subconjunto LOINC agrupado; medicamentos através de `GET /v1/search` |
| Gravar uma nota | `POST /v1/patients/{id}/observations` com `author_type: "ai"` | apenas com um âmbito de escrita |

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

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

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

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](https://developers.anpheros.com/pt/guides/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](https://developers.anpheros.com/pt/guides/ai-agent-access-medical-records): tutorial passo a passo em Python
- [Servidor FHIR MCP para agentes de IA](https://developers.anpheros.com/pt/guides/mcp)
- [Aplicações de IA na área da saúde](https://developers.anpheros.com/pt/guides/ai-healthcare)
- [Aplicações LLM e dados de saúde](https://developers.anpheros.com/pt/guides/llm-healthcare-data)
- [Como construir um chatbot médico com dados estruturados](https://developers.anpheros.com/pt/guides/ai-medical-assistant)
- [Modelo de consentimento e acesso](https://developers.anpheros.com/pt/guides/consent)
- [Autenticação e OAuth](https://developers.anpheros.com/pt/guides/authentication)
- [Dados de medicação para aplicações de saúde e agentes de IA](https://developers.anpheros.com/pt/guides/medication-data-ai-agents): a lista do paciente vs fontes de conhecimento de medicamentos