Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Interaktiivsed vidinad

Õppetund 19 / 25 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Mis on ChatKiti vidin?
  2. Konteinerid ja komponendid
  3. Vidina kujundamine Vidinate koostajas
  4. Mida mall sisaldab
  5. Vidina kuvamine respond kaudu
  6. Otsuse langetamine agendi poolt
  7. Klõpsatav loend
  8. Vidina uuendamine kuvamise ajal
  9. Mis saab Pythoni klassidest?
  10. Millal vidinat kasutada
  11. Peamised punktid

Tund kirjutati ümber 3. novembril 2026. Eelmine versioon kirjeldas vidinaid arendaja kirjutatud ja liidesesse registreeritud Reacti komponentidena, kasutades olematut moodulit @openai/chatkit/react. ChatKitis on vidin deklaratiiivne kirjeldus, mille koostab sinu server ja mille ChatKit ise renderdab. See tund järgib openai-chatkit Pythoni SDK versiooni 1.6.5, mis loob vidinaid .widget mallidest: selle Card, Text, Badge… klassid on iganenud. Näited käivitati kohalikus ChatKiti serveris. Allikad: ChatKiti vidinad · Vidinad (Pythoni SDK) · Interaktiivsete vastuste loomine vidinatega · Vidinate koostaja.

Mis on ChatKiti vidin?

Tekstivastus sobib selgitusteks. Kuid tellimuse esitamiseks, kolme paketi võrdlemiseks või kohtumise kinnitamiseks muutub tekst kiiresti realeaks, mida kasutaja peab uuesti läbi lugema. Vidinad asendavad selle teksti liidesega: kaardi, loendi, vormi või diagrammiga, mis kuvatakse vestlusvoos.

Lähenemine on deklaratiiivne. Sinu server ei edasta ei HTML-i ega Reacti komponenti: see kirjeldab vidinat JSON-formaadis, kasutades suletud hulka komponente ja omadusi, ning saadab selle lõimesse täieõigusliku elemendina (WidgetItem). ChatKit joonistab selle oma komponentidega, kasutades eelmises tunnis käsitletud teemavärve. Sellest tulenevad kaks järeldust:

  • Saad kasutada ainult komponente ja omadusi, mida ChatKit tunneb. Tasuks jääb renderdus ülejäänud liidesega kooskõlaliseks ning serverilt ei jõua lehele suvalist HTML-i ega JavaScripti.
  • Vidin on ajaloo osa: järgnevates voorudes teisendatakse see mudeli sisendiks, mistõttu mudel „näeb“, mida ta kasutajale näitas.

Konteinerid ja komponendid

Igal vidinal on juurelement, mis valitakse kolme konteineri seast:

KonteinerKasutus
CardIseseisev sisu: kokkuvõte, kinnitus, vorm. Võtab vastu oleku ning kinnituse/tühistamise nupud sisu all
ListViewValikute hulk: restoranid, failid, tellimused. Selle lapsed on ListViewItem-id, sisseehitatud „vaata rohkem“ funktsionaalsusega (limit)
BasicReserveeritud üksuste eelvaadetele, mis kuvatakse mainimisel hõljumisel

Seespool koostad komponendid: tekst (Title, Text, Caption, Markdown), sildid (Badge), paigutus (Row, Col, Box, Spacer, Divider), meedia (Image, Icon), käsud (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, mida Form saab rühmitada), diagrammid (Chart) ja animatsioonid (Transition). Vidinate koostaja komponentide leht loetleb ühe omadused koos redaktoriga nende proovimiseks.

Vidina kujundamine Vidinate koostajas

Soovitatav töövoog algab ChatKit Studio Vidinate koostajast. Kujundad seal paigutuse, täidad andmepaneeli näidisväärtustega, et hinnata renderdust, ja seejärel ekspordid .widget faili. See on JSON-fail, mis ühendab malli, oodatavate andmete skeemi (jsonSchema) ja näidisandmed. Versioonihalda seda koos oma serverikoodiga, näiteks kaustas widgets/.

Serveripoolselt laadib WidgetTemplate faili ja build täidab selle tegelike andmetega:

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

Suhteline tee lahendatakse Pythoni failist, mis kutsub from_file, mitte käivituskataloogist. build aktsepteerib sõnastikku või Pydanticu mudelit.

Mida mall sisaldab

Mall on Jinja mudel, mis toodab vidina JSON-i. Tellimuse kaardi mall näeb välja selline:

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

Sa kirjutad malle harva käsitsi, kuna Vidinate koostaja genereerib need. Kuid ühe lugemine säästab aega, kui tekib esimene probleem. Kolm märkust:

  • Filter tojson teisendab iga väärtuse kehtivaks JSON-iks (jutumärkides string, tõeväärtus kui true või false) ja ekraanib erimärgid: tootenimes olev ülakoma või jutumärk ei riku JSON-i.
  • Jinja töötab ranges režiimis: puuduvad andmed põhjustavad build ebaõnnestumise, mitte pooltühja vidina loomise.
  • build ei valideeri andmeid jsonSchema vastu. See skeem dokumenteerib andmeid; kui need pärinevad tööriistast või andmebaasist, valideeri need eelnevalt, näiteks Pydanticu mudeliga.

