Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Widgeti interaktivni

Lekcija 19 od 25 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Što je ChatKit widget?
  2. Kontejneri i komponente
  3. Dizajniranje widgeta u Widget Builderu
  4. Što predložak sadrži
  5. Prikazivanje widgeta iz respond
  6. Dopuštanje agentu da odluči
  7. Klikabilni popis
  8. Ažuriranje widgeta tijekom prikaza
  9. Što je s Python klasama?
  10. Kada koristiti widget
  11. Ključne točke

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 prati openai-chatkit Python SDK 1.6.5, koji gradi widgete iz .widget predložaka: njegove klase Card, 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:

KontejnerUpotreba
CardSamostalni sadržaj: sažetak, potvrda, obrazac. Prihvaća status i gumbe za potvrdu/odustajanje ispod sadržaja
ListViewSkup opcija: restorani, datoteke, narudžbe. Njegova djeca su ListViewItemi, s ugrađenom funkcionalnošću „vidi više“ (limit)
BasicRezervirano 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 tojson pretvara svaku vrijednost u valjani JSON (navodnik stringa, boolean kao true ili false) 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.
  • build ne validira podatke protiv jsonSchema. 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 .widget datoteku, učitaj je s WidgetTemplate.from_file(...), i popuni s build(data); klase Card, Text… su zastarjele
  • Emitiraj s stream_widget iz respond, ili iz alata agenta s ctx.context.stream_widget
  • Asinkroni generator ažurira widget uživo; samo Text i Markdown s id-om streamaju riječ po riječ