Epic connector for AI agents

Tools your clinical agent reaches for on Epic, scoped per user.

CALL ANY TOOL

53 tools for clinical records in Epic over FHIR: search and match patients, read conditions, medications, lab results, and clinical notes, find and book appointment slots, and file allergies, problems, vitals, and notes.

epic_allergy_intolerance_create

Create allergy intolerance

File a new allergy or intolerance for a patient in Epic. Returns the created AllergyIntolerance resource. Epic saves it to a holding area with verification status 'unconfirmed' until a clinician reconciles it into the chart. Use this to record an allergy the patient reports. Use epic_allergy_intolerance_search first to avoid filing a duplicate. Requires a patient FHIR ID: run epic_patient_search or epic_patient_match first.

Parameters

Name

Type

Required

Description

patient_id

string

Required

FHIR ID of the patient whose allergy to return. Get it from epic_patient_search or epic_patient_match. Example: 12345.

substance_text

string

Required

Name of the allergen as free text. Example: Penicillin.

category

string

Optional

Category of the allergen: food, medication, environment or biologic. One of: `food`, `medication`, `environment`, `biologic`.

clinical_status

string

Optional

Clinical status of the allergy: active or resolved. A resolved allergy needs an onset end date in the past. One of: `active`, `resolved`.

criticality

string

Optional

Risk of clinical harm: low, high or unable-to-assess. One of: `low`, `high`, `unable-to-assess`.

note

string

Optional

Free-text comment about the allergy. Example: Reported by patient at intake.

onset_date

string

Optional

Date the allergy was identified, as YYYY-MM-DD. Example: 2024-01-15.

reaction

string

Optional

Reaction the patient had, as free text. Example: Hives.

reaction_severity

string

Optional

Severity of the reaction: mild, moderate or severe. Used only when Reaction is set. One of: `mild`, `moderate`, `severe`.

substance_code

string

Optional

Code for the allergen in the system given by Substance System, such as an RxNorm code. Example: 7980.

substance_system

string

Optional

Coding system URI or OID of Substance Code. Example: http://www.nlm.nih.gov/research/umls/rxnorm.

type

string

Optional

Underlying mechanism: allergy or intolerance. One of: `allergy`, `intolerance`.

epic_allergy_intolerance_read

Read allergy intolerance

epic_allergy_intolerance_search

Search allergy intolerance

epic_appointment_book

Appointment book

epic_appointment_find_slots

Appointment find slots

Find open appointment times in Epic for a visit type, within an optional time window and with optional patient details ($find, STU3). Returns a searchset Bundle of proposed Appointment resources (status proposed, start, end, minutesDuration, serviceType, participants for the provider and department, and the held Slot as a contained resource). Only the first page is returned (10 by default); epic_next_page cannot page these results. Use this to offer bookable times, then epic_appointment_book with the chosen entry's id. Use epic_appointment_search for appointments a patient already has. The health system must have built Epic scheduling rules for this app; those rules decide which inputs are used or required and which slots come back.

Parameters

Name

Type

Required

Description

service_type_code

string

Required

Code of the visit type (Epic visit type) to find slots for. Visit type codes are set up by each health system. Example: 12345.

service_type_system

string

Required

Code system of the visit type code, usually the health system's visit type OID. Example: urn:oid:1.2.840.114350.1.13.0.1.7.3.808267.11.

days_of_week

array

Optional

Days of the week to search, as FHIR day codes. Example: ["tue", "thu"].

duration

number

Optional

Appointment duration, in the unit given by Duration Unit. Example: 30.

duration_unit

string

Optional

Unit of Duration: s (seconds), min (minutes), h (hours) or d (days). One of: `s`, `min`, `h`, `d`.

end_time

string

Optional

Latest end of the slots to search, as a FHIR dateTime with time zone. Example: 2024-05-05T22:00:00Z.

indication_codings

array

Optional

Diagnosis codes the visit is for, each with system, code and optional display. Epic accepts a community diagnosis code and/or a SNOMED code; if both are sent, the community diagnosis code wins. Example: [{"system": "urn:oid:2.16.840.1.113883.6.96", "code": "46866001", "display": "Fracture of lower limb"}].

