Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Interaktívne widgety

Lekcia 19 z 25 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Čo je widget ChatKit?
  2. Kontajnery a komponenty
  3. Návrh widgetu vo Widget Builderi
  4. Čo obsahuje šablóna
  5. Zobrazenie widgetu z respond
  6. Nechaj rozhodnutie na agenta
  7. Klikateľný zoznam
  8. Aktualizácia widgetu počas zobrazenia
  9. Čo s Python triedami?
  10. Kedy použiť widget
  11. Kľúčové poznatky

Lekcia prepísaná 3. novembra 2026. Predchádzajúca verzia opisovala widgety ako React komponenty napísané vývojárom a registrované v rozhraní pomocou neexistujúceho modulu @openai/chatkit/react. V ChatKite je widget deklaratívny opis, ktorý zostaví tvoj server a ktorý ChatKit sám vykreslí. Táto lekcia vychádza z Python SDK openai-chatkit 1.6.5, ktoré zostavuje widgety zo šablón .widget: jeho triedy Card, Text, Badge… sú zastarané. Príklady boli spustené na lokálnom serveri ChatKit. Zdroje: ChatKit widgets · Widgets (Python SDK) · Build interactive responses with widgets · Widget Builder.

Čo je widget ChatKit?

Textová odpoveď stačí na vysvetlenie. Ak však potrebuješ prezentovať objednávku, porovnať tri tarify alebo potvrdiť stretnutie, text sa rýchlo zmení na múr riadkov, ktoré si musí používateľ znova čítať. Widgety nahrádzajú tento text rozhraním: kartou, zoznamom, formulárom alebo grafom, ktoré sa zobrazia priamo v priebehu konverzácie.

Prístup je deklaratívny. Tvoj server nedodáva ani HTML, ani React komponent: opisuje widget v JSONe pomocou uzavretej množiny komponentov a vlastností a odosiela ho do vlákna ako plnohodnotný prvok (WidgetItem). ChatKit ho vykreslí svojimi vlastnými komponentmi s použitím farieb témy z predchádzajúcej lekcie. Vyplývajú z toho dva dôsledky:

  • Môžeš použiť iba komponenty a vlastnosti, ktoré ChatKit pozná. Na oplátku zostáva vykresľovanie konzistentné so zvyškom rozhrania a na stránku sa nedostane žiadne ľubovoľné HTML ani JavaScript zo servera.
  • Widget je súčasťou histórie: v následných krokoch sa konvertuje na vstup pre model, ktorý teda „vidí“, čo ukázal používateľovi.

Kontajnery a komponenty

Každý widget má koreňový prvok vybraný z troch kontajnerov:

KontajnerPoužitie
CardSamostatný obsah: zhrnutie, potvrdenie, formulár. Akceptuje stav a tlačidlá potvrdenia/zrušenia pod obsahom
ListViewSada možností: reštaurácie, súbory, objednávky. Jeho deťmi sú ListViewItem so vstavanou funkciou „zobraziť viac“ (limit)
BasicVyhradené pre náhľady entít zobrazované pri prechode myšou nad zmienkou

Vnútri skladáš komponenty: text (Title, Text, Caption, Markdown), štítky (Badge), rozloženie (Row, Col, Box, Spacer, Divider), médiá (Image, Icon), príkazy (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, ktoré môže zoskupovať Form), grafy (Chart) a animácie (Transition). Stránka Components v Widget Builderi uvádza vlastnosti každého z nich spolu s editorom na ich vyskúšanie.

Návrh widgetu vo Widget Builderi

Odporúčaný pracovný postup začína v Widget Builderi v ChatKit Studio. Tam navrhneš rozloženie, vyplníš panel údajov vzorovými hodnotami, aby si posúdil vykresľovanie, a následne exportuješ súbor .widget. Ide o JSON súbor, ktorý kombinuje šablónu, schému očakávaných údajov (jsonSchema) a vzorové údaje. Tento súbor verzionuj spolu so kódom svojho servera, napríklad v priečinku widgets/.

Na strane servera WidgetTemplate načíta súbor a build ho vyplní reálnymi údajmi:

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",
})

Relatívna cesta sa rieši voči Python súboru, ktorý volá from_file, nie voči spúšťaciemu adresáru. build akceptuje slovník alebo Pydantic model.

Čo obsahuje šablóna

Šablóna je Jinja model, ktorý produkuje JSON widgetu. Šablóna karty objednávky vyzerá takto:

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})

Šablónu budeš len zriedka písať ručne, keďže ju generuje Widget Builder. Jej čítanie ti však ušetrí čas, keď nastane prvý problém. Tri poznámky:

  • Filter tojson konvertuje každú hodnotu na platný JSON (reťazec v úvodzovkách, boolean ako true alebo false) a escapuje špeciálne znaky: apostrof alebo úvodzovka v názve produktu nerozbijú JSON.
  • Jinja beží v striktnom režime: chýbajúce údaje spôsobia zlyhanie build namiesto vytvorenia napoly prázdneho widgetu.
  • build nevaliduje údaje proti jsonSchema. Táto schéma dokumentuje údaje; ak pochádzajú z nástroja alebo databázy, validuj ich vopred, napríklad pomocou Pydantic modelu.

