Widget integration for Python tools

Develop your tool response to return the following types of widgets:

Form widgets
Interactive forms with various input field types including text inputs, text areas, number inputs, date pickers, date range pickers, radio buttons, checkboxes, combo boxes, file uploads, and tables for structured data collection.
For interactive forms, you can handle data from form submission with the on_event callback. This is how you capture and process user input from form submissions.
Custom widgets (user_defined)
Custom UI components with flexible rendering. This option is supported in embedded chat only.

Forms with interactive widgets

Form widgets provide structured input forms with various field types. You can create forms using either the FormWidget class or the dictionary format with the _meta field. The FormWidget class provides a Python-based approach to creating form widgets when using the ToolResult return format.

Import

Import the FormWidget class and input components to create forms in your Python tools:

from ibm_watsonx_orchestrate.run.widgets.forms import (
    FormWidget, TextInput, TextArea, NumberInput, DatePicker,
    DateRangePicker, RadioButton, Checkbox, ToolEvent, MessageEvent
)

Constructor parameters

title

str

required

The form title displayed to users.The following example sets the form title that appears at the top of the form:

title="User Registration Form"

inputs

List[InputWidget]

required

List of input widgets that define the form fields. Supported input types include:

TextInput
TextArea
NumberInput
DatePicker
DateRangePicker
RadioButton
Checkbox

The following example defines a list of input widgets for the form, including a required email field and an optional comments field:

inputs=[
    TextInput(
        name="email",
        title="Email Address",
        required=True
    ),
    TextArea(
        name="comments",
        title="Comments",
        placeholder="Enter your feedback"
    )
]

For more details on each input widget, see Additional features of Python tools: Creating a form tool.

description

str

Optional description text displayed below the form title.The following example adds a description that appears below the form title to provide additional context:

description="Please complete all required fields to submit your request."

submit_text

str

Custom text for the submit button. Defaults to “Submit”.The following example customizes the submit button text:

submit_text="Register Now"

cancel_text

str

Custom text for the cancel button. Defaults to “Cancel”.The following example customizes the cancel button text:

cancel_text="Go Back"

on_event

List[Union[ToolEvent, MessageEvent]]

List of event handlers that define actions when the form is submitted. For more information, see Handling data from form submission.These examples show how to configure event handlers for form submission using either ToolEvent or MessageEvent:

# Example for ToolEvent
on_event=[
    ToolEvent(
        tool="process_form",
        parameters={"email": "", "name": ""},
        map_input_to="submit"
    )
]

# Example for MessageEvent
on_event=[
    MessageEvent(
        message="Thank you for completing the survey! Your feedback helps us improve.",
        map_input_to="submit"
    )
]

When using the dictionary return format, widget contracts are defined in the _meta["com.ibm.orchestrate/widget"] field.

_meta

Dict[str, Any]

Additional metadata for custom extensions or context. Widget contracts in _meta["com.ibm.orchestrate/widget"] require the following fields:

Field	Type	Description
`response_type`	`string`	Must be `"forms"` for form widgets.
`json_schema`	`object`	JSON Schema defining form fields and validation rules. For more information, see JSON Schema details.
`ui_schema`	`object`	UI schema specifying widget types per field. For more information, see UI Schema details.
`form_data`	`object`	Pre-populated default values for form fields. For more information, see Form Data details.
`on_event`	`array`	Actions triggered on form submission. For more information, see Handling data from form submission.

The following example shows the basic structure of a tool response with a form widget using the dictionary format:

return {
    "content": [
        {
            "type": "text",
            "annotations": {
                "audience": ["user"]
            },
            "text": "Message text"
        }
    ],
    "_meta": {
        "com.ibm.orchestrate/widget": {
            "response_type": "forms",
            "json_schema": {...},
            "ui_schema": {...},
            "form_data": {...},
            "on_event": [...]
        }
    }
}

JSON Schema details

The json_schema field defines the structure, validation rules, and metadata for form fields. Implement the following properties to determine what data the form collects and how it must be validated:

Property	Type	Description
`title`	`string`	The form title displayed to users
`description`	`string`	Optional description text displayed below the form title
`type`	`string`	Must be `"object"` for form schemas
`required`	`array`	Array of field names that are required
`properties`	`object`	Object containing field definitions. For more information, see `properties` definition.

`properties` definition

Each field in the properties object can include:

