Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Gníomhartha Úsáideora

Ceacht 20 as 25 Nuashonraithe 3 Samhain 2026 Forbróir
Ar an leathanach seo
  1. Cad is gníomh ann?
  2. Gníomh a phróiseáil ar an bhfreastalaí
  3. Foirmeacha
  4. Deimhnigh sula ngníomhaíonn tú
  5. Gníomh a phróiseáil sa bhrabhsálaí
  6. Stáit Ualaithe
  7. Príomhphointí

Ceacht athscríofa an 3 Samhain 2026. Láimhsíodh briatharú i gcomhpháirteanna React saincheaptha sa leagan roimhe seo agus cheap sé “suggestion actions”. I ChatKit, is réad é gníomh a bhaineann le comhpháirt widget (cnaipe, sraith liosta, foirm). De réir réamhshocraithe, próiseáiltear ar do fhreastalaí é i modh action de chuid ChatKitServer, nó sa bhrabhsálaí má shonraíonn tú a mhalairt. Leanann an cheacht seo an treoir Actions in ChatKit agus SDK openai-chatkit 1.6.5. Rithheadh an freastalaí, na teimpléid agus an fhoirm go háitiúil; fíoraíodh an cód React le compileáil. Foinsí: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.

Cad is gníomh ann?

Níl i widget nach dtaispeánann ach ábhar ach freagra deas. Déanann gníomhartha úsáideach é: spreagann brú ar “Cancel Order”, roghnú sraith i liosta, nó foirm a chur isteach próiseáil gan gá don úsáideoir teachtaireacht a chlóscríobh. Seolann ChatKit an gníomh chuig d’fhreastalaí, a d’fhéadfadh gníomhú ar do chórais, an widget a nuashonrú, freagra a chur leis an snáithe, nó an t-aonán a atosú.

Fógraíonn tú gníomh i dteimpléad an widget ar chomhpháirt a ghlacann leis (onClickAction do Button nó ListViewItem, onChangeAction do Select, onSubmitAction do Form, confirm agus cancel do Card). Is réad JSON beag é:

RéimseRól
typeAinm an ghnímh a thástálann do chód: "order.cancel"
payloadSonraí úsáideacha: {"number": "C-42"}
handler"server" (réamhshocraithe) nó "client" chun é a phróiseáil sa bhrabhsálaí
loadingBehaviorAn staid ualaithe a thaispeántar le linn próiseála (féach thíos)

Gníomh a phróiseáil ar an bhfreastalaí