indication_text

string

Optional

Plain-text description of the diagnosis indications. Example: Broken leg.

location_reference

string

Optional

Reference to the Location (department) to search in, as Location/<FHIR ID> or the full STU3 Location URL. Example: Location/12345.

patient_address_line

array

Optional

Street lines of the patient's home address. Example: ["123 Main St"].

patient_birth_date

string

Optional

Patient's date of birth as YYYY-MM-DD. Example: 1980-01-01.

patient_city

string

Optional

City of the patient's home address. Example: Madison.

patient_country

string

Optional

Country of the patient's home address. Example: US.

patient_district

string

Optional

County of the patient's home address. Example: Dane.

patient_email

string

Optional

Patient's email address. Example: patient@example.com.

patient_family

string

Optional

Patient's family (last) name, used by the health system's scheduling rules. Example: Testpatient.

patient_gender

string

Optional

Patient's legal sex as a FHIR gender code: male, female, other or unknown. One of: `male`, `female`, `other`, `unknown`.

patient_given

array

Optional

Patient's given names (first, then middle). Example: ["Jane"].

patient_identifier_system

string

Optional

System of a patient identifier, such as the health system's MRN OID. Send together with Patient Identifier Value. Example: urn:oid:1.2.3.4.

patient_identifier_value

string

Optional

Value of the identifier named by Patient Identifier System, such as the MRN. Example: 12345.

patient_name_use

string

Optional

Kind of name sent: usual or official. One of: `usual`, `official`.

patient_phone

string

Optional

Patient's phone number. Example: 555-555-0100.

patient_phone_use

string

Optional

Kind of phone number: home, mobile or work. One of: `home`, `mobile`, `work`.

patient_postal_code

string

Optional

ZIP code of the patient's home address, as nnnnn or nnnnn-nnnn. Example: 53703.

patient_state

string

Optional

State of the patient's home address, as a two-letter postal code. Example: WI.

patient_temporary_country

string

Optional

Country of the patient's temporary address. Example: US.

patient_temporary_state

string

Optional

State of the patient's temporary address (where the patient is now, if different from home), as a two-letter postal code. Example: IL.

patient_timezone

string

Optional

Patient's time zone, as an IANA time zone name. Example: America/Chicago.

referral_id

string

Optional

Referral ID; Epic uses the referral to pick the right visit type and providers. Example: 12345.

referral_system

string

Optional

Code system of the referral ID, if the health system uses one. Example: urn:oid:1.2.3.4.

service_type_display

string

Optional

Display name of the visit type. Example: Office Visit.

specialty_code

string

Optional

Department specialty code to limit slots to. Example: 12345.

specialty_display

string

Optional

Display name of the specialty. Example: Gastroenterology.

specialty_system

string

Optional

Code system of the specialty code, usually a health-system OID. Example: urn:oid:1.2.3.4.

start_time

string

Optional

Earliest start of the slots to search, as a FHIR dateTime with time zone. Example: 2024-05-01T13:00:00Z.

times_of_day

array

Optional

Preferred times of day for the appointment, as HH:MM:SS. Example: ["09:00:00"].

epic_appointment_read

Read appointment

epic_appointment_search

Search appointment

epic_care_plan_read

Read care plan

epic_care_team_search

Search care team

epic_condition_create

Create condition

epic_condition_read

Read condition

epic_coverage_search

Search coverage

epic_diagnostic_report_read

Read diagnostic report

epic_diagnostic_report_search

Search diagnostic report

epic_encounter_read

Read encounter

epic_encounter_search

Search encounter

epic_immunization_read

Read immunization

epic_immunization_search

Search immunization

epic_location_read

Read location

epic_medication_request_read

Read medication request

epic_medication_request_search

Search medication request

epic_observation_create

Create observation

File one vital sign or flowsheet reading for a patient's open encounter in Epic. Returns the created Observation resource (category vital-signs, status final). Use this to document a single measurement such as temperature, pulse or weight. Epic rejects a reading that already exists at the same time, on a closed encounter or on a future appointment. Requires a patient FHIR ID and an open encounter ID: run epic_patient_search and epic_encounter_search first.