Konštruktor WidgetTemplate(...) prijíma rovnaký obsah ako už načítaný súbor .widget: to sa hodí pri testoch alebo pri šablóne generovanej tvojim vlastným kódom.

Zobrazenie widgetu z respond

Na odoslanie widgetu do vlákna stream_widget produkuje zodpovedajúce udalosti ChatKit. Tie preposielaš zo svojej metódy respond:

from chatkit.server import stream_widget

# Vo vašej triede ChatKitServer
async def respond(self, thread, input_user_message, context):
    card = order_template.build(await get_order_data("C-42"))  # vaše údaje
    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 je text skopírovaný do schránky, keď používateľ klikne na tlačidlo kopírovania pod odpoveďou. Server ukladá widget do úložiska (store) sám, ako ktorýkoľvek iný element vysielania.

Nechaj rozhodnutie na agenta

Najčastejšie to nie je tvoj kód, kto rozhodne o zobrazení karty, ale agent, keď si to konverzácia vyžiada. Poskytni mu nástroj, ktorý vysiela widget pomocou AgentContext.stream_widget: stream_agent_response, ktoré sme videli v lekcii 17, ho prenesie do rozhrania uprostred odpovede.

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)  # váš prístup k údajom
    await ctx.context.stream_widget(order_template.build(data))
    return f"The card for order {number} is displayed."

Pridaj nástroj do zoznamu tools agenta. Reťazec vrátený nástrojom slúži modelu, ktorý tak vie, že karta je na obrazovke, a môže ju komentovať namiesto toho, aby ju opakoval.

Klikateľný zoznam

Na ponúknutie výberu ListView prezentuje klikateľné riadky. Každý ListViewItem môže niesť akciu, ktorá sa spustí kliknutím bez toho, aby používateľ musel niečo písať; ako ju vybaviť na strane servera, ukáže nasledujúca lekcia.

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"}]})

Za hranicou limit zobrazí ChatKit odkaz „zobraziť viac“.

Aktualizácia widgetu počas zobrazenia

Widget sa môže vyvíjať priamo pred očami používateľa, napríklad na zobrazenie konceptu, ktorý píše model. Poskytni stream_widget asynchrónny generátor, ktorý produkuje postupné stavy widgetu: ChatKit vypočíta rozdiely a odošle len to, čo sa zmenilo.

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})
    # Konečný stav, keď je text kompletný
    yield draft_template.build({"text": text, "in_progress": False})

Iba komponenty Text a Markdown s id zobrazujú svoje aktualizácie v streamovaní, slovo po slove; pri ostatných ChatKit nahradí len upravenú časť widgetu.

Čo s Python triedami?

Dokonca aj v sprievodcoch OpenAI narážiš na widgety zostavené pomocou tried: Card(children=[Text(value="…")]). Stále fungujú, ale SDK openai-chatkit 1.6.5 ich označuje ako zastarané v prospech WidgetTemplate: ich použitie vyvolá varovanie odkazujúce na súbory .widget. Pre nový projekt začni so šablónami. Pre existujúci projekt migruj vlastným tempom: varovanie nič neblokuje, ale zastaraná trieda môže v budúcej verzii zmiznúť.

Kedy použiť widget

Dokumentácia uvádza typické použitia:

  • zber štruktúrovaného vstupu pomocou formulára alebo prezentácia bohatého výsledku (tabuľka, karta, graf), ktorý text renderuje zle;
  • ponuka výberu medzi niekoľkými možnosťami;
  • kombinácia widgetu s akciami na validáciu výberu, potvrdenie kroku alebo spustenie spracovania na strane servera;
  • doplnenie krátkeho vysvetľujúceho textu interaktívnym príkazom.

Naopak, neumiestňuj ich všade. Widget, ktorý slovo od slova opakuje to, čo hovorí text, neprináša nič navyše a konverzácia presýtená kartami sa stáva rovnako ťažko čitateľnou ako múr textu.

Kľúčové poznatky

  • Widget ChatKit je deklaratívny opis (JSON) zostavený tvojím serverom, nie React komponent: ChatKit ho vykresľuje sám
  • Tri kontajnery: Card (samostatný obsah), ListView (zoznam možností), Basic (náhľady entít)
  • Navrhni vo Widget Builderi, exportuj súbor .widget, načítaj ho pomocou WidgetTemplate.from_file(...) a vyplň pomocou build(data); triedy Card, Text… sú zastarané
  • Vysielaj pomocou stream_widget z respond alebo z nástroja agenta pomocou ctx.context.stream_widget
  • Asynchrónny generátor aktualizuje widget naživo; iba Text a Markdown s id streamujú slovo po slove