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

AI 에이전트 및 의료 데이터

AI 에이전트의 환자 기록에 대한 제어된 액세스: OAuth 범위, 에이전트가 필요한 도구, 감사 및 읽고 쓰는 내용의 출처, 이벤트 기반 에이전트.

AI 에이전트는 언어 모델이 작업을 완료하기 위해 어떤 작업을 수행할지 — 어떤 데이터를 읽을지, 어떤 도구를 호출할지, 무엇을 쓸지 — 단계별로 결정하는 프로그램입니다. 작업에 환자의 의료 기록이 포함되는 경우, 에이전트는 제어된 액세스가 필요합니다. 즉, 허용된 기록에만 접근해야 하며, 필요한 부분만 접근해야 하고, 읽은 내용의 흔적을 남기고, AI 생성으로 표시된 내용을 작성해야 합니다. Anpheros는 API를 통해 이러한 제어된 액세스를 제공합니다. 에이전트 프레임워크와 모델은 귀하의 것입니다.

Anpheros에는 내장된 에이전트 런타임, Model Context Protocol(MCP) 서버, 또는 어떤 에이전트 프레임워크나 모델 제공업체와의 공식 통합도 없습니다. 에이전트는 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 승인을 받아야 합니다. 이는 한 명의 환자에 대해 30일에서 365일 동안 유효합니다.
어떤 데이터. 스코프는 리소스 유형과 작업을 제한하며, 선택적으로 카테고리를 지정할 수 있습니다. patient/Observation.rs?category=laboratory는 에이전트가 검사 결과를 읽고 검색할 수 있도록 허용하며 다른 작업은 수행할 수 없습니다. 컨텍스트를 구축하려면 승인이 관찰, 상태, 약물 및 알레르기(예: patient/*.rs)를 읽을 수 있도록 허용해야 합니다.
기본적으로 읽기 전용. 에이전트가 무언가를 기록하도록 의도된 경우에만 쓰기 스코프를 부여하십시오.
취소 가능. 개인은 언제든지 승인을 취소할 수 있습니다. 그러면 에이전트의 다음 호출이 거부됩니다.

에이전트가 일반적으로 필요로 하는 도구

도구	Anpheros 호출	참고 사항
작업 컨텍스트 가져오기	`POST /v1/context`	대부분의 작업에 대한 첫 번째 호출; 예산 및 소스 레이블 지정(LLM 애플리케이션 및 의료 데이터)
최근 결과 목록	`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=…`	유형별 연대기적 목록
전체 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` 및 `author_type: "ai"`	쓰기 범위가 있는 경우에만

OpenAPI 사양(https://developers.anpheros.com/openapi.json)은 모든 엔드포인트를 설명하며 도구 정의로 변환될 수 있습니다. TypeScript 및 Dart SDK는 도구로 직접 래핑될 수 있습니다.

예시: 환자 동의를 받은 방문 준비 에이전트

Anpheros에 이미 기록이 있는 환자가 제3자 어시스턴트에게 심장학 방문에 대한 질문을 준비해 달라고 요청합니다. 에이전트는 제한된 시간 동안 해당 기록에 대한 읽기 액세스 권한만 필요합니다.

1. 동의 (OAuth 2.1 + PKCE, SMART v2 스코프). 어시스턴트는 컨텍스트(관찰, 상태, 약물 및 알레르기)를 허용하는 가장 좁은 스코프를 가진 동의 페이지로 사용자를 보냅니다.

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 호출입니다.

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 포함)을 포함한 모든 호출은 해당 사용자의 이 애플리케이션에 대한 액세스 로그에 기록됩니다. 사용자가 액세스를 취소하면 다음 호출은 401로 응답하며 에이전트는 중지해야 합니다. 새로 고침 토큰은 이를 복구할 수 없습니다.

4. 출력. 에이전트는 사용한 소스와 함께 의사에게 질문을 반환합니다. 쓰기 스코프가 부여되지 않았으므로 아무것도 다시 작성하지 않습니다.

감사 및 출처

에이전트가 수행하는 모든 호출은 레코드에 대한 액세스이며 애플리케이션의 환자 액세스 로그에 표시됩니다. 여기에는 각 컨텍스트 요청도 포함되며, 컨텍스트 요청은 사용된 섹션 및 소스의 매니페스트도 저장합니다.
에이전트가 작성하는 모든 내용은 Provenance에 AI 작성으로 기록됩니다. 나중에 컨텍스트가 빌드될 때 AI 작성 값은 임상 사실과 분리되어 ai_notes 아래에 나열되므로 에이전트가 자체 이전 출력을 증거로 인용하는 일이 발생하지 않습니다.

이벤트로부터 에이전트 시작하기

웹훅을 사용하면 폴링하는 대신, 새로운 검사 결과(resource.created), 새로운 동의(consent.granted) 등 변경 사항이 발생했을 때 에이전트를 실행할 수 있습니다. 이벤트는 ID만 전달하며, 에이전트는 이후 자신의 스코프가 허용하는 범위 내에서 데이터를 읽습니다. 웹훅

유지해야 할 디자인 규칙

에이전트에게 작업을 완료하는 데 필요한 가장 좁은 범위(scope)를 부여합니다.
원시 대량 읽기(raw bulk reads)가 아닌 컨텍스트(context)에서 시작합니다. omitted 및 warnings을 존중합니다.
에이전트의 답변에 환자의 데이터 소스를 표시합니다.
에이전트가 자체적으로 진단을 제시하거나 치료를 변경하도록 절대 허용하지 않습니다. 이러한 출력은 임상의에게 전달해야 합니다.
사람이 나중에 답변의 근거를 확인할 수 있도록 각 컨텍스트의 manifest_id을 에이전트의 답변 옆에 기록합니다.