Tógaimis cárta orduithe a chuireann cealú ar fáil. Fógraíonn an teimpléad an gníomh ar chnaipí deimhnithe agus cealaithe an 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 }}}}}
}
"""

Ar thaobh an fhreastalaí, cuir modh action le do ChatKitServer. Faigheann sé an snáithe, an gníomh, an widget a sheol é (sender) agus do chomhthéacs, agus filleann sé teagmhasaim ar nós 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(...) : as in lesson 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", ""))
            # The payload comes from the browser: re-verify permissions
            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)
            # A trace for the model, never shown to the user
            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.")

Tagann trí riail chun solais ón gcód seo:

  • Tagann an payload gan iontaoibh. Tiocfaidh sé ón mbrabhsálaí, áit a bhféadfadh duine ar bith é a athrú: éilíonn treoir OpenAI é a láimhseáil mar shonraí neamhfíordheimhnithe. Roimh chealú, seiceálann an freastalaí gur don úsáideoir fíordheimhnithe atá an t-ordú. Is é user_id sa chomhthéacs an ceann a chuireann do chríochphointe fíordheimhnithe ann (ceacht 21).
  • Caithfidh an múnla a fháil amach cad a tharla. Ní teachtaireacht í briogáil: gan rian, bheadh ar an aonán a bheith gan fhios ag an chéad seal eile gur cealaíodh an t-ordú. Cuireann HiddenContextItem an t-eolas seo leis an snáithe gan é a thaispeáint. Ní thaifeadann an SDK go huathoibríoch ach eilimintí craoltha, agus níor cheart eilimint fholaithe a chraoladh riamh: ní mór duit féin í a chur leis an store.
  • Sruth teagmhas is ea an freagra. Teachtaireacht shimplí anseo; d’fhéadfadh sé a bheith ina widget nuashonraithe, craolta le stream_widget mar sa cheacht roimhe.

Chun go ndéanfaidh an t-aonán trácht ar an méid a tharla anois díreach, atos é tar éis an ghnímh: async for event in self.respond(thread, None, context): yield event. Athléann do mhodh respond an snáithe, aimsíonn sé an eilimint fholaithe, agus freagraíonn dá réir.

Foirmeacha

Nuair a chuirtear réimsí ionchuir (Input, Textarea, Select, Checkbox, DatePicker…) isteach i Form, cuirtear a luachanna le payload aon ghnímh a sheoltar ón bhfoirm sin, faoi ainm gach réimse:

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

Ar sheoladh, beidh source, order, category agus detail i action.payload. Gineann ainm poncaithe, "client.name", luach neadaithe: payload["client"]["name"]. Má bhuaileann ainm réimse le eochair atá sa payload cheana, déantar neamhaird den luach agus seolann ChatKit teagmhas earráide: roghnaigh ainmneacha ar leith.

Is ar thaobh an bhrabhsúraigh atá bailíochtú na foirme: cuireann required agus pattern cosc ar sheoladh fad is atá réimse neamhbhailí. Compord úsáideora é seo, ní cosaint: athbhailíochtaigh ar an bhfreastalaí, le samhail Pydantic mar shampla.

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)


# In the action method
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.")

I gcás bailíochtú níos saibhre, le teachtaireachtaí earráide saincheaptha, molann an doiciméadacht imeacht ón widget: osclaíonn gníomh cliaint fuinneog i d’fheidhmchlár, agus filleann an toradh ar ChatKit trí sendCustomAction. Tabhair faoi deara freisin go bhfeidhmíonn Card arna fhógra le "asForm": true mar fhoirm: bailíochtaítear a réimsí agus seoltar iad chuig a ghníomh confirm.

Deimhnigh sula ngníomhaíonn tú

Léiríonn an cárta cealaithe ag an tús riail ba chóir a ghinearálú: teastaíonn deimhniú soiléir d’gníomh nach féidir a chasadh ar ais nó a bhfuil íogaireacht leis. Cealú ordu, seoladh ríomhphoist, aisíocaíocht, scriosadh: molann an t-aonán, deimhníonn an t-úsáideoir ar chárta a deir go soiléir cad a tharlóidh, agus is é do fhreastalaí, ní an múnla, a fhorghníomhnaíonn tar éis ceadanna a athsheiceáil. Rinneadh cnaipí confirm agus cancel de chuid Card dá chomhair. Liathann a staid ualaithe réamhshocraithe an cárta ar fad le linn próiseála, rud a chuireann cosc ar dhéchriog.

Gníomh a phróiseáil sa bhrabhsálaí

Níl áit ar bith ag gníomhartha áirithe ar an bhfreastalaí: leathanach a oscailt i d’fheidhmchlár, nasc a chóipeáil, módal a thaispeáint. Fógraíonn tú iad le "handler": "client" sa teimpléad, mar shampla {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Tiocfaidh siad ansin isteach sa rogha widgets.onAction den chomhéadan:

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');
          // Notify the server, which can update the widget
          await chatkit.sendCustomAction(
            { type: 'order.tracked', payload: action.payload },
            widgetItem.id,
          );
        }
      },
    },
  });

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

Seolann sendCustomAction gníomh chuig d’fhreastalaí amhail is dá dtarlódh sé ó widget. Feidhmíonn sé lasmuigh de ChatKit freisin: is féidir le cnaipe ar do leathán chatkit.sendCustomAction({ type: 'cart.empty' }) a ghlaoch ionas go ndéanann an cúntóir freagairt don méid atá ag tarlú in áit eile san iarratas.

Stáit Ualaithe

Rialaíonn loadingBehavior an méid a fheiceann an t-úsáideoir le linn gníomh á phróiseáil:

LuachIarmhairt
auto (réamhshocraithe)Oiriúnaíonn don chomhpháirt: an cnaipe leis féin do Button, tada do Select, an cárta ar fad do confirm de chuid Card
selfStaid ualaithe ar an gcomhpháirt aonair a iompraíonn an gníomh
containerMaolaíonn an widget ar fad agus éiríonn neamhghníomhach
noneGan staid ualaithe

Molann an doiciméadacht auto a choinneáil, mura bhfuil gá ar leith agat. De réir réamhshocraithe, cuirter bac ar ghníomhartha ar widget le linn freagra ag sruthú chomh maith, chun coinbhleachtaí a sheachaint. Ó leagan 1.6.2 den SDK, téann gníomh arna fhógra le "streaming": false thar an mbac seo: próiseálann modh sync_action an fhreastalaí é, atá in áirithe do ghníomhartha a nuashonraíonn a widget féin amháin nó a ghníomhaíonn lasmuigh den snáithe.

Príomhphointí

  • Is réad é gníomh {type, payload, handler, loadingBehavior} a bhaineann le comhpháirt widget; spreagann sé próiseáil gan teachtaireacht úsáideora
  • Ar an bhfreastalaí, faigheann modh action de chuid ChatKitServer é agus filleann sé teagmhasaim: teachtaireacht, widget nuashonraithe, nó freagra nua ón aonán trí respond
  • Tagann an payload ón mbrabhsálaí: athsheiceáil ceadanna agus sonraí ar an bhfreastalaí (Pydantic), fiú nuair a bhailíochtaíonn an fhoirm required agus pattern ann féin
  • Cuirtear HiddenContextItem, arna chur leis an store de láimh, an múnla ar an eolas faoin méid a rinne an t-úsáideoir
  • Téann gníomhartha íogair trí chárta deimhnithe; próiseáiltear gníomhartha atá go hiomlán áitiúil sa bhrabhsálaí (handler: "client", widgets.onAction, sendCustomAction)