Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Interaktív widgetek

19. lecke 25 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Mi az a ChatKit widget?
  2. Konténerek és komponensek
  3. A widget tervezése a Widget Builderben
  4. Mit tartalmaz egy sablon?
  5. A widget megjelenítése a respond függvényből
  6. Döntés az ágens kezében
  7. Egy kattintható lista
  8. Widget frissítése megjelenítés közben
  9. Mi a helyzet a Python osztályokkal?
  10. Mikor használj widgetet?
  11. 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/react modulon 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 az openai-chatkit Python SDK 1.6.5 verzióját követi, amely .widget sablonokból építi fel a widgeteket: a Card, 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énerHasználat
CardÖnálló tartalom: összefoglaló, megerősítés, űrlap. Elfogad egy állapotot, valamint megerősítő/mégse gombokat a tartalom alatt
ListViewOpciók halmaza: éttermek, fájlok, rendelések. Gyermekei ListViewItem elemek, beépített „továbbiak megtekintése“ funkcióval (limit)
BasicEmlí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 tojson szűrő minden értéket érvényes JSON-ná alakít (idézett sztring, boolean mint true vagy false), é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 build meghibásodik, ahelyett, hogy félig üres widgetet hozna létre.
  • A build nem validálja az adatokat a jsonSchema alapjá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 .widget fájlt, töltsd be a WidgetTemplate.from_file(...) segítségével, és töltsd fel a build(data) metódussal; a Card, Text… osztályok elavultak
  • Közvetítsd a stream_widget függvénnyel a respond metódusból, vagy egy ágens eszközből a ctx.context.stream_widget segítségével
  • Egy aszinkron generátor élőben frissíti a widgetet; csak az id-vel rendelkező Text és Markdown elemek streamelnek szóról szóra