Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Widgets Interattivi

Lezzjoni 19 / 25 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. X’inhu widget ta’ ChatKit?
  2. Kontenituri u komponenti
  3. Id-disinn tal-widget fil-Widget Builder
  4. X’fih mudell
  5. L-esibizzjoni tal-widget minn respond
  6. Il-ħalli l-aġent jiddeċiedi
  7. Lista li tista’ tikklikkjaha
  8. Aġġornament ta’ widget waqt li jkun muri
  9. X’jiġri mill-klassijiet tal-Python?
  10. Meta tuża widget
  11. Punti Ewlenin

Lezzjoni miktuba mill-ġdid fit-3 ta’ Novembru 2026. Il-verżjoni preċedenti kienet tiddeskrivi l-widgets bħala komponenti React miktuba mill-iżviluppatur u rreġistrati fl-interfaċċa, billi tuża modulu @openai/chatkit/react li ma jeżistix. F’ChatKit, widget huwa deskrizzjoni dikjarattiva li is-server tiegħek jibni u li ChatKit jirrendi huwa stess. Din il-lezzjoni ssegwi l-SDK tal-Python openai-chatkit 1.6.5, li jibni l-widgets minn mudelli .widget: il-klassijiet Card, Text, Badge… tiegħu huma skaduti. L-eżempji ġew eżegwiti fuq server ChatKit lokali. Sorsi: ChatKit widgets · Widgets (Python SDK) · Build interactive responses with widgets · Widget Builder.

X’inhu widget ta’ ChatKit?

Tweġiba b’test biżżejjed għall-ispjegazzjonijiet. Iżda biex tippreżenta ordni, tqabbel tliet pjanijiet, jew tikkonferma appuntament, it-test malajr isir ħajt ta’ linji li l-utent irid jerġa’ jaqra. Il-widgets jissostitwixxu dak it-test b’interfaċċa: karta, lista, formola, jew grafika, murija fil-fluss tal-konversazzjoni.

L-approċċ huwa dikjarattiv. Is-server tiegħek ma jwassal la HTML u lanqas komponent React: jiddeskrivi l-widget f’JSON, billi juża sett magħluq ta’ komponenti u proprjetajiet, u jibgħatu fil-thread bħala element sħiħ (a WidgetItem). ChatKit jiġbdu bil-komponenti tiegħu stess, billi juża l-kuluri tat-tema mil-lezzjoni preċedenti. Jirriżultaw żewġ konsegwenzi:

  • Tista’ tuża biss komponenti u proprjetajiet li ChatKit jaf. Min-naħa l-oħra, ir-rendering jibqa’ konsistenti mal-bqija tal-interfaċċa, u l-ebda HTML arbitrarju jew JavaScript mis-server ma jilħaq il-paġna.
  • Il-widget huwa parti mill-istorja: f’dawriet sussegwenti, jiġi kkonvertit f’input għall-mudell, li għalhekk “jara” x’wera lill-utent.

Kontenituri u komponenti

Kull widget għandu għerq, magħżul minn tliet kontenituri:

KonteniturUżu
CardKontenut awtonomu: sommarju, konferma, formola. Jaċċetta status u buttuni ta’ konferma/kanċellazzjoni taħt il-kontenut
ListViewSett ta’ għażliet: ristoranti, fajls, ordnijiet. It-tfal tiegħu huma ListViewItems, b’funzjonalità integrata “ara aktar” (limit)
BasicRiżervat għal previżjonijiet ta’ entitajiet murija meta wieħed ipoġġi l-maws fuq semma

Ġewwa, tgħaqqad komponenti: test (Title, Text, Caption, Markdown), tikketta (Badge), layout (Row, Col, Box, Spacer, Divider), media (Image, Icon), kmandi (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, li Form tista’ tgħaqqad), grafiċi (Chart), u animazzjonijiet (Transition). Il-paġna tal-Komponenti tal-Widget Builder telenka l-proprjetajiet ta’ kull wieħed, b’editur biex tipprovahom.

Id-disinn tal-widget fil-Widget Builder

Il-fluss ta’ xogħol maħsub jibda fil-Widget Builder ta’ ChatKit Studio. Hemmhekk tiddisinja l-layout, timla l-pannel tad-data b’valuri kampjun biex tikkunsidra r-rendering, u mbagħad tesporta fajl .widget. Dan huwa fajl JSON li jgħaqqad il-mudell, l-iskema tad-data mistennija (jsonSchema), u d-data kampjun. Ikkontrolla l-verżjoni tiegħu flimkien mal-kodiċi tas-server tiegħek, pereżempju f’folder widgets/.

Fuq in-naħa tas-server, WidgetTemplate itella’ l-fajl u build jimlieh b’data reali:

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

Mogħdija relattiva tiġi solvuta mill-fajl Python li jsejjaħ from_file, mhux mid-direttorju tal-ħruġ. build jaċċetta dizzjunarju jew mudell Pydantic.

X’fih mudell

Il-mudell huwa mudell Jinja li jipproduċi l-JSON tal-widget. Il-mudell tal-karta tal-ordni jidher hekk:

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

Rari se tikteb mudell bl-idejn, peress li l-Widget Builder jiġġenerah. Iżda li taqra wieħed iffrankalek ħin meta tinħoloq l-ewwel problema. Tliet osservazzjonijiet:

  • Il-filtru tojson jikkonverti kull valur f’JSON validu (stringa ċċitata, boolean bħala true jew false) u jaħrab karattri speċjali: apostrofu jew kwotazzjoni f’isem prodott ma tkissirx il-JSON.
  • Jinja jaħdem f’mod strett: data nieqsa tikkawża li build ifalli, minflok ma jipproduċi widget nofsu vojt.
  • build ma jivvalidax id-data kontra l-jsonSchema. Din l-iskema tiddokumenta d-data; jekk tiġi minn għodda jew database, ivvalidaha minn qabel, pereżempju b’mudell Pydantic.

