Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Interaktive widgets

Lektion 19 af 25 Opdateret 3. november 2026 Udvikler
På denne side
  1. Hvad er en ChatKit-widget?
  2. Containere og komponenter
  3. Design af widgetten i Widget Builder
  4. Hvad en skabelon indeholder
  5. Visning af widgetten fra respond
  6. Lad agenten beslutte
  7. En klikbar liste
  8. Opdatering af en widget, mens den vises
  9. Hvad med Python-klasserne?
  10. Hvornår skal du bruge en widget?
  11. Vigtige pointer

Lektionen er omskrevet den 3. november 2026. Den tidligere version beskrev widgets som React-komponenter skrevet af udvikleren og registreret i grænsefladen ved hjælp af et ikke-eksisterende @openai/chatkit/react-modul. I ChatKit er en widget en deklarativ beskrivelse, som din server bygger, og som ChatKit selv renderer. Denne lektion følger openai-chatkit Python SDK 1.6.5, der bygger widgets ud fra .widget-skabeloner: dens klasser Card, Text, Badge… er forældede. Eksemplerne er kørt på en lokal ChatKit-server. Kilder: ChatKit widgets · Widgets (Python SDK) · Build interactive responses with widgets · Widget Builder.

Hvad er en ChatKit-widget?

Et tekstsvar er nok til forklaringer. Men når du skal præsentere en ordre, sammenligne tre abonnementer eller bekræfte en aftale, bliver tekst hurtigt til en mur af linjer, som brugeren skal genlæse. Widgets erstatter den tekst med en grænseflade: et kort, en liste, en formular eller et diagram, vist direkte i samtaleforløbet.

Tilgangen er deklarativ. Din server leverer hverken HTML eller en React-komponent: den beskriver widgetten i JSON ved hjælp af et lukket sæt komponenter og egenskaber og sender den ind i tråden som et fuldt udgyldigt element (en WidgetItem). ChatKit tegner den med sine egne komponenter og bruger temafarverne fra den foregående lektion. Det har to konsekvenser:

  • Du kan kun bruge komponenter og egenskaber, som ChatKit kender. Til gengæld forbliver renderingen konsistent med resten af grænsefladen, og vilkårlig HTML eller JavaScript fra serveren når aldrig siden.
  • Widgetten er en del af historikken: I efterfølgende runder konverteres den til input for modellen, som derfor „ser”, hvad den har vist brugeren.

Containere og komponenter

Hver widget har en rod, valgt blandt tre containere:

ContainerAnvendelse
CardSelvstændigt indhold: et resumé, en bekræftelse, en formular. Accepterer en status samt bekræftelses-/annulleringsknapper under indholdet
ListViewEt sæt valgmuligheder: restauranter, filer, ordrer. Dens børn er ListViewItems med indbygget „se mere”-funktionalitet (limit)
BasicReserveret til forhåndsvisning af enheder, der vises, når man holder musen over en omtale

Indeni samler du komponenter: tekst (Title, Text, Caption, Markdown), mærkater (Badge), layout (Row, Col, Box, Spacer, Divider), medier (Image, Icon), kommandoer (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, som en Form kan gruppere), diagrammer (Chart) og animationer (Transition). Siden Components i Widget Builder lister egenskaberne for hver enkelt med en editor, hvor du kan afprøve dem.

Design af widgetten i Widget Builder

Den anbefalede arbejdsgang starter i ChatKit Studios Widget Builder. Her designer du layoutet, udfylder datapanelet med prøveværdier for at vurdere renderingen og eksporterer derefter en .widget-fil. Det er en JSON-fil, der kombinerer skabelonen, skemaet for de forventede data (jsonSchema) og prøvedataene. Versionsstyr den sammen med din serverkode, f.eks. i en mappe widgets/.

På serversiden indlæser WidgetTemplate filen, og build udfylder den med rigtige data:

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

En relativ sti opløses ud fra den Python-fil, der kalder from_file, ikke fra startmappen. build accepterer enten et dictionary eller en Pydantic-model.

Hvad en skabelon indeholder

Skabelonen er en Jinja-model, der producerer widgettens JSON. Skabelonen til ordrekortet ser sådan ud:

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

