Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Διαδραστικά Widgets

Μάθημα 19 / 25 Ενημερώθηκε 3 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Τι είναι ένα widget του ChatKit;
  2. Containers και components
  3. Σχεδίαση του widget στον Widget Builder
  4. Τι περιέχει ένα template
  5. Εμφάνιση του widget από την respond
  6. Να αποφασίζει ο agent
  7. Λίστα που ανταποκρίνεται σε κλικ
  8. Ενημέρωση ενός widget που είναι ήδη ορατό
  9. Τι γίνεται με τις κλάσεις της Python;
  10. Πότε χρησιμοποιείτε widget
  11. Βασικά σημεία

Το μάθημα ξαναγράφτηκε στις 3 Νοεμβρίου 2026. Η προηγούμενη έκδοση περιέγραφε τα widget ως React components που τα γράφει ο προγραμματιστής και τα καταχωρεί στη διεπαφή, με ένα ανύπαρκτο module @openai/chatkit/react. Στο ChatKit, ένα widget είναι μια declarative περιγραφή την οποία ο server σας κατασκευάζει και την αποδίδει μόνος του το ChatKit. Αυτό το μάθημα ακολουθεί το Python SDK openai-chatkit 1.6.5, που χτίζει widgets από templates .widget: οι κλάσεις Card, Text, Badge… έχουν καταργηθεί. Τα παραδείγματα εκτελέστηκαν σε έναν τοπικό server ChatKit. Πηγές: ChatKit widgets · Widgets (Python SDK) · Κατασκευή διαδραστικών απαντήσεων με widgets · Widget Builder.

Τι είναι ένα widget του ChatKit;

Μια κειμενική απάντηση αρκεί για τις εξηγήσεις. Όμως, για να παρουσιάσετε μια παραγγελία, να συγκρίνετε τρία πλάνα ή να επιβεβαιώσετε ένα ραντεβού, το κείμενο γίνεται γρήγορα τοίχος γραμμών που ο χρήστης ξαναδιαβάζει με το ζόρι. Τα widget αντικαθιστούν αυτό το κείμενο με μια διεπαφή: κάρτα, λίστα, φόρμα ή γράφημα, εμφανιζόμενη μέσα στη ροή της συνομιλίας.

Η προσέγγιση είναι declarative. Ο server σας δεν στέλνει ούτε HTML ούτε React component: περιγράφει το widget σε JSON, με ένα κλειστό σύνολο components και ιδιοτήτων, και το στέλνει στη συνομιλία ως πλήρες στοιχείο (ένα WidgetItem). Το ChatKit το σχεδιάζει με τα δικά του components, φορώντας τα χρώματα του θέματος από το προηγούμενο μάθημα. Δύο συνέπειες:

  • Χρησιμοποιείτε μόνο components και ιδιότητες που γνωρίζει το ChatKit. Αντίμετρο: η απόδοση παραμένει συνεπής με το υπόλοιπο περιβάλλον, και κανένα αυθαίρετο HTML ή JavaScript από τον server δεν φτάνει στη σελίδα.
  • Το widget ανήκει στο ιστορικό: στις επόμενες στροφές μετατρέπεται σε εισαγωγή για το μοντέλο, που άρα «βλέπει» τι έδειξε στον χρήστη.

Containers και components

Κάθε widget έχει μια ρίζα, διαλεγμένη ανάμεσα σε τρία containers:

ContainerΧρήση
CardΑυτόνομο περιεχόμενο: περίληψη, επιβεβαίωση, φόρμα. Δέχεται status και κουμπιά αποδοχής/ακύρωσης κάτω από το περιεχόμενο
ListViewΣύνολο επιλογών: εστιατόρια, αρχεία, παραγγελίες. Τα παιδιά του είναι ListViewItem, με ενσωματωμένη λειτουργία «δείτε περισσότερα» (limit)
BasicΠροορίζεται αποκλειστικά για προεπισκοπήσεις οντοτήτων που εμφανίζονται στο hover πάνω από μια αναφορά

Μέσα τους συναρμολογείτε components: κείμενο (Title, Text, Caption, Markdown), ετικέτες (Badge), διάταξη (Row, Col, Box, Spacer, Divider), πολυμέσα (Image, Icon), εντολές (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, που μπορεί να τα ομαδοποιεί μια Form), γραφήματα (Chart) και κινήσεις (Transition). Η σελίδα Components του Widget Builder παραθέτει τις ιδιότητες του καθενός, με επεξεργαστή για δοκιμές.

