Skip to content

Commit 025fbf8

Browse files
mamigotmamigot
committed
docs: replace insurance-specific metadata examples with SaaS examples
1 parent da8596d commit 025fbf8

1 file changed

Lines changed: 57 additions & 59 deletions

File tree

‎developer/agents/chat-metadata.md‎

Lines changed: 57 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Pass arbitrary context alongside chat messages to any AI Mentor so it can tailor
66

77
## Overview
88

9-
The chat metadata feature lets you pass arbitrary context alongside chat messages to any IBL Mentor. This context (e.g., product group, licensing level, state) is automatically injected into the mentor's awareness, allowing it to tailor responses to the user's exact situation without the user having to explain their context manually.
9+
The chat metadata feature lets you pass arbitrary context alongside chat messages to any IBL Mentor. This context (e.g., product name, plan tier, user role) is automatically injected into the mentor's awareness, allowing it to tailor responses to the user's exact situation without the user having to explain their context manually.
1010

1111
**Key points:**
1212
- The `metadata` field is a **free-form JSON object** — any key-value pairs are accepted, no enforced schema
@@ -21,7 +21,7 @@ The chat metadata feature lets you pass arbitrary context alongside chat message
2121
```
2222
Frontend Application
2323
|
24-
| Sends: { prompt, metadata: { productGroup, stateCode, ... } }
24+
| Sends: { prompt, metadata: { product, planTier, ... } }
2525
|
2626
v
2727
IBL Mentor Backend
@@ -32,16 +32,17 @@ IBL Mentor Backend
3232
v
3333
Mentor (LLM) receives the user's message with context appended:
3434
35-
"What are the licensing requirements?"
35+
"How do I set up SSO?"
3636
3737
<CONTEXT METADATA> Here is additional context metadata for this conversation:
38-
productGroup: LICENSING
39-
productLevel: LH
40-
stateCode: CA
38+
product: Analytics
39+
planTier: Enterprise
40+
userRole: Admin
41+
region: EU
4142
</END CONTEXT METADATA>
4243
```
4344

44-
The mentor sees this context and responds accordingly — e.g., answering about Health insurance licensing in California rather than generic insurance topics.
45+
The mentor sees this context and responds accordingly — e.g., answering with Enterprise-tier SSO setup steps for the Analytics product with EU data-residency considerations, rather than generic help.
4546

4647
---
4748

@@ -57,12 +58,10 @@ ws.send(JSON.stringify({
5758
prompt: userMessage,
5859
page_content: pageContent, // optional
5960
metadata: { // optional
60-
productGroup: 'LICENSING',
61-
productLevel: 'LH',
62-
productLevelDisplay: 'Life & Health',
63-
productFamily: 'INSURANCE',
64-
stateCode: 'CA',
65-
name: 'Health'
61+
product: 'Analytics',
62+
planTier: 'Enterprise',
63+
userRole: 'Admin',
64+
region: 'EU'
6665
},
6766
flow: { name: mentorId, tenant: tenantKey }
6867
}));
@@ -78,10 +77,12 @@ Content-Type: application/json
7877
7978
{
8079
"session_id": "uuid",
81-
"prompt": "What are the requirements?",
80+
"prompt": "How do I set up SSO?",
8281
"metadata": {
83-
"productGroup": "LICENSING",
84-
"stateCode": "CA"
82+
"product": "Analytics",
83+
"planTier": "Enterprise",
84+
"userRole": "Admin",
85+
"region": "EU"
8586
},
8687
"flow": { "name": "mentor-slug", "tenant": "tenant-key" }
8788
}
@@ -96,9 +97,10 @@ iframe.contentWindow.postMessage({
9697
type: 'context',
9798
page_content: '<html content of current page>',
9899
metadata: {
99-
productGroup: 'LICENSING',
100-
productLevel: 'LH',
101-
stateCode: 'CA'
100+
product: 'Analytics',
101+
planTier: 'Enterprise',
102+
userRole: 'Admin',
103+
region: 'EU'
102104
}
103105
}, '*');
104106
```
@@ -116,10 +118,10 @@ Metadata is **cached per session** and only needs to be sent once. Here's how it
116118

117119
| Message | `metadata` sent | What the mentor sees |
118120
|---------|-----------------|----------------------|
119-
| #1 | `{ productGroup: "LICENSING", stateCode: "CA" }` | User's prompt + LICENSING / CA context |
120-
| #2 | _(not sent)_ | User's prompt + LICENSING / CA context (reused from #1) |
121-
| #3 | `{ productGroup: "CE", stateCode: "NY" }` | User's prompt + CE / NY context (replaced) |
122-
| #4 | _(not sent)_ | User's prompt + CE / NY context (reused from #3) |
121+
| #1 | `{ product: "Analytics", planTier: "Enterprise" }` | User's prompt + Analytics / Enterprise context |
122+
| #2 | _(not sent)_ | User's prompt + Analytics / Enterprise context (reused from #1) |
123+
| #3 | `{ product: "Payments", planTier: "Starter" }` | User's prompt + Payments / Starter context (replaced) |
124+
| #4 | _(not sent)_ | User's prompt + Payments / Starter context (reused from #3) |
123125

124126
**Rules:**
125127
- **Send once** — metadata persists automatically for the rest of the session
@@ -133,16 +135,13 @@ Metadata is **cached per session** and only needs to be sent once. Here's how it
133135

134136
The metadata field accepts **any** JSON object. There is no enforced schema — use whatever keys make sense for your application.
135137

136-
**Example: Insurance education platform**
138+
**Example: SaaS customer support**
137139
```json
138140
{
139-
"productGroup": "LICENSING",
140-
"productLevel": "LH",
141-
"productLevelDisplay": "Life & Health",
142-
"productFamily": "INSURANCE",
143-
"productFamilyDisplay": null,
144-
"stateCode": "CA",
145-
"name": "Health"
141+
"product": "Analytics",
142+
"planTier": "Enterprise",
143+
"userRole": "Admin",
144+
"region": "EU"
146145
}
147146
```
148147

@@ -156,13 +155,13 @@ The metadata field accepts **any** JSON object. There is no enforced schema —
156155
}
157156
```
158157