Parameters

Name

Type

Required

Description

code

string

Required

Code of the measurement: a LOINC code (e.g. 8310-5 body temperature, 8867-4 heart rate, 29463-7 body weight) or an Epic flowsheet row ID. LOINC works only when it maps to a single flowsheet row; if Epic answers "Multiple Flowsheet rows found by given codes", send the flowsheet row ID instead (e.g. 8 for pulse) with the organization's flowsheet-row OID in Code System. Example: 8310-5.

effective_date_time

string

Required

Date and time the reading was taken, ISO 8601 with a time zone. Example: 2024-01-15T14:30:00Z.

encounter_id

string

Required

FHIR ID of the open encounter to file the reading to. Required for clinician apps. Example: 12345.

patient_id

string

Required

FHIR ID of the patient whose reading to return. Get it from epic_patient_search or epic_patient_match. Example: 12345.

code_system

string

Optional

Coding system of Code. Defaults to http://loinc.org, which works when the LOINC code maps to one flowsheet row. If Epic answers "Multiple Flowsheet rows found by given codes", send the flowsheet row ID as Code with the organization's flowsheet-row OID system: urn:oid:1.2.840.114350.1.13.0.1.7.2.707679 in Epic's sandbox; in production, the organization's own OID ending .7.2.707679. Example: urn:oid:1.2.840.114350.1.13.0.1.7.2.707679.

note

string

Optional

Comment on the reading, up to 254 characters. Example: Taken after exercise.

unit

string

Optional

Unit for Value Quantity in UCUM form. Epic validates and converts height, weight and temperature units. Example: Cel.

value_quantity

number

Optional

Numeric value of the reading. Send this or Value String. Example: 37.2.

value_string

string

Optional

Text value for a reading without units. Send this or Value Quantity. Example: Regular.

epic_observation_search

Search observation

epic_organization_read

Read organization

epic_patient_match

Patient match

epic_practitioner_read

Read practitioner

epic_practitioner_role_search

Search practitioner role

epic_procedure_read

Read procedure

epic_procedure_search

Search procedure

epic_schedule_get

Get schedule

For more tools, view docs.

Build your Agent

Same auth pattern across LangChain, OpenAI, Anthropic, and Google ADK.

import { ScalekitClient } from "@scalekit-sdk/node";
import { createReactAgent } from "@langchain/langgraph/prebuilt";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);

// Epic tools scoped to this user
const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["epic"], toolNames: [
    "epic_patient_search",
    "epic_appointment_find_slots",
    "epic_appointment_book"] },
  pageSize: 100,
});

const agent = createReactAgent({ llm, tools });
await agent.invoke({ messages: [{ role: "user", content: "Find Maria Lopez and book her into the next open new patient visit" }] });

import OpenAI from "openai";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);
const openai = new OpenAI();

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["epic"] }, pageSize: 100,
});

const res = await openai.chat.completions.create({
  model: "gpt-5",
  messages: [{ role: "user", content: "Find Maria Lopez and book her into the next open new patient visit" }],
  tools,
});

// Execute the tool call with the user's vaulted Epic OAuth token
await sk.tools.executeTool(res.choices[0].message.tool_calls[0], "user_123");

import Anthropic from "@anthropic-ai/sdk";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);
const anthropic = new Anthropic();

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["epic"] }, pageSize: 100,
});

const msg = await anthropic.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Find Maria Lopez and book her into the next open new patient visit" }],
  tools,
});

// Tool call runs with the user's vaulted Epic OAuth token
await sk.tools.executeTool(msg.content, "user_123");

import { Agent } from "@google/adk/agents";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["epic"] }, pageSize: 100,
});

const agent = new Agent({
  name: "clinical_agent",
  model: "gemini-2.5-pro",
  instruction: "Epic tools scoped to this user",
  tools,
});

await agent.run("Find Maria Lopez and book her into the next open new patient visit");

Try these prompts

