Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Actions utilisateur

Lektion 20 av 25 Uppdaterad 3 november 2026 Utvecklare
På denna sida
  1. Qu’est-ce qu’une action ?
  2. Traitement d’une action sur le serveur
  3. Formulaires
  4. Confirmer avant d’agir
  5. Traitement d’une action dans le navigateur
  6. États de chargement
  7. Viktiga punkter

Leçon réécrite le 3 novembre 2026. La version précédente gérait les clics dans des composants React personnalisés et inventait des « actions de suggestion ». Dans ChatKit, une action est un objet attaché à un composant widget (bouton, ligne de liste, formulaire). Par défaut, elle est traitée sur votre serveur dans la méthode action de ChatKitServer, ou dans le navigateur si vous le spécifiez autrement. Cette leçon suit le guide Actions in ChatKit et le SDK openai-chatkit 1.6.5. Le serveur, les modèles et le formulaire ont été exécutés localement ; le code React a été vérifié par compilation. Sources : Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.

Qu’est-ce qu’une action ?

Un widget qui se contente d’afficher du contenu n’est qu’une jolie réponse. Les actions le rendent utile : cliquer sur « Annuler la commande », sélectionner une ligne dans une liste ou soumettre un formulaire déclenche un traitement sans que l’utilisateur ait à taper un message. ChatKit envoie l’action à votre serveur, qui peut agir sur vos systèmes, mettre à jour le widget, ajouter une réponse au fil de discussion ou redémarrer l’agent.

Vous déclarez une action dans le modèle du widget sur un composant qui en accepte une (onClickAction pour un Button ou ListViewItem, onChangeAction pour un Select, onSubmitAction pour un Form, confirm et cancel pour un Card). C’est un petit objet JSON :

ChampRôle
typeLe nom de l’action que votre code teste : "order.cancel"
payloadDonnées utiles : {"number": "C-42"}
handler"server" (par défaut) ou "client" pour le traiter dans le navigateur
loadingBehaviorL’état de chargement affiché pendant le traitement (voir ci-dessous)

Traitement d’une action sur le serveur

