Gradniki z vmesnikom
Na tej strani
Lekcija na novo napisana 3. novembra 2026. Prejšnja različica je gradnike opisovala kot komponente React, ki jih napiše razvijalec in registrira v vmesniku, z uporabo neobstoječega modula
@openai/chatkit/react. V ChatKitu je gradnik deklarativni opis, ki ga zgradi vaš strežnik, ChatKit pa ga sam izriše. Ta lekcija sledi Python SDKopenai-chatkitrazličice 1.6.5, ki gradi gradnike iz predlog.widget: njegovi razrediCard,Text,Badge… so zastareli. Primeri so bili izvedeni na lokalnem strežniku ChatKit. Viri: Gradniki ChatKit · Gradniki (Python SDK) · Izgradnja interaktivnih odgovorov z gradniki · Graditelj gradnikov.
Kaj je gradnik ChatKit?
Besedilni odgovor zadostuje za razlage. A ko želiš predstaviti naročilo, primerjati tri pakete ali potrditi termin, besedilo hitro postane zid vrstic, ki jih mora uporabnik znova brati. Gradniki nadomestijo to besedilo z vmesnikom: kartico, seznamom, obrazcem ali grafom, prikazanim znotraj toka pogovora.
Pristop je deklarativen. Vaš strežnik ne dostavi niti HTML niti komponente React: gradnik opiše v JSON-u z uporabo zaprtega nabora komponent in lastnosti ter ga pošlje v nit kot polnopraven element (WidgetItem). ChatKit ga izriše s svojimi komponentami in uporabi barve teme iz prejšnje lekcije. Sledita dve posledici:
- Uporabljaš lahko le komponente in lastnosti, ki jih ChatKit pozna. V zameno ostane izris skladen z ostalim vmesnikom, noben poljuben HTML ali JavaScript s strežnika pa ne pride na stran.
- Gradnik je del zgodovine: v naslednjih korakih se pretvori v vhod za model, ki tako „vidi”, kar je pokazal uporabniku.
Zabojniki in komponente
Vsak gradnik ima koren, izbran med tremi zabojniki:
| Zabojnik | Uporaba |
|---|---|
Card | Samostojna vsebina: povzetek, potrditev, obrazec. Sprejme stanje in gumbe za potrditev/preklic pod vsebino |
ListView | Nabor možnosti: restavracije, datoteke, naročila. Njegovi otroci so ListViewItem z vgrajeno funkcionalnostjo „poglej več” (limit) |
Basic | Rezerviran za predoglede entitet, prikazane ob lebdenju nad omembo |
Znotraj njih sestavljaš komponente: besedilo (Title, Text, Caption, Markdown), oznake (Badge), postavitve (Row, Col, Box, Spacer, Divider), medije (Image, Icon), ukaze (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, ki jih lahko združi Form), grafe (Chart) in animacije (Transition). Stran komponent v Graditelju gradnikov navaja lastnosti vsake od njih in ponuja urejevalnik za preizkušanje.
Načrtovanje gradnika v Graditelju gradnikov
Predvideni potek dela se začne v Graditelju gradnikov studia ChatKit. Tam oblikuješ postavitev, v podatkovno ploščo vneseš vzorčne vrednosti za oceno izrisa in nato izvoziš datoteko .widget. To je datoteka JSON, ki združuje predlogo, shemo pričakovanih podatkov (jsonSchema) in vzorčne podatke. Različico hrani skupaj s kodo strežnika, na primer v mapi widgets/.
Na strani strežnika WidgetTemplate naloži datoteko, build pa jo napolni s pravimi podatki:
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 pot se razreši glede na datoteko Python, ki kliče from_file, ne glede na zagonski imenik. build sprejme slovar ali model Pydantic.
Kaj vsebuje predloga?
Predloga je model Jinja, ki ustvari JSON gradnika. Predloga kartice naročila izgleda takole:
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})
Predloge redko pišeš ročno, saj jo Graditelj gradnikov ustvari sam. A branje ti bo prihranilo čas, ko se pojavi prva težava. Tri opombe:
- Filter
tojsonvsako vrednost pretvori v veljaven JSON (niz v narekovajih, boolean kottruealifalse) in ubeži posebne znake: apostrof ali narekovaj v imenu izdelka ne bo pokvaril JSON-a. - Jinja teče v strogem načinu: manjkajoči podatki povzročijo neuspeh
build, namesto da bi nastal polprazen gradnik. buildne preverja podatkov glede najsonSchema. Ta shema dokumentira podatke; če prihajajo iz orodja ali baze podatkov, jih prej preveri, na primer z modelom Pydantic.
Konstruktor WidgetTemplate(...) sprejme enako vsebino kot že prebrana datoteka .widget: to je priročno za teste ali za predlogo, ki jo generira tvoja koda.
Prikaz gradnika iz respond
Če želiš poslati gradnik v nit, stream_widget ustvari ustrezne dogodke ChatKit. Te posreduješ iz svoje metode respond:
from chatkit.server import stream_widget
# V vašem razredu ChatKitServer
async def respond(self, thread, input_user_message, context):
card = order_template.build(await get_order_data("C-42")) # vaši podatki
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 besedilo, kopirano v odložišče, ko uporabnik klikne gumb za kopiranje pod odgovorom. Strežnik sam shrani gradnik v shrambo kot vsak drug oddani element.
Odločitev prepustiš agentu
Najpogosteje ne odloči tvoja koda, kdaj prikazati kartico, temveč agent, ko to zahteva pogovor. Daj mu orodje, ki oddaja gradnik z AgentContext.stream_widget: stream_agent_response, obravnavano v lekciji 17, ga posreduje vmesniku sredi odgovora.
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) # vaš dostop do podatkov
await ctx.context.stream_widget(order_template.build(data))
return f"The card for order {number} is displayed."
Orodje dodaj na seznam tools agenta. Niz, ki ga vrne orodje, služi modelu, ki tako ve, da je kartica na zaslonu, in jo lahko komentira namesto da bi jo ponavljal.
Seznam s klikom
Za ponudbo izbire ListView predstavi klikljive vrstice. Vsak ListViewItem lahko nosi dejanje, sproženo ob kliku, brez da bi moral uporabnik karkoli tipkati; naslednja lekcija prikazuje, kako to obravnavati na strani strežnika.
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"}]})
Poleg limit ChatKit prikaže povezavo „poglej več”.
Posodobitev gradnika med prikazom
Gradnik se lahko razvija pred očmi uporabnika, na primer za prikaz osnutka, ki ga piše model. Podaj stream_widget asinhroni generator, ki proizvaja zaporedna stanja gradnika: ChatKit izračuna razlike in pošlje le tisto, kar se spremeni.
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})
# Končno stanje, ko je besedilo končano
yield draft_template.build({"text": text, "in_progress": False})
Le komponenti Text in Markdown z id prikazujeta posodobitve v toku, besedo za besedo; pri drugih ChatKit nadomesti spremenjeni del gradnika.
Kaj pa razredi Python?
Naletel boš, celo v vodilih OpenAI, na gradnike, zgrajene z razredi: Card(children=[Text(value="…")]). Še vedno delujejo, a SDK openai-chatkit 1.6.5 declares them deprecated v korist WidgetTemplate: njihova uporaba sproži opozorilo, ki kaže na datoteke .widget. Za nov projekt začni s predlogami. Za obstoječ projekt migriraj po svojem tempu: opozorilo ničesar ne blokira, a zastareli razred lahko izgine v prihodnji različici.
Kdaj uporabiti gradnik
Dokumentacija navaja tipične uporabe:
- zbiranje strukturiranega vnosa z obrazcem ali predstavitev bogatega rezultata (tabela, kartica, graf), ki ga besedilo slabo izriše;
- ponudba izbire med več možnostmi;
- združitev gradnika z dejanji za potrditev izbire, potrditev koraka ali zagon obdelave na strani strežnika;
- spremstvo kratkega pojasnjevalnega besedila z interaktivnim ukazom.
Nasprotno, ne postavljaj jih povsod. Gradnik, ki besedo za besedo ponavlja tisto, kar pravi besedilo, ne doda ničesar, pogovor, nasičen s karticami, pa postane težko berljiv kot zid besedila.
Ključne ugotovitve
- Gradnik ChatKit je deklarativni opis (JSON), ki ga zgradi tvoj strežnik, ne komponenta React: ChatKit ga sam izriše
- Trije zabojniki:
Card(samostojna vsebina),ListView(seznam možnosti),Basic(predogledi entitet) - Načrtuj v Graditelju gradnikov, izvozi datoteko
.widget, naloži jo zWidgetTemplate.from_file(...)in napolni zbuild(data); razrediCard,Text… so zastareli - Oddajaj z
stream_widgetizrespondali iz orodja agenta zctx.context.stream_widget - Asinhroni generator posodablja gradnik v živo; le
TextinMarkdownzidstreamata besedo za besedo