Property	Type	Description
`type`	`string`	Data type: `"string"`, `"integer"`, `"number"`, `"boolean"`, `"array"`, `"object"`.
`title`	`string`	Label displayed for the field.
`description`	`string`	Help text or description for the field.
`default`	`any`	Default value for the field.
`enum`	`array`	Array of allowed values for selection widgets.
`enumNames`	`array`	Human-readable labels for enum values.
`format`	`string`	Format specification, for example, `"date"` for date fields.
`minimum`	`number`	Minimum value for numeric fields.
`maximum`	`number`	Maximum value for numeric fields.
`minItems`	`number`	Minimum number of items for array fields.
`maxItems`	`number`	Maximum number of items for array fields.
`oneOf`	`array`	Array of schema options for conditional validation.

The following example demonstrates a complete JSON Schema for a user registration form with required fields, validation rules, and data types:

{
  "title": "User Registration",
  "description": "Please complete all required fields",
  "type": "object",
  "required": ["firstName", "email"],
  "properties": {
    "firstName": {
      "type": "string",
      "title": "First Name"
    },
    "email": {
      "type": "string",
      "title": "Email Address",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "title": "Age",
      "minimum": 18,
      "maximum": 120
    }
  }
}

UI schema details

The ui_schema field specifies how form renders widget type and appearance for each field. You can define the following properties:

Property	Type	Description
`ui:widget`	`string`	Widget type to render.
`ui:placeholder`	`string`	Placeholder text for input fields.
`ui:options`	`object`	Additional widget-specific options.
`ui:enumNames`	`array`	Custom labels for enum values for combobox widget.

The ui_schema and json_schema work together to define form fields. They reference the same field names as keys:

JSON schema (json_schema.properties.fieldName) defines the data structure, type, validation rules, and metadata for a field.
UI schema (ui_schema.fieldName) specifies how that same field must be rendered as a widget.

For example, if you define a field called "firstName" in your JSON Schema properties, you must use the same key "firstName" in your UI Schema to specify its widget type. The field name acts as the connection point between the two schemas.The following example shows how the same field name ("firstName") is used consistently across all three schema objects:

{
  "json_schema": {
    "properties": {
      "firstName": {           // Field name: "firstName"
        "type": "string",
        "title": "First Name"
      }
    }
  },
  "ui_schema": {
    "firstName": {             // Same field name: "firstName"
      "ui:widget": "TextWidget"
    }
  },
  "form_data": {
    "firstName": "John"        // Same field name: "firstName"
  }
}

All three objects (json_schema.properties, ui_schema, and form_data) use the same field name as the key to reference the same form field.

Show TextWidget

Single-line text input for short text entries like names, emails, or identifiers.The following UI schema configures a TextWidget with a placeholder for a first name field:

{
  "firstName": {
    "ui:widget": "TextWidget",
    "ui:placeholder": "Enter your first name."
  }
}

The following JSON Schema defines the data structure for the first name field:

{
  "firstName": {
    "type": "string",
    "title": "First name"
  }
}

Show TextareaWidget

Multi-line text area for longer text entries like comments, descriptions, or messages.The following UI schema configures a TextareaWidget for multi-line text input:

{
  "accountNumber": {
    "ui:widget": "TextareaWidget"
  }
}

The following JSON Schema defines the account number field as a string type:

{
  "accountNumber": {
    "title": "Receiver account number",
    "type": "string"
  }
}

Show NumberWidget

Numeric input field for integer or decimal numbers.The following UI schema configures a NumberWidget for numeric input:

{
  "amount": {
    "ui:widget": "NumberWidget"
  }
}

The following JSON Schema defines a numeric field with a default value:

{
  "amount": {
    "title": "Amount to transfer",
    "type": "integer",
    "default": 50
  }
}

Show RadioWidget

Radio button group for single selection from a set of options.The following UI schema configures a RadioWidget for single selection:

{
  "account": {
    "ui:widget": "RadioWidget"
  }
}

The following JSON Schema defines radio button options with enum values and labels:

{
  "account": {
    "title": "Show Account Status",
    "type": "string",
    "enum": [true, false],
    "enumNames": ["Yes", "No"]
  }
}

Show CheckboxWidget

Checkbox for boolean yes/no selection.The following UI schema configures a CheckboxWidget for boolean selection:

