Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Interaktivní widgety

Lekce 19 z 25 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Co je to widget ChatKit?
  2. Kontejnery a komponenty
  3. Návrh widgetu ve Widget Builderu
  4. Co šablona obsahuje
  5. Zobrazení widgetu z respond
  6. Nechání rozhodnutí na agentovi
  7. Klikací seznam
  8. Aktualizace widgetu během zobrazení
  9. Co s Python třídami?
  10. Kdy použít widget
  11. Klíčové poznatky

Lekce přepsána 3. listopadu 2026. Předchozí verze popisovala widgety jako React komponenty psané vývojářem a registrované v rozhraní pomocí neexistujícího modulu @openai/chatkit/react. V ChatKitu je widget deklarativní popis, který sestaví váš server a který ChatKit sám vykreslí. Tato lekce vychází z Python SDK openai-chatkit 1.6.5, které buduje widgety ze šablon .widget: jeho třídy Card, Text, Badge… jsou zastaralé. Příklady byly spuštěny na lokálním serveru ChatKit. Zdroje: ChatKit widgets · Widgets (Python SDK) · Build interactive responses with widgets · Widget Builder.

Co je to widget ChatKit?

Textová odpověď stačí na vysvětlení. Ale když potřebujete představit objednávku, porovnat tři tarify nebo potvrdit schůzku, text se rychle změní ve zeď řádků, které si uživatel musí znovu číst. Widgety nahrazují tento text rozhraním: kartou, seznamem, formulářem nebo grafem, zobrazeným přímo v průběhu konverzace.

Přístup je deklarativní. Váš server nedodává ani HTML, ani React komponentu: popisuje widget v JSONu pomocí uzavřené sady komponent a vlastností a odešle jej do vlákna jako plnohodnotný prvek (WidgetItem). ChatKit jej vykreslí svými vlastními komponentami s využitím barev motivu z předchozí lekce. Vyplývají z toho dva důsledky:

  • Můžete použít pouze komponenty a vlastnosti, které ChatKit zná. Na oplátku zůstává vykreslení konzistentní se zbytkem rozhraní a na stránku se nedostane žádné libovolné HTML ani JavaScript ze serveru.
  • Widget je součástí historie: v následujících kolech se převede na vstup pro model, který tedy „vidí“, co ukázal uživateli.

Kontejnery a komponenty

Každý widget má kořenový prvek vybraný ze tří kontejnerů:

KontejnerPoužití
CardSamostatný obsah: shrnutí, potvrzení, formulář. Přijímá stav a tlačítka pro potvrzení/zrušení pod obsahem
ListViewSada možností: restaurace, soubory, objednávky. Jeho dětmi jsou ListViewItems s vestavěnou funkcionalitou „zobrazit více“ (limit)
BasicVyhrazeno pro náhledy entit zobrazené při najetí myší na zmínku

Uvnitř skládáte komponenty: text (Title, Text, Caption, Markdown), štítky (Badge), rozložení (Row, Col, Box, Spacer, Divider), média (Image, Icon), příkazy (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, které může seskupit Form), grafy (Chart) a animace (Transition). Stránka Components ve Widget Builderu uvádí vlastnosti každé z nich spolu s editorem pro jejich vyzkoušení.

Návrh widgetu ve Widget Builderu

Doporučený pracovní postup začíná ve Widget Builderu v ChatKit Studiu. Zde navrhnete rozložení, vyplníte datový panel ukázkovými hodnotami, abyste posoudili vykreslení, a následně exportujete soubor .widget. Jedná se o JSON soubor, který kombinuje šablonu, schéma očekávaných dat (jsonSchema) a ukázková data. Tento soubor verzionujte společně s kódem serveru, například ve složce widgets/.

Na straně serveru WidgetTemplate načte soubor a build jej vyplní skutečnými daty:

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

Relativní cesta se řeší vůči Python souboru, který volá from_file, nikoli vůči adresáři spuštění. build přijímá slovník nebo Pydantic model.

Co šablona obsahuje

Šablona je Jinja model, který produkuje JSON widgetu. Šablona karty objednávky vypadá 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})

Šablony budete jen zřídka psát ručně, protože je generuje Widget Builder. Ale umět je číst vám ušetří čas, když nastane první problém. Tři poznámky:

  • Filtr tojson převádí každou hodnotu na platný JSON (řetězec v uvozovkách, boolean jako true nebo false) a escapuje speciální znaky: apostrof nebo uvozovka v názvu produktu nerozbijí JSON.
  • Jinja běží v přísném režimu: chybějící data způsobí selhání build, místo aby produkovala napůl prázdný widget.
  • build nevaliduje data proti jsonSchema. Toto schéma dokumentuje data; pokud pocházejí z nástroje nebo databáze, validujte je předem, například pomocí Pydantic modelu.

