building-chat-widgets

Name: building-chat-widgets
Author: mjunaidca

22installs11forks

How to install building-chat-widgets?

mjunaidca/mjs-agent-skills/building-chat-widgets

$npx -y skills add mjunaidca/mjs-agent-skills --skill building-chat-widgets

Installs into the current project.

Summary

Build interactive AI chat widgets with buttons, forms, and bidirectional actions. Use when creating agentic UIs with clickable widgets, entity tagging (@mentions), composer tools, or server-handled widget actions. Covers full widget lifecycle. NOT when building simple text-only c

Files · 1

View on GitHub

SKILL.md

1	# Building Chat Widgets
2
3	Create interactive widgets for AI chat with actions and entity tagging.
4
5	## Quick Start
6
7	```typescript
8	const chatkit = useChatKit({
9	api: { url: API_URL, domainKey: DOMAIN_KEY },
10
11	widgets: {
12	onAction: async (action, widgetItem) => {
13	if (action.type === "view_details") {
14	navigate(`/details/${action.payload.id}`);
15	}
16	},
17	},
18	});
19	```
20
21	---
22
23	## Action Handler Types
24
25	\| Handler \| Defined In \| Processed By \| Use Case \|
26	\|---------\|------------\|--------------\|----------\|
27	\| `"client"` \| Widget template \| Frontend `onAction` \| Navigation, local state \|
28	\| `"server"` \| Widget template \| Backend `action()` \| Data mutation, widget replacement \|
29
30	---
31
32	## Widget Lifecycle
33
34	```
35	1. Agent tool generates widget → yield WidgetItem
36	2. Widget renders in chat with action buttons
37	3. User clicks action → action dispatched
38	4. Handler processes action:
39	- client: onAction callback in frontend
40	- server: action() method in ChatKitServer
41	5. Optional: Widget replaced with updated state
42	```
43
44	---
45
46	## Core Patterns
47
48	### 1. Widget Templates
49
50	Define reusable widget layouts with dynamic data:
51
52	```json
53	{
54	"type": "ListView",
55	"children": [
56	{
57	"type": "ListViewItem",
58	"key": "item-1",
59	"onClickAction": {
60	"type": "item.select",
61	"handler": "client",
62	"payload": { "itemId": "item-1" }
63	},
64	"children": [
65	{
66	"type": "Row",
67	"gap": 3,
68	"children": [
69	{ "type": "Icon", "name": "check", "color": "success" },
70	{ "type": "Text", "value": "Item title", "weight": "semibold" }
71	]
72	}
73	]
74	}
75	]
76	}
77	```
78
79	### 2. Client-Handled Actions
80
81	Actions that update local state, navigate, or send follow-up messages:
82
83	Widget Definition:
84
85	```json
86	{
87	"type": "Button",
88	"label": "View Article",
89	"onClickAction": {
90	"type": "open_article",
91	"handler": "client",
92	"payload": { "id": "article-123" }
93	}
94	}
95	```
96
97	Frontend Handler:
98
99	```typescript
100	const chatkit = useChatKit({
101	api: { url: API_URL, domainKey: DOMAIN_KEY },
102
103	widgets: {
104	onAction: async (action, widgetItem) => {
105	switch (action.type) {
106	case "open_article":
107	navigate(`/article/${action.payload?.id}`);
108	break;
109
110	case "more_suggestions":
111	await chatkit.sendUserMessage({ text: "More suggestions, please" });
112	break;
113
114	case "select_option":
115	setSelectedOption(action.payload?.optionId);
116	break;
117	}
118	},
119	},
120	});
121	```
122
123	### 3. Server-Handled Actions
124
125	Actions that mutate data, update widgets, or require backend processing:
126
127	Widget Definition:
128
129	```json
130	{
131	"type": "ListViewItem",
132	"onClickAction": {
133	"type": "line.select",
134	"handler": "server",
135	"payload": { "id": "blue-line" }
136	}
137	}
138	```
139
140	Backend Handler:
141
142	```python
143	from chatkit.types import (
144	Action, WidgetItem, ThreadItemReplacedEvent,
145	ThreadItemDoneEvent, AssistantMessageItem, ClientEffectEvent,
146	)
147
148	class MyServer(ChatKitServer[dict]):
149
150	async def action(
151	self,
152	thread: ThreadMetadata,
153	action: Action[str, Any],
154	sender: WidgetItem \| None,
155	context: RequestContext, # Note: Already RequestContext, not dict
156	) -> AsyncIterator[ThreadStreamEvent]:
157
158	if action.type == "line.select":
159	line_id = action.payload["id"] # Use .payload, not .arguments
160
161	# 1. Update widget with selection
162	updated_widget = build_selector_widget(selected=line_id)
163	yield ThreadItemReplacedEvent(
164	item=sender.model_copy(update={"widget": updated_widget})
165	)
166
167	# 2. Stream assistant message
168	yield ThreadItemDoneEvent(
169	item=AssistantMessageItem(
170	id=self.store.generate_item_id("msg", thread, context),
171	thread_id=thread.id,
172	created_at=datetime.now(),
173	content=[{"text": f"Selected {line_id}"}],
174	)
175	)
176
177	# 3. Trigger client effect
178	yield ClientEffectEvent(
179	name="selection_changed",
180	data={"lineId": line_id},
181	)
182	```
183
184	### 4. Entity Tagging (@mentions)
185
186	Allow users to @mention entities in messages:
187
188	```typescript
189	const chatkit = useChatKit({
190	api: { url: API_URL, domainKey: DOMAIN_KEY },
191
192	entities: {
193	onTagSearch: async (query: string): Promise<Entity[]> => {
194	const results = await fetch(`/api/search?q=${query}`).then(r => r.json());
195
196	return results.map((item) => ({
197	id: item.id,
198	tit

People who liked this also viewed

6 picks

Type

building-chat-widgets

22installs11forks

View on GitHub

How to install building-chat-widgets?

mjunaidca/mjs-agent-skills/building-chat-widgets

$npx -y skills add mjunaidca/mjs-agent-skills --skill building-chat-widgets

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Building Chat Widgets
2
3	Create interactive widgets for AI chat with actions and entity tagging.
4
5	## Quick Start
6
7	```typescript
8	const chatkit = useChatKit({
9	api: { url: API_URL, domainKey: DOMAIN_KEY },
10
11	widgets: {
12	onAction: async (action, widgetItem) => {
13	if (action.type === "view_details") {
14	navigate(`/details/${action.payload.id}`);
15	}
16	},
17	},
18	});
19	```
20
21	---
22
23	## Action Handler Types
24
25	\| Handler \| Defined In \| Processed By \| Use Case \|
26	\|---------\|------------\|--------------\|----------\|
27	\| `"client"` \| Widget template \| Frontend `onAction` \| Navigation, local state \|
28	\| `"server"` \| Widget template \| Backend `action()` \| Data mutation, widget replacement \|
29
30	---
31
32	## Widget Lifecycle
33
34	```
35	1. Agent tool generates widget → yield WidgetItem
36	2. Widget renders in chat with action buttons
37	3. User clicks action → action dispatched
38	4. Handler processes action:
39	- client: onAction callback in frontend
40	- server: action() method in ChatKitServer
41	5. Optional: Widget replaced with updated state
42	```
43
44	---
45
46	## Core Patterns
47
48	### 1. Widget Templates
49
50	Define reusable widget layouts with dynamic data:
51
52	```json
53	{
54	"type": "ListView",
55	"children": [
56	{
57	"type": "ListViewItem",
58	"key": "item-1",
59	"onClickAction": {
60	"type": "item.select",
61	"handler": "client",
62	"payload": { "itemId": "item-1" }
63	},
64	"children": [
65	{
66	"type": "Row",
67	"gap": 3,
68	"children": [
69	{ "type": "Icon", "name": "check", "color": "success" },
70	{ "type": "Text", "value": "Item title", "weight": "semibold" }
71	]
72	}
73	]
74	}
75	]
76	}
77	```
78
79	### 2. Client-Handled Actions
80
81	Actions that update local state, navigate, or send follow-up messages:
82
83	Widget Definition:
84
85	```json
86	{
87	"type": "Button",
88	"label": "View Article",
89	"onClickAction": {
90	"type": "open_article",
91	"handler": "client",
92	"payload": { "id": "article-123" }
93	}
94	}
95	```
96
97	Frontend Handler:
98
99	```typescript
100	const chatkit = useChatKit({
101	api: { url: API_URL, domainKey: DOMAIN_KEY },
102
103	widgets: {
104	onAction: async (action, widgetItem) => {
105	switch (action.type) {
106	case "open_article":
107	navigate(`/article/${action.payload?.id}`);
108	break;
109
110	case "more_suggestions":
111	await chatkit.sendUserMessage({ text: "More suggestions, please" });
112	break;
113
114	case "select_option":
115	setSelectedOption(action.payload?.optionId);
116	break;
117	}
118	},
119	},
120	});
121	```
122
123	### 3. Server-Handled Actions
124
125	Actions that mutate data, update widgets, or require backend processing:
126
127	Widget Definition:
128
129	```json
130	{
131	"type": "ListViewItem",
132	"onClickAction": {
133	"type": "line.select",
134	"handler": "server",
135	"payload": { "id": "blue-line" }
136	}
137	}
138	```
139
140	Backend Handler:
141
142	```python
143	from chatkit.types import (
144	Action, WidgetItem, ThreadItemReplacedEvent,
145	ThreadItemDoneEvent, AssistantMessageItem, ClientEffectEvent,
146	)
147
148	class MyServer(ChatKitServer[dict]):
149
150	async def action(
151	self,
152	thread: ThreadMetadata,
153	action: Action[str, Any],
154	sender: WidgetItem \| None,
155	context: RequestContext, # Note: Already RequestContext, not dict
156	) -> AsyncIterator[ThreadStreamEvent]:
157
158	if action.type == "line.select":
159	line_id = action.payload["id"] # Use .payload, not .arguments
160
161	# 1. Update widget with selection
162	updated_widget = build_selector_widget(selected=line_id)
163	yield ThreadItemReplacedEvent(
164	item=sender.model_copy(update={"widget": updated_widget})
165	)
166
167	# 2. Stream assistant message
168	yield ThreadItemDoneEvent(
169	item=AssistantMessageItem(
170	id=self.store.generate_item_id("msg", thread, context),
171	thread_id=thread.id,
172	created_at=datetime.now(),
173	content=[{"text": f"Selected {line_id}"}],
174	)
175	)
176
177	# 3. Trigger client effect
178	yield ClientEffectEvent(
179	name="selection_changed",
180	data={"lineId": line_id},
181	)
182	```
183
184	### 4. Entity Tagging (@mentions)
185
186	Allow users to @mention entities in messages:
187
188	```typescript
189	const chatkit = useChatKit({
190	api: { url: API_URL, domainKey: DOMAIN_KEY },
191
192	entities: {
193	onTagSearch: async (query: string): Promise<Entity[]> => {
194	const results = await fetch(`/api/search?q=${query}`).then(r => r.json());
195
196	return results.map((item) => ({
197	id: item.id,
198	tit

People who liked this also viewed

6 picks

Type