Designing Grounded Experiences
Practical UX guidance for building on AI Query's real response fields — chart, follow-ups, streaming and cost.
AI Query returns more than an answer string — a computed chart, follow-up questions, cost and a conversation id all come back on every call. The best integrations design around those fields directly instead of treating the response as one opaque string.
#Design principles
- Ground the experience, not just the answer. Every reading is consistent with a real computed chart — build the UI so users can see that, not just read prose. See Grounding & Citations.
- Treat a session as a thread, not one-off calls. Multi-turn context is a first-class capability — design the conversation, not just the request.
- Be transparent, not opaque, about cost if you pass usage costs on to your own users.
- Present readings as guidance — spiritual and entertainment context, not a substitute for professional advice.
#UX patterns that work
| Pattern | Why |
|---|---|
Show birthChart alongside the reading | Lets users (and your own QA) see the chart the answer is grounded in — real transparency, not a black box. |
Surface followUps as tappable next questions | They are chart-relevant, not generic — a cheap way to deepen engagement with zero extra latency. |
| Stream the answer instead of a spinner | Tokens arrive as they are produced, so perceived speed is much better than waiting for the full response. See Streaming. |
| Respond in the user's language | 14 languages are supported end to end — pass language, or let the engine auto-detect it from the question. |
Keep one stable conversationId per user thread | Coherent, memory-aware follow-ups instead of the user re-explaining context every turn. See Multi-turn & Conversations. |
#Pitfalls to avoid
- Don't drop or vary
birthDetailsbetween turns of the same conversation — small changes break both consistency and cache hits. - Don't hide the cost if you charge your own users for it —
metadata.cost.costUsdis exact and returned on every call; surface it honestly. - Don't discard
followUps— they cost nothing extra and are already chart-relevant. - Don't present a reading as medical, legal or financial advice. Frame it as guidance — see Policies for the acceptable-use framing.