Copy any prompt into your agent. Each maps directly to a Epic tool. Click to copy, paste into your agent, done.

Patient records

Copy the prompt

Copied

Find the Epic patient that matches this name, birth date, and phone number.

Copy the prompt

Copied

List this patient's active problem list items.

Copy the prompt

Copied

Generate an International Patient Summary for this patient.

Results and notes

Copy the prompt

Copied

Show this patient's lab results from the last 30 days.

Copy the prompt

Copied

Find the clinical notes from this patient's last encounter.

Copy the prompt

Copied

List this patient's active medication orders.

Scheduling and charting

Copy the prompt

Copied

Find open appointment times for a new patient visit next week.

Copy the prompt

Copied

Book the 10am time you found for this patient.

Copy the prompt

Copied

File a blood pressure reading of 128/82 to this patient's open encounter.

SEE HOW AUTH WORKS

Each user signs in to Epic once, and Scalekit stores and refreshes their tokens. Credentials stay vaulted, every call is scope checked, and every action is logged.

Authorize

Your user connects

Epic

once. We tie it to their identity and the meetings they approved — no shared bot account, no org-wide access

Who:

user ‘A’

when:

Once per user

access:

Limited to user

Store

Their

Epic

token lives in a vault scoped to them. User A's meetings are never reachable by an agent acting for user B, even on the same connection

vault:

encrypted

scope:

per-user

tokens:

auto-refreshed

Resolve

When your agent calls a

Epic

tool, we fetch the right token server-side. It never touches your agent, never appears in the LLM context, never shows up in your logs

speed:

~40ms

check:

before every call

seen by:

nobody

Audit

Every

Epic

tool call is logged — who triggered it, which meeting was fetched, what came back. 90 days of history, tied to the user who authorized it

history:

90 days

export:

SIEM-ready

logged:

every call

Test other agents

See the same per-user auth pattern across other healthcare connectors.

Support and Ops Teams

Meeting prep

Pulls agenda, participant context, and open action items before every meeting.

Engineering Teams

Slack triage

Polls Slack for new messages, classifies bugs and support requests with a LangGraph router, files GitHub issues or Zendesk tickets, and confirms in the thread.

Why Scalekit

Secure your agent's access. Connectors ship in minutes

01.

Shared tokens break per-user analytics

A shared Epic token looks fine in a demo. In production every chart read and booking looks like one service account, and you cannot tell which user triggered it. Scalekit resolves the credential of the actual user who triggered the agent, never a shared bot.

// shared token
audit → bot_service_account

// scalekit
audit → user_abc ✓

02.

Authentication is not authorization

03.

Multi-tenancy is architectural

04.

Epic today. Ten connectors tomorrow.

“Our agents act across Salesforce, Gong, Google Drive, and more, on behalf of every customer. Scalekit behind the scenes meant we can keep adding tools without ever rebuilding how credentials or tool calling work.”

Venu Madhav Kattagoni

Head of Engineering / Von

FAQs

Frequently Asked Questions

Does the agent access Epic as the user or through a shared service account?

As the user. Each user signs in to Epic once with SMART on FHIR, and Scalekit stores and refreshes their tokens. Every chart read and write in your audit trail is attributed to that user, not a shared service account.

Where is the Epic OAuth token stored?

In Scalekit's managed AES-256 token vault, namespaced per tenant. Refresh is automatic. Revocation is a single dashboard action. Credentials never appear in prompts, logs, or LLM context.

Can I limit what the agent does in Epic?

Yes. Filter by tool name in listScopedTools to expose only what you want, for example the read and search tools without epic_appointment_book or epic_document_reference_create. The connector has no delete tools. Scalekit also enforces scope checks before every API call.

What happens when a user revokes Epic access?

The connection is invalidated on the next tool call. Subsequent requests for that user fail closed with a clear error. Other users in the tenant remain unaffected. The event is logged for audit.

Is this connector for the Epic EHR?

Yes. It connects to the Epic EHR used by health systems, through its FHIR API, not to Epic Games. The tools work with clinical records in your health system's Epic instance: patients, conditions, encounters, results, notes, and appointments.