# AIエージェントと医療データ

> 患者記録へのAIエージェントによる制御されたアクセス：OAuthスコープ、エージェントが必要とするツール、読み書きの監査と来歴、イベント駆動型エージェント。

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

**AIエージェントとは、言語モデルがタスクを完了するために、どのデータにアクセスし、どのツールを呼び出し、何を書くかといったアクションを段階的に決定するプログラムです。** タスクが患者の医療記録に関わる場合、エージェントは制御されたアクセスを必要とします。つまり、許可された記録にのみアクセスし、必要な部分のみにアクセスし、読み取った内容の痕跡を残し、書き込んだ内容はAI生成としてマークする必要があります。Anpherosは、そのAPIを通じてそのような制御されたアクセスを提供します。エージェントフレームワークとモデルは、お客様のものです。

Anpherosには、組み込みのエージェントランタイム、Model Context Protocol (MCP) サーバー、および任意の agent framework または model provider との公式な統合はありません。エージェントは、RESTおよびFHIR APIまたはSDKを通じて、他のアプリケーションと同様にAnpherosを使用します。

## アーキテクチャ

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

このモデルはアクションを提案し、実行環境は保持している認証情報を使用してそれらを実行します。モデル自体は Anpheros キーやトークンを保持することはありません。

## アクセス制御

- **どの患者の記録か。** APIキーを使用すると、エージェントはプロジェクトが作成した患者を表示できます。既存の誰かの記録に対して操作を行うには、その人物からのOAuthグラントが必要です。これは、1人の患者に対して、30日から365日間有効です。
- **どのデータか。** スコープは、リソースタイプとアクションを制限し、オプションでカテゴリを指定できます。`patient/Observation.rs?category=laboratory` は、エージェントが検査結果の読み取りと検索のみを許可し、それ以外の操作は許可しません。コンテキストを構築するには、グラントで観察結果、病状、薬剤、アレルギーの読み取りを許可する必要があります（例：`patient/*.rs`）。
- **デフォルトは読み取り専用。** 書き込みスコープは、エージェントが何かを記録する場合にのみ付与してください。
- **取り消し可能。** 患者はいつでもグラントを取り消すことができます。その場合、エージェントの次の呼び出しは拒否されます。

## エージェントが通常必要とするツール

