chatkit-actions

Name: chatkit-actions
Author: mjunaidca

1installs11forks

How to install chatkit-actions?

mjunaidca/mjs-agent-skills/chatkit-actions

$npx -y skills add mjunaidca/mjs-agent-skills --skill chatkit-actions

Installs into the current project.

Summary

Implements interactive widget actions and bidirectional communication patterns for ChatKit. This skill should be used when building AI-driven interactive UIs with buttons, forms, entity tagging (@mentions), composer tools, and server-handled widget actions. Covers the full widget

Files · 1

View on GitHub

SKILL.md

1	# ChatKit Actions Skill
2
3	## Overview
4
5	This skill unlocks the full power of ChatKit's agentic UI capabilities - where AI can render interactive widgets, users can click buttons that trigger both client and server actions, and the conversation becomes a two-way interactive experience.
6
7	## Core Concepts
8
9	### Action Handler Types
10
11	Widgets can specify where actions are handled:
12
13	\| Handler \| Defined In \| Processed By \| Use Case \|
14	\|---------\|------------\|--------------\|----------\|
15	\| `"client"` \| Widget template \| Frontend `onAction` \| Navigation, local state, send follow-up \|
16	\| `"server"` \| Widget template \| Backend `action()` method \| Data mutation, widget replacement \|
17
18	### Widget Lifecycle
19
20	```
21	1. Agent tool generates widget → yield WidgetItem
22	2. Widget renders in chat with action buttons
23	3. User clicks action → action dispatched
24	4. Handler processes action:
25	- client: onAction callback in frontend
26	- server: action() method in ChatKitServer
27	5. Optional: Widget replaced with updated state
28	```
29
30	## Implementation Patterns
31
32	### Pattern 1: Widget Templates (.widget files)
33
34	When: Define reusable widget layouts with dynamic data
35
36	Widget Template Format:
37	```json
38	{
39	"version": "1.0",
40	"name": "task_list",
41	"template": "{\"type\":\"ListView\",\"children\":[...jinja template...]}",
42	"jsonSchema": {
43	"type": "object",
44	"properties": {
45	"tasks": { "type": "array", "items": {...} }
46	}
47	}
48	}
49	```
50
51	Widget Components Available:
52	- Layout: `ListView`, `ListViewItem`, `Row`, `Col`, `Box`
53	- Content: `Text`, `Title`, `Image`, `Icon`
54	- Interactive: `Button` (with `onClickAction`)
55	- Styling: `gap`, `padding`, `background`, `border`, `radius`
56
57	Example - Task List Widget:
58	```json
59	{
60	"type": "ListView",
61	"children": [
62	{
63	"type": "ListViewItem",
64	"key": "task-1",
65	"onClickAction": {
66	"type": "task.select",
67	"handler": "client",
68	"payload": { "taskId": "task-1" }
69	},
70	"children": [
71	{
72	"type": "Row",
73	"gap": 3,
74	"children": [
75	{ "type": "Icon", "name": "check", "color": "success" },
76	{ "type": "Text", "value": "Complete review", "weight": "semibold" }
77	]
78	}
79	]
80	}
81	]
82	}
83	```
84
85	Python - Loading Templates:
86	```python
87	from chatkit.widgets import WidgetTemplate, WidgetRoot
88
89	# Load template from file
90	task_list_template = WidgetTemplate.from_file("task_list.widget")
91
92	def build_task_list_widget(tasks: list[Task]) -> WidgetRoot:
93	return task_list_template.build(
94	data={
95	"tasks": [task.model_dump() for task in tasks],
96	"selected": None,
97	}
98	)
99	```
100
101	Evidence: `cat-lounge/backend/app/widgets/cat_name_suggestions.widget`
102
103	### Pattern 2: Client-Handled Actions
104
105	When: Actions that update local state, navigate, or send follow-up messages
106
107	Widget Definition (handler: "client"):
108	```json
109	{
110	"type": "Button",
111	"label": "View Article",
112	"onClickAction": {
113	"type": "open_article",
114	"handler": "client",
115	"payload": { "id": "article-123" }
116	}
117	}
118	```
119
120	Frontend Handler:
121	```typescript
122	import { useChatKit, type Widgets } from "@openai/chatkit-react";
123
124	const chatkit = useChatKit({
125	api: { url: API_URL, domainKey: DOMAIN_KEY },
126
127	widgets: {
128	onAction: async (
129	action: { type: string; payload?: Record<string, unknown> },
130	widgetItem: { id: string; widget: Widgets.Card \| Widgets.ListView }
131	) => {
132	switch (action.type) {
133	case "open_article":
134	// Navigate to article
135	navigate(`/article/${action.payload?.id}`);
136	break;
137
138	case "more_suggestions":
139	// Send follow-up message
140	await chatkit.sendUserMessage({ text: "More suggestions, please" });
141	break;
142
143	case "select_option":
144	// Update local state
145	setSelectedOption(action.payload?.optionId);
146	break;
147	}
148	},
149	},
150	});
151	```
152
153	Evidence: `news-guide/frontend/src/components/ChatKitPanel.tsx:55-79`
154
155	### Pattern 3: Server-Handled Actions
156
157	When: Actions that mutate data, update widgets, or require backend processing
158
159	Widget Definition (handler: "server"):
160	```json
161	{
162	"type": "ListViewItem",
163	"onClickAction": {
164	"type": "line.select",
165	"handler": "server",
166	"payload": { "id": "blue-line" }
167	}
168	}
169	```
170
171	Backend Handler:
172	```python
173	from chatkit.server import ChatKitServer
174	from chatkit.types import (
175	Action,
176	WidgetItem,
177	ThreadItemReplacedEvent,
178	ThreadItemDoneEvent,
179	AssistantMessageItem,
180	HiddenContextItem,
181	ClientEffectEvent,
182	)
183
184	class MyServer(ChatKitServer[dict]):

People who liked this also viewed

6 picks

Type

chatkit-actions

1installs11forks

View on GitHub

How to install chatkit-actions?

mjunaidca/mjs-agent-skills/chatkit-actions

$npx -y skills add mjunaidca/mjs-agent-skills --skill chatkit-actions

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# ChatKit Actions Skill
2
3	## Overview
4
5	This skill unlocks the full power of ChatKit's agentic UI capabilities - where AI can render interactive widgets, users can click buttons that trigger both client and server actions, and the conversation becomes a two-way interactive experience.
6
7	## Core Concepts
8
9	### Action Handler Types
10
11	Widgets can specify where actions are handled:
12
13	\| Handler \| Defined In \| Processed By \| Use Case \|
14	\|---------\|------------\|--------------\|----------\|
15	\| `"client"` \| Widget template \| Frontend `onAction` \| Navigation, local state, send follow-up \|
16	\| `"server"` \| Widget template \| Backend `action()` method \| Data mutation, widget replacement \|
17
18	### Widget Lifecycle
19
20	```
21	1. Agent tool generates widget → yield WidgetItem
22	2. Widget renders in chat with action buttons
23	3. User clicks action → action dispatched
24	4. Handler processes action:
25	- client: onAction callback in frontend
26	- server: action() method in ChatKitServer
27	5. Optional: Widget replaced with updated state
28	```
29
30	## Implementation Patterns
31
32	### Pattern 1: Widget Templates (.widget files)
33
34	When: Define reusable widget layouts with dynamic data
35
36	Widget Template Format:
37	```json
38	{
39	"version": "1.0",
40	"name": "task_list",
41	"template": "{\"type\":\"ListView\",\"children\":[...jinja template...]}",
42	"jsonSchema": {
43	"type": "object",
44	"properties": {
45	"tasks": { "type": "array", "items": {...} }
46	}
47	}
48	}
49	```
50
51	Widget Components Available:
52	- Layout: `ListView`, `ListViewItem`, `Row`, `Col`, `Box`
53	- Content: `Text`, `Title`, `Image`, `Icon`
54	- Interactive: `Button` (with `onClickAction`)
55	- Styling: `gap`, `padding`, `background`, `border`, `radius`
56
57	Example - Task List Widget:
58	```json
59	{
60	"type": "ListView",
61	"children": [
62	{
63	"type": "ListViewItem",
64	"key": "task-1",
65	"onClickAction": {
66	"type": "task.select",
67	"handler": "client",
68	"payload": { "taskId": "task-1" }
69	},
70	"children": [
71	{
72	"type": "Row",
73	"gap": 3,
74	"children": [
75	{ "type": "Icon", "name": "check", "color": "success" },
76	{ "type": "Text", "value": "Complete review", "weight": "semibold" }
77	]
78	}
79	]
80	}
81	]
82	}
83	```
84
85	Python - Loading Templates:
86	```python
87	from chatkit.widgets import WidgetTemplate, WidgetRoot
88
89	# Load template from file
90	task_list_template = WidgetTemplate.from_file("task_list.widget")
91
92	def build_task_list_widget(tasks: list[Task]) -> WidgetRoot:
93	return task_list_template.build(
94	data={
95	"tasks": [task.model_dump() for task in tasks],
96	"selected": None,
97	}
98	)
99	```
100
101	Evidence: `cat-lounge/backend/app/widgets/cat_name_suggestions.widget`
102
103	### Pattern 2: Client-Handled Actions
104
105	When: Actions that update local state, navigate, or send follow-up messages
106
107	Widget Definition (handler: "client"):
108	```json
109	{
110	"type": "Button",
111	"label": "View Article",
112	"onClickAction": {
113	"type": "open_article",
114	"handler": "client",
115	"payload": { "id": "article-123" }
116	}
117	}
118	```
119
120	Frontend Handler:
121	```typescript
122	import { useChatKit, type Widgets } from "@openai/chatkit-react";
123
124	const chatkit = useChatKit({
125	api: { url: API_URL, domainKey: DOMAIN_KEY },
126
127	widgets: {
128	onAction: async (
129	action: { type: string; payload?: Record<string, unknown> },
130	widgetItem: { id: string; widget: Widgets.Card \| Widgets.ListView }
131	) => {
132	switch (action.type) {
133	case "open_article":
134	// Navigate to article
135	navigate(`/article/${action.payload?.id}`);
136	break;
137
138	case "more_suggestions":
139	// Send follow-up message
140	await chatkit.sendUserMessage({ text: "More suggestions, please" });
141	break;
142
143	case "select_option":
144	// Update local state
145	setSelectedOption(action.payload?.optionId);
146	break;
147	}
148	},
149	},
150	});
151	```
152
153	Evidence: `news-guide/frontend/src/components/ChatKitPanel.tsx:55-79`
154
155	### Pattern 3: Server-Handled Actions
156
157	When: Actions that mutate data, update widgets, or require backend processing
158
159	Widget Definition (handler: "server"):
160	```json
161	{
162	"type": "ListViewItem",
163	"onClickAction": {
164	"type": "line.select",
165	"handler": "server",
166	"payload": { "id": "blue-line" }
167	}
168	}
169	```
170
171	Backend Handler:
172	```python
173	from chatkit.server import ChatKitServer
174	from chatkit.types import (
175	Action,
176	WidgetItem,
177	ThreadItemReplacedEvent,
178	ThreadItemDoneEvent,
179	AssistantMessageItem,
180	HiddenContextItem,
181	ClientEffectEvent,
182	)
183
184	class MyServer(ChatKitServer[dict]):

People who liked this also viewed

6 picks

Type