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

Azzjonijiet tal-Utent

Lezzjoni 20 / 25 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. X’inhi azzjoni?
  2. Ipproċessar ta’ azzjoni fuq is-server
  3. Formoli
  4. Ikkonferma qabel ma taġixxi
  5. Ipproċessar ta’ azzjoni fil-browser
  6. Stati ta’ tagħbija
  7. Punti Ewlenin

Lezzjoni miktuba mill-ġdid fit-3 ta’ Novembru 2026. Il-verżjoni preċedenti kienet tittratta l-klikks f’komponenti React personalizzati u ħolqot “azzjonijiet ta’ suġġeriment” inventati. F’ChatKit, azzjoni hija oġġett imwaħħal ma’ komponent widget (buttuna, ringiela ta’ lista, formola). B’mod default, tiġi pproċessata fis-server tiegħek fil-metodu action ta’ ChatKitServer, jew fil-browser jekk tispeċifika mod ieħor. Din il-lezzjoni ssegwi l-gwida Actions in ChatKit u l-SDK openai-chatkit 1.6.5. Is-server, it-templates, u l-formola tħaddmu lokalment; il-kodiċi React ġie vverifikat permezz tal-kompilazzjoni. Sorsi: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.

X’inhi azzjoni?

Widget li juri biss kontenut huwa sempliċiment tweġiba sabiħa. L-azzjonijiet jagħmluha utli: il-klikk fuq “Ikkanċella l-Ordni”, l-għażla ta’ ringiela f’lista, jew is-sottomissjoni ta’ formola jattivaw l-ipproċessar mingħajr ma l-utent ikollu jikteb messaġġ. ChatKit jibgħat l-azzjoni lis-server tiegħek, li jista’ jaġixxi fuq is-sistemi tiegħek, jaġġorna l-widget, iżid tweġiba fit-thread, jew jerġa’ jibda l-aġent.

Tiddikjara azzjoni fit-template tal-widget fuq komponent li jaċċettaha (onClickAction għal Button jew ListViewItem, onChangeAction għal Select, onSubmitAction għal Form, confirm u cancel għal Card). Huwa oġġett JSON żgħir:

QasamRwol
typeL-isem tal-azzjoni li l-kodiċi tiegħek jittestja: "order.cancel"
payloadData utli: {"number": "C-42"}
handler"server" (default) jew "client" biex tipproċessaha fil-browser
loadingBehaviorL-istat ta’ tagħbija muri waqt l-ipproċessar (ara hawn taħt)

Ipproċessar ta’ azzjoni fuq is-server

Ħa nieħdu kard tal-ordni li toffri l-kanċellazzjoni. It-template jiddikjara l-azzjoni fuq il-buttuni ta’ konferma u kanċellazzjoni tal-Card:

CANCEL_TEMPLATE = """
{
  "type": "Card",
  "children": [
    {"type": "Title", "value": {{ ("Order " ~ number) | tojson }}, "size": "sm"},
    {"type": "Text", "value": "Do you really want to cancel this order?"}
  ],
  "confirm": {"label": "Cancel Order",
              "action": {"type": "order.cancel", "payload": {"number": {{ number | tojson }}}}},
  "cancel": {"label": "Keep Order",
             "action": {"type": "order.keep", "payload": {"number": {{ number | tojson }}}}}
}
"""

Fuq in-naħa tas-server, żid metodu action fil-ChatKitServer tiegħek. Jirċievi t-thread, l-azzjoni, il-widget li emettiha (sender), u l-kuntest tiegħek, u jirritorna avvenimenti bħal respond:

from datetime import datetime
from typing import Any, AsyncIterator

from chatkit.actions import Action
from chatkit.server import ChatKitServer
from chatkit.types import (
    AssistantMessageContent,
    AssistantMessageItem,
    HiddenContextItem,
    ThreadItemDoneEvent,
    ThreadMetadata,
    ThreadStreamEvent,
    WidgetItem,
)


class MyChatKitServer(ChatKitServer[dict[str, Any]]):
    # respond(...) : kif fil-lezzjoni 17

    def message(self, thread: ThreadMetadata, context: dict[str, Any], text: str) -> ThreadItemDoneEvent:
        return ThreadItemDoneEvent(
            item=AssistantMessageItem(
                thread_id=thread.id,
                id=self.store.generate_item_id("message", thread, context),
                created_at=datetime.now(),
                content=[AssistantMessageContent(text=text)],
            )
        )

    async def action(
        self,
        thread: ThreadMetadata,
        action: Action[str, Any],
        sender: WidgetItem | None,
        context: dict[str, Any],
    ) -> AsyncIterator[ThreadStreamEvent]:
        if action.type == "order.cancel":
            number = str((action.payload or {}).get("number", ""))
            # Il-payload jiġi mill-browser: ivverifika mill-ġdid il-permessi
            if not await is_user_order(number, context.get("user_id")):
                yield self.message(thread, context, "This order does not belong to you.")
                return
            await cancel_order(number)
            # Traċċa għall-mudell, qatt muriha lill-utent
            await self.store.add_thread_item(
                thread.id,
                HiddenContextItem(
                    id=self.store.generate_item_id("message", thread, context),
                    thread_id=thread.id,
                    created_at=datetime.now(),
                    content=f"<USER_ACTION>User canceled order {number}.</USER_ACTION>",
                ),
                context,
            )
            yield self.message(thread, context, f"Done: order {number} is canceled.")
        elif action.type == "order.keep":
            yield self.message(thread, context, "Very well, the order is kept.")

