Interaktivní widgety
Na této stránce
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 SDKopenai-chatkit1.6.5, které buduje widgety ze šablon.widget: jeho třídyCard,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ů:
| Kontejner | Použití |
|---|---|
Card | Samostatný obsah: shrnutí, potvrzení, formulář. Přijímá stav a tlačítka pro potvrzení/zrušení pod obsahem |
ListView | Sada možností: restaurace, soubory, objednávky. Jeho dětmi jsou ListViewItems s vestavěnou funkcionalitou „zobrazit více“ (limit) |
Basic | Vyhrazeno 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
tojsonpřevádí každou hodnotu na platný JSON (řetězec v uvozovkách, boolean jakotruenebofalse) 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. buildnevaliduje data protijsonSchema. 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řídyCard,Text… jsou zastaralé - Vysílejte pomocí
stream_widgetzrespond, nebo z nástroje agenta pomocíctx.context.stream_widget - Asynchronní generátor aktualizuje widget živě; pouze
TextaMarkdownsidstreamují slovo po slovu