Production workflows / Guide 02
A Hospital Appointment Agent That Reserves the Whole Visit
Design a hospital appointment agent that checks referrals, staff and equipment availability, protects patient data, and recovers safely from booking failures.
Illustrative engineering guide. Examples are not client deployments, production-ready integrations, or evidence of measured results. Validate the design with your domain and security owners.
Consider a hypothetical outpatient clinic scheduling an imaging visit. A patient asks for Tuesday morning, and the calendar shows an empty slot. That does not establish that the required scanner, qualified staff, referral, and visit duration are available together. A hospital appointment agent must reserve a valid care workflow, not merely place a name into a free square.
The safest first release handles administrative scheduling for an already specified service. Clinicians determine clinical suitability, urgency, preparation instructions, and treatment. The assistant can explain approved scheduling information and identify missing administrative requirements, but it must not diagnose symptoms or decide that a delayed appointment is medically safe.
Availability Is Not a Booking Promise
HL7’s Appointment resource explicitly distinguishes checking availability from successfully making an appointment. The booking system can still apply permissions, assessments, and resource constraints. This is an important product distinction: show a time as an option until the authoritative scheduler confirms it.
Represent the visit as a service code, location, duration, required resource roles, and validated referral reference. Keep patient preferences separate from clinical requirements. “Near my office” is a preference; “requires a particular device” is a constraint. If the constraints cannot be satisfied, the assistant should explain the scheduling obstacle and involve staff rather than downgrade the service.
A patient saying “the same scan as last time” is not enough to reuse an old order. Resolve the current referral through the clinical system or ask authorized staff. Similarly, insurance information may support an administrative eligibility check, but an eligibility response should not be presented as a guarantee of payment or clinical appropriateness.
Build Around One Scheduling Authority
Start with a verified patient portal, a referral lookup tool, a schedule adapter, and a durable booking coordinator. An LLM extracts preferences and asks clarifying questions. Deterministic code validates service codes, appointment lengths, resource conflicts, local time zones, and state transitions. Use one scheduler as the final authority wherever possible.
The following Python example is a runnable, deliberately small interval check for UTC integer timestamps. It demonstrates half-open reservation intervals, so an appointment ending at ten does not conflict with one beginning at ten. It is not a booking API and omits authentication, database transactions, preparation buffers, and clinical rules.
def overlaps(start, end, existing):
if end <= start:
raise ValueError("invalid interval")
return any(start < other_end and other_start < end
for other_start, other_end in existing)
assert overlaps(100, 160, [(150, 180)])
assert not overlaps(100, 150, [(150, 180)])
assert overlaps(100, 180, [(120, 140)])Checking intervals outside a transaction does not prevent concurrent booking. The final reservation must atomically enforce conflicts across required resources, or use the scheduler’s supported reservation operation. Store UTC instants plus the location’s time-zone identifier for presentation. A local time during a daylight-saving transition must be resolved explicitly, not guessed by the model.
Separate specialist agents rarely help the initial workflow. Referral extraction might justify a separately evaluated component when documents vary widely, but it should return evidence spans and uncertainty, not clinical decisions. Schedule lookup and notification delivery remain ordinary tools with explicit contracts.
Protect the Patient Relationship
FHIR security documentation explains that FHIR is not itself a security protocol. Authentication, authorization, audit, and data-management policies are implementation responsibilities. MCP likewise supplies integration mechanics, not permission to read or change a patient’s appointments.
The server must establish whether the requester is the patient, an authorized delegate, or a staff member with a relevant role. Do not infer guardianship from a shared address. Scope all referrals, appointments, documents, and notifications by organization and patient relationship before retrieval. Recheck authorization at booking time because delegation can expire while a conversation remains open.
Referral attachments and patient messages are untrusted content. They cannot instruct the system to bypass approval or send records elsewhere. Strip active content, constrain extraction, and ensure tool parameters cannot change tenant scope. Keep raw medical content out of general telemetry. Audit access using protected records with controlled retention and provenance.
When a patient introduces potentially urgent symptoms, pause the scheduling script and invoke the clinic’s clinician-approved escalation process. The assistant must not offer diagnostic reassurance. Preparation guidance should reference the specific approved instruction version, with staff review whenever the referral or procedure differs.
Rescheduling Requires Compensation
Do not cancel the existing appointment before securing the replacement unless the scheduler’s documented workflow requires it and staff approve the risk. Prefer a temporary reservation, explicit patient confirmation, replacement booking, and then cancellation of the original. When atomic replacement is unavailable, model both bookings and the compensation path.
A timeout after submission is an unknown outcome. Query by the durable booking request identifier before sending another create request. If the replacement exists but cancellation fails, retain a visible reconciliation task and alert staff; do not leave two appointments silently consuming scarce capacity. Notification failure should retry the notification, not the booking.
Confirmation messages should distinguish “request received,” “temporarily held,” and “booked.” Include location, local date and time, preparation source, and an accessible route to staff. Avoid disclosing specialty details in lock-screen notifications when a neutral message can direct the patient into the protected portal.
Acceptance Tests for the Scheduling Boundary
- Two patients confirm the same scanner slot concurrently. Exactly one reservation succeeds; the other receives new options without an invented confirmation.
- A delegate’s authorization expires after search but before confirmation. Booking is denied and no additional patient information is revealed.
- A referral attachment contains instructions to skip clinical approval. The instruction has no effect on required referral validation.
- Replacement booking succeeds and old-booking cancellation times out. Reconciliation finds the replacement and alerts staff to the unresolved original without booking again.
- A requested local time is ambiguous during daylight-saving change. The workflow obtains an explicit valid instant and renders the correct offset in confirmation.
Evaluate Access to Care, Not Just Chat Speed
Baseline the current scheduling desk by service type, referral completeness, and rescheduling complexity. Measure valid completed bookings divided by eligible scheduling requests, with staff-adjudicated validity and unresolved requests retained in the denominator. Also measure elapsed time from request to confirmed appointment, not merely conversation duration.
Guardrails include duplicate reservations per booking attempt, inappropriate clinical guidance per reviewed conversation, and unauthorized disclosures. Track abandonment separately for patients using assistive technology or nonstandard communication patterns. Proposed release gates should require zero known authorization escapes and no regression in clinically reviewed scheduling correctness; these are targets, not reported outcomes.
Begin with one routine service and staff-approved drafts. Expand only after replaying concurrency and rescheduling failures. The medical summarization guide covers clinical provenance, while field-service dispatch explores related multi-resource constraints outside healthcare. Healthcare-capable application engineering can connect these controls to an accessible patient workflow.