Interaktív widgetek
Ezen az oldalon
- Mi az a ChatKit widget?
- Konténerek és komponensek
- A widget tervezése a Widget Builderben
- Mit tartalmaz egy sablon?
- A widget megjelenítése a respond függvényből
- Döntés az ágens kezében
- Egy kattintható lista
- Widget frissítése megjelenítés közben
- Mi a helyzet a Python osztályokkal?
- Mikor használj widgetet?
- Főbb megállapítások
Lecke átírva: 2026. november 3. A korábbi verzió a widgeteket fejlesztő által írt React-komponensként írta le, amelyeket egy nem létező
@openai/chatkit/reactmodulon keresztül regisztráltak a felületen. A ChatKitben a widget egy deklaratív leírás, amelyet a szervered épít fel, és amelyet maga a ChatKit jelenít meg. Ez a lecke azopenai-chatkitPython SDK 1.6.5 verzióját követi, amely.widgetsablonokból építi fel a widgeteket: aCard,Text,Badge… osztályai elavultak. A példákat helyi ChatKit szerveren futtattuk. Források: ChatKit widgetek · Widgetek (Python SDK) · Interaktív válaszok építése widgetekkel · Widget Builder.
Mi az a ChatKit widget?
Egy szöveges válasz elegendő magyarázatokhoz. De ha rendelést kell bemutatni, három csomagtervet összehasonlítani vagy egy időpontot megerősíteni, a szöveg gyorsan sorok falává válik, amelyet a felhasználónak újra át kell olvasnia. A widgetek ezt a szöveget egy felülettel helyettesítik: egy kártyával, listával, űrlappal vagy diagrammal, amely a beszélgetés folyamatán belül jelenik meg.
A megközelítés deklaratív. A szervered nem szállít HTML-t vagy React-komponenst: JSON-ban írja le a widgetet, egy zárt komponens- és tulajdonságkészletet használva, és teljes értékű elemként (WidgetItem) küldi el a szálba. A ChatKit a saját komponenseivel rajzolja ki, az előző leckéből származó téma színeit használva. Ebből két következmény adódik:
- Csak azokat a komponenseket és tulajdonságokat használhatod, amelyeket a ChatKit ismer. Cserébe a megjelenítés konzisztens marad a felület többi részével, és semmilyen önkényes HTML vagy JavaScript nem jut a szerverről az oldalra.
- A widget a történet része: a későbbi körökben bemenetté alakul a modell számára, amely így „látja“, amit mutatott a felhasználónak.
Konténerek és komponensek
Minden widgetnek van egy gyökéreleme, amelyet három konténer közül választhatsz:
| Konténer | Használat |
|---|---|
Card | Önálló tartalom: összefoglaló, megerősítés, űrlap. Elfogad egy állapotot, valamint megerősítő/mégse gombokat a tartalom alatt |
ListView | Opciók halmaza: éttermek, fájlok, rendelések. Gyermekei ListViewItem elemek, beépített „továbbiak megtekintése“ funkcióval (limit) |
Basic | Említésekre való rámutatáskor megjelenő entitás-előnézetek számára fenntartva |
Belül komponenseket állítasz össze: szöveg (Title, Text, Caption, Markdown), címkék (Badge), elrendezés (Row, Col, Box, Spacer, Divider), média (Image, Icon), parancsok (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, amelyeket egy Form csoportosíthat), diagramok (Chart) és animációk (Transition). A Widget Builder Komponensek oldala felsorolja az egyes elemek tulajdonságait, egy szerkesztővel a kipróbálásukhoz.
A widget tervezése a Widget Builderben
A javasolt munkafolyamat a ChatKit Studio Widget Builder eszközében kezdődik. Ittervezed az elrendezést, kitöltöd az adatpanelt mintaadatokkal a megjelenítés megítéléséhez, majd exportálsz egy .widget fájlt. Ez egy JSON-fájl, amely egyesíti a sablont, a várt adatok sémáját (jsonSchema) és a mintaadatokat. Verziókezd a szerverkódoddal együtt, például egy widgets/ mappában.
A szerveroldalon a WidgetTemplate betölti a fájlt, a build pedig feltölti valós adatokkal:
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",
})
A relatív elérési utat a from_file-t hívó Python-fájlból oldja fel, nem az indítási könyvtárból. A build elfogad egy szótárat vagy egy Pydantic modellt.
Mit tartalmaz egy sablon?
A sablon egy Jinja-modell, amely előállítja a widget JSON-ját. A rendelési kártya sablonja így néz ki:
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})
Ritkán írsz kézzel sablont, mivel a Widget Builder generálja azt. De ha elolvasod egyet, időt spórolsz meg, amikor az első hiba fellép. Három megjegyzés:
- A
tojsonszűrő minden értéket érvényes JSON-ná alakít (idézett sztring, boolean minttruevagyfalse), és kiemeli a speciális karaktereket: egy aposztróf vagy idézőjel egy terméknevében nem töri meg a JSON-t. - A Jinja szigorú módban fut: a hiányzó adatok miatt a
buildmeghibásodik, ahelyett, hogy félig üres widgetet hozna létre. - A
buildnem validálja az adatokat ajsonSchemaalapján. Ez a séma dokumentálja az adatokat; ha egy eszközből vagy adatbázisból származik, előtte validáld őket, például egy Pydantic modellel.
A WidgetTemplate(...) konstruktor ugyanazt a tartalmat fogadja el, mint egy már beolvasott .widget fájl: ez hasznos tesztekhez, vagy a saját kódod által generált sablonokhoz.
A widget megjelenítése a respond függvényből
A widget szálba küldéséhez a stream_widget előállítja a megfelelő ChatKit eseményeket. Ezeket továbbítod a respond metódusodból:
from chatkit.server import stream_widget
# A ChatKitServer osztályodban
async def respond(self, thread, input_user_message, context):
card = order_template.build(await get_order_data("C-42")) # a te adataid
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
A copy_text az a szöveg, amely a vágólapra kerül, amikor a felhasználó rákattint a válasz alatti másolás gombra. A szerver maga menti el a widgetet a tárolóba (store), akárcsak bármely más közvetített elemet.
Döntés az ágens kezében
Legtöbbször nem a kódod dönti el egy kártya megjelenítését, hanem az ágens, amikor a beszélgetés ezt megköveteli. Adj neki egy eszközt, amely a AgentContext.stream_widget segítségével közvetíti a widgetet: a stream_agent_response, amelyet a 17. leckében láttál, továbbítja azt a felületnek a válasz közepette.
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) # a te adathozzáférésed
await ctx.context.stream_widget(order_template.build(data))
return f"The card for order {number} is displayed."
Add hozzá az eszközt az ágens tools listájához. Az eszköz által visszaadott sztring a modell számára szolgál, amely így tudja, hogy a kártya a képernyőn van, és kommentálhatja azt ahelyett, hogy megismételné.
Egy kattintható lista
Választási lehetőség felkínálásához a ListView kattintható sorokat jelenít meg. Minden ListViewItem hordozhat egy műveletet, amely kattintásra aktiválódik anélkül, hogy a felhasználónak bármit be kellene írnia; a következő lecke mutatja meg, hogyan kezeld ezt a szerveroldalon.
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"}]})
A limit értékén túl a ChatKit egy „továbbiak megtekintése“ hivatkozást jelenít meg.
Widget frissítése megjelenítés közben
Egy widget fejlődhet a felhasználó szeme láttára, például egy piszkozat megjelenítésére, amelyet a modell éppen ír. Adj a stream_widget függvénynek egy aszinkron generátort, amely előállítja a widget egymást követő állapotait: a ChatKit kiszámítja a különbségeket, és csak a változásokat küldi el.
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})
# Végső állapot, amikor a szöveg kész
yield draft_template.build({"text": text, "in_progress": False})
Csak az id-vel rendelkező Text és Markdown komponensek jelenítik meg frissítéseiket streamelve, szóról szóra; mások esetén a ChatKit kicseréli a widget módosított részét.
Mi a helyzet a Python osztályokkal?
Találkozhatsz – még az OpenAI útmutatóiban is – olyan widgetekkel, amelyeket osztályokkal építettek fel: Card(children=[Text(value="…")]). Ezek még működnek, de az openai-chatkit 1.6.5 SDK elavultnak nyilvánítja őket a WidgetTemplate javára: használatuk figyelmeztetést generál, amely a .widget fájlokra irányít. Egy új projektnél kezdj sablonokkal. Egy meglévő projekt esetén saját tempódban migrálj: a figyelmeztetés nem blokkol semmit, de egy elavult osztály eltűnhet egy jövőbeli verzióban.
Mikor használj widgetet?
A dokumentáció tipikus felhasználási eseteket említ:
- strukturált bemenet gyűjtése űrlappal, vagy gazdag eredmény (táblázat, kártya, diagram) bemutatása, amelyet a szöveg rosszul jelenít meg;
- választási lehetőség felkínálása több opció között;
- a widget kombinálása műveletekkel egy kiválasztás érvényesítésére, egy lépés megerősítésére vagy szerveroldali feldolgozás indítására;
- rövid magyarázó szöveg kiegészítése interaktív paranccsal.
Ezzel szemben ne helyezd el őket mindenhol. Egy olyan widget, amely szóról szóra megismétli, amit a szöveg mond, nem ad hozzá semmit, és a kártyákkal telített beszélgetés ugyanolyan nehezen olvashatóvá válik, mint a szövegfal.
Főbb megállapítások
- A ChatKit widget egy deklaratív leírás (JSON), amelyet a szervered épít fel, nem egy React-komponens: a ChatKit maga jeleníti meg
- Három konténer:
Card(önálló tartalom),ListView(opciók listája),Basic(entitás-előnézetek) - Tervezd meg a Widget Builderben, exportálj egy
.widgetfájlt, töltsd be aWidgetTemplate.from_file(...)segítségével, és töltsd fel abuild(data)metódussal; aCard,Text… osztályok elavultak - Közvetítsd a
stream_widgetfüggvénnyel arespondmetódusból, vagy egy ágens eszközből actx.context.stream_widgetsegítségével - Egy aszinkron generátor élőben frissíti a widgetet; csak az
id-vel rendelkezőTextésMarkdownelemek streamelnek szóról szóra