Интерактивни уиджети
На тази страница
- Какво е ChatKit уиджет?
- Контейнери и компоненти
- Проектиране на уиджета в Widget Builder
- Какво съдържа един шаблон
- Показване на уиджета от respond
- Позволяване на агента да решава
- Списък с възможност за кликване
- Актуализиране на уиджет, докато се показва
- А какво става с Python класовете?
- Кога да използвате уиджет
- Ключови изводи
Урокът е пренаписан на 3 ноември 2026 г. Предишната версия описваше уиджетите като React компоненти, написани от разработчика и регистрирани в интерфейса, използвайки несъществуващия модул
@openai/chatkit/react. В ChatKit уиджетът е декларативно описание, което Вашият сървър изгражда и което ChatKit сам рендира. Този урок следва Python SDKopenai-chatkitверсия 1.6.5, който изгражда уиджети от.widgetшаблони: неговите класовеCard,Text,Badge… са обявени за остарели. Примерите бяха изпълнени на локален ChatKit сървър. Източници: ChatKit уиджети · Уиджети (Python SDK) · Изграждане на интерактивни отговори с уиджети · Widget Builder.
Какво е ChatKit уиджет?
Текстовият отговор е достатъчен за обяснения. Но за да представите поръчка, да сравните три плана или да потвърдите среща, текстът бързо се превръща в стена от редове, които потребителят трябва да препрочита. Уиджетите заменят този текст с интерфейс: карта, списък, форма или диаграма, показани в рамките на потока на разговора.
Подходът е декларативен. Вашият сървър не доставя нито HTML, нито React компонент: той описва уиджета в JSON, използвайки затворен набор от компоненти и свойства, и го изпраща в нишката като пълноправен елемент (WidgetItem). ChatKit го изчертава със собствените си компоненти, използвайки цветовата тема от предишния урок. От това следват две последствия:
- Можете да използвате само компоненти и свойства, които ChatKit познава. В замяна рендирането остава консистентно с останалата част от интерфейса и никакъв произволен HTML или JavaScript от сървъра не достига до страницата.
- Уиджетът е част от историята: при следващите завъртания той се конвертира във входни данни за модела, който по този начин „вижда“ какво е показал на потребителя.
Контейнери и компоненти
Всеки уиджет има корен, избран от три контейнера:
| Контейнер | Употреба |
|---|---|
Card | Самостоятелно съдържание: обобщение, потвърждение, форма. Приема статус и бутони за потвърждение/отказ под съдържанието |
ListView | Набор от опции: ресторанти, файлове, поръчки. Неговите деца са ListViewItem-и с вградена функционалност „виж още“ (limit) |
Basic | Запазен за прегледи на entities, показвани при задържане на курсора върху споменаване |
Вътре в тях сглобявате компоненти: текст (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 Builder
Предвиденият работен поток започва в Widget Builder на ChatKit Studio. Там проектирате оформлението, попълвате панела с данни с примерни стойности, за да прецените рендирането, и след това експортирате .widget файл. Това е JSON файл, който комбинира шаблона, схемата на очакваните данни (jsonSchema) и примерните данни. Версионирайте го заедно с кода на сървъра си, например в папка widgets/.
От страната на сървъра 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 приема речник (dictionary) или Pydantic модел.
Какво съдържа един шаблон
Шаблонът е Jinja модел, който генерира JSON-а на уиджета. Шаблонът за карта с поръчка изглежда така:
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})
Рядко ще пишете шаблон на ръка, тъй като Widget Builder го генерира. Но четенето му ще Ви спести време, когато възникне първият проблем. Три забележки:
- Филтърът
tojsonконвертира всяка стойност в валиден JSON (низ в кавички, булева стойност катоtrueилиfalse) и екранира специалните символи: апостроф или кавичка в име на продукт няма да счупи JSON-а. - Jinja работи в стриктен режим: липсващите данни карат
buildда се провали, вместо да произведе полу-празен уиджет. buildне валидира данните спрямоjsonSchema. Тази схема документира данните; ако те идват от инструмент или база данни, валидирайте ги предварително, например с Pydantic модел.
Конструкторът WidgetTemplate(...) приема същото съдържание като вече прочетен .widget файл: това е удобно за тестове или за шаблон, генериран от Вашия собствен код.
Показване на уиджета от respond
За да изпратите уиджета в нишката, stream_widget генерира съответните ChatKit събития. Вие ги препредавате от Вашия метод respond:
from chatkit.server import stream_widget
# Във Вашия клас ChatKitServer
async def respond(self, thread, input_user_message, context):
card = order_template.build(await get_order_data("C-42")) # Вашите данни
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 е текстът, копиран в клипборда, когато потребителят кликне бутона за копиране под отговора. Сървърът запазва уиджета в хранилището (store) сам, като всеки друг елемент за излъчване.
Позволяване на агента да решава
Най-често не Вашият код решава да покаже карта, а агентът, когато разговорът го изисква. Дайте му инструмент, който излъчва уиджета с 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) # Вашият достъп до данни
await ctx.context.stream_widget(order_template.build(data))
return f"The card for order {number} is displayed."
Добавете инструмента към списъка tools на агента. Низът, върнат от инструмента, служи на модела, който по този начин знае, че картата е на екрана и може да я коментира, вместо да я повтаря.
Списък с възможност за кликване
За да предложите избор, ListView представя редове, върху които може да се клика. Всеки ListViewItem може да носи действие, задействано при кликване, без потребителят да трябва да пише каквото и да е; следващият урок показва как да се обработи това от страната на сървъра.
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 показва връзка „виж още“.
Актуализиране на уиджет, докато се показва
Един уиджет може да еволюира пред очите на потребителя, например за да покаже чернова, която моделът пише. Подайте на stream_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})
# Крайно състояние, след като текстът е завършен
yield draft_template.build({"text": text, "in_progress": False})
Само компонентите Text и Markdown с id показват своите актуализации в поток, дума по дума; за другите ChatKit заменя модифицираната част на уиджета.
А какво става с Python класовете?
Ще срещнете, дори в ръководствата на OpenAI, уиджети, изградени с класове: Card(children=[Text(value="…")]). Те все още работят, но SDK openai-chatkit 1.6.5 ги обявява за остарели в полза на WidgetTemplate: използването им генерира предупреждение, насочващо към .widget файлове. За нов проект започнете от шаблони. За съществуващ проект мигрирайте в свое собствено темпо: предупреждението не блокира нищо, но остарял клас може да изчезне в бъдеща версия.
Кога да използвате уиджет
Документацията цитира типични употреби:
- събиране на структуриран вход чрез форма или представяне на богат резултат (таблица, карта, диаграма), който текстът предава лошо;
- предлагане на избор между няколко опции;
- комбиниране на уиджета с действия за валидиране на избор, потвърждаване на стъпка или стартиране на обработка от страна на сървъра;
- придружаване на кратък обяснителен текст с интерактивна команда.
Обратно, не ги поставяйте навсякъде. Уиджет, който повтаря дума по дума това, което казва текстът, не добавя нищо, а разговор, наситен с карти, става толкова труден за четене, колкото и стена от текст.
Ключови изводи
- ChatKit уиджетът е декларативно описание (JSON), изградено от Вашия сървър, а не React компонент: ChatKit го рендира сам
- Три контейнера:
Card(самостоятелно съдържание),ListView(списък с опции),Basic(прегледи на entities) - Проектирайте в Widget Builder, експортирайте
.widgetфайл, заредете го сWidgetTemplate.from_file(...)и го попълнете сbuild(data); класоветеCard,Text… са остарели - Излъчвайте с
stream_widgetотrespondили от инструмент на агент сctx.context.stream_widget - Асинхронен генератор актуализира уиджета на живо; само
TextиMarkdownсidпредават поток дума по дума