Production workflows / Guide 24
A Hotel Operations Agent That Never Confuses Clean With Available
Design a hotel operations agent that reconciles room readiness, guest requests, maintenance blocks, and staff dispatch without issuing unsafe room assignments.
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.
A hotel operations agent should know that a clean room can still be unavailable. Imagine a hypothetical hotel during an early-arrival surge: housekeeping has finished room 412, engineering has blocked its bathroom, and the front desk is looking for a room for a family already in the lobby. If an assistant sees only “clean,” it can make an expensive promise. This reference design reconciles operational states before suggesting assignments, dispatches, or guest messages.
Model Independent Room States
Do not compress room readiness into one field. Track occupancy, housekeeping completion, inspection, engineering blocks, inventory allocation, and access-key status independently. A vacant room may be dirty. An inspected room may be allocated to an arriving guest. A room released by engineering may still need housekeeping inspection after the repair.
Name an authoritative owner for each dimension. The property management system owns reservation allocation; housekeeping owns its work record; engineering owns maintenance clearance. The assistant reads those facts and explains conflicts. It should not overwrite the property management system’s state simply to make sources agree.
An LLM can classify “the air conditioner is rattling” as a maintenance request and ask useful follow-up questions. It cannot certify electrical safety or decide that a guest’s room is vacant. Deterministic rules decide what evidence makes a room eligible for assignment. Front-desk staff approve room moves, compensation, upgrades, and any exception affecting a guest’s stay.
A Readiness Gate Before Every Promise
The smallest useful architecture combines an authenticated request channel, a room-state reader, a rules service, a task writer, and a reconciliation worker. A guest channel resolves the active stay server-side. Staff tools require property-level and role-level permission checks. The model receives a minimal snapshot with source timestamps, not unrestricted access to guest profiles.
The following executable Python is an illustrative eligibility gate for a single room. It assumes validated inputs and deliberately excludes reservation selection.
def ready_for_assignment(room, max_age_seconds=60):
return (
0 <= room["snapshot_age_seconds"] <= max_age_seconds
and room["occupancy"] == "vacant"
and room["housekeeping"] == "inspected"
and room["engineering_blocks"] == 0
and room["allocation"] == "unassigned"
)
room = {"snapshot_age_seconds": 12, "occupancy": "vacant",
"housekeeping": "inspected", "engineering_blocks": 1,
"allocation": "unassigned"}
assert not ready_for_assignment(room)
assert ready_for_assignment({**room, "engineering_blocks": 0})
assert not ready_for_assignment({**room, "engineering_blocks": 0,
"snapshot_age_seconds": 120})Production needs accessible-room suitability, room-type entitlements, linked reservations, transaction isolation, identity checks, and a conditional allocation operation. The freshness limit is an illustrative operational choice, not an industry standard. A room can change immediately after the check, so the eventual assignment must compare the source version and reserve atomically.
PostgreSQL constraints provide useful building blocks for unique assignment keys and valid state values. They do not automatically enforce a hotel’s complete allocation model. Cross-row occupancy windows and external property-system state require deliberate transactional design rather than a model-generated update statement.
Dispatch Tasks, Not Autonomous Staff Personas
Start with one coordinator and typed tools for creating housekeeping or engineering tasks. A specialist sub-agent is warranted only if it performs independently useful reasoning, such as interpreting maintenance manuals for an engineer with a distinct evidence policy. A task queue with ownership and acknowledgment is usually more valuable than separate “concierge,” “housekeeper,” and “manager” chatbots.
For a towel request, create a bounded task containing property, stay reference, requested quantity, destination, priority, and access restrictions. Do not include the guest’s full payment profile. For a water leak, follow the property’s approved urgent-response playbook and notify the duty team. The assistant must not diagnose building safety or reassure a guest that an active hazard is harmless.
Acknowledgment is separate from completion. A message sent to a staff device does not establish that someone accepted the task. Maintain states such as queued, acknowledged, in progress, completed, and blocked. Escalate overdue acknowledgments to a supervisor using configured duty schedules. If the task cannot be completed, give the guest an accurate status rather than silently closing it.
Recover Across Shift Changes and Outages
Use a stable key for the guest request and task type so chat retries do not dispatch three employees. If task creation times out, query by that reference before resending. When a room move is approved, re-read reservation and room versions before committing. If key issuance fails after allocation, surface a partial state for staff; do not move the guest again automatically.
Keep a shift-handoff view of unresolved work, source ages, and accountable teams. Offline staff updates should carry event IDs and device timestamps, but server receipt and source sequence determine ordering. An old “cleaned” event must not erase a newer engineering block. Preserve the events for investigation instead of flattening every update into the latest received value.
Server-side authorization must prevent one property’s staff from searching another property’s guests. Row-level security can reinforce this boundary, with explicit tests for privileged-role bypass. Guest possession of a room number is not proof of an active stay. Do not expose occupancy, key status, or guest names through an unauthenticated concierge conversation.
Guest notes and vendor messages may contain malicious instructions. OWASP’s LLM project documents why retrieved text cannot be trusted as control instructions. Allowlisted task types, restricted destinations, and independent approval gates keep such content from issuing keys, waiving charges, or exporting guest lists.
Acceptance Tests and Operational Evidence
Test realistic collisions rather than only happy-path requests:
- A room is inspected but engineering-blocked. It never appears as ready for assignment, regardless of a guest’s urgency.
- Two front-desk users approve the same room for different stays. Exactly one conditional allocation succeeds; the other receives a conflict.
- A task write succeeds but its response is lost. A retry produces one dispatch and preserves the original task ID.
- An offline cleaning update arrives after a maintenance block. The block remains effective and the event history remains inspectable.
- A guest asks for another room’s occupant or embeds key-issuance instructions in a request. No private details or access credentials are returned.
Baseline request-to-acknowledgment time, room-ready accuracy, and staff correction effort across similar arrival periods. Measure readiness precision as rooms actually assignable when checked by staff divided by rooms recommended as ready. Measure completed-on-time tasks against all accepted tasks, including blocked work rather than removing it from the denominator.
Guardrails include conflicting assignments, unauthorized key actions, repeated dispatches, and misleading completion messages. Roll out first to one low-risk request category on one property and shift. Only expand after supervisors review disagreement cases; any time-saving target remains proposed until observed.
The property management guide explores longer-lived maintenance obligations, while field service dispatch develops technician assignment constraints. Golang Backend & API Engineering supports transactional integration. Begin by mapping who owns each room-state dimension and recording one full shift of conflicting updates before automating guest promises.