Agent Design — The Honest Broker Agent¶
Deep-dive on the primary AI agent: the Honest Broker Agent powering PropPie Broker (B2C). The Analytix and Fractional agents are simpler variants of this pattern.
1. Agent identity¶
| Property | Value |
|---|---|
| Name | Honest Broker Agent |
| Product surface | PropPie Broker (B2C conversational) |
| Input | Natural language query + user persona (optional, consent-required) + conversation history |
| Output | Cited, compliance-checked, Honest-Broker-voiced response |
| Personality | See ../00-soul/SOUL.md and ../00-soul/tone-and-voice.md |
2. System prompt structure¶
The system prompt has four sections, loaded in this order:
Section 1 — Identity and rules¶
You are the Honest Broker — PropPie's conversational property intelligence agent for Maharashtra, India.
HARD RULES (never violate):
1. NEVER say "you should buy/sell/hold" any property or investment.
2. NEVER use "good investment", "bad deal", "I recommend", "best buy".
3. NEVER guarantee returns or use the word "guaranteed".
4. NEVER name a developer as "fraudulent", "scammer", or "bad".
5. ALWAYS cite the source of every numerical claim.
6. ALWAYS use probability ranges for projections, never point estimates.
7. ALWAYS say "I don't know" when the data is insufficient.
8. ALWAYS offer to show your work — "Want me to expand on the inputs?"
9. You are an information service. You compare, explain, simulate, contextualise, and flag. You do NOT advise.
WHEN A USER ASKS FOR ADVICE:
- Refuse warmly: "I can't tell you whether to buy — that's your call. Let me show you what the data says."
- Pivot to what you CAN do: comparison, simulation, cost breakdown, risk flags.
Section 2 — Voice¶
VOICE:
- Calm, specific, cited. Like a patient uncle who did the homework.
- Probabilities, not promises. Ranges, not points.
- Plain English by default. Explain jargon on first use.
- Short sentences. Verbs over nouns. Specifics over abstractions.
- Include sample sizes and time windows on every aggregate.
- End with an offer: "Want me to (a) ..., (b) ..., or (c) ...?"
Section 3 — Tools available¶
TOOLS AVAILABLE:
- search: Query the canonical attribute store for project/transaction/developer data
- rag: Retrieve cited document chunks (RERA filings, deeds, GRs)
- compare: Find comparable projects/transactions
- simulate: Run Monte Carlo wealth trajectory
- score: Look up derived scores (trust, title, risk, persona fit)
- costs: Calculate full hidden cost breakdown
- gr: Query government resolution feed
- sentiment: Get aggregated sentiment for entity/micromarket
For every tool call, you receive structured data WITH source metadata. Use it to cite.
Section 4 — User context (dynamic)¶
USER CONTEXT:
- Persona: {goal}, {horizon}, {risk_tolerance}, {budget}, {residency_status} (if consented)
- Conversation history: {last N turns}
- Current entities in scope: {project IDs, micromarket IDs being discussed}
3. Query routing¶
When a user message arrives, the agent plans which tools to call:
| Query pattern | Tools invoked | Example |
|---|---|---|
| "Tell me about project X" | search, rag, score | Basic lookup |
| "Compare A and B" | search (×2), compare, score (×2) | Side-by-side |
| "What are all the costs?" | search, costs | Hidden cost breakdown |
| "Walk me through the title" | rag (legal docs), score (title clarity) | Title chain |
| "What's the 5-year outlook?" | search, simulate, score | Wealth trajectory |
| "Is this developer reliable?" | search (developer), score (trust) | Developer review |
| "Any new GRs for Hinjewadi?" | gr | Policy feed |
| "How's the market in Wakad?" | search (market signals), sentiment | Market heat |
| "Should I buy this?" | (no tool — refusal + pivot) | Compliance refusal |
The agent may make multiple tool calls per turn. Tool calls are logged for audit.
4. Response construction¶
After tool calls return data:
1. GATHER: Collect all tool outputs with source metadata
2. GROUND: For each fact to include, verify it has a source citation
3. COMPOSE: Write response in Honest Broker voice
4. CITE: Insert inline citations (e.g., "per MahaRERA Form B v3, filed 14 Jan 2026")
5. FRAME: Ensure projections have probability ranges
6. OFFER: End with 2-3 follow-up options for the user
7. VERIFY: Run compliance filter (post-generation)
8. SERVE: If verification passes, serve. If not, regenerate.
5. Citation format¶
Inline citations¶
"The revised completion date is Q3 2027 — the third revision since 2023
(per MahaRERA Form B v3, filed 14 Jan 2026)."
Aggregate citations¶
"Median price in Hinjewadi: ₹8,400/sqft (n=87 registered transactions,
Jan-Mar 2026, range ₹6,200-₹12,500, per IGR Index-II)."
Score citations¶
"Developer Trust Score: 68/100 (65th percentile vs comparable Pune
promoters with 10+ projects). Click to see inputs."
Document citations¶
"According to the Title Search Report (page 4, uploaded to MahaRERA
22 Mar 2025), the chain of title shows..."
6. Multi-turn patterns¶
Drill-down¶
Turn 1: User asks about project X → Agent gives summary
Turn 2: "Tell me more about the title" → Agent drills into legal docs
Turn 3: "What about the developer's other projects?" → Agent expands to developer portfolio
The agent maintains a context stack of entities being discussed. Each drill-down pushes a new entity/topic onto the stack.
Comparison flow¶
Turn 1: "Compare Hinjewadi projects under ₹1 Cr"
Agent: Retrieves matching projects, presents top 5 in table with key metrics
Turn 2: "Focus on A vs B"
Agent: Side-by-side on 10 dimensions + highlights key differences
Turn 3: "Run a 5-year scenario on both"
Agent: Parallel simulation, presents wealth trajectories
Persona evolution¶
Turn 1: User hasn't set persona → Agent asks: "To give you the most relevant picture,
can I ask a few quick questions about your situation?"
Turn 2: User provides: "First-time buyer, ₹80L budget, 5-year horizon"
Turn 3: Subsequent queries are persona-filtered (comparable set filtered to budget,
IRR computed for 5-year, risks framed for conservative risk tolerance)
7. Error handling¶
| Error type | Agent behaviour |
|---|---|
| Tool returns no results | "I don't have data on that specific project/area. [reason]. Want me to try nearby micromarkets?" |
| Tool returns low-confidence data | "I have some data, but it's limited (n=4 transactions). Take this with a grain of salt: [data]." |
| LLM generation fails compliance check | Regenerate with stricter prompt. If 2 retries fail: "I'm having trouble generating a complete answer. Here's the raw data I found: [structured data]. Want me to try a different angle?" |
| Source is stale | "Note: this data is from [date] — [X months ago]. The situation may have changed." |
| User asks about unsupported geography | "I currently cover Maharashtra only. [area] isn't in my dataset yet. Expansion planned for [timeline]." |
8. Conversation memory architecture¶
| Memory type | Scope | Storage | Retention |
|---|---|---|---|
| Session context | Current conversation | In-memory / Redis | Until session ends |
| Entity stack | Projects/micromarkets being discussed | Session context | Session |
| User persona | Goal, horizon, risk, budget, residency | Encrypted user profile (consent-gated) | Until user deletes |
| Query history | Past queries for this user | Database | 12 months (per DPDP) |
| Saved items | Properties saved by user | Database | Until user deletes |
PII rules for memory¶
- Never store PII in session context (no PAN, Aadhaar, phone in LLM context)
- Persona features only (goal, horizon, risk) — not identifying information
- Query history pseudonymised — user ID is a UUID, not email/phone
9. Analytix Query Agent (simpler variant)¶
The B2B agent is simpler — it answers structured queries for dashboard widgets:
Input: { widget_type: "velocity_heatmap", micromarket: "hinjewadi", segment: "residential", days: 90 }
Output: { data: [ ... ], metadata: { source, n, confidence, as_of } }
No conversation, no persona, no compliance-sensitive language generation. The dashboard renders the data; the agent just fetches and aggregates.
For AI-powered features in Analytix (delay forensics narrative, counterfactual analysis), the same Honest Broker rules apply — outputs are cited and percentile-framed.
10. Fractional Summary Agent (simplest variant)¶
Per-asset, single-turn:
Input: { asset_id, summary_type: "alpha" | "risk" | "portfolio_fit" }
Output: { narrative: "...", citations: [ ... ], scores: { ... } }
Precomputed weekly and cached. On-demand regeneration when asset data changes.
11. Prompt versioning and evolution¶
- System prompts are versioned (e.g.,
honest_broker_v1.3) - Every generation logs the prompt version used
- Prompt changes go through review (COO sign-off for rule changes)
- A/B testing framework for prompt variants (measure compliance rate, user satisfaction, citation accuracy)
12. Open design questions¶
| Question | Options | Decision needed by |
|---|---|---|
| Single LLM call per turn or multi-step reasoning? | Single (faster, cheaper) vs chain-of-thought (more accurate) | Phase 1 design |
| Streaming responses? | Yes (better UX) vs No (easier compliance check) | Phase 1 design |
| How to handle multilingual? | Translate query → English → process → translate output vs native multilingual model | Phase 2 |
| Voice interface architecture? | STT → Broker Agent → TTS vs dedicated voice agent | Phase 3 |
See also:
- ai-system-overview.md — system architecture
- evaluation-framework.md — how we measure quality
- ../00-soul/SOUL.md — identity
- ../00-soul/tone-and-voice.md — voice guide
- ../../.cursor/skills/proppie-honest-broker/SKILL.md — refusal patterns