{
  "account": {
    "ui:widget": "CheckboxWidget"
  }
}

The following JSON Schema defines a boolean field with oneOf validation for checkbox options:

{
  "account": {
    "title": "Show Account Status",
    "type": "boolean",
    "oneOf": [
      {
        "const": true,
        "title": "Yes"
      },
      {
        "const": false,
        "title": "No"
      }
    ]
  }
}

Show DateWidget (Single Date)

Date picker for single date selection. Use format: "date" in JSON Schema.The following UI schema configures a DateWidget for single date selection with a specific format:

{
  "account": {
    "ui:widget": "DateWidget",
    "format": "YYYY-MM-DD"
  }
}

The following JSON Schema defines a date field with a default value:

{
  "account": {
    "title": "Date to transfer amount",
    "type": "string",
    "format": "date",
    "default": "2025-08-12"
  }
}

Show DateWidget (Date Range)

Date range picker for selecting a start and end date. Requires ui:options with range: true.The following UI schema configures a DateWidget for date range selection by enabling the range option:

{
  "account": {
    "ui:widget": "DateWidget",
    "ui:options": {
      "range": true
    }
  }
}

The following JSON Schema defines a date range field as an array of date strings:

{
  "account": {
    "title": "Date to transfer amount",
    "type": "array",
    "items": {
      "type": "string",
      "format": "date"
    }
  }
}

The following form data example shows how to pre-populate a date range with start and end dates:

{
  "account": ["2025-09-12", "2025-09-25"]
}

Show ComboboxWidget

Dropdown/combobox for single selection from a list of options. Use ui:enumNames to provide human-readable labels.The following UI schema configures a ComboboxWidget with custom labels for dropdown options:

{
  "accountNumber": {
    "ui:widget": "ComboboxWidget",
    "ui:enumNames": [
      "Orchestrate account",
      "Watsonx account",
      "Instana account",
      "Linuxone account"
    ]
  }
}

The following JSON Schema defines the enum values that correspond to the custom labels:

{
  "accountNumber": {
    "title": "Select your account number",
    "enum": ["231", "312", "456", "654"]
  }
}

Show Table

Data table widget for displaying and selecting tabular data. Supports single or multi-row selection.The following UI schema configures a Table widget for displaying tabular data:

{
  "accountNumber": {
    "ui:widget": "Table"
  }
}

The following JSON Schema defines a table with column headers, selection mode, and display options:

{
  "accountNumber": {
    "title": "Select your account number",
    "type": "array",
    "headers": [
      { "key": "rowId", "header": "Employee ID" },
      { "key": "name", "header": "Name" },
      { "key": "band", "header": "Band" },
      { "key": "completed", "header": "Completed" }
    ],
    "items": {},
    "tableType": "multi",
    "isSortable": true,
    "isSearchable": true,
    "defaultRowSize": 10,
    "maxItems": 10,
    "minItems": 2
  }
}

The following table describes table-specific JSON Schema properties:

Property	Type	Description
`headers`	`array`	Array of column definitions with `key` and `header` properties
`tableType`	`string`	Selection mode: `"single"` or `"multi"`
`isSortable`	`boolean`	Enable column sorting
`isSearchable`	`boolean`	Enable table search functionality
`defaultRowSize`	`number`	Number of rows to display per page
`maxItems`	`number`	Maximum number of rows
`minItems`	`number`	Minimum number of rows

The following form data example shows how to populate table rows with employee data:

{
  "accountNumber": [
    { "rowId": "E1023", "id": "1", "name": "Ail, Alexis", "band": 7, "completed": "Yes" },
    { "rowId": "E1024", "id": "2", "name": "Baba, Arwen", "band": 8, "completed": "No" }
  ]
}

Show FileUpload

File upload widget for uploading one or multiple files.The following UI schema configures a FileUpload widget for file uploads:

{
  "accountDetails": {
    "ui:widget": "FileUpload"
  }
}

The following JSON Schema defines file upload constraints including size limits, allowed file types, and quantity restrictions:

{
  "accountDetails": {
    "type": "array",
    "title": "Please upload a file",
    "description": "These are the instructions",
    "file_max_size": 12,
    "file_types": [".csv", ".doc"],
    "multi": true,
    "maxItems": 5,
    "minItems": 1,
    "items": {}
  }
}

The following table describes file upload-specific JSON Schema properties:

