building-chat-widgets_skill

Overview

This skill teaches how to build interactive AI chat widgets with buttons, forms, entity tagging (@mentions), composer tools, and both client- and server-handled actions. It covers the full widget lifecycle, common patterns, component reference, and critical implementation details for robust integrations. Use it to create agentic UIs where users click, tag, or trigger backend workflows from chat.

How this skill works

Widgets are produced by agent tools as WidgetItem objects and rendered in the chat UI. Actions on widgets dispatch events that are processed either by a frontend onAction callback (client handler) or by a backend action() method (server handler). Server handlers can replace widgets, stream assistant messages, and emit client effects. Entity tagging and composer tools let users mention entities and select AI modes that influence agent routing.

When to use it

• When you need clickable UI elements inside chat (buttons, list items, selectors).
• When actions must trigger backend processing, data mutation, or widget replacement.
• When you want entity tagging (@mentions) that resolves to interactive search results.
• When providing composer tools or mode selection that change agent behavior.
• Not for simple text-only chat flows without interactive elements.

Best practices

• Choose a single handler per action: client OR server, never both.
• Always include meaningful data in action.payload (do not use action.arguments).
• Treat context as a RequestContext object — don’t rewrap it. Access context.user_id and metadata directly.
• When emitting synthetic user messages, include all required fields (id, thread_id, created_at, content with type="input_text").
• Replace or update widgets after actions to reflect state; stream assistant messages for follow-up UX.

Example use cases

• Clickable ListView of search results where client actions navigate to detail pages.
• Server-handled selection that updates a selector widget, streams a confirmation assistant message, and triggers a client effect.
• Entity tagging for people or articles that resolves via onTagSearch and navigates on entity click.
• Composer tool selection (e.g., Chat vs. Event Finder) that routes the thread to different agents on the backend.
• Buttons that request more suggestions by sending follow-up user messages from the frontend.