Learn how to design widgets in your agent experience.

Widgets are the containers and components that come with the inference.sh runtime. You can use prebuilt widgets, modify templates, or design your own to fully customize the agent UI in your product.

Overview

Widgets provide a structured way to render rich UI elements in agent conversations. They support:

Interactive elements - Forms, buttons, inputs, selects
Layout primitives - Rows, columns, boxes with flexible spacing
Typography - Text, titles, captions with styling variants
Visual elements - Badges, images, icons, dividers
Actions - Server-side and client-side event handling

Architecture

Widgets are constructed with a single container (Widget), which contains many components (WidgetNode).

code

1Widget (Container)2├── type: "ui" | "html"3├── title?: string4├── children: WidgetNode[]5└── actions?: WidgetActionButton[]

Type	Description
`ui`	Structured JSON - frontend renders WidgetNodes recursively
`html`	Raw HTML string - frontend renders directly (for generated content)

Quick Start

Go SDK

1import "inference.sh/common-go/pkg/models"2 3widget := &models.Widget{4    Type:  models.WidgetTypeUI,5    Title: "Task Complete",6    Children: []models.WidgetNode{7        {Type: models.WidgetNodeTypeText, Value: "Your task was completed successfully.", Variant: "muted"},8        {Type: models.WidgetNodeTypeBadge, Label: "success", Variant: "secondary"},9    },10}

Widgets are attached to tool invocations:

1toolInvocation.Widget = widget

Handle Actions

Widget actions allow users to trigger logic from the UI. Actions can be bound to different events on various widget nodes (e.g., button clicks) and then handled by your server.

1widget := &models.Widget{2    Type: models.WidgetTypeUI,3    Actions: []models.WidgetActionButton{4        {5            Label:   "Confirm",6            Variant: "default",7            Action: models.WidgetAction{8                Type:    "confirm",9                Payload: map[string]interface{}{"id": 123},10            },11        },12    },13}

Reference

Use the component documentation to see all available options:

Containers

Card - A bounded container for widgets

Layout

Row - Arranges children horizontally
Col - Arranges children vertically

Typography

Text - Displays plain text with styling
Markdown - Renders markdown-formatted text

Controls

Button - A flexible action button
Input - Text input field
Select - Dropdown single-select input
Checkbox - Binary selection control

Content

Image - Displays an image
Badge - A small label for status or metadata

Actions

Actions - Handle user interactions

Widgets Overview