Property	Type	Description
`file_max_size`	`number`	Maximum file size in MB
`file_types`	`array`	Allowed file extensions (e.g., `[".csv", ".doc"]`)
`multi`	`boolean`	Allow multiple file uploads
`maxItems`	`number`	Maximum number of files
`minItems`	`number`	Minimum number of files required

The following form data example shows the structure of uploaded file data with filename and URL:

{
  "accountDetails": {
    "fileName": "abc.csv",
    "url": "https://abc.in"
  }
}

Show FileDownloadWidget

File download link widget for providing downloadable files.The following UI schema configures a FileDownloadWidget for providing file download links:

{
  "accountDetails": {
    "ui:widget": "FileDownloadWidget"
  }
}

The following JSON Schema defines the file download structure with file metadata:

{
  "accountDetails": {
    "type": "string",
    "files": {
      "id": "dummy_id",
      "url": "http://localhost:9000/wxo-server-storage-bucket/02f7aba3-0c34-4aa2-8582-d7cab8faf1bd/output.pdf",
      "fileName": "output.pdf"
    }
  }
}

File download-specific JSON Schema properties. The files object contains:

Property	Type	Description
`id`	`string`	Unique identifier for the file
`url`	`string`	Download URL for the file
`fileName`	`string`	Display name of the file

Form data details

The form_data field provides pre-populated default values for form fields. These values appear in the form when it’s first displayed to the user, providing sensible defaults to guide users and pre-populating fields with known user data when available. Consider the following implementation details for form data:

Field names in form_data must match the field names defined in json_schema.properties.
Values must match the data type specified in the JSON schema.
Optional fields can be omitted or set to empty values. Use empty strings ("") for optional text fields.
For array fields such as date ranges or tables, provide an array of values.
For date fields, use ISO 8601 format (YYYY-MM-DD).
For selection widgets, ensure default values match one of the enum options.
For file upload fields, provide an object with fileName and url properties.

The following example demonstrates pre-populated form data with various field types including text, numbers, dates, and file uploads:

{
  "firstName": "John",
  "email": "john@example.com",
  "age": 25,
  "dateRange": ["2025-09-12", "2025-09-25"],
  "accountNumber": "231",
  "comments": "",
  "uploadedFile": {
    "fileName": "document.pdf",
    "url": "https://example.com/files/document.pdf"
  }
}

Handling data from form submission

The on_event defines actions triggered when users interact with the form. This is how you capture and process user input from form submissions:

`on_event` parameters

type

string

required

The action type to perform. Implement the code based on the format:

If you use the dictionary format, set the type value to either "tool" or "message".
If you use the FormWidget() class, you must call either ToolEvent() or MessageEvent() to perform the action.

tool

string

The name of the tool to invoke. Required when type is "tool".

parameters

object

Key-value pairs mapping form field names to their values. Required when type is "tool". Values are populated automatically from form data.

map_input_to

string

required

The event trigger. Use "submit" to trigger the action when the form is submitted.

message

string

The message to send to the agent. Required when type is "message".

Tool call

The ToolEvent() or type: "tool" actions invoke another tool with form data as parameters when the form is submitted. This is the most common approach for processing form submissions. You can use this approach when you need to process form data with custom logic, validate inputs, make API calls, or perform complex operations. The tool specified must accept parameters matching the form field names. When the user submits the form, this tool is automatically called with the form data.

Using `ToolEvent()` with `FormWidget`

When using the FormWidget class, configure on_event by using the ToolEvent class.

ToolEvent class

The ToolEvent class defines a tool invocation event that triggers when a form is submitted. Use this class with FormWidget to process form data through another tool.

Import

Import the ToolEvent class to define tool invocation events:

from ibm_watsonx_orchestrate.run.widgets.forms import ToolEvent

Constructor parameters

tool

str

required

The name of the tool to invoke when the event is triggered. This tool must be defined in your agent and accept parameters matching the form field names.The following example specifies the tool to invoke when the form is submitted:

tool="process_registration"

parameters

Dict[str, str]

required

Dictionary mapping form field names to their parameter names in the target tool. Keys must match the name attributes of form inputs. Values are typically empty strings that get populated with form data on submission.The following example maps form field names to tool parameters that will be populated with form data:

parameters={
    "firstName": "",
    "email": "",
    "age": ""
}

map_input_to

str

required

