Widgeti interaktivni
Na ovoj stranici
Lekcija prepisana 3. studenoga 2026. Prethodna verzija opisivala je widgete kao React komponente koje piše programer i registrira u sučelju, koristeći nepostojeći modul
@openai/chatkit/react. U ChatKitu, widget je deklarativni opis koji gradi tvoj poslužitelj, a ChatKit ga sam iscrtava. Ova lekcija pratiopenai-chatkitPython SDK 1.6.5, koji gradi widgete iz.widgetpredložaka: njegove klaseCard,Text,Badge… su zastarjele. Primjeri su izvršeni na lokalnom ChatKit poslužitelju. Izvori: ChatKit widgeti · Widgeti (Python SDK) · Izgradi interaktivne odgovore s widgetima · Widget Builder.
Što je ChatKit widget?
Tekstualni odgovor dovoljan je za objašnjenja. No, za prikaz narudžbe, usporedbu triju planova ili potvrdu termina, tekst brzo postaje zid redaka koje korisnik mora ponovno čitati. Widgeti zamjenjuju taj tekst sučeljem: karticom, popisom, obrascem ili grafikonom, prikazanim unutar tijeka razgovora.
Pristup je deklarativan. Tvoj poslužitelj ne isporučuje HTML niti React komponentu: on opisuje widget u JSON-u, koristeći zatvoren skup komponenti i svojstava, te ga šalje u nit kao punopravni element (WidgetItem). ChatKit ga iscrtava vlastitim komponentama, koristeći boje teme iz prethodne lekcije. Slijede dvije posljedice:
- Možeš koristiti samo komponente i svojstva koja ChatKit poznaje. Zauzvrat, prikaz ostaje dosljedan ostatku sučelja, a nikakav proizvoljan HTML ili JavaScript s poslužitelja ne dospijeva na stranicu.
- Widget je dio povijesti: u narednim koracima pretvara se u ulaz za model, koji stoga „vidi“ što je pokazao korisniku.
Kontejneri i komponente
Svaki widget ima korijen, odabran iz triju kontejnera:
| Kontejner | Upotreba |
|---|---|
Card | Samostalni sadržaj: sažetak, potvrda, obrazac. Prihvaća status i gumbe za potvrdu/odustajanje ispod sadržaja |
ListView | Skup opcija: restorani, datoteke, narudžbe. Njegova djeca su ListViewItemi, s ugrađenom funkcionalnošću „vidi više“ (limit) |
Basic | Rezervirano za preglede entiteta prikazane pri lebdenju iznad spomena |
Unutra sastavljaš komponente: tekst (Title, Text, Caption, Markdown), oznake (Badge), izgled (Row, Col, Box, Spacer, Divider), medije (Image, Icon), naredbe (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, koje Form može grupirati), grafikone (Chart) i animacije (Transition). Stranica Components u Widget Builderu navodi svojstva svakoga, s uređivačem za isprobavanje.
Dizajniranje widgeta u Widget Builderu
Namijenjeni tijek rada počinje u Widget Builderu unutar ChatKit Studija. Ondje dizajniraš izgled, popunjavaš ploču s podacima uzorkovanim vrijednostima kako bi procijenio prikaz, a zatim izvoziš .widget datoteku. To je JSON datoteka koja kombinira predložak, shemu očekivanih podataka (jsonSchema) i uzorkovane podatke. Stavi je pod nadzor verzija uz kod svog poslužitelja, primjerice u mapu widgets/.
Na strani poslužitelja, WidgetTemplate učitava datoteku, a build je popunjava stvarnim podacima:
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",
})
Relativna putanja razrješava se iz Python datoteke koja poziva from_file, a ne iz direktorija pokretanja. build prihvaća rječnik ili Pydantic model.
Što predložak sadrži
Predložak je Jinja model koji proizvodi JSON widgeta. Predložak kartice narudžbe izgleda ovako:
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})
Rijetko ćeš pisati predložak ručno, jer ga Widget Builder generira. No, čitanje jednoga uštedjet će ti vrijeme kada se pojavi prvi problem. Tri napomene:
- Filtrar
tojsonpretvara svaku vrijednost u valjani JSON (navodnik stringa, boolean kaotrueilifalse) i izbjegava posebne znakove: apostrof ili navodnik u nazivu proizvoda neće slomiti JSON. - Jinja radi u strogom načinu: nedostajući podaci uzrokuju neuspjeh
build, umjesto da proizvode napola prazan widget. buildne validira podatke protivjsonSchema. Ova shema dokumentira podatke; ako dolaze iz alata ili baze podataka, validiraj ih unaprijed, primjerice s Pydantic modelom.
Konstruktor WidgetTemplate(...) uzima isti sadržaj kao već pročitanu .widget datoteku: ovo je zgodno za testove ili za predložak koji generira tvoj vlastiti kod.
Prikazivanje widgeta iz respond
Za slanje widgeta u nit, stream_widget proizvodi odgovarajuće ChatKit događaje. Proslijediš ih iz svoje metode respond:
from chatkit.server import stream_widget
# U tvojoj klasi ChatKitServer
async def respond(self, thread, input_user_message, context):
card = order_template.build(await get_order_data("C-42")) # tvoji podaci
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 tekst koji se kopira u međuspremnik kada korisnik klikne gumb za kopiranje ispod odgovora. Poslužitelj sam sprema widget u store, kao i svaki drugi element emitiranja.
Dopuštanje agentu da odluči
Najčešće, nije tvoj kod taj koji odlučuje prikazati karticu, već agent, kada razgovor to zahtijeva. Daj mu alat koji emitira widget s AgentContext.stream_widget: stream_agent_response, viđen u lekciji 17, prenosi ga u sučelje usred odgovora.
from agents import RunContextWrapper, function_tool
from chatkit.agents import AgentContext
@function_tool(description_override="Prikazuje detalje narudžbe kao karticu.")
async def show_order(ctx: RunContextWrapper[AgentContext], number: str) -> str:
data = await get_order_data(number) # tvoj pristup podacima
await ctx.context.stream_widget(order_template.build(data))
return f"Kartica za narudžbu {number} je prikazana."
Dodaj alat na popis tools agenta. Niz koji vrati alat služi modelu, koji tako zna da je kartica na zaslonu i može je komentirati umjesto da je ponavlja.
Klikabilni popis
Za ponudu izbora, ListView prikazuje klikabilne retke. Svaki ListViewItem može nositi radnju, koja se pokreće klikom bez da korisnik mora išta tipkati; sljedeća lekcija pokazuje kako to obraditi na strani poslužitelja.
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"}]})
Iznad limita, ChatKit prikazuje poveznicu „vidi više“.
Ažuriranje widgeta tijekom prikaza
Widget se može razvijati pred očima korisnika, primjerice za prikaz nacrta koji model piše. Daj stream_widget asinkroni generator koji proizvodi uzastopna stanja widgeta: ChatKit izračunava razlike i šalje samo ono što se mijenja.
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})
# Konačno stanje, kada je tekst potpun
yield draft_template.build({"text": text, "in_progress": False})
Samo komponente Text i Markdown s id-om prikazuju svoja ažuriranja u streamu, riječ po riječ; za ostale, ChatKit zamjenjuje modificirani dio widgeta.
Što je s Python klasama?
Naići ćeš, čak i u OpenAI vodičima, na widgete građene s klasama: Card(children=[Text(value="…")]). One još uvijek rade, ali openai-chatkit 1.6.5 SDK proglašava ih zastarjelima u korist WidgetTemplate: njihova upotreba emitira upozorenje koje upućuje na .widget datoteke. Za novi projekt, kreni od predložaka. Za postojeći projekt, migriraj vlastitim tempom: upozorenje ništa ne blokira, ali zastarjela klasa može nestati u budućoj verziji.
Kada koristiti widget
Dokumentacija navodi tipične upotrebe:
- prikupljanje strukturiranog unosa obrascem ili prikaz bogatog rezultata (tablica, kartica, grafikon) koji tekst loše renderira;
- ponuda izbora između nekoliko opcija;
- kombiniranje widgeta s radnjama za validaciju odabira, potvrdu koraka ili pokretanje obrade na strani poslužitelja;
- pratnja kratkog objašnjenja interaktivnom naredbom.
Suprotno tome, ne stavljaj ih svugdje. Widget koji ponavlja riječ po riječ ono što tekst kaže ne dodaje ništa, a razgovor zasićen karticama postaje jednako težak za čitanje kao i zid teksta.
Ključne točke
- ChatKit widget je deklarativni opis (JSON) koji gradi tvoj poslužitelj, a ne React komponenta: ChatKit ga sam iscrtava
- Tri kontejnera:
Card(samostalni sadržaj),ListView(popis opcija),Basic(pregledi entiteta) - Dizajniraj u Widget Builderu, izvezi
.widgetdatoteku, učitaj je sWidgetTemplate.from_file(...), i popuni sbuild(data); klaseCard,Text… su zastarjele - Emitiraj s
stream_widgetizrespond, ili iz alata agenta sctx.context.stream_widget - Asinkroni generator ažurira widget uživo; samo
TextiMarkdownsid-om streamaju riječ po riječ