Σχεδίαση του widget στον Widget Builder

Ο προβλεπόμενος τρόπος εργασίας ξεκινά από τον Widget Builder του ChatKit Studio. Εκεί στήνετε τη διάταξη, γεμίζετε τον πίνακα δεδομένων με ενδεικτικές τιμές για να κρίνετε το αποτέλεσμα, και μετά εξάγετε ένα αρχείο .widget: αρχείο JSON που συνδυάζει το template, το schema των αναμενόμενων δεδομένων (jsonSchema) και τα ενδεικτικά δεδομένα. Φυλάσσετε το σε έλεγχο εκδόσεων δίπλα στον κώδικα του server, για παράδειγμα σε φάκελο widgets/.

Από την πλευρά του server, το WidgetTemplate φορτώνει το αρχείο και το build το γεμίζει με πραγματικά δεδομένα:

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

Μια σχετική διαδρομή αναλύεται ως προς το αρχείο Python που καλεί το from_file, όχι ως προς τον φάκελο εκκίνησης. Το build δέχεται λεξικό ή μοντέλο Pydantic.

Τι περιέχει ένα template

Το template είναι ένα Jinja μοντέλο που παράγει το JSON του widget. Το template της κάρτας παραγγελίας έχει ως εξής:

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

Σπάνια θα γράφατε μόνοι σας ένα template, αφού το δημιουργεί ο Widget Builder. Το να διαβάζετε όμως ένα έτοιμο template θα σας γλιτώσει χρόνο όταν εμφανιστεί το πρώτο πρόβλημα. Τρία σχόλια:

  • Το φίλτρο tojson μετατρέπει κάθε τιμή σε έγκυρο JSON (κείμενο με εισαγωγικά, boolean ως true ή false) και κάνει escaping τους ειδικούς χαρακτήρες: ένα απόστροφος ή εισαγωγικό σε όνομα προϊόντος δεν σπάει το JSON.
  • Το Jinja τρέχει σε αυστηρή λειτουργία: απόντα δεδομένα κάνουν το build να αποτύχει, αντί να παραγάγει ένα μισοάδειο widget.
  • Το build δεν επαληθεύει τα δεδομένα απέναντι στο jsonSchema. Αυτό το schema τεκμηριώνει τα δεδομένα· αν προέρχονται από εργαλείο ή βάση δεδομένων, ελέγξτε τα εκ των προτέρων, για παράδειγμα με ένα μοντέλο Pydantic.

Ο constructor WidgetTemplate(...) δέχεται το ίδιο ακριβώς περιεχόμενο με ένα ήδη διαβασμένο αρχείο .widget: βολικός για δοκιμές ή για template που γεννάει ο δικός σας κώδικας.

Εμφάνιση του widget από την respond

Για να ταξιδέψει το widget στη συνομιλία, το stream_widget παράγει τα αντίστοιχα events του ChatKit. Τα μεταβιβάζετε μέσα από τη μέθοδο respond σας:

from chatkit.server import stream_widget

# In your ChatKitServer class
async def respond(self, thread, input_user_message, context):
    card = order_template.build(await get_order_data("C-42"))  # your data
    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 είναι το κείμενο που αντιγράφεται στο πρόχειρο όταν ο χρήστης πατά το κουμπί αντιγραφής κάτω από την απάντηση. Ο server αποθηκεύει ο ίδιος το widget στο store, όπως κάθε στοιχείο που μεταδίδεται.

Να αποφασίζει ο agent

Στις περισσότερες περιπτώσεις δεν αποφασίζει ο κώδικάς σας να εμφανίσει κάρτα, αλλά ο agent, όταν το ζητάει η συνομιλία. Τού δίνετε ένα εργαλείο που μεταδίδει το widget με το AgentContext.stream_widget: το stream_agent_response, που γνωρίζετε από το μάθημα 17, το περνά στη διεπαφή στη μέση της απάντησης.

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)  # your data access
    await ctx.context.stream_widget(order_template.build(data))
    return f"The card for order {number} is displayed."