Tliet regoli joħorġu minn dan il-kodiċi:

  • Il-payload mhuwiex affidabbli. Jasal mill-browser, fejn kulħadd jista’ jimmodifikah: il-gwida ta’ OpenAI teħtieġ li tittrattah bħala data mhux ivverifikata. Qabel ma tikkanċella, is-server jiċċekkja li l-ordni tappartjeni lill-utent awtentikat. L-user_id fil-kuntest huwa dak li l-endpoint awtentikat tiegħek ipoġġi hemmhekk (lezzjoni 21).
  • Il-mudell irid ikun jaf x’ġara. Klikk mhix messaġġ: mingħajr traċċa, l-aġent jinjora fit-tidwira li jmiss li l-ordni ġiet ikkanċellata. HiddenContextItem iżid din l-informazzjoni fit-thread mingħajr ma juriha. L-SDK jirreġistra awtomatikament biss elementi mxandra, u element moħbi qatt m’għandu jintbagħat b’broadcast: trid iżidu int stess fil-maħżen (store).
  • It-tweġiba hija fluss ta’ avvenimenti. Hawnhekk messaġġ sempliċi; jista’ jkun widget aġġornat, mxandar b’stream_widget bħal fil-lezzjoni preċedenti.

Biex l-aġent jikkummenta dwar dak li għadu kemm ġara, erġa’ bdieh wara l-azzjoni: async for event in self.respond(thread, None, context): yield event. Il-metodu respond tiegħek jerġa’ jaqra t-thread, isib l-element moħbi, u jwieġeb skont dan.

Formoli

Meta oqsma ta’ input (Input, Textarea, Select, Checkbox, DatePicker…) jitqiegħdu ġewwa Form, il-valuri tagħhom jiżdiedu mal-payload ta’ kwalunkwe azzjoni emessa minn dik il-formola, taħt l-isem ta’ kull qasam:

REPORT_TEMPLATE = """
{
  "type": "Card",
  "children": [
    {"type": "Form", "direction": "col", "gap": 3,
     "onSubmitAction": {"type": "ticket.create", "payload": {"source": "chat"}},
     "children": [
       {"type": "Title", "value": "Report an Issue", "size": "sm"},
       {"type": "Label", "value": "Order Number", "fieldName": "order"},
       {"type": "Input", "name": "order", "required": true, "pattern": "C-[0-9]+", "placeholder": "C-42"},
       {"type": "Label", "value": "Category", "fieldName": "category"},
       {"type": "Select", "name": "category", "placeholder": "Select",
        "options": [{"label": "Damaged Package", "value": "damaged"},
                    {"label": "Delay", "value": "delay"},
                    {"label": "Other", "value": "other"}]},
       {"type": "Textarea", "name": "detail", "rows": 3, "placeholder": "Describe the issue"},
       {"type": "Button", "label": "Submit", "submit": true}
     ]}
  ]
}
"""

Mas-sottomissjoni, action.payload fih source, order, category, u detail. Isem b’punt, "client.name", jipproduċi valur imbejjat: payload["client"]["name"]. Jekk isem ta’ qasam jikkolliża ma’ ċavetta diġà preżenti fil-payload, il-valur tal-qasam jiġi injorat u ChatKit jemetti avveniment ta’ żball: agħżel ismijiet distinti.

Il-validazzjoni tal-formola hija fuq in-naħa tal-browser: required u pattern jimblokkaw is-sottomissjoni waqt li qasam ikun invalidu. Din hija konvenjenza għall-utent, mhux protezzjoni: erġa’ vvalida fuq is-server, pereżempju b’mudell Pydantic.

from typing import Literal

from pydantic import BaseModel, Field, ValidationError


class Report(BaseModel):
    order: str = Field(pattern=r"^C-[0-9]+$")
    category: Literal["damaged", "delay", "other"]
    detail: str = Field(default="", max_length=2000)


# Fil-metodu tal-azzjoni
if action.type == "ticket.create":
    try:
        report = Report.model_validate(action.payload or {})
    except ValidationError:
        yield self.message(thread, context, "The form is incomplete or invalid.")
        return
    ticket_number = await create_ticket(report, context.get("user_id"))
    yield self.message(thread, context, f"Ticket {ticket_number} created, we will get back to you.")