The event trigger type. Use "submit" to trigger the action when the form is submitted.The following example sets the event trigger to activate when the form is submitted:

map_input_to="submit"

The following example shows how to create a ToolEvent instance for processing form submissions:

from ibm_watsonx_orchestrate.run.widgets.forms import ToolEvent

# Define a tool event that processes form submission
event = ToolEvent(
    tool="process_user_data",
    parameters={
        "name": "",
        "email": "",
        "phone": ""
    },
    map_input_to="submit"
)

This complete example demonstrates a contact form with ToolEvent handling:

from ibm_watsonx_orchestrate.agent_builder.tools import tool
from ibm_watsonx_orchestrate.run.widgets.forms import FormWidget, TextInput, ToolEvent
from ibm_watsonx_orchestrate.run.tool_result import ToolResult, TextContent, Annotations, Role

@tool()
def show_contact_form():
    """Display contact information form."""
    form = FormWidget(
        title="Contact Information",
        inputs=[
            TextInput(
                name="name",
                title="Full Name",
                required=True
            ),
            TextInput(
                name="email",
                title="Email",
                required=True
            ),
            TextInput(
                name="phone",
                title="Phone Number",
                required=False
            )
        ],
        on_event=[
            ToolEvent(
                tool="save_contact",
                parameters={
                    "name": "",
                    "email": "",
                    "phone": ""
                },
                map_input_to="submit"
            )
        ]
    )
    
    return ToolResult(
        content=[
            TextContent(
                text="Please provide your contact information",
                annotations=Annotations(
                    audience=[Role.USER]
                )
            )
        ],
        widget=form
    )

@tool()
def save_contact(name: str, email: str, phone: str = ""):
    """Save contact information."""
    # Process the contact data
    return ToolResult(
        content=[
            TextContent(
                text=f"Contact saved: {name} ({email})",
                annotations=Annotations(
                    audience=[Role.USER]
                )
            )
        ]
    )

Using `type: "tool"` with dictionary format

When using the dictionary return format, configure on_event within the _meta field: The following example shows the basic structure of a tool event configuration in dictionary format:

"on_event": [
    {
        "type": "tool",
        "tool": "process_registration",
        "parameters": {
            "firstName": "",
            "email": ""
        },
        "map_input_to": "submit"
    }
]

This complete example demonstrates a two-tool workflow where the first tool displays a registration form and the second tool processes the submitted data:

@tool()
def show_registration_form():
    """Display registration form."""
    return {
        "content": [
            {
                "type": "text",
                "annotations": {
                    "audience": ["user"]
                },
                "text": "Please complete the registration form"
            }
        ],
        "_meta": {
            "com.ibm.orchestrate/widget": {
                "response_type": "forms",
                "json_schema": {
                    "title": "User Registration",
                    "type": "object",
                    "properties": {
                        "firstName": {"type": "string", "title": "First Name"},
                        "email": {"type": "string", "title": "Email"}
                    }
                },
                "ui_schema": {
                    "firstName": {"ui:widget": "TextWidget"},
                    "email": {"ui:widget": "TextWidget"}
                },
                "form_data": {"firstName": "", "email": ""},
                "on_event": [
                    {
                        "type": "tool",
                        "tool": "process_registration",  # Name of the tool to call when the event is triggered.
                        "parameters": {
                            # Each key must match a parameter name in process_registration(...).
                            # With map_input_to set to "submit", these fields are populated from the form submission.
                            "firstName": "",
                            "email": ""
                        },
                        "map_input_to": "submit"  # Maps submitted form values to the parameters above.
                    }
                ]
            }
        },
        "structuredContent": None,
        "context_updates": {}
    }

@tool()
def process_registration(firstName: str, email: str):
    """Process the registration form submission."""
    return {
        "content": [
            {
                "type": "text",
                "annotations": {
                    "audience": ["user"]
                },
                "text": f"Registration successful! Welcome, {firstName}. Confirmation sent to {email}."
            }
        ],
        "_meta": {},
        "structuredContent": None,
        "context_updates": {}
    }

Message call

The MessageEvent() or type: "message" actions send a predefined message to the agent instead of calling a tool. The agent processes this message as if the user had typed it. You can use this approach when you want to trigger a conversational flow or simple acknowledgment without custom processing logic.

Using `MessageEvent()` with `FormWidget`

