Widgets Interattivi
F'din il-paġna
Lezzjoni miktuba mill-ġdid fit-3 ta’ Novembru 2026. Il-verżjoni preċedenti kienet tiddeskrivi l-widgets bħala komponenti React miktuba mill-iżviluppatur u rreġistrati fl-interfaċċa, billi tuża modulu
@openai/chatkit/reactli ma jeżistix. F’ChatKit, widget huwa deskrizzjoni dikjarattiva li is-server tiegħek jibni u li ChatKit jirrendi huwa stess. Din il-lezzjoni ssegwi l-SDK tal-Pythonopenai-chatkit1.6.5, li jibni l-widgets minn mudelli.widget: il-klassijietCard,Text,Badge… tiegħu huma skaduti. L-eżempji ġew eżegwiti fuq server ChatKit lokali. Sorsi: ChatKit widgets · Widgets (Python SDK) · Build interactive responses with widgets · Widget Builder.
X’inhu widget ta’ ChatKit?
Tweġiba b’test biżżejjed għall-ispjegazzjonijiet. Iżda biex tippreżenta ordni, tqabbel tliet pjanijiet, jew tikkonferma appuntament, it-test malajr isir ħajt ta’ linji li l-utent irid jerġa’ jaqra. Il-widgets jissostitwixxu dak it-test b’interfaċċa: karta, lista, formola, jew grafika, murija fil-fluss tal-konversazzjoni.
L-approċċ huwa dikjarattiv. Is-server tiegħek ma jwassal la HTML u lanqas komponent React: jiddeskrivi l-widget f’JSON, billi juża sett magħluq ta’ komponenti u proprjetajiet, u jibgħatu fil-thread bħala element sħiħ (a WidgetItem). ChatKit jiġbdu bil-komponenti tiegħu stess, billi juża l-kuluri tat-tema mil-lezzjoni preċedenti. Jirriżultaw żewġ konsegwenzi:
- Tista’ tuża biss komponenti u proprjetajiet li ChatKit jaf. Min-naħa l-oħra, ir-rendering jibqa’ konsistenti mal-bqija tal-interfaċċa, u l-ebda HTML arbitrarju jew JavaScript mis-server ma jilħaq il-paġna.
- Il-widget huwa parti mill-istorja: f’dawriet sussegwenti, jiġi kkonvertit f’input għall-mudell, li għalhekk “jara” x’wera lill-utent.
Kontenituri u komponenti
Kull widget għandu għerq, magħżul minn tliet kontenituri:
| Kontenitur | Użu |
|---|---|
Card | Kontenut awtonomu: sommarju, konferma, formola. Jaċċetta status u buttuni ta’ konferma/kanċellazzjoni taħt il-kontenut |
ListView | Sett ta’ għażliet: ristoranti, fajls, ordnijiet. It-tfal tiegħu huma ListViewItems, b’funzjonalità integrata “ara aktar” (limit) |
Basic | Riżervat għal previżjonijiet ta’ entitajiet murija meta wieħed ipoġġi l-maws fuq semma |
Ġewwa, tgħaqqad komponenti: test (Title, Text, Caption, Markdown), tikketta (Badge), layout (Row, Col, Box, Spacer, Divider), media (Image, Icon), kmandi (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, li Form tista’ tgħaqqad), grafiċi (Chart), u animazzjonijiet (Transition). Il-paġna tal-Komponenti tal-Widget Builder telenka l-proprjetajiet ta’ kull wieħed, b’editur biex tipprovahom.
Id-disinn tal-widget fil-Widget Builder
Il-fluss ta’ xogħol maħsub jibda fil-Widget Builder ta’ ChatKit Studio. Hemmhekk tiddisinja l-layout, timla l-pannel tad-data b’valuri kampjun biex tikkunsidra r-rendering, u mbagħad tesporta fajl .widget. Dan huwa fajl JSON li jgħaqqad il-mudell, l-iskema tad-data mistennija (jsonSchema), u d-data kampjun. Ikkontrolla l-verżjoni tiegħu flimkien mal-kodiċi tas-server tiegħek, pereżempju f’folder widgets/.
Fuq in-naħa tas-server, WidgetTemplate itella’ l-fajl u build jimlieh b’data reali:
from chatkit.widgets import WidgetTemplate
order_template = WidgetTemplate.from_file("widgets/order.widget")
card = order_template.build({
"number": "C-42",
"status": "Shipped",
"color": "success",
"items": [{"name": "Keyboard", "price": "$49.90"}, {"name": "Mouse", "price": "$10.00"}],
"total": "$59.90",
})
Mogħdija relattiva tiġi solvuta mill-fajl Python li jsejjaħ from_file, mhux mid-direttorju tal-ħruġ. build jaċċetta dizzjunarju jew mudell Pydantic.
X’fih mudell
Il-mudell huwa mudell Jinja li jipproduċi l-JSON tal-widget. Il-mudell tal-karta tal-ordni jidher hekk:
ORDER_TEMPLATE = """
{
"type": "Card",
"children": [
{"type": "Row", "justify": "between", "align": "center", "children": [
{"type": "Title", "value": {{ ("Order " ~ number) | tojson }}, "size": "sm"},
{"type": "Badge", "label": {{ status | tojson }}, "color": {{ color | tojson }}}
]},
{"type": "Divider"},
{"type": "Col", "gap": 2, "children": [
{%- for item in items %}
{"type": "Row", "justify": "between", "children": [
{"type": "Text", "value": {{ item.name | tojson }}},
{"type": "Text", "value": {{ item.price | tojson }}}
]}{% if not loop.last %},{% endif %}
{%- endfor %}
]},
{"type": "Divider"},
{"type": "Row", "justify": "between", "children": [
{"type": "Text", "value": "Total", "weight": "semibold"},
{"type": "Text", "value": {{ total | tojson }}, "weight": "semibold"}
]}
]
}
"""
order_template = WidgetTemplate({"version": "1.0", "name": "order", "template": ORDER_TEMPLATE})
Rari se tikteb mudell bl-idejn, peress li l-Widget Builder jiġġenerah. Iżda li taqra wieħed iffrankalek ħin meta tinħoloq l-ewwel problema. Tliet osservazzjonijiet:
- Il-filtru
tojsonjikkonverti kull valur f’JSON validu (stringa ċċitata, boolean bħalatruejewfalse) u jaħrab karattri speċjali: apostrofu jew kwotazzjoni f’isem prodott ma tkissirx il-JSON. - Jinja jaħdem f’mod strett: data nieqsa tikkawża li
buildifalli, minflok ma jipproduċi widget nofsu vojt. buildma jivvalidax id-data kontra l-jsonSchema. Din l-iskema tiddokumenta d-data; jekk tiġi minn għodda jew database, ivvalidaha minn qabel, pereżempju b’mudell Pydantic.
Il-kostruttur WidgetTemplate(...) jieħu l-istess kontenut bħal fajl .widget diġà moqri: dan huwa utli għat-testijiet, jew għal mudell iġġenerat mill-kodiċi tiegħek stess.
L-esibizzjoni tal-widget minn respond
Biex tibgħat il-widget fit-thread, stream_widget jipproduċi l-avvenimenti korrispondenti ta’ ChatKit. Inti tgħaddihom mill-metodu respond tiegħek:
from chatkit.server import stream_widget
# Fil-klassi ChatKitServer tiegħek
async def respond(self, thread, input_user_message, context):
card = order_template.build(await get_order_data("C-42")) # id-data tiegħek
async for event in stream_widget(
thread,
card,
copy_text="Order C-42: shipped, $59.90",
generate_id=lambda item_type: self.store.generate_item_id(item_type, thread, context),
):
yield event
copy_text huwa t-test ikkupjat fil-clipboard meta l-utent jikklikkja l-buttuna tal-kopja taħt it-tweġiba. Is-server isalva l-widget fil-maħżen innifsu, bħal kull element tax-xandir.
Il-ħalli l-aġent jiddeċiedi
L-aktar spiss, mhux il-kodiċi tiegħek li jiddeċiedi li juri karta, iżda l-aġent, meta l-konversazzjoni titlobha. Agħtih għodda li xxandar il-widget b’AgentContext.stream_widget: stream_agent_response, meħuda mil-lezzjoni 17, tittrażmettih lill-interfaċċa f’nofs it-tweġiba.
from agents import RunContextWrapper, function_tool
from chatkit.agents import AgentContext
@function_tool(description_override="Displays order details as a card.")
async def show_order(ctx: RunContextWrapper[AgentContext], number: str) -> str:
data = await get_order_data(number) # l-aċċess għad-data tiegħek
await ctx.context.stream_widget(order_template.build(data))
return f"The card for order {number} is displayed."
Żid l-għodda fil-lista tools tal-aġent. L-istringa rritornata mill-għodda sservi lill-mudell, li għalhekk ikun jaf li l-karta tinsab fuq l-iskrin u jista’ jikkummenta fuqha minflok ma jerġa’ jgħidha.
Lista li tista’ tikklikkjaha
Biex toffri għażla, ListView tippreżenta ringieli li jistgħu jiġu kklikkjati. Kull ListViewItem jista’ ġġorr azzjoni, attivata bil-klikk mingħajr ma l-utent ikollu jikteb xejn; il-lezzjoni li jmiss turi kif timmaniġġjah fuq in-naħa tas-server.
LIST_TEMPLATE = """
{
"type": "ListView",
"limit": 5,
"children": [
{%- for o in orders %}
{
"type": "ListViewItem",
"key": {{ o.number | tojson }},
"onClickAction": {"type": "order.open", "payload": {"number": {{ o.number | tojson }}}},
"children": [
{"type": "Col", "children": [
{"type": "Text", "value": {{ ("Order " ~ o.number) | tojson }},
{"type": "Caption", "value": {{ o.date | tojson }}}
]}
]
}{% if not loop.last %},{% endif %}
{%- endfor %}
]
}
"""
order_list_template = WidgetTemplate({"version": "1.0", "name": "order_list", "template": LIST_TEMPLATE})
list_widget = order_list_template.build({"orders": [{"number": "C-42", "date": "November 2"}, {"number": "C-41", "date": "October 28"}]})
Lil hinn mil-limit, ChatKit juri link “ara aktar”.
Aġġornament ta’ widget waqt li jkun muri
Widget jista’ jevolvi quddiem għajnejn l-utent, pereżempju biex juri abbozz li l-mudell qed jikteb. Agħti lil stream_widget ġeneratur asinkronu li jipproduċi stati suċċessivi tal-widget: ChatKit jikkalkula d-differenzi u jibgħat biss dak li jinbidel.
from collections.abc import AsyncGenerator
from chatkit.widgets import DynamicWidgetRoot, WidgetTemplate
draft_template = WidgetTemplate({
"version": "1.0",
"name": "draft",
"template": """{"type": "Card", "children": [
{"type": "Title", "value": "Draft"},
{"type": "Text", "id": "body", "value": {{ text | tojson }}, "streaming": {{ in_progress | tojson }}}
]}""",
})
async def streaming_draft(chunks: AsyncGenerator[str, None]) -> AsyncGenerator[DynamicWidgetRoot, None]:
text = ""
async for chunk in chunks:
text += chunk
yield draft_template.build({"text": text, "in_progress": True})
# Stat finali, ladarba t-test ikun komplut
yield draft_template.build({"text": text, "in_progress": False})
Biss il-komponenti Text u Markdown b’id juru l-aġġornamenti tagħhom f’fluss, kelma b’kelma; għal oħrajn, ChatKit jissostitwixxi l-parti mmodifikata tal-widget.
X’jiġri mill-klassijiet tal-Python?
Se tiltaqa’, anke fil-gwidi ta’ OpenAI, ma’ widgets mibnija b’klassijiet: Card(children=[Text(value="…")]). Għadhom jaħdmu, iżda l-SDK openai-chatkit 1.6.5 jiddikjarahom skaduti favur WidgetTemplate: l-użu tagħhom joħroġ twissija li tissuġġerixxi fajls .widget. Għal proġett ġdid, ibda minn mudelli. Għal proġett eżistenti, immigra bir-ritmu tiegħek: it-twissija ma timblokka xejn, iżda klassi skaduta tista’ tisparixxi f’verżjoni futura.
Meta tuża widget
Id-dokumentazzjoni tiċċita użi tipiċi:
- il-ġbir ta’ input strutturat b’formola, jew il-preżentazzjoni ta’ riżultat rikk (tabella, karta, grafika) li t-test jirrendi ħażin;
- l-offerta ta’ għażla bejn diversi għażliet;
- il-kombinazzjoni tal-widget ma’ azzjonijiet, biex tivvalida għażla, tikkonferma pass, jew tniedi ipproċessar fuq in-naħa tas-server;
- l-akkumpanjament ta’ test spjegattiv qasir b’kmand interattiv.
Min-naħa l-oħra, tpoġġihomx kullimkien. Widget li jirrepeti kelma b’kelma dak li jgħid it-test ma jżid xejn, u konversazzjoni mimlija karti ssir diffiċli biex taqra daqs ħajt ta’ test.
Punti Ewlenin
- Widget ta’ ChatKit huwa deskrizzjoni dikjarattiva (JSON) mibnija mis-server tiegħek, mhux komponent React: ChatKit jirrendih huwa stess
- Tliet kontenituri:
Card(kontenut awtonomu),ListView(lista ta’ għażliet),Basic(previżjonijiet ta’ entitajiet) - Iddisinja fil-Widget Builder, esporta fajl
.widget, itlagħh b’WidgetTemplate.from_file(...), u imlieh b’build(data); il-klassijietCard,Text… huma skaduti - Ixandar b’
stream_widgetminnrespond, jew minn għodda tal-aġent b’ctx.context.stream_widget - Ġeneratur asinkronu jaġġorna l-widget ħaj; biss
TextuMarkdownb’idjixandru kelma b’kelma