Valdikliai (Widgets)
Šiame puslapyje
Pamoka perrašyta 2026 m. lapkričio 3 d. Ankstesnė versija apibūdino valdiklius kaip kūrėjo rašytus „React“ komponentus, registruojamus sąsajoje naudojant neegzistuojantį
@openai/chatkit/reactmodulį. „ChatKit“ sistemoje valdiklis yra deklaratyvus aprašymas, kurį sukuria jūsų serveris, o „ChatKit“ jį atvaizduoja pati. Ši pamoka remiasiopenai-chatkitPython SDK 1.6.5 versija, kuri kuria valdiklius iš.widgetšablonų: josCard,Text,Badge… klasės yra pasenusios (deprecated). Pavyzdžiai buvo vykdomi vietiniame „ChatKit“ serveryje. Šaltiniai: ChatKit valdikliai · Valdikliai (Python SDK) · Interaktyvių atsakymų kūrimas naudojant valdiklius · Valdiklių kūrimo įrankis (Widget Builder).
Kas yra „ChatKit“ valdiklis?
Tekstinio atsakymo pakanka paaiškinimams. Tačiau norint pateikti užsakymą, palyginti tris planus arba patvirtinti susitikimą, tekstas greitai virsta eilučių siena, kurią vartotojas turi perskaityti iš naujo. Valdikliai pakeičia tą tekstą sąsaja: kortele, sąrašu, forma arba diagrama, rodoma tiesiogiai pokalbio eigose.
Požiūris yra deklaratyvus. Jūsų serveris nepateikia nei HTML, nei „React“ komponento: jis aprašo valdiklį JSON formatu, naudodamas uždarą komponentų ir savybių rinkinį, ir siunčia jį į pokalbį kaip pilnavertį elementą (WidgetItem). „ChatKit“ jį nupiešia naudodama savo komponentus ir ankstesnėje pamokoje aptartas temos spalvas. Iš to išplaukia dvi pasekmės:
- Galite naudoti tik tuos komponentus ir savybes, kuriuos „ChatKit“ žino. Už tai atvaizdavimas lieka nuoseklus su visa sąsaja, o į puslapį nepatenka joks savavališkas serverio HTML arba JavaScript kodas.
- Valdiklis tampa istorijos dalimi: vėlesniuose pokalbio etapuose jis konvertuojamas į modelio įvestį, todėl modelis „mato“, ką parodė vartotojui.
Konteineriai ir komponentai
Kiekvienas valdiklis turi šakninį elementą, pasirenkamą iš trijų konteinerių:
| Konteineris | Naudojimas |
|---|---|
Card | Savarankiškas turinys: santrauka, patvirtinimas, forma. Priima būseną ir patvirtinimo/atšaukimo mygtukus po turiniu |
ListView | Parinkčių rinkinys: restoranai, failai, užsakymai. Jo vaikiniai elementai yra ListViewItem, turintys integruotą „žiūrėti daugiau“ funkcionalumą (limit) |
Basic | Skirtas entitetų peržiūroms, rodomoms užvedus pelę ant paminėjimo |
Viduje jūs surenkate komponentus: tekstą (Title, Text, Caption, Markdown), etiketes (Badge), išdėstymą (Row, Col, Box, Spacer, Divider), mediją (Image, Icon), komandas (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, kuriuos gali sugrupuoti Form), diagramas (Chart) ir animacijas (Transition). Valdiklių kūrimo įrankio komponentų puslapyje išvardytos kiekvieno savybės ir pateiktas redaktorius jiems išbandyti.
Valdiklio projektavimas naudojant „Widget Builder“
Rekomenduojama darbo eiga prasideda „ChatKit Studio“ Valdiklių kūrimo įrankyje. Ten sukuriate išdėstymą, užpildote duomenų skydelį pavyzdinėmis reikšmėmis, kad įvertintumėte atvaizdavimą, ir tada eksportuojate .widget failą. Tai JSON failas, kuriame sujungiamas šablonas, tikėtinų duomenų schema (jsonSchema) ir pavyzdiniai duomenys. Saugokite jį versijų kontrolėje kartu su serverio kodu, pavyzdžiui, aplanke widgets/.
Serverio pusėje WidgetTemplate įkelia failą, o build užpildo jį tikrais duomenimis:
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",
})
Santykinis kelias išsprendžiamas nuo Python failo, kuris kviečia from_file, o ne nuo paleidimo katalogo. build priima žodyną arba Pydantic modelį.
Ką turi šablonas?
Šablonas yra „Jinja“ modelis, kuris sukuria valdiklio JSON. Užsakymo kortelės šablonas atrodo taip:
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})
Šablonų retai rašysite ranka, nes „Widget Builder“ juos sugeneruoja. Tačiau gebėjimas juos skaityti sutaupys laiko, kai iškils pirmoji problema. Trys pastabos:
- Filtras
tojsonkiekvieną reikšmę konvertuoja į tinkamą JSON (citatuotą eilutę, boolean kaiptruearbafalse) ir išvengia specialių simbolių: apostrofas arba kabutės produkto pavadinime nesugadins JSON. - „Jinja“ veikia griežtu režimu: trūkstami duomenys priverčia
buildnepavykti, užuot kūrus pusiau tuščią valdiklį. buildnetikrina duomenų pagaljsonSchema. Ši schema dokumentuoja duomenis; jei jie ateina iš įrankio ar duomenų bazės, patikrinkite juos iš anksto, pavyzdžiui, naudodami Pydantic modelį.
Konstruktorius WidgetTemplate(...) priima tą patį turinį kaip jau nuskaitytas .widget failas: tai patogu testams arba šablonui, sugeneruotam jūsų pačių kodo.
Valdiklio rodymas iš respond
Norėdami išsiųsti valdiklį į pokalbį, stream_widget sukuria atitinkamus „ChatKit“ įvykius. Jūs juos perduodate iš savo respond metodo:
from chatkit.server import stream_widget
# Jūsų ChatKitServer klasėje
async def respond(self, thread, input_user_message, context):
card = order_template.build(await get_order_data("C-42")) # jūsų duomenys
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 yra tekstas, nukopijuojamas į iškarpinę, kai vartotojas paspaudžia kopijavimo mygtuką po atsakymu. Serveris pats išsaugo valdiklį saugykloje (store), kaip ir bet kurį kitą transliuojamą elementą.
Leidimas agentui spręsti
Dažniausiai ne jūsų kodas nusprendžia rodyti kortelę, o agentas, kai pokalbis to reikalauja. Suteikite jam įrankį, kuris transliuoja valdiklį naudodamas AgentContext.stream_widget: stream_agent_response, matytas 17 pamokoje, perduoda jį sąsajai atsakymo viduryje.
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) # jūsų duomenų prieiga
await ctx.context.stream_widget(order_template.build(data))
return f"The card for order {number} is displayed."
Pridėkite įrankį prie agento tools sąrašo. Įrankio grąžinta eilutė skirta modeliui, kuris taip žino, kad kortelė yra ekrane, ir gali ją komentuoti užuot ją kartojęs.
Paspaudžiamas sąrašas
Norėdami pasiūlyti pasirinkimą, ListView pateikia paspaudžiamas eilutes. Kiekvienas ListViewItem gali turėti veiksmą, suaktyvinamą paspaudus, nereikalaujant, kad vartotojas ką nors rašytų; kitoje pamokoje parodysime, kaip tai apdoroti serverio pusėje.
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"}]})
Viršijus limit, „ChatKit“ rodo nuorodą „žiūrėti daugiau“.
Valdiklio atnaujinimas rodymo metu
Valdiklis gali keistis vartotojo akivaizdoje, pavyzdžiui, norint parodyti juodraštį, kurį rašo modelis. Pateikite stream_widget asinchroninį generatorių, kuris gamina nuoseklias valdiklio būsenas: „ChatKit“ apskaičiuoja skirtumus ir siunčia tik tai, kas pasikeitė.
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})
# Galutinė būsena, kai tekstas baigtas
yield draft_template.build({"text": text, "in_progress": False})
Tik Text ir Markdown komponentai su id rodo savo atnaujinimus srautu, žodis po žodžio; kitiems „ChatKit“ pakeičia tik modifikuotą valdiklio dalį.
O kaip dėl Python klasių?
Net ir „OpenAI“ gairėse sutiksite valdiklių, sukurtų naudojant klases: Card(children=[Text(value="…")]). Jos vis dar veikia, tačiau openai-chatkit 1.6.5 SDK jas skelbia pasenusiomis WidgetTemplate naudai: jų naudojimas išmeta įspėjimą, nukreipiantį į .widget failus. Naujam projektui pradėkite nuo šablonų. Esamam projektui migruokite savo tempu: įspėjimas nieko neblokuoja, tačiau pasenusi klasė gali išnykti būsimose versijose.
Kada naudoti valdiklį?
Dokumentacijoje nurodomi tipiniai naudojimo atvejai:
- struktūruotos įvesties rinkimas naudojant formą arba turtingo rezultato (lentelės, kortelės, diagramos) pateikimas, kurį tekstas atvaizduoja prastai;
- pasirinkimo siūlymas tarp kelių parinkčių;
- valdiklio derinimas su veiksmais, norint patvirtinti pasirinkimą, patvirtinti žingsnį arba paleisti serverio pusės apdorojimą;
- trumpo paaiškinamojo teksto papildymas interaktyvia komanda.
Kita vertus, nedėkite jų visur. Valdiklis, kuris žodis žodin kartoja tai, ką sako tekstas, nieko neprideda, o pokalbis, perpildytas kortelėmis, tampa toks pat sunkiai skaitomas kaip teksto siena.
Svarbiausi punktai
- „ChatKit“ valdiklis yra deklaratyvus aprašymas (JSON), kurį kuria jūsų serveris, o ne „React“ komponentas: „ChatKit“ jį atvaizduoja pati
- Trys konteineriai:
Card(savarankiškas turinys),ListView(parinkčių sąrašas),Basic(entitetų peržiūros) - Projektuokite naudodami „Widget Builder“, eksportuokite
.widgetfailą, įkelkite jį suWidgetTemplate.from_file(...)ir užpildykite naudodamibuild(data);Card,Text… klasės yra pasenusios - Transliuokite naudodami
stream_widgetišrespondarba iš agento įrankio naudodamictx.context.stream_widget - Asinchroninis generatorius atnaujina valdiklį gyvai; tik
TextirMarkdownsuidsrautiniu būdu rodo žodžius po vieną