Prenons une carte de commande qui propose une annulation. Le modèle déclare l’action sur les boutons de confirmation et d’annulation de la 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 }}}}}
}
"""

Côté serveur, ajoutez une méthode action à votre ChatKitServer. Elle reçoit le fil de discussion, l’action, le widget qui l’a émise (sender) et votre contexte, et retourne des événements comme 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(...) : comme dans la leçon 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", ""))
            # Le payload vient du navigateur : revérifiez les 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)
            # Une trace pour le modèle, jamais affichée à l'utilisateur
            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.")

Trois règles se dégagent de ce code :

  • Le payload n’est pas fiable. Il arrive depuis le navigateur, où n’importe qui peut le modifier : le guide OpenAI exige de le traiter comme une donnée non vérifiée. Avant d’annuler, le serveur vérifie que la commande appartient bien à l’utilisateur authentifié. Le user_id dans le contexte est celui que votre point de terminaison authentifié y place (leçon 21).
  • Le modèle doit savoir ce qui s’est passé. Un clic n’est pas un message : sans trace, l’agent ignorerait au tour suivant que la commande est annulée. Un HiddenContextItem ajoute cette information au fil de discussion sans l’afficher. Le SDK n’enregistre automatiquement que les éléments diffusés, et un élément caché ne doit jamais être diffusé : vous devez l’ajouter vous-même au store.
  • La réponse est un flux d’événements. Ici un simple message ; cela pourrait être un widget mis à jour, diffusé avec stream_widget comme dans la leçon précédente.

Pour que l’agent commente ce qui vient de se produire, redémarrez-le après l’action : async for event in self.respond(thread, None, context): yield event. Votre méthode respond relit le fil de discussion, trouve l’élément caché et répond en conséquence.

Formulaires

Lorsque des champs de saisie (Input, Textarea, Select, Checkbox, DatePicker…) sont placés dans un Form, leurs valeurs sont ajoutées au payload de toute action émise depuis ce formulaire, sous le nom de chaque champ :

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

À la soumission, action.payload contient source, order, category et detail. Un nom pointé, "client.name", produit une valeur imbriquée : payload["client"]["name"]. Si un nom de champ entre en collision avec une clé déjà présente dans le payload, la valeur du champ est ignorée et ChatKit émet un événement d’erreur : choisissez des noms distincts.

La validation du formulaire se fait côté navigateur : required et pattern bloquent la soumission tant qu’un champ est invalide. C’est un confort utilisateur, pas une protection : re-validez sur le serveur, par exemple avec un modèle 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)


# Dans la méthode action
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.")

Pour une validation plus riche, avec des messages d’erreur personnalisés, la documentation conseille de sortir du widget : une action côté client ouvre une fenêtre dans votre application, et le résultat revient à ChatKit via sendCustomAction. Notez aussi qu’une Card déclarée avec "asForm": true se comporte comme un formulaire : ses champs sont validés et passés à son action confirm.

Confirmer avant d’agir

La carte d’annulation du début illustre une règle à généraliser : une action irréversible ou sensible nécessite une confirmation explicite. Annuler une commande, envoyer un e-mail, rembourser, supprimer : l’agent propose, l’utilisateur valide sur une carte qui indique clairement ce qui va se passer, et c’est votre serveur, pas le modèle, qui exécute après avoir revérifié les permissions. Les boutons confirm et cancel d’une Card sont faits pour cela. Leur état de chargement par défaut grise toute la carte pendant le traitement, ce qui empêche les doubles clics.

Traitement d’une action dans le navigateur

Certaines actions n’ont rien à faire sur le serveur : ouvrir une page dans votre application, copier un lien, afficher une modale. Déclarez-les avec "handler": "client" dans le modèle, par exemple {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Elles arrivent alors dans l’option widgets.onAction de l’interface :

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');
          // Notifier le serveur, qui peut mettre à jour le widget
          await chatkit.sendCustomAction(
            { type: 'order.tracked', payload: action.payload },
            widgetItem.id,
          );
        }
      },
    },
  });

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

sendCustomAction envoie une action à votre serveur comme si elle venait d’un widget. Cela fonctionne aussi hors de ChatKit : un bouton sur votre page peut appeler chatkit.sendCustomAction({ type: 'cart.empty' }) pour que l’assistant réagisse à ce qui se passe ailleurs dans l’application.

États de chargement

loadingBehavior contrôle ce que l’utilisateur voit pendant le traitement d’une action :

ValeurEffet
auto (par défaut)S’adapte au composant : le bouton seul pour un Button, rien pour un Select, toute la carte pour le confirm d’une Card
selfÉtat de chargement sur le composant unique détenant l’action
containerTout le widget s’estompe et devient inactif
noneAucun état de chargement

La documentation recommande de garder auto, sauf besoin spécifique. Par défaut, les actions sur un widget sont aussi bloquées pendant qu’une réponse est diffusée, pour éviter les conflits. Depuis la version 1.6.2 du SDK, une action déclarée avec "streaming": false contourne ce blocage : elle est traitée par la méthode sync_action du serveur, réservée aux actions qui ne mettent à jour que leur propre widget ou agissent hors du fil de discussion.

Viktiga punkter

  • Une action est un objet {type, payload, handler, loadingBehavior} attaché à un composant widget ; elle déclenche un traitement sans message utilisateur
  • Sur le serveur, la méthode action de ChatKitServer la reçoit et retourne des événements : message, widget mis à jour, ou nouvelle réponse de l’agent via respond
  • Le payload vient du navigateur : revérifiez les permissions et les données sur le serveur (Pydantic), même si le formulaire valide déjà required et pattern
  • Un HiddenContextItem, ajouté manuellement au store, informe le modèle de ce que l’utilisateur a fait
  • Les actions sensibles passent par une carte de confirmation ; les actions purement locales sont traitées dans le navigateur (handler: "client", widgets.onAction, sendCustomAction)