Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Gradniki z vmesnikom

Lekcija 19 od 25 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Kaj je gradnik ChatKit?
  2. Zabojniki in komponente
  3. Načrtovanje gradnika v Graditelju gradnikov
  4. Kaj vsebuje predloga?
  5. Prikaz gradnika iz respond
  6. Odločitev prepustiš agentu
  7. Seznam s klikom
  8. Posodobitev gradnika med prikazom
  9. Kaj pa razredi Python?
  10. Kdaj uporabiti gradnik
  11. Ključne ugotovitve

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 SDK openai-chatkit različice 1.6.5, ki gradi gradnike iz predlog .widget: njegovi razredi Card, 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:

ZabojnikUporaba
CardSamostojna vsebina: povzetek, potrditev, obrazec. Sprejme stanje in gumbe za potrditev/preklic pod vsebino
ListViewNabor možnosti: restavracije, datoteke, naročila. Njegovi otroci so ListViewItem z vgrajeno funkcionalnostjo „poglej več” (limit)
BasicRezerviran 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 tojson vsako vrednost pretvori v veljaven JSON (niz v narekovajih, boolean kot true ali false) 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.
  • build ne preverja podatkov glede na jsonSchema. 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 z WidgetTemplate.from_file(...) in napolni z build(data); razredi Card, Text… so zastareli
  • Oddajaj z stream_widget iz respond ali iz orodja agenta z ctx.context.stream_widget
  • Asinhroni generator posodablja gradnik v živo; le Text in Markdown z id streamata besedo za besedo