Προσθέστε το εργαλείο στη λίστα tools του agent. Το κείμενο που επιστρέφει εξυπηρετεί το μοντέλο, που έτσι ξέρει πως η κάρτα είναι ήδη στην οθόνη και μπορεί να τη σχολιάσει αντί να την επαναλάβει.

Λίστα που ανταποκρίνεται σε κλικ

Για να προτείνετε επιλογή, το ListView παρουσιάζει γραμμές που ανταποκρίνονται σε κλικ. Κάθε ListViewItem μπορεί να κουβαλά ενέργεια, που πυροδοτείται με ένα κλικ χωρίς ο χρήστης να πληκτρολογήσει οτιδήποτε· το επόμενο μάθημα δείχνει τον χειρισμό της στον 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"}]})

Πέρα από το limit, το ChatKit εμφανίζει σύνδεσμο «δείτε περισσότερα».

Ενημέρωση ενός widget που είναι ήδη ορατό

Ένα widget μπορεί να εξελίσσεται μπροστά στα μάτια του χρήστη, για παράδειγμα για να δείχνει ένα προσχέδιο που γράφει το μοντέλο. Δώστε στο stream_widget έναν async generator που παράγει διαδοχικές καταστάσεις του widget: το ChatKit υπολογίζει τις διαφορές και στέλνει μόνο ό,τι αλλάζει.

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})
    # Final state, once the text is complete
    yield draft_template.build({"text": text, "in_progress": False})

Μόνο τα components Text και Markdown με id δείχνουν τις ενημερώσεις τους σε ροή, λέξη προς λέξη· για τα υπόλοιπα, το ChatKit αντικαθιστά το τροποποιημένο τμήμα του widget.

Τι γίνεται με τις κλάσεις της Python;

Θα συναντήσετε, ακόμα και σε οδηγούς της OpenAI, widgets χτισμένα με κλάσεις: Card(children=[Text(value="…")]). Δουλεύουν ακόμα, αλλά το SDK openai-chatkit 1.6.5 τις δηλώνει καταργημένες υπέρ του WidgetTemplate: η χρήση τους εκπέμπει προειδοποίηση που παραπέμπει σε αρχεία .widget. Για νέο έργο, ξεκινάτε από templates. Για υπάρχον έργο, μεταναστεύετε με τον δικό σας ρυθμό: η προειδοποίηση δεν εμποδίζει τίποτα, αλλά μια καταργημένη κλάση μπορεί να λείπει σε μελλοντική έκδοση.

Πότε χρησιμοποιείτε widget

Η τεκμηρίωση αναφέρει ενδεικτικές χρήσεις:

  • συλλογή δομημένης εισόδου με φόρμα, ή παρουσίαση πλούσιου αποτελέσματος — πίνακας, κάρτα, γράφημα — που το κείμενο το αποδίδει άσχημα·
  • πρόταση επιλογής ανάμεσα σε περισσότερες δυνατότητες·
  • συνδυασμός του widget με ενέργειες, για επικύρωση επιλογής, επιβεβαίωση βήματος ή δρομολόγηση επεξεργασίας στον server·
  • συνοδεία μιας σύντομης κειμενικής εξήγησης με μια διαδραστική εντολή.

Αντίθετα, μην τα απλώνετε παντού. Ένα widget που επαναλαμβάνει λέξη προς λέξη όσα λέει ήδη το κείμενο δεν προσθέτει τίποτα, και μια συνομιλία ασφυκτικά γεμάτη κάρτες διαβάζεται το ίδιο δύσκολα με έναν τοίχο κειμένου.

Βασικά σημεία

  • Ένα widget ChatKit είναι declarative περιγραφή (JSON) που χτίζει ο server σας, όχι React component: το ChatKit το αποδίδει μόνο του
  • Τρία containers: Card (αυτόνομο περιεχόμενο), ListView (λίστα επιλογών), Basic (προεπισκοπήσεις οντοτήτων)
  • Σχεδίαση στον Widget Builder, εξαγωγή αρχείου .widget, φόρτωση με WidgetTemplate.from_file(...), γέμισμα με build(data)· οι κλάσεις Card, Text… έχουν καταργηθεί
  • Μετάδοση με stream_widget από την respond, ή από εργαλείο του agent με ctx.context.stream_widget
  • Ένας async generator ενημερώνει το widget ζωντανά· μόνο Text και Markdown με id εκτυλίσσονται σε ροή λέξη προς λέξη