| ツール | Anpheros コール | 備考 |
|---|---|---|
| タスクのコンテキストを取得する | `POST /v1/context` | ほとんどのタスクで最初のコール。予算とソースがラベル付けされています ([LLM applications and healthcare data](https://developers.anpheros.com/ja/guides/llm-healthcare-data)) |
| 最近の結果を一覧表示する | `GET /v1/patients/{id}/observations?category=laboratory&from=…` | フィルター: `category`, `code`, `from`, `to` |
| 現在の処方薬 | `GET /v1/patients/{id}/medications?status=active` | |
| 何がいつ起こったか | `GET /v1/patients/{id}/timeline?from=…` | タイプを横断する 1 つの時系列リスト |
| 完全な FHIR 詳細 | `GET /fhir/R4/{type}?patient=…` | 要約では不十分な場合 |
| 標準的な要約 | `GET /fhir/R4/Patient/{id}/$summary` | International Patient Summary バンドル |
| コードを検索する | `GET /v1/terminology/loinc?q=…` | バンドルされた LOINC サブセット。医薬品は `GET /v1/search` 経由 |
| メモを記録する | `POST /v1/patients/{id}/observations` with `author_type: "ai"` | 書き込みスコープがある場合のみ |

OpenAPI 仕様 (`https://developers.anpheros.com/openapi.json`) はすべてのエンドポイントを記述しており、ツール定義に変換できます。TypeScript および Dart SDK はツールとして直接ラップできます。

## 例：患者の同意を得た来院準備エージェント

Anpheros に既に記録を保持している患者が、循環器科の受診に向けた質問準備をサードパーティのアシスタントに依頼します。エージェントは、限定された期間、その記録への読み取りアクセス権を必要とします。それ以上の権限は不要です。

**1. 同意 (OAuth 2.1 + PKCE, SMART v2 スコープ)。** アシスタントは、コンテキスト（観察、状態、投薬、アレルギー）を許可する最も狭いスコープで、ユーザーを同意ページに誘導します。

```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. ツール。** エージェントランタイムは、モデルにいくつかの関数を公開します。各関数は、アクセストークンを使用して行われる実際の API 呼び出しです。

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

モデル API が使用する任意のツールまたは関数呼び出し形式で、それらをモデルに説明します。モデルが呼び出しを提案し、ランタイムがそれを実行して JSON を返します。モデルはトークンを見ることはありません。

**3. プラットフォームが強制すること。** トークンは、そのユーザーの記録にのみ到達し、スコープされたタイプにのみアクセスできます。それ以外のものは、`403`（スコープ外のタイプ）または `404`（別のユーザー）という応答になります。コンテキストリクエスト（`manifest_id` を含む）を含むすべての呼び出しは、このアプリケーションのユーザーのアクセスログに記録されます。ユーザーがアクセスを revocation すると、次の呼び出しは `401` という応答になり、エージェントは停止する必要があります。リフレッシュトークンでは復旧できません。

**4. 出力。** エージェントは、使用したソースとともに、医師への質問を返します。書き込みスコープが与えられていないため、何も書き戻しません。

## 監査と来歴

- エージェントが行うすべての呼び出しはレコードへのアクセスとみなされ、アプリケーションの患者アクセスログに記録されます。これには、各コンテキストリクエストも含まれ、使用されたセクションとソースのマニフェストも保存されます。
- エージェントが書き込むすべての内容は、`Provenance` に AI 作成として記録されます。後でコンテキストが構築される際、AI 作成値は臨床的事実とは別に `ai_notes` の下にリストされ、エージェントが自身の以前の出力を証拠として引用することを防ぎます。

## イベントからのエージェントの開始

Webhook を使用すると、ポーリングではなく、何かが変更されたとき（新しい検査結果 `resource.created`、新しい同意 `consent.granted` など）にエージェントを実行できます。イベントは ID のみを含み、エージェントはその後、スコープで許可されているものを読み取ります。[Webhook](https://developers.anpheros.com/ja/guides/webhooks)

## 考慮すべき設計ルール

1. タスクを完了するために必要な、最も狭いスコープをエージェントに与えます。
2. 生のバルクリードからではなく、コンテキストから開始します。`omitted` および `warnings` を尊重してください。
3. エージェントの回答に患者のデータソースを表示します。
4. エージェントが単独で診断を下したり、治療を変更したりすることを決して許可しないでください。そのような出力は臨床医にルーティングしてください。
5. 回答の根拠となったコンテキストを特定できるように、各コンテキストの`manifest_id` をエージェントの回答の横に記録します。

## 関連情報

- [AIエージェントに医療記録へのアクセス権を付与する方法](https://developers.anpheros.com/ja/guides/ai-agent-access-medical-records): Pythonによるステップバイステップチュートリアル
- [AIエージェント向けFHIR MCPサーバー](https://developers.anpheros.com/ja/guides/mcp)
- [AIヘルスケアアプリケーション](https://developers.anpheros.com/ja/guides/ai-healthcare)
- [LLMアプリケーションとヘルスケアデータ](https://developers.anpheros.com/ja/guides/llm-healthcare-data)
- [構造化データを用いた医療チャットボットの構築方法](https://developers.anpheros.com/ja/guides/ai-medical-assistant)
- [同意とアクセスモデル](https://developers.anpheros.com/ja/guides/consent)
- [認証とOAuth](https://developers.anpheros.com/ja/guides/authentication)
- [ヘルスケアアプリおよびAIエージェント向けの医薬品データ](https://developers.anpheros.com/ja/guides/medication-data-ai-agents): 患者リストと医薬品知識ソース