159-
**Example: K-12 education**
158+
**Example: E-commerce product advisor**
160159
```json
161160
{
162-
"gradeLevel": 10,
163-
"subject": "Biology",
164-
"unit": "Cell Division",
165-
"standard": "NGSS HS-LS1-4"
161+
"category": "Laptops",
162+
"brand": "ThinkPad",
163+
"priceRange": "1000-2000",
164+
"customerSegment": "Business"
166165
}
167166
```
168167

@@ -174,10 +173,10 @@ The metadata is appended to the user's prompt as context. The mentor's **system
174173

175174
**Example system prompt excerpt:**
176175
```
177-
You are a licensing exam preparation assistant. When the user's context
178-
includes a stateCode, always tailor your answers to that state's specific
179-
licensing requirements. When productLevel is provided, focus your answers
180-
on that specific license type.
176+
You are a product support assistant. When the user's context includes a
177+
product name, tailor your answers to that specific product's features and
178+
documentation. When planTier is provided, only suggest features available
179+
on that plan. When region is EU, highlight GDPR and data-residency details.
181180
```
182181

183182
---
@@ -197,9 +196,10 @@ Response:
197196
{
198197
"summary": {
199198
"client_context": {
200-
"productGroup": "LICENSING",
201-
"stateCode": "CA",
202-
"productLevel": "LH"
199+
"product": "Analytics",
200+
"planTier": "Enterprise",
201+
"userRole": "Admin",
202+
"region": "EU"
203203
}
204204
}
205205
}
@@ -233,43 +233,41 @@ The full `Session.metadata` object is included, which contains the `client_conte
233233

234234
## Example: Single Mentor Serving Multiple Contexts
235235

236-
**Scenario:** One mentor handles all insurance licensing questions, but users are on different product/state pages.
236+
**Scenario:** One support mentor handles questions across your entire SaaS platform, but users are on different product pages with different plans.
237237

238-
**Page: Health Insurance Licensing in California**
238+
**Page: Analytics product — Enterprise plan**
239239

240240
The frontend sends:
241241
```json
242242
{
243243
"metadata": {
244-
"productGroup": "LICENSING",
245-
"productLevel": "LH",
246-
"productLevelDisplay": "Life & Health",
247-
"stateCode": "CA",
248-
"name": "Health"
244+
"product": "Analytics",
245+
"planTier": "Enterprise",
246+
"userRole": "Admin",
247+
"region": "EU"
249248
}
250249
}
251250
```
252251

253-
**User asks:** "What topics are on the exam?"
252+
**User asks:** "How do I set up SSO?"
254253

255-
**Mentor responds** with California-specific Life & Health exam topics — not generic insurance information.
254+
**Mentor responds** with Enterprise-tier SSO setup steps for the Analytics product, noting EU data-residency requirements — not generic help docs.
256255

257-
**Page: Property & Casualty in New York**
256+
**Page: Payments product — Starter plan**
258257

259258
The frontend sends:
260259
```json
261260
{
262261
"metadata": {
263-
"productGroup": "LICENSING",
264-
"productLevel": "PC",
265-
"productLevelDisplay": "Property & Casualty",
266-
"stateCode": "NY",
267-
"name": "Property & Casualty"
262+
"product": "Payments",
263+
"planTier": "Starter",
264+
"userRole": "Developer",
265+
"region": "US"
268266
}
269267
}
270268
```
271269

272-
**Same mentor** now responds with New York-specific P&C content.
270+
**Same mentor** now responds with Starter-plan Payments integration guides, and notes that SSO requires upgrading to the Pro plan.
273271

274272
If the mentor's responses don't align with the expected behavior, adjust the **system prompt** to instruct the mentor on how to use the metadata fields.
275273

0 commit comments

Comments
 (0)