Healthcare patient portal

This agent lets a verified patient book an appointment and read their medications, allergies, and conditions from a FHIR-compatible EMR API. A preprocessor holds every message until the patient has consented, a postprocessor appends a disclaimer to every reply, and the patient id comes from the user profile, never from the conversation. It is six files, and every TypeScript file compiles against lua-cli 3.33.0; run it with the steps on Running any example. The example shows the integration shape; it is not a compliance review. Verified against lua-cli 3.33.0.

The conversation

The patient’s first message is blocked by hipaa-consent with a request to reply “I consent”. When they do, the preprocessor records the consent on their profile and lets the message through; later messages pass without a check.
The patient asks for an appointment. schedule_appointment reads patientId from the profile and posts a FHIR Appointment for that patient and the chosen practitioner.
The patient asks about their medications. view_medical_records reads the matching FHIR resources for the same patient id.
medical-disclaimer appends one fixed sentence to every reply.

Primitives and channels

Skill and tools: patient-portal, with schedule_appointment and view_medical_records.
Preprocessor hipaa-consent at priority 10, and postprocessor medical-disclaimer.
Runtime objects: User.get, user.update, and env for EMR_API_URL and EMR_API_KEY.
Channels: the web widget inside the signed-in portal, where the portal can write patientId to the profile. Any other channel works once that field is set.

The code

The tools refuse when the profile has no patientId; the skill’s context tells the model what to do then.

src/skills/tools/ScheduleAppointmentTool.ts

import { LuaTool, User, env } from 'lua-cli';
import { z } from 'zod';

export default class ScheduleAppointmentTool implements LuaTool {
  name = 'schedule_appointment';
  description = 'Request an appointment for the verified patient with a practitioner at a given time';

  inputSchema = z.object({
    practitionerId: z.string().describe('FHIR Practitioner id, for example "prac-204"'),
    start: z.string().datetime().describe('Requested start time in ISO 8601'),
    reason: z.string().describe('Why the patient wants to be seen'),
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    // The patient id was written to the profile when the patient verified their identity.
    const user = await User.get();
    const patientId = user?.data.patientId;
    if (!patientId) {
      return { scheduled: false, reason: 'The patient has not verified their identity in this portal' };
    }

    const res = await fetch(`${env('EMR_API_URL')}/Appointment`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${env('EMR_API_KEY')}`,
        'Content-Type': 'application/fhir+json',
      },
      body: JSON.stringify({
        resourceType: 'Appointment',
        status: 'proposed',
        reasonCode: [{ text: input.reason }],
        requestedPeriod: [{ start: input.start }],
        participant: [
          { actor: { reference: `Patient/${patientId}` }, status: 'accepted' },
          { actor: { reference: `Practitioner/${input.practitionerId}` }, status: 'needs-action' },
        ],
      }),
    });
    if (!res.ok) {
      throw new Error(`EMR responded ${res.status}`);
    }

    const appointment = await res.json();
    return { scheduled: true, appointmentId: appointment.id, start: input.start };
  }
}

The records tool searches one FHIR resource type by patient and returns the resources for the model to summarize.

src/skills/tools/ViewMedicalRecordsTool.ts

import { LuaTool, User, env } from 'lua-cli';
import { z } from 'zod';

export default class ViewMedicalRecordsTool implements LuaTool {
  name = 'view_medical_records';
  description = "Read the verified patient's medications, allergies, or conditions from the EMR";

  inputSchema = z.object({
    recordType: z.enum(['MedicationStatement', 'AllergyIntolerance', 'Condition']),
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const user = await User.get();
    const patientId = user?.data.patientId;
    if (!patientId) {
      return { records: [], reason: 'The patient has not verified their identity in this portal' };
    }

    const url = new URL(`${env('EMR_API_URL')}/${input.recordType}`);
    url.searchParams.set('patient', patientId);
    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${env('EMR_API_KEY')}`, Accept: 'application/fhir+json' },
    });
    if (!res.ok) {
      throw new Error(`EMR responded ${res.status}`);
    }

    const bundle = await res.json();
    const entries: Array<{ resource: Record<string, unknown> }> = bundle.entry ?? [];
    return { recordType: input.recordType, records: entries.map((e) => e.resource) };
  }
}

The skill never asks for a patient id.

src/skills/patient-portal.skill.ts

import { LuaSkill } from 'lua-cli';
import ScheduleAppointmentTool from './tools/ScheduleAppointmentTool';
import ViewMedicalRecordsTool from './tools/ViewMedicalRecordsTool';

export default new LuaSkill({
  name: 'patient-portal',
  description: 'Appointments and medical records for a verified patient',
  context: `Both tools act on the patient who is signed in; never ask for a patient id.
If a tool reports that identity is not verified, send the patient to the portal's
verification page instead of retrying. Explain records in plain language and remind the
patient to raise clinical questions with their provider.`,
  tools: [new ScheduleAppointmentTool(), new ViewMedicalRecordsTool()],
});