Konstruktor WidgetTemplate(...) přijímá stejný obsah jako již načtený soubor .widget: to se hodí pro testy nebo pro šablonu generovanou vaším vlastním kódem.

Zobrazení widgetu z respond

Chcete-li widget odeslat do vlákna, stream_widget vytvoří odpovídající události ChatKit. Ty předáte ze své metody respond:

from chatkit.server import stream_widget

# Ve vaší třídě ChatKitServer
async def respond(self, thread, input_user_message, context):
    card = order_template.build(await get_order_data("C-42"))  # vaše data
    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 zkopírovaný do schránky, když uživatel klikne na tlačítko kopírování pod odpovědí. Server uloží widget do úložiště sám, stejně jako jakýkoli jiný vysílaný prvek.

Nechání rozhodnutí na agentovi

Nejčastěji to není váš kód, kdo rozhodne o zobrazení karty, ale agent, když to konverzace vyžaduje. Dejte mu nástroj, který vysílá widget pomocí AgentContext.stream_widget: stream_agent_response, které jste viděli v lekci 17, jej přenáší do rozhraní uprostřed odpovědi.

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áš přístup k datům
    await ctx.context.stream_widget(order_template.build(data))
    return f"The card for order {number} is displayed."

Přidejte nástroj do seznamu tools agenta. Řetězec vrácený nástrojem slouží modelu, který tak ví, že je karta na obrazovce, a může se k ní vyjádřit, místo aby ji opakoval.

Klikací seznam

Chcete-li nabídnout výběr, ListView prezentuje klikatelné řádky. Každý ListViewItem může nést akci, která se spustí při kliknutí, aniž by uživatel musel cokoli psát; jak se s tím vypořádat na straně serveru, ukáže další lekce.

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 hranicí limit zobrazí ChatKit odkaz „zobrazit více“.

Aktualizace widgetu během zobrazení

Widget se může vyvíjet před očima uživatele, například pro zobrazení konceptu, který model píše. Dejte stream_widget asynchronní generátor, který produkuje postupné stavy widgetu: ChatKit vypočítá rozdíly a odešle pouze to, co se změnilo.

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, jakmile je text kompletní
    yield draft_template.build({"text": text, "in_progress": False})

Pouze komponenty Text a Markdown s id zobrazují své aktualizace ve streamu slovo po slově; u ostatních ChatKit nahradí pouze upravenou část widgetu.

Co s Python třídami?

Setkáte se s nimi, dokonce i v průvodcích OpenAI: widgety postavené pomocí tříd: Card(children=[Text(value="…")]). Stále fungují, ale SDK openai-chatkit 1.6.5 je prohlašuje za zastaralé ve prospěch WidgetTemplate: jejich použití vydává varování odkazující na soubory .widget. Pro nový projekt začněte se šablonami. Pro existující projekt migrujte vlastním tempem: varování nic neblokuje, ale zastaralá třída může v budoucí verzi zmizet.

Kdy použít widget

Dokumentace uvádí typická použití:

  • sběr strukturovaného vstupu pomocí formuláře nebo prezentace bohatého výsledku (tabulka, karta, graf), který text špatně vykresluje;
  • nabídka výběru mezi několika možnostmi;
  • kombinace widgetu s akcemi pro validaci výběru, potvrzení kroku nebo spuštění zpracování na straně serveru;
  • doprovod krátkého vysvětlujícího textu interaktivním příkazem.

Naopak je nedávejte všude. Widget, který slovo od slova opakuje to, co říká text, nic nepřidává, a konverzace přesycená kartami se stává stejně obtížně čitelnou jako zeď textu.

Klíčové poznatky

  • Widget ChatKit je deklarativní popis (JSON) budovaný vaším serverem, nikoli React komponenta: ChatKit jej vykresluje sám
  • Tři kontejnery: Card (samostatný obsah), ListView (seznam možností), Basic (náhledy entit)
  • Navrhujte ve Widget Builderu, exportujte soubor .widget, načtěte jej pomocí WidgetTemplate.from_file(...) a vyplňte pomocí build(data); třídy Card, Text… jsou zastaralé
  • Vysílejte pomocí stream_widget z respond, nebo z nástroje agenta pomocí ctx.context.stream_widget
  • Asynchronní generátor aktualizuje widget živě; pouze Text a Markdown s id streamují slovo po slovu