Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Widgets interactifs

Les 19 van 25 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Qu’est-ce qu’un widget ChatKit ?
  2. Conteneurs et composants
  3. Concevoir le widget dans le Widget Builder
  4. Contenu d’un modèle
  5. Afficher le widget depuis respond
  6. Laisser l’agent décider
  7. Une liste cliquable
  8. Mettre à jour un widget pendant son affichage
  9. Et les classes Python ?
  10. Quand utiliser un widget
  11. Belangrijkste punten

Leçon réécrite le 3 novembre 2026. La version précédente décrivait les widgets comme des composants React écrits par le développeur et enregistrés dans l’interface, utilisant un module inexistant @openai/chatkit/react. Dans ChatKit, un widget est une description déclarative que votre serveur construit et que ChatKit rend lui-même. Cette leçon suit le SDK Python openai-chatkit 1.6.5, qui construit les widgets à partir de modèles .widget : ses classes Card, Text, Badge… sont dépréciées. Les exemples ont été exécutés sur un serveur ChatKit local. Sources : Widgets ChatKit · Widgets (SDK Python) · Créer des réponses interactives avec des widgets · Widget Builder.

Qu’est-ce qu’un widget ChatKit ?

Une réponse textuelle suffit pour des explications. Mais pour présenter une commande, comparer trois formules ou confirmer un rendez-vous, le texte devient rapidement un mur de lignes que l’utilisateur doit relire. Les widgets remplacent ce texte par une interface : une carte, une liste, un formulaire ou un graphique, affichés directement dans le fil de conversation.

L’approche est déclarative. Votre serveur ne fournit ni HTML ni composant React : il décrit le widget en JSON, en utilisant un ensemble fermé de composants et de propriétés, et l’envoie dans le fil comme un élément à part entière (un WidgetItem). ChatKit le dessine avec ses propres composants, en utilisant les couleurs du thème vues dans la leçon précédente. Deux conséquences en découlent :

  • Vous ne pouvez utiliser que les composants et propriétés que ChatKit connaît. En contrepartie, le rendu reste cohérent avec le reste de l’interface et aucun HTML ou JavaScript arbitraire provenant du serveur n’atteint la page.
  • Le widget fait partie de l’historique : lors des tours suivants, il est converti en entrée pour le modèle, qui « voit » donc ce qu’il a montré à l’utilisateur.

Conteneurs et composants

Chaque widget possède une racine, choisie parmi trois conteneurs :

ConteneurUsage
CardContenu autonome : un résumé, une confirmation, un formulaire. Accepte un statut et des boutons de confirmation/annulation sous le contenu
ListViewUn ensemble d’options : restaurants, fichiers, commandes. Ses enfants sont des ListViewItem, avec une fonctionnalité intégrée « voir plus » (limit)
BasicRéservé aux aperçus d’entités affichés lors du survol d’une mention

À l’intérieur, vous assemblez des composants : texte (Title, Text, Caption, Markdown), étiquettes (Badge), mise en page (Row, Col, Box, Spacer, Divider), médias (Image, Icon), commandes (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, qu’un Form peut regrouper), graphiques (Chart) et animations (Transition). La page Composants du Widget Builder liste les propriétés de chacun, avec un éditeur pour les tester.

Concevoir le widget dans le Widget Builder

Le flux de travail recommandé commence dans le Widget Builder de ChatKit Studio. Vous y concevez la mise en page, remplissez le panneau de données avec des valeurs d’exemple pour juger du rendu, puis exportez un fichier .widget. Il s’agit d’un fichier JSON combinant le modèle, le schéma des données attendues (jsonSchema) et les données d’exemple. Placez-le sous contrôle de version aux côtés de votre code serveur, par exemple dans un dossier widgets/.

Côté serveur, WidgetTemplate charge le fichier et build le remplit avec les données réelles :

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

Un chemin relatif est résolu à partir du fichier Python appelant from_file, et non depuis le répertoire de lancement. build accepte un dictionnaire ou un modèle Pydantic.

Contenu d’un modèle

Le modèle est un modèle Jinja qui produit le JSON du widget. Le modèle de carte de commande ressemble à ceci :

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

Vous écrirez rarement un modèle à la main, car le Widget Builder le génère. Mais savoir en lire un vous fera gagner du temps dès le premier problème. Trois remarques :

  • Le filtre tojson convertit chaque valeur en JSON valide (une chaîne entre guillemets, un booléen sous forme de true ou false) et échappe les caractères spéciaux : une apostrophe ou un guillemet dans un nom de produit ne cassera pas le JSON.
  • Jinja s’exécute en mode strict : des données manquantes font échouer build, au lieu de produire un widget à moitié vide.
  • build ne valide pas les données contre le jsonSchema. Ce schéma documente les données ; si elles proviennent d’un outil ou d’une base de données, validez-les au préalable, par exemple avec un modèle Pydantic.