The preprocessor runs before the model sees a message; block ends the turn with its response, and proceed lets the message through.

src/preprocessors/hipaaConsent.ts

import { PreProcessor } from 'lua-cli';

export default new PreProcessor({
  name: 'hipaa-consent',
  description: 'Holds every message until the patient has consented to share health information',
  priority: 10,

  execute: async (user, messages) => {
    if (user.data.hipaaConsentGiven === true) {
      return { action: 'proceed' };
    }

    const text = messages.flatMap((m) => (m.type === 'text' ? [m.text] : [])).join(' ');
    if (/\bI consent\b/i.test(text)) {
      await user.update({ hipaaConsentGiven: true, hipaaConsentAt: new Date().toISOString() });
      return { action: 'proceed' };
    }

    return {
      action: 'block',
      response:
        'Before I can help with appointments or records, please confirm that you consent to sharing your health information in this chat. Reply "I consent" to continue.',
    };
  },
});

The postprocessor receives the reply and returns the text to send.

src/postprocessors/medicalDisclaimer.ts

import { PostProcessor } from 'lua-cli';

export default new PostProcessor({
  name: 'medical-disclaimer',
  description: 'Appends the portal disclaimer to every reply',

  execute: async (_user, _message, response) => ({
    modifiedResponse: `${response}

This portal does not give medical advice. In an emergency, call your local emergency number.`,
  }),
});

The agent registers the skill and both processors.

src/index.ts

import { LuaAgent } from 'lua-cli';
import patientPortalSkill from './skills/patient-portal.skill';
import hipaaConsent from './preprocessors/hipaaConsent';
import medicalDisclaimer from './postprocessors/medicalDisclaimer';

const agent = new LuaAgent({
  name: 'riverside-patient-portal',
  persona: `You are the patient portal assistant for Riverside Clinic.
Help patients book appointments and read their records. Be calm and precise, use plain
language for medical terms, and never interpret results or suggest treatment.
Direct emergencies to the emergency number and billing questions to the billing office.`,
  skills: [patientPortalSkill],
  preProcessors: [hipaaConsent],
  postProcessors: [medicalDisclaimer],
});

First run

Run the preprocessor with a first message on the web widget’s channel, pop; it blocks and returns the consent request.

lua env sandbox -k EMR_API_URL -v https://emr.example.com/fhir
lua env sandbox -k EMR_API_KEY -v <api-key>
lua test --ci preprocessor --name hipaa-consent --input '{"message":"Can I see my medications?","channel":"pop"}'

Output

✅ Compiled 6 primitives (1 agent, 1 skill, 2 tools, 1 preprocessor, 1 postprocessor) in 538ms
✅ Selected preprocessor: hipaa-consent
🚀 Executing preprocessor...
Input message: Can I see my medications?
Channel: pop
✅ PreProcessor execution successful!

Action: BLOCK
Response: Before I can help with appointments or records, please confirm that you consent to sharing your health information in this chat. Reply "I consent" to continue.

The same command with "message":"I consent" proceeds and writes hipaaConsentGiven to the test user’s profile. Test a tool with lua test --ci skill --name view_medical_records --input '{"recordType":"Condition"}'; without patientId on the profile it returns the not-verified reason. For the full loop with the model, send lua chat --ci -e sandbox -m "Can I see my medications?" -t; it uploads the .env values with the sandbox version. Then release it with lua push all --ci --force, lua version create --ci -m "<message>", and lua version promote <n>; Release an agent to production explains what each command changes.

Ways to make it yours

Write patientId to the profile after your portal verifies identity, either from a verification tool with user.update({ patientId }) or through the user data REST endpoints. The tools trust that field and nothing the model says.
Replace the consent text and the disclaimer with the wording your compliance team approves; both are strings in one file each.
Vary the disclaimer by channel with the fourth argument of the postprocessor’s execute (pop for the web widget, whatsapp for WhatsApp), for example a shorter sentence on WhatsApp.
Summarize FHIR resources into plain fields inside view_medical_records when the model’s replies are too raw; the tool’s return value is what the model reads.

Next steps

Add a processor

Order, priority, blocking, and testing preprocessors and postprocessors.

Identify users

The profile, custom fields, and cross-channel identity.

Call your API

Keys in env(), errors, and timeouts when a tool calls an external service.

Get started

Concepts

Build

Channels

Integrations

Devices

Ship and operate

Marketplace

Build with AI

Examples

Healthcare patient portal

The conversation

Primitives and channels

The code

First run

Ways to make it yours

Next steps

Add a processor

Identify users

Call your API

​The conversation

​Primitives and channels

​The code

​First run

​Ways to make it yours

​Next steps

Add a processor

Identify users

Call your API

The conversation

Primitives and channels

The code

First run

Ways to make it yours

Next steps