Konstruktor WidgetTemplate(...) võtab sama sisu juba loetud .widget failist: see on kasulik testide jaoks või koodi poolt genereeritud malli puhul.

Vidina kuvamine respond kaudu

Vidina lõimesse saatmiseks toodab stream_widget vastavad ChatKiti sündmused. Edastad need oma respond meetodist:

from chatkit.server import stream_widget

# Sinu ChatKitServer klassis
async def respond(self, thread, input_user_message, context):
    card = order_template.build(await get_order_data("C-42"))  # sinu andmed
    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 on tekst, mis kopeeritakse lõikelauale, kui kasutaja klõpsab vastuse all olevat kopeerimisnuppu. Server salvestab vidina ise poodi nagu iga edastatava elemendi.

Otsuse langetamine agendi poolt

Enamasti ei otsusta kaardi kuvamist sinu kood, vaid agent, kui vestlus seda nõuab. Anna talle tööriist, mis edastab vidina funktsiooniga AgentContext.stream_widget: stream_agent_response, mida nähti tunnis 17, edastab selle liidesesse vastuse keskele.

from agents import RunContextWrapper, function_tool
from chatkit.agents import AgentContext


@function_tool(description_override="Kuvab tellimuse üksikasjad kaardina.")
async def show_order(ctx: RunContextWrapper[AgentContext], number: str) -> str:
    data = await get_order_data(number)  # sinu andmete juurdepääs
    await ctx.context.stream_widget(order_template.build(data))
    return f"Tellimuse {number} kaart on kuvatud."

Lisa tööriist agendi tools loendisse. Tööriista tagastatud string teenib mudelit, mis teab seega, et kaart on ekraanil, ja saab seda kommenteerida, selle asemel et seda korrata.

Klõpsatav loend

Valiku pakkumiseks esitab ListView klõpsatavad read. Iga ListViewItem võib kanda tegevust, mis käivitub klõpsamisel ilma, et kasutaja peaks midagi trükkima; järgmine tund näitab, kuidas seda serveripoolselt käsitleda.

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

Piirangust limit kaugemale kuvab ChatKit lingi „vaata rohkem“.

Vidina uuendamine kuvamise ajal

Vidin võib kasutaja silme all muutuda, näiteks mustandi kuvamiseks, mida mudel parajasti kirjutab. Anna stream_widget-ile asünkroonne generaator, mis toodab vidina järjestikuseid olekuid: ChatKit arvutab erinevused ja saadab ainult muutunud osa.

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})
    # Lõppolek, kui tekst on valmis
    yield draft_template.build({"text": text, "in_progress": False})

Ainult Text ja Markdown komponendid, millel on id, kuvavad oma uuendusi voona, sõna haaval; teiste puhul asendab ChatKit vidina muudetud osa.

Mis saab Pythoni klassidest?

Kohtad isegi OpenAI juhendites vidinaid, mis on ehitatud klassidega: Card(children=[Text(value="…")]). Need toimivad endiselt, kuid openai-chatkit 1.6.5 SDK kuulutab need iganenuks WidgetTemplate kasuks: nende kasutamine tekitab hoiatuse, viidates .widget failidele. Uue projekti puhul alusta mallidest. Olemasoleva projekti puhul vii üle oma tempos: hoiatus ei blokeeri midagi, kuid iganenud klass võib tulevases versioonis kaduda.

Millal vidinat kasutada

Dokumentatsioon toob välja tüüpilised kasutusjuhud:

  • struktureeritud sisu kogumine vormiga või rikka tulemuse (tabel, kaart, diagramm) esitamine, mida tekst halvasti edasi annab;
  • valiku pakkumine mitme variandi vahel;
  • vidina kombineerimine tegevustega, et valideerida valik, kinnitada samm või käivitada serveripoolne töötlemine;
  • lühikese selgitava teksti kõrvale interaktiivse käsuga kaasamine.

Vastupidiselt ära paiguta neid igale poole. Vidin, mis kordab sõna-sõnalt seda, mida tekst ütleb, ei lisa midagi, ja kaartidega küllastunud vestlus muutub sama raskesti loetavaks kui tekstisein.

Peamised punktid

  • ChatKiti vidin on sinu serveri loodud deklaratiiivne kirjeldus (JSON), mitte Reacti komponent: ChatKit renderdab selle ise
  • Kolm konteinerit: Card (iseseisev sisu), ListView (valikute loend), Basic (üksuste eelvaated)
  • Kujunda Vidinate koostajas, ekspordi .widget fail, laadi see WidgetTemplate.from_file(...)-ga ja täida build(data)-ga; klassid Card, Text… on iganenud
  • Edasta stream_widget-ga respond-ist või agendi tööriistast ctx.context.stream_widget kaudu
  • Asünkroonne generaator uuendab vidinat reaalajas; ainult Text ja Markdown koos id-ga voogavad sõna haaval