Le constructeur WidgetTemplate(...) prend le même contenu qu’un fichier .widget déjà lu : c’est pratique pour les tests, ou pour un modèle généré par votre propre code.

Afficher le widget depuis respond

Pour envoyer le widget dans le fil, stream_widget produit les événements ChatKit correspondants. Vous les relayez depuis votre méthode respond :

from chatkit.server import stream_widget

# Dans votre classe ChatKitServer
async def respond(self, thread, input_user_message, context):
    card = order_template.build(await get_order_data("C-42"))  # vos données
    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 est le texte copié dans le presse-papiers lorsque l’utilisateur clique sur le bouton de copie sous la réponse. Le serveur enregistre lui-même le widget dans le store, comme tout élément diffusé.

Laisser l’agent décider

Le plus souvent, ce n’est pas votre code qui décide d’afficher une carte, mais l’agent, lorsque la conversation l’exige. Donnez-lui un outil qui diffuse le widget avec AgentContext.stream_widget : stream_agent_response, vu à la leçon 17, le transmet à l’interface au milieu de la réponse.

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)  # votre accès aux données
    await ctx.context.stream_widget(order_template.build(data))
    return f"The card for order {number} is displayed."

Ajoutez l’outil à la liste tools de l’agent. La chaîne renvoyée par l’outil sert au modèle, qui sait ainsi que la carte est à l’écran et peut la commenter au lieu de la répéter.

Une liste cliquable

Pour proposer un choix, ListView présente des lignes cliquables. Chaque ListViewItem peut porter une action, déclenchée au clic sans que l’utilisateur ait rien à taper ; la prochaine leçon montre comment la gérer côté serveur.

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

Au-delà de la limit, ChatKit affiche un lien « voir plus ».

Mettre à jour un widget pendant son affichage

Un widget peut évoluer sous les yeux de l’utilisateur, par exemple pour afficher un brouillon que le modèle est en train d’écrire. Donnez à stream_widget un générateur asynchrone qui produit les états successifs du widget : ChatKit calcule les différences et n’envoie que ce qui change.

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})
    # État final, une fois le texte complet
    yield draft_template.build({"text": text, "in_progress": False})

Seuls les composants Text et Markdown dotés d’un id affichent leurs mises à jour en flux, mot par mot ; pour les autres, ChatKit remplace la partie modifiée du widget.

Et les classes Python ?

Vous rencontrerez, même dans les guides OpenAI, des widgets construits avec des classes : Card(children=[Text(value="…")]). Ils fonctionnent toujours, mais le SDK openai-chatkit 1.6.5 les déclare dépréciés en faveur de WidgetTemplate : leur utilisation émet un avertissement pointant vers les fichiers .widget. Pour un nouveau projet, partez des modèles. Pour un projet existant, migrez à votre rythme : l’avertissement ne bloque rien, mais une classe dépréciée pourrait disparaître dans une version future.

Quand utiliser un widget

La documentation cite des usages typiques :

  • collecter des entrées structurées avec un formulaire, ou présenter un résultat riche (tableau, carte, graphique) que le texte rend mal ;
  • offrir un choix entre plusieurs options ;
  • combiner le widget avec des actions, pour valider une sélection, confirmer une étape ou lancer un traitement côté serveur ;
  • accompagner un court texte explicatif d’une commande interactive.

À l’inverse, n’en mettez pas partout. Un widget qui répète mot pour mot ce que dit le texte n’ajoute rien, et une conversation saturée de cartes devient aussi difficile à lire qu’un mur de texte.

Belangrijkste punten

  • Un widget ChatKit est une description déclarative (JSON) construite par votre serveur, pas un composant React : ChatKit le rend lui-même
  • Trois conteneurs : Card (contenu autonome), ListView (liste d’options), Basic (aperçus d’entités)
  • Concevez dans le Widget Builder, exportez un fichier .widget, chargez-le avec WidgetTemplate.from_file(...), et remplissez-le avec build(data) ; les classes Card, Text… sont dépréciées
  • Diffusez avec stream_widget depuis respond, ou depuis un outil d’agent avec ctx.context.stream_widget
  • Un générateur asynchrone met à jour le widget en direct ; seuls Text et Markdown avec un id diffusent mot par mot