Għal validazzjoni aktar rikka, b’messaġġi ta’ żball personalizzati, id-dokumentazzjoni tissuġġerixxi li toħroġ barra mill-widget: azzjoni fuq in-naħa tal-klijent tiftaħ tieqa fl-applikazzjoni tiegħek, u r-riżultat jerġa’ lura lejn ChatKit permezz ta’ sendCustomAction. Innota wkoll li Card iddikjarata b’"asForm": true tiġi ttrattata bħala formola: il-kampi tagħha jiġu vvalidati u mgħoddija lill-azzjoni confirm tagħha.

Ikkonferma qabel ma taġixxi

Il-kard tal-kanċellazzjoni fil-bidu turi regola li għandha tiġi ġeneralizzata: azzjoni irreversibbli jew sensittiva teħtieġ konferma espliċita. Il-kanċellazzjoni ta’ ordni, l-ibgħat ta’ email, ir-rimbors, it-tħassir: l-aġent jipproponi, l-utent jivvalida fuq kard li tiddikjara b’mod ċar x’se jiġri, u huwa s-server tiegħek, mhux il-mudell, li jesegwixxi wara li jerġa’ jivverifika l-permessi. Il-buttuni confirm u cancel ta’ Card huma magħmula għal dan. L-istat ta’ tagħbija default tagħhom jagħmel il-kard kollha griża waqt l-ipproċessar, li jipprevjeni d-doppju klikk.

Ipproċessar ta’ azzjoni fil-browser

Xi azzjonijiet m’għandhom x’jaqsmu xejn mas-server: il-ftuħ ta’ paġna fl-applikazzjoni tiegħek, il-kopja ta’ link, jew il-wiri ta’ modali. Iddikjarahom b’"handler": "client" fit-template, pereżempju {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Imbagħad jaslu fl-għażla widgets.onAction tal-interfaċċa:

import { ChatKit, useChatKit } from '@openai/chatkit-react';

export function AssistantOrders() {
  const chatkit = useChatKit({
    api: { url: '/chatkit', domainKey: 'local-dev' },
    widgets: {
      onAction: async (action, widgetItem) => {
        if (action.type === 'order.track') {
          window.open(`/orders/${String(action.payload?.number ?? '')}`, '_blank');
          // Avża lis-server, li jista' jaġġorna l-widget
          await chatkit.sendCustomAction(
            { type: 'order.tracked', payload: action.payload },
            widgetItem.id,
          );
        }
      },
    },
  });

  return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}

sendCustomAction jibgħat azzjoni lis-server tiegħek daqslikieku ġejja minn widget. Taħdem ukoll barra minn ChatKit: buttuna fil-paġna tiegħek tista’ ssejjaħ chatkit.sendCustomAction({ type: 'cart.empty' }) biex l-assistent jirreaġixxi għal dak li qed jiġri f’post ieħor fl-applikazzjoni.

Stati ta’ tagħbija

loadingBehavior jikkontrolla x’jara l-utent waqt li azzjoni tkun qed tiġi pproċessata:

ValurEffett
auto (default)Jadatta għall-komponent: il-buttuna waħedha għal Button, xejn għal Select, il-kard kollha għall-confirm ta’ Card
selfStat ta’ tagħbija fuq il-komponent wieħed li fih l-azzjoni
containerIl-widget kollu jsir ċar u jsir inattiv
noneL-ebda stat ta’ tagħbija

Id-dokumentazzjoni tirrakkomanda li żżomm auto, sakemm ma jkollokx ħtieġa speċifika. B’mod default, l-azzjonijiet fuq widget huma mblukkati wkoll waqt li tweġiba tkun qed tiġi mxandra, biex jiġu evitati kunflitti. Mill-verżjoni 1.6.2 tal-SDK ‘l quddiem, azzjoni ddikjarata b’"streaming": false taqbeż dan il-blokk: tiġi pproċessata mill-metodu sync_action tas-server, riżervat għal azzjonijiet li jaġġornaw biss il-widget tagħhom stess jew jaġixxu barra mit-thread.

Punti Ewlenin

  • Azzjoni hija oġġett {type, payload, handler, loadingBehavior} imwaħħal ma’ komponent widget; tattivaw l-ipproċessar mingħajr messaġġ tal-utent
  • Fuq is-server, il-metodu action ta’ ChatKitServer jirċieviha u jirritorna avvenimenti: messaġġ, widget aġġornat, jew tweġiba ġdida tal-aġent permezz ta’ respond
  • Il-payload jiġi mill-browser: erġa’ vverifika l-permessi u d-data fuq is-server (Pydantic), anke meta l-formola diġà tivvalida required u pattern
  • HiddenContextItem, miżjud manwalment fil-maħżen, jinforma lill-mudell dwar dak li għamel l-utent
  • Azzjonijiet sensittivi jgħaddu minn kard ta’ konferma; azzjonijiet purament lokali jiġu pproċessati fil-browser (handler: "client", widgets.onAction, sendCustomAction)