Il-kostruttur WidgetTemplate(...) jieħu l-istess kontenut bħal fajl .widget diġà moqri: dan huwa utli għat-testijiet, jew għal mudell iġġenerat mill-kodiċi tiegħek stess.

L-esibizzjoni tal-widget minn respond

Biex tibgħat il-widget fit-thread, stream_widget jipproduċi l-avvenimenti korrispondenti ta’ ChatKit. Inti tgħaddihom mill-metodu respond tiegħek:

from chatkit.server import stream_widget

# Fil-klassi ChatKitServer tiegħek
async def respond(self, thread, input_user_message, context):
    card = order_template.build(await get_order_data("C-42"))  # id-data tiegħek
    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 huwa t-test ikkupjat fil-clipboard meta l-utent jikklikkja l-buttuna tal-kopja taħt it-tweġiba. Is-server isalva l-widget fil-maħżen innifsu, bħal kull element tax-xandir.

Il-ħalli l-aġent jiddeċiedi

L-aktar spiss, mhux il-kodiċi tiegħek li jiddeċiedi li juri karta, iżda l-aġent, meta l-konversazzjoni titlobha. Agħtih għodda li xxandar il-widget b’AgentContext.stream_widget: stream_agent_response, meħuda mil-lezzjoni 17, tittrażmettih lill-interfaċċa f’nofs it-tweġiba.

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)  # l-aċċess għad-data tiegħek
    await ctx.context.stream_widget(order_template.build(data))
    return f"The card for order {number} is displayed."

Żid l-għodda fil-lista tools tal-aġent. L-istringa rritornata mill-għodda sservi lill-mudell, li għalhekk ikun jaf li l-karta tinsab fuq l-iskrin u jista’ jikkummenta fuqha minflok ma jerġa’ jgħidha.

Lista li tista’ tikklikkjaha

Biex toffri għażla, ListView tippreżenta ringieli li jistgħu jiġu kklikkjati. Kull ListViewItem jista’ ġġorr azzjoni, attivata bil-klikk mingħajr ma l-utent ikollu jikteb xejn; il-lezzjoni li jmiss turi kif timmaniġġjah fuq in-naħa tas-server.

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

Lil hinn mil-limit, ChatKit juri link “ara aktar”.

Aġġornament ta’ widget waqt li jkun muri

Widget jista’ jevolvi quddiem għajnejn l-utent, pereżempju biex juri abbozz li l-mudell qed jikteb. Agħti lil stream_widget ġeneratur asinkronu li jipproduċi stati suċċessivi tal-widget: ChatKit jikkalkula d-differenzi u jibgħat biss dak li jinbidel.

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})
    # Stat finali, ladarba t-test ikun komplut
    yield draft_template.build({"text": text, "in_progress": False})

Biss il-komponenti Text u Markdown b’id juru l-aġġornamenti tagħhom f’fluss, kelma b’kelma; għal oħrajn, ChatKit jissostitwixxi l-parti mmodifikata tal-widget.

X’jiġri mill-klassijiet tal-Python?

Se tiltaqa’, anke fil-gwidi ta’ OpenAI, ma’ widgets mibnija b’klassijiet: Card(children=[Text(value="…")]). Għadhom jaħdmu, iżda l-SDK openai-chatkit 1.6.5 jiddikjarahom skaduti favur WidgetTemplate: l-użu tagħhom joħroġ twissija li tissuġġerixxi fajls .widget. Għal proġett ġdid, ibda minn mudelli. Għal proġett eżistenti, immigra bir-ritmu tiegħek: it-twissija ma timblokka xejn, iżda klassi skaduta tista’ tisparixxi f’verżjoni futura.

Meta tuża widget

Id-dokumentazzjoni tiċċita użi tipiċi:

  • il-ġbir ta’ input strutturat b’formola, jew il-preżentazzjoni ta’ riżultat rikk (tabella, karta, grafika) li t-test jirrendi ħażin;
  • l-offerta ta’ għażla bejn diversi għażliet;
  • il-kombinazzjoni tal-widget ma’ azzjonijiet, biex tivvalida għażla, tikkonferma pass, jew tniedi ipproċessar fuq in-naħa tas-server;
  • l-akkumpanjament ta’ test spjegattiv qasir b’kmand interattiv.

Min-naħa l-oħra, tpoġġihomx kullimkien. Widget li jirrepeti kelma b’kelma dak li jgħid it-test ma jżid xejn, u konversazzjoni mimlija karti ssir diffiċli biex taqra daqs ħajt ta’ test.

Punti Ewlenin

  • Widget ta’ ChatKit huwa deskrizzjoni dikjarattiva (JSON) mibnija mis-server tiegħek, mhux komponent React: ChatKit jirrendih huwa stess
  • Tliet kontenituri: Card (kontenut awtonomu), ListView (lista ta’ għażliet), Basic (previżjonijiet ta’ entitajiet)
  • Iddisinja fil-Widget Builder, esporta fajl .widget, itlagħh b’WidgetTemplate.from_file(...), u imlieh b’build(data); il-klassijiet Card, Text… huma skaduti
  • Ixandar b’stream_widget minn respond, jew minn għodda tal-aġent b’ctx.context.stream_widget
  • Ġeneratur asinkronu jaġġorna l-widget ħaj; biss Text u Markdown b’id jixandru kelma b’kelma