Du vil sjældent skrive en skabelon i hånden, da Widget Builder genererer den for dig. Men evnen til at læse en vil spare dig tid, når det første problem opstår. Tre bemærkninger:

  • Filteret tojson konverterer hver værdi til gyldig JSON (en streng i anførselstegn, en boolean som true eller false) og escaper specialtegn: En apostrof eller et citationstegn i et produktnavn vil ikke ødelægge JSON’en.
  • Jinja kører i streng tilstand: Manglende data får build til at fejle i stedet for at producere en halvtom widget.
  • build validerer ikke data mod jsonSchema. Dette skema dokumenterer dataene; hvis de kommer fra et værktøj eller en database, skal du validere dem på forhånd, f.eks. med en Pydantic-model.

Konstruktøren WidgetTemplate(...) tager det samme indhold som en allerede indlæst .widget-fil: Det er praktisk til tests eller til en skabelon genereret af din egen kode.

Visning af widgetten fra respond

For at sende widgetten ind i tråden producerer stream_widget de tilsvarende ChatKit-begivenheder. Du videresender dem fra din respond-metode:

from chatkit.server import stream_widget

# I din ChatKitServer-klasse
async def respond(self, thread, input_user_message, context):
    card = order_template.build(await get_order_data("C-42"))  # dine 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 er den tekst, der kopieres til udklipsholderen, når brugeren klikker på kopieringsknappen under svaret. Serveren gemmer widgetten i store selv, ligesom ethvert andet broadcast-element.

Lad agenten beslutte

Ofte er det ikke din kode, der beslutter at vise et kort, men agenten, når samtalen kræver det. Giv den et værktøj, der udsender widgetten med AgentContext.stream_widget: stream_agent_response, set i lektion 17, transmitterer den til grænsefladen midt i svaret.

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

Tilføj værktøjet til agentens liste over tools. Strengen, som værktøjet returnerer, tjener modellen, som dermed ved, at kortet er på skærmen og kan kommentere det i stedet for at gentage det.

En klikbar liste

For at tilbyde et valg præsenterer ListView klikbare rækker. Hvert ListViewItem kan bære en handling, der udløses ved klik, uden at brugeren behøver at taste noget; næste lektion viser, hvordan du håndterer det på serversiden.

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

Ud over limit viser ChatKit et link til „se mere”.

Opdatering af en widget, mens den vises

En widget kan udvikle sig for brugerens øjne, f.eks. for at vise et udkast, som modellen skriver. Giv stream_widget en asynkron generator, der producerer successive tilstande af widgetten: ChatKit beregner forskellene og sender kun det, der ændres.

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})
    # Endelig tilstand, når teksten er færdig
    yield draft_template.build({"text": text, "in_progress": False})

Kun komponenterne Text og Markdown med en id viser deres opdateringer i en stream, ord for ord; for andre erstatter ChatKit den modificerede del af widgetten.

Hvad med Python-klasserne?

Du vil støde på widgets bygget med klasser, selv i OpenAI-guides: Card(children=[Text(value="…")]). De virker stadig, men openai-chatkit 1.6.5 SDK erklærer dem forældede til fordel for WidgetTemplate: Brug af dem udsender en advarsel, der peger på .widget-filer. Start nye projekter med skabeloner. For eksisterende projekter kan du migrere i dit eget tempo: Advarslen blokerer ikke noget, men en forældet klasse kan forsvinde i en fremtidig version.

Hvornår skal du bruge en widget?

Dokumentationen nævner typiske anvendelser:

  • Indsamling af struktureret input med en formular eller præsentation af et rigt resultat (tabel, kort, diagram), som tekst gengiver dårligt;
  • Tilbud om et valg mellem flere muligheder;
  • Kombination af widgetten med handlinger for at validere et valg, bekræfte et trin eller starte server-side behandling;
  • Ledsagelse af en kort forklarende tekst med en interaktiv kommando.

Omvendt skal du ikke placere dem overalt. En widget, der gentager ord for ord, hvad teksten siger, tilføjer intet, og en samtale mættet med kort bliver lige så svær at læse som en mur af tekst.

Vigtige pointer

  • En ChatKit-widget er en deklarativ beskrivelse (JSON) bygget af din server, ikke en React-komponent: ChatKit renderer den selv
  • Tre containere: Card (selvstændigt indhold), ListView (liste over valgmuligheder), Basic (forhåndsvisning af enheder)
  • Design i Widget Builder, eksportér en .widget-fil, indlæs den med WidgetTemplate.from_file(...), og udfyld den med build(data); klasserne Card, Text… er forældede
  • Udsend med stream_widget fra respond eller fra et agent-værktøj med ctx.context.stream_widget
  • En asynkron generator opdaterer widgetten live; kun Text og Markdown med en id streamer ord for ord