WiseAI Realtor — AI Agents (Voice + Chat) Config Expected Output Spec
⛔ STATUS: DRAFT — NOT APPROVED. CLAUDE.md Rule #17 (HARD GATE) is NOT satisfied.
Stage-1 agent research, pre-populated from the realtor design docs + the
agent-config.htmlmock +ai-guardrails.md. Do not build the customer-facing screen until the founder approves and confirms the open items in a Stage-2 interview. Voice-agent changes are LIFE-SAFETY, deploy-gated, and owned by thevoice-agent-engineeragent (independent QA voice review + founder go before ANY deploy).
Sourced from (read-only, 2026-06-29):
ai-guardrails.md(the RE conversation guardrail contract — fair-housing/anti-steering, no-regulated-advice, honesty/facts-used receipt, identity/disclosure, escalation, autopilot/co-pilot, regression coverage), the approvedacceptance/ai-front-desk.md(the capture/ FAQ/escalate front-desk behaviour this screen configures),data-model.md§1.9 (local_business_voice_linesline_type/language), andrealtor-mockups/agent-config.html.
0. Scope — what this spec covers, and what it does NOT
This spec covers the AI Agents config screen — where the agent configures
Aria (voice + chat): working mode (autopilot/co-pilot), the guardrails
surface, the Premium voice line + Community language lines, knowledge
sources, conversation rules, website placement, capture fields, and a live
test panel. It is Settings › AI Agents.
This spec BUILDS ON and does NOT duplicate acceptance/ai-front-desk.md —
the approved sibling that defines the front-desk behaviour itself (greeting +
AI disclosure, FAQ from the setup profile, lead capture → local_business_leads,
emergency/escalation, at-capacity fallback, the universal crisis/safety layer,
paused/cancelled). This screen configures that behaviour; it does not
re-specify it. Where this spec says "Aria greets / captures / escalates", the
behaviour is ai-front-desk.md §V/§C.
It surfaces — and does NOT replace — ai-guardrails.md (the RE conversation
guardrail contract). The guardrail enforcement (system-prompt frame, intent
classifier, post-LLM belt, facts-used receipt, regression suite) is ai-guardrails.md;
this screen exposes the guardrails the agent can see/edit and the test panel
to exercise them.
Does NOT cover: the conversation inbox / take-over (realtor-inbox-mvp.md);
the public website embed surface (website specs); provisioning/telephony
mechanics (ai-front-desk.md §3 + voice provisioning runbook).
Build posture: the RE voice vertical + multilingual chat already exist
(voice-agent-livekit/verticals/real_estate/, api/chatbot/stream RE branch);
this config screen reads/writes their config (setup profile + voice lines +
modules), it does not rebuild the agents (do-not-reinvent.md).
1. The mock screen this spec governs + what it reads
Governs: realtor-mockups/agent-config.html — a Voice | Chat tabbed
screen with a header status ("Aria is live · answered 9 today") and Save/Discard.
- Voice tab: a Working mode card (Co-pilot ⇄ Autopilot, with the AI-bridge note "she is a bridge to you, never a stand-in") + a Guardrails summary (chips: won't give legal advice / won't quote a home's value or guarantee a price / no fair-housing-protected steering / always offers a human / identifies as an AI assistant) with Edit guardrails; a Premium Voice Line card (DID, voice actor + preview, EN/ES/FR, hours, greeting, Test call, Transcripts →, and sub-cards: Questions to ask & capture / Escalation rules / Call-summary format); and a Community Language Lines card (the differentiator — shared Community DID auto-detecting language, Google STT/TTS, per-language rows Punjabi/Urdu/Hindi/Mandarin with voice actor + greeting + enable toggle, "inherits Premium Line" rules with override, "Add a language").
- Chat tab: Knowledge sources (agent/team profile, listings, neighbourhood guides, buyer/seller guides, FAQs, brokerage policies — each toggleable, with "she only speaks from these — won't invent facts"), multilingual replies, Conversation rules & guardrails, Website placement (bubble, inline on listing pages, listing-context awareness, embed code), Lead-capture fields, and a sticky live Test panel (sandbox; "test conversations aren't saved as leads"; shows listing-context + Punjabi detection + captured fields).
Reads/writes (verify exact route names; do not fabricate):
| Surface | Underlying store |
|---|---|
| Working mode (autopilot/co-pilot) | per-channel autopilot config (ai-guardrails.md RULE 6) |
| Guardrails surface | the RE guardrail set (ai-guardrails.md RULE 1–4) — read/edit of the configurable parts; the §R5 NEVER list is enforced, not removable |
| Premium + Community voice lines | local_business_voice_lines (DID, voice_id, language, line_type, status, hours) |
| Greeting / capture / escalation / summary | local_business_setup_profiles (greeting, services, faqs, escalation_rules, notification_preferences, forbidden_claims, brand_voice) |
| Chat knowledge sources | profile + local_business_listings + content guides + product_knowledge |
| Module enablement | local_business_modules (voice_agent / chatbot) |
| Test panel | a sandbox (not saved as leads) hitting the RE chat/voice path |
Demo tenant: Terry & Sheri Real Estate (…0c01). Aria/voice config is demo;
NEVER mutate a real customer tenant (feedback_never_modify_customer_data).
2. The AI-Bridge / honesty anchor (this screen configures the bridge)
Per architecture/ai-bridge-principle.md + ai-guardrails.md §2 (the RE AI
Bridge Frame, injected FIRST in every channel):
- Aria is a bridge, not a stand-in. The working-mode copy says so; the guardrails make it true. Aria identifies as AI, always offers a human, and defers anything requiring licensed judgment (value/legal/finance/tax/ representation) with zero advice.
- Guardrails are enforced, not cosmetic. The chips on this screen map to the
ai-guardrails.mdenforcement layers (frame + classifier + belt + receipt). The agent may tune configurable settings (tone, capture fields, hours, escalation contacts, which languages), but the §R5 NEVER list and the disclosure clauses are not removable by the agent.
3. Role-based visibility
| Bucket | Roles | Config scope |
|---|---|---|
| Brokerage management | brokerage_owner, broker_admin (brokerage scope) | Full config + Save; edit guardrail-configurable settings, lines, escalation routing |
| Team management | team_admin (team scope) | Same, team-scoped |
| Agent / ISA | agent, isa (own scope) | View + (per policy) edit own capture/greeting; cannot change brokerage-identity/guardrail settings or trigger a voice deploy |
| Support / external | transaction_coordinator, marketing_assistant, external_partner (bounded) | View / scoped; no Save of safety-critical settings; external_partner is read-only |
Voice deploys are never a UI action for any role — they go through the
voice-agent-engineer + founder gate (§9).
4. Expected outputs
4.1 — Working mode (autopilot/co-pilot) + guardrails surface
Should see:
- A Co-pilot ⇄ Autopilot switch with honest descriptions (Co-pilot = drafts,
human approves; Autopilot = answers/qualifies/escalates on her own). The mode
maps to
ai-guardrails.mdRULE 6 (sensitive topics never autopilot; outbound off in MVP). - A Guardrails summary (the chips) + Edit guardrails, exposing the configurable parts (tone, capture, hours, escalation) while showing the non-removable safety set (no steering / no value-legal-finance-tax advice / never guarantee values / always offers a human / identifies as AI).
Should NOT see:
- A control that lets the agent disable the AI disclosure, the fair-housing
refusal, the no-valuation rule, or the no-confidentiality rule (these are
enforced; not toggleable —
ai-guardrails.md§R5/§1/§2/§4). - An "Autopilot" that would answer a §R5 topic autonomously (it must block/escalate).
- ⚠️ Carried-forward: working-mode copy must not say Autopilot "books
showings on her own" as a confirmed booking — Aria captures a showing
request; the agent confirms (§6;
ai-front-desk.mddecision 4).
Success: the agent controls autonomy and sees the guardrails, but cannot weaken the safety floor.
4.2 — Premium voice line + Community language lines (the differentiator)
Should see:
- The Premium Voice Line (Cartesia, EN/ES/FR): DID, voice actor + preview,
hours, an editable greeting (with AI disclosure + recording disclosure
baked in per
ai-front-desk.md§V1 /ai-guardrails.md§4), capture fields, escalation rules, call-summary format, Test call, Transcripts →. - The Community Language Lines (Punjabi/Urdu/Hindi/Mandarin via Google) framed as a feature ("not a lesser line — how you win listings nobody else is reaching"), a shared Community DID that auto-detects language, per-language rows (voice actor + greeting + enable toggle), inherited rules with override, and Add a language (30+ via Google). Languages shown are the tenant's enabled set — never a hardcoded list (consistent with the Smart-List / inbox language rule).
- A Native-review indicator: non-English canned greetings/disclosures are
[NATIVE REVIEW REQUIRED] before they ship as deterministic copy
(
ai-guardrails.md§1/§4 — do not auto-translate a steering refusal or a consent line).
Should NOT see:
- A Community line framed as broken/inferior (design-blueprint UX rule: "coverage-first language lines", not "lower-quality").
- A hardcoded language set unrelated to what the tenant serves.
- An editable greeting that lets the agent strip the AI/recording disclosure.
Success: the agent configures multilingual lines as a selling point; disclosures are non-removable; non-English copy is flagged for native review.
4.3 — Chat: knowledge sources, rules, placement, capture, test panel
Should see:
- Knowledge sources (profile, listings, neighbourhood/buyer/seller guides,
FAQs, brokerage policies), each toggleable, with the honesty note "Aria only
speaks from these — won't invent facts" (maps to
ai-guardrails.mdRULE 3 + the facts-used receipt, §4.4). Brokerage policies are Required (TRESA/RECO identity). - Conversation rules & guardrails (tone, reply length, when to ask for contact, when unsure → offer a human) + the same non-removable guardrail chips.
- Website placement (bubble, inline "Ask about this home", listing-context awareness) + an embed code for bring-your-own sites.
- Lead-capture fields (Name + Phone/Email required; buying/selling, budget, area, timeline, financing, language preference toggleable) — "asked conversationally, never a wall of form fields".
- A sticky live Test panel — a sandbox that exercises the real RE chat path with listing context + language detection + shows captured fields, and states "test conversations aren't saved as leads."
Should NOT see:
- A knowledge toggle that lets Aria answer beyond her sources (no-hallucination).
- The test panel writing a real
local_business_leadsrow. - ⚠️ Minor flag: the mock's embed snippet shows
cdn.wiseairealtor.com/widget.jsand placement onteambeckett.ca— the real embed uses the existing chatbot embed infrastructure (the<script data-business-id="…">pattern inai-front-desk.md§C1), served from the production host. Treat the mock host as illustrative; do not introduce a new embed domain (do-not-reinvent).
Success: the agent configures Aria's chat knowledge + placement + capture and can test it live in a sandbox that never creates a real lead.
4.4 — Guardrails enforcement surface + "facts used" receipt
Should see (the enforcement this screen represents — ai-guardrails.md):
- The configurable guardrail set, with the enforced RE rules visible but
locked: no fair-housing steering (RULE 1), no regulated advice
(value/legal/finance/tax/investment/offer/representation — RULE 2, "never
guarantee values"), honesty/no-hallucination with the facts-used receipt
extended to chat AND voice (RULE 3 — every turn stating a listing/market
fact attaches the live rows it used; no receipt → no factual claim), and
identity/disclosure (AI disclosure + brokerage identity + recording consent
- no false confidentiality — RULE 4).
- Escalation rules surface (human request / transactional intent / pushed §R5 topic / steering-complaint / crisis / language-mismatch) routing to a language-matched human (RULE 5).
Should NOT see:
- A facts-used receipt that can be turned off (it is the honesty audit trail).
- The universal crisis/safety layer presented as gateable — it is NEVER
gated (
ai-front-desk.md§V7;ai-guardrails.mdRULE 5).
Success: the screen makes the RE guardrail contract visible and testable; the safety floor and the facts receipt are enforced, not optional.
5. Empty / loading / error states
| State | Expected output |
|---|---|
| Not provisioned | Honest "Connect your voice line / enable chat to configure Aria" + a setup CTA — not a fake "live" status (mirrors ai-front-desk.md §9). |
| Incomplete setup profile | Inline warnings (e.g. "Add an escalation SMS number", "Brokerage identity required to publish") — never silently OK. |
| Loading | Section skeletons, not a spinner (anti-pattern #7). |
| Test panel error | Inline "Test unavailable — retry"; config still editable. |
| Save error | Non-destructive inline error; unsaved changes preserved; Discard/Save honest. |
6. Carried-forward constraints (consistent across the batch)
- Aria does NOT book/schedule — working-mode + greeting copy frame showings
as captured requests the agent confirms, never AI-confirmed bookings
(
ai-front-desk.mddecision 4; scheduler "named, not designed"). - SMS is consent-gated + OFF by default (no unattended sender) until founder
confirms SMS-in-scope; crisis/safety is NEVER gated (
ai-guardrails.mdRULE 5). - Role enum (rbac.ts — implemented source of truth): agent | team_admin | transaction_coordinator | broker_admin | brokerage_owner | marketing_assistant | isa | external_partner (scopes own|team|brokerage).
- No realtor pricing — gate by role/module.
- Honest metrics only; "Not measured" when unknown. Language never hardcoded.
⚠️ NEW INCONSISTENCY — flagged, not silently resolved. The mock's Voice escalation rules say "Caller asks for a person → live-transfer to Sheri, then Terry."
ai-guardrails.mdRULE 5/6 permits a warm live transfer for the RE voice vertical (in-hours, available agent), but the local-businessai-front-desk.mddecision 7 forbids live transfer (capture + notify only). These differ.ai-guardrails.mdis the RE-specific canonical doc and allows transfer — but the build must confirm with the founder which governs the RE vertical before shipping a live-transfer escalation, and (if allowed) it is a voice-agent-engineer change, deploy-gated.
7. Accessibility (AODA → WCAG 2.1 AA)
- Tabs (Voice/Chat): proper tablist semantics; keyboard-switchable.
- Toggles/switches (line enable, knowledge source, capture field, mode) are labelled with state; not color-only.
- Voice preview / Test call / Test panel controls are keyboard-operable with visible focus; audio preview has a text label.
- Guardrail chips convey meaning by text; locked/enforced ones are marked as such (not just visually).
- Contrast ≥4.5:1; gold accent only; teal actions/links meet AA; reduced-motion honored.
8. Acceptance checklist (QA runs on the deployed URL)
Behavioural verification on wiseaiagency.com (real host) against the demo
tenant (…0c01). Voice-path behaviour is verified by a real test call + the
ai-guardrails.md regression suite — NOT a green build. Any voice change requires
voice-agent-engineer review.
// Mode + guardrails (enforced, not cosmetic)
test.fixme('Co-pilot/Autopilot switch maps to ai-guardrails RULE 6; sensitive topics never autopilot', () => {});
test.fixme('agent CANNOT disable AI disclosure, fair-housing refusal, no-valuation, or no-confidentiality', () => {});
test.fixme('working-mode copy frames showings as captured REQUESTS, not AI-confirmed bookings', () => {});
// Voice lines
test.fixme('Premium + Community lines configure; Community languages = tenant enabled set, never hardcoded', () => {});
test.fixme('editable greeting keeps AI + recording disclosure baked in; non-EN canned copy flagged [NATIVE REVIEW REQUIRED]', () => {});
test.fixme('escalation "live transfer" path is confirmed against ai-front-desk vs ai-guardrails and deploy-gated', () => {});
// Chat + test panel + receipt
test.fixme('knowledge-source toggles bound Aria to her sources (no hallucination); brokerage policies required', () => {});
test.fixme('the live Test panel is a sandbox — it does NOT write a real local_business_leads row', () => {});
test.fixme('facts-used receipt is enforced on chat AND voice; cannot be turned off; no receipt → no factual claim', () => {});
// Safety floor
test.fixme('the universal crisis/safety layer is NOT presented as gateable and stays on every line', () => {});
// States + a11y
test.fixme('not-provisioned/incomplete/loading/error states render per §5; no fake "live"', () => {});
test.fixme('tabs/toggles/preview are keyboard-operable + labelled; enforced guardrails marked; reduced-motion honored', () => {});
9. Guardrails for agents building against this spec
- Rule #17 not satisfied — do not build until founder approval.
- Voice = LIFE-SAFETY, deploy-gated — any change to
voice-agent-livekit/**, SIP, prompts, ormoderation.pygoes through thevoice-agent-engineeragent + independent QA voice review + founder go. This config screen writes config; it must not become a backdoor to deploy or to weaken the safety floor. - Build ON ai-front-desk.md (front-desk behaviour) + surface ai-guardrails.md (the RE guardrail contract) — do not duplicate or fork them; if the screen needs new behaviour, update those specs first.
- Guardrails are enforced — frame + classifier + belt + facts-used receipt
(
ai-guardrails.md); the agent tunes configurable settings only. - Aria books nothing; SMS off-by-default + consent-gated; crisis never gated; language never hardcoded; honest metrics; verify on the real host; evidence-or-nothing.
- If code diverges, update the spec first (founder approval), then the code.
End of spec. STATUS: DRAFT — NOT APPROVED. Open items for Stage-2: (1) whether the RE voice vertical permits warm live transfer (reconcile ai-front-desk decision 7 vs ai-guardrails RULE 5/6); (2) which guardrail settings are agent-editable vs locked; (3) the embed host/domain (use the existing chatbot embed, not a new domain); (4) native-review sign-off gating for each non-English line before it goes live.