The MessageEvent class defines a message event that sends a predefined message to the agent when a form is submitted. Use this class with FormWidget to trigger conversational flows without custom processing logic.

Import

Import the MessageEvent class to define message events:

from ibm_watsonx_orchestrate.run.widgets.forms import MessageEvent

Constructor parameters

message

str

required

The message to send to the agent when the event is triggered. The agent processes this message as if the user had typed it.The following example defines the message that will be sent to the agent when the form is submitted:

message="Thank you for your submission. Your request has been received."

map_input_to

str

required

The event trigger type. Use "submit" to trigger the action when the form is submitted.The following example sets the event trigger to activate when the form is submitted:

map_input_to="submit"

Example

The following example demonstrates a survey form using MessageEvent to send a thank you message upon submission:

from ibm_watsonx_orchestrate.agent_builder.tools import tool
from ibm_watsonx_orchestrate.run.widgets.forms import FormWidget, TextArea, RadioButton, MessageEvent
from ibm_watsonx_orchestrate.run.tool_result import ToolResult, TextContent, Annotations, Role

@tool()
def show_survey_form():
    """Display a simple survey form."""
    form = FormWidget(
        title="Quick Survey",
        description="Help us improve by sharing your feedback",
        inputs=[
            RadioButton(
                name="satisfaction",
                title="How satisfied are you?",
                options=["very_satisfied", "satisfied", "neutral", "dissatisfied"],
                option_labels=["Very Satisfied", "Satisfied", "Neutral", "Dissatisfied"],
                required=True
            ),
            TextArea(
                name="feedback",
                title="Additional Comments",
                placeholder="Share your thoughts...",
                required=False
            )
        ],
        submit_text="Submit Survey",
        on_event=[
            MessageEvent(
                message="Thank you for completing the survey! Your feedback helps us improve.",
                map_input_to="submit"
            )
        ]
    )
    
    return ToolResult(
        content=[
            TextContent(
                text="Please take a moment to complete our survey",
                annotations=Annotations(
                    audience=[Role.USER]
                )
            )
        ],
        widget=form
    )

Using `type: "message"` with dictionary format

When using the dictionary return format, configure on_event within the _meta field: The following example shows the basic structure of a message event configuration in dictionary format:

"on_event": [
    {
        "type": "message",
        "message": "Registration completed successfully",
        "map_input_to": "submit"
    }
]

The following example demonstrates a feedback form that sends a message to the agent upon submission:

@tool()
def show_feedback_form():
    """Display feedback form that sends a message to the agent."""
    return {
        "content": [
            {
                "type": "text",
                "annotations": {
                    "audience": ["user"]
                },
                "text": "Please provide your feedback"
            }
        ],
        "_meta": {
            "com.ibm.orchestrate/widget": {
                "response_type": "forms",
                "json_schema": {
                    "title": "Feedback Form",
                    "type": "object",
                    "properties": {
                        "rating": {"type": "string", "title": "Rating"},
                        "comments": {"type": "string", "title": "Comments"}
                    }
                },
                "ui_schema": {
                    "rating": {"ui:widget": "RadioButtonWidget"},
                    "comments": {"ui:widget": "TextAreaWidget"}
                },
                "form_data": {"rating": "", "comments": ""},
                "on_event": [
                    {
                        "type": "message",
                        "message": "Thank you for your feedback! Your response has been recorded.",
                        "map_input_to": "submit"
                    }
                ]
            }
        },
        "structuredContent": None,
        "context_updates": {}
    }

Custom widgets with `user_defined`

Create flexible UI components with custom widgets by rendering your own rich element logic. These widgets are passed through the _meta parameter and are rendered in embedded chat by using the userDefinedResponse event. Custom widgets in tool responses is a custom solution that operates independently of standardized UI protocols such as MCP-UI or A2UI. Application builders are responsible for implementing the rendering logic and managing security considerations.

The user_defined response type from tools is supported only in embedded chat. The webpage builder is responsible for implementing the rendering logic.

The following example demonstrates how to create a custom widget with user-defined response type and structured data:

from ibm_watsonx_orchestrate.agent_builder.tools import tool
from datetime import datetime, timezone

@tool
def get_custom_widget(
    widget_type: str = "custom_component",
    title: str = "Custom Widget",
    message: str = "This is a custom user-defined widget",
    action_url: str = "https://ibm.com"
):
    """
    Generate a custom widget with user_defined response type.
    
    This tool creates a custom widget that can be rendered in the watsonx Orchestrate
    embedded chat interface using custom rendering logic.
    """
    
    return {
        "content": [
            {
                "type": "text",
                "annotations": {
                    "audience": ["user"]
                },
                "text": f"{title}: {message}"
            }
        ],
        "_meta": {
            "com.ibm.orchestrate/widget": {
                "response_type": "user_defined",
                "user_defined": {
                    "user_defined_type": widget_type,
                    "title": title,
                    "text": message,
                    "timestamp": datetime.now(timezone.utc).isoformat(),
                    "action_url": action_url,
                    "custom_field": "You can add any custom data here",
                    "interactive": True
                }
            }
        },
        "structuredContent": None,
        "context_updates": {}
    }

Custom widget structure

When creating custom widgets, you must structure the metadata in a specific nested format that the chat can recognize and process. Place the widget data within the _meta parameter of your tool response by using the standardized namespace key to ensure proper routing to the userDefinedResponse event handler. The following example shows the required structure for custom widget metadata with detailed annotations:

_meta={
    # Namespace key that identifies this as an widget
    "com.ibm.orchestrate/widget": {
        # Indicates this is a custom user-defined response type
        "response_type": "user_defined",
        
        # Container object that holds all your custom widget properties
        # All custom data must be nested within this object
        "user_defined": {
            # Required: Identifies the specific type of widget being rendered
            # Use this to differentiate between different widget implementations in your handler
            "user_defined_type": "your_widget_type",
            
            # Optional: Display title for the widget
            "title": "Widget Title",
            
            # Optional: Main content or message text
            "text": "Widget content",
            
            # Add any additional custom properties your widget needs
            # Examples: timestamps, URLs, status flags, nested objects, arrays, etc.
            # All properties here are accessible in the userDefinedResponse event handler
        }
    }
}

Where:

Container structure: Nest all custom properties inside the user_defined object. This object acts as a container that isolates your custom data from the standard response structure.
Widget identification: Use the required user_defined_type field to identify your widget type. Your rendering logic uses this field to determine how to display the widget.
Flexible properties: Beyond the required user_defined_type, include any custom properties your widget needs, such as title, text, data, config, or domain-specific fields. The structure adapts to your requirements.
Multiple widget types: This flexible structure accommodates various widget types, from simple cards and notifications to complex dashboards and interactive components. Implement and test the rendering logic for each widget type to ensure proper display.

Rendering custom widgets

The webpage builder must implement the rendering logic for custom widgets in embedded chat. For complete implementation details, examples, and event handling, see the userDefinedResponse event documentation.

Release Notes

Get Started

Build

Deploy

Analyze

Developer experience

Legal notices

Forms with interactive widgets

Widget contract with FormWidget class

Import

Constructor parameters

Widget contract with dictionary format

JSON Schema details

`properties` definition

UI schema details

Form data details

Handling data from form submission

`on_event` parameters

Tool call

Using `ToolEvent()` with `FormWidget`

ToolEvent class

Import

Constructor parameters

Using `type: "tool"` with dictionary format

Message call

Using `MessageEvent()` with `FormWidget`

Import

Constructor parameters

Example

Using `type: "message"` with dictionary format

Custom widgets with `user_defined`

Custom widget structure

Rendering custom widgets

​Forms with interactive widgets

​Widget contract with FormWidget class

Import

Constructor parameters

​Widget contract with dictionary format

JSON Schema details

properties definition

UI schema details

Form data details

​Handling data from form submission

​on_event parameters

​Tool call

​Using ToolEvent() with FormWidget

ToolEvent class

Import

Constructor parameters

​Using type: "tool" with dictionary format

​Message call

​Using MessageEvent() with FormWidget

Import

Constructor parameters

Example

​Using type: "message" with dictionary format

​Custom widgets with user_defined

Custom widget structure

Rendering custom widgets

Forms with interactive widgets

Widget contract with FormWidget class

Widget contract with dictionary format

`properties` definition

Handling data from form submission

`on_event` parameters

Tool call

Using `ToolEvent()` with `FormWidget`

Using `type: "tool"` with dictionary format

Message call

Using `MessageEvent()` with `FormWidget`

Using `type: "message"` with dictionary format

Custom widgets with `user_defined`