AI Agent Widget

The AI Agent Widget adds a conversational AI experience to a Page. Use it when visitors or Project Users should interact with a configured Project AI Agent directly from the application's interface.

The widget controls how the AI Agent is presented on the Page. The AI Agent itself—including its instructions, knowledge, available functions, and behavior—is configured separately in AI Agents.

For other ready-made Page components, see Widgets. For configuring an agent's capabilities, see AI Agents.

When to Use an AI Agent Widget

Use an AI Agent Widget when you need:

• A conversational assistant embedded in a support, help, or application Page.
• A guided onboarding or knowledge experience that users can interact with through chat.
• A Page-specific entry point to an existing Project AI Agent.
• A floating AI launcher that users can access while working with other Page content.
• A conversation experience that receives Page context through supported Page Flow integration.

For example, a customer portal might provide an AI Agent that explains how to use the portal, while a product Page might offer an assistant that helps visitors understand available products or services.

Use AI Agents rather than the widget settings when you need to create or modify the underlying agent, manage its Knowledge Sources, configure functions, or change how the agent responds.

Understanding the Widget and the AI Agent

The Widget and the AI Agent work together, but they serve different purposes.

Component	Responsibility
AI Agent Widget	Places the conversation interface on a Page and controls its title, imagery, helper text, disclaimer, and appearance.
AI Agent	Defines the instructions, knowledge, and available functions that shape the conversation and the agent's capabilities.
Page Flow	Coordinates supported browser-side interactions and can provide Page context when that integration is available.
Backend / Cloud Flow	Handles protected processing and authorization-sensitive operations when required by the agent's functions or the application's workflow.

For example, changing a widget's Title changes the title presented to users; it does not rename or reconfigure the underlying AI Agent. Similarly, changing Prompt Guide text does not replace the agent's instructions.

A Project can use the same configured AI Agent from more than one Page where supported, while presenting it differently through each Page's widget settings.

Before Adding the Widget

The AI Agent Widget depends on an AI Agent configured in the Project.

Before setting up the Page interface:

1. Create or select the AI Agent in the AI Agents section.
2. Configure its instructions and relevant Knowledge Sources.
3. Configure any functions the agent needs to use, if applicable.
4. Check whether its intended operations require Project User access, Database access rules, or protected Backend processing.
5. Test the agent's behavior with representative questions and workflows.

A widget's appearance cannot correct missing agent instructions, unavailable knowledge, or incorrectly configured functions.

If the Page requires additional browser-side coordination, plan that separately through Page Flow.

Adding an AI Agent Widget

A typical setup workflow is:

1. Open the Page or Page Slice in the Page Editor.
2. Select the area where the AI Agent experience should appear.
3. Open the Element Library and add the AI Agent Widget.
4. Select the widget and open Element Settings.
5. Choose the configured Agent.
6. Set the Title, Logo Image URL or Media Library image, Prompt Guide, and AI Disclaimer as needed.
7. Choose the Appearance: Default or Floating.
8. Save and Preview the Page.
9. Test the conversation, its available controls, and any configured Agent functions or Page Flow interactions.

When using a floating widget, also verify that the launcher is easy to find and does not interfere with other controls on the Page.

For help with placing and configuring Page Elements, see Element Library and Element Settings.

AI Agent Widget Settings

The following settings configure the Widget's Page-level experience:

Setting	What It Controls
Agent	Selects the Project AI Agent used by the widget.
Title	Sets the title displayed in the AI Agent interface.
Logo Image URL	Specifies the image used for the AI Agent experience.
Select from Media Library	Allows an image to be selected from Project media.
Prompt Guide	Sets helper text displayed in the message box before the user types.
AI Disclaimer	Sets the disclaimer displayed below the message box.
Appearance	Chooses between an in-page chat area and a floating launcher.

Agent is required. Without a selected AI Agent, the widget cannot start a conversation.

These are the widget-specific options. General Design or Advanced properties, where supported, are covered under Element Settings.

Agent

Agent selects the configured Project AI Agent that responds to conversations started through this widget.

Choose an Agent whose instructions, knowledge, and available functions match the purpose of the Page.

For example:

Page Purpose	Appropriate Agent Configuration
Help Center	An agent configured to answer questions using the application's help knowledge.
Customer Portal	An agent configured for relevant account or service questions, subject to the application's access controls.
Onboarding	An agent configured to guide users through supported setup tasks.
Internal Operations	An agent configured for the specific processes and permitted functions needed by authorized users.

Selecting the Agent determines which configured agent the widget uses. It does not automatically grant that agent permission to access records, perform sensitive actions, or use functions that have not been properly configured.

When changing the selected Agent, retest the widget's messages, knowledge-based responses, and any connected workflows.

Title

Title controls the text shown as the title of the AI Agent interface.

Choose a title that communicates the assistant's purpose to the application's users. Examples include:

• Help Assistant
• Product Advisor
• Registration Assistant
• Customer Support
• Getting Started Guide

A clear title is especially helpful when a Page contains other interactive features or offers more than one support channel.

The Title is presentation text. It does not change the AI Agent's identity, instructions, or available functions in the AI Agents section.

Logo Image

The widget provides two related ways to choose the image used for the AI Agent experience:

Setting	Use
Logo Image URL	Specify the location of the desired image.
Select from Media Library	Choose an image already available in the Project's Media Library.

Choose an image that represents the assistant or its role. A simple icon or recognizable brand mark is usually more effective than a detailed illustration, particularly for a small floating launcher.

Image Considerations

• Use a clear image that remains recognizable at small sizes.
• Prefer a suitable square or compact image for launcher-style presentation.
• Check that the selected image is available in the intended Page context.
• Avoid images containing tiny text that becomes unreadable when reduced.
• Preview the widget on desktop, tablet, and mobile screens.

For managing Project media, see Media.

Prompt Guide

Prompt Guide is helper text shown in the message box before a user types a message. It provides a short indication of the kinds of questions or requests the assistant is intended to handle.

Examples include:

Experience	Example Prompt Guide
Support	Ask about your account, order, or next steps.
Onboarding	Tell me what you need help setting up.
Product guidance	Ask a question about our products or services.
Knowledge assistant	Ask a question about this Project's help content.

Writing an Effective Prompt Guide

A useful Prompt Guide should:

• Be short enough to read inside the message box.
• Use language that the Page's users understand.
• Describe tasks the selected AI Agent is actually configured to support.
• Avoid promising access to data or operations that the agent cannot perform.

For example, Ask me to cancel an order would be misleading if the Agent can only explain the cancellation procedure and cannot carry out the action.

Prompt Guide is not the Agent's instructions. It is interface guidance for the person using the chat. Agent behavior belongs in the AI Agents configuration.

AI Disclaimer

AI Disclaimer sets the disclaimer shown below the message box.

Use this text to set expectations about the AI-generated responses and remind users when important information should be verified.

A general-purpose example is:

AI can make mistakes. Verify important information before acting on it.

For an application with more consequential workflows, tailor the text to the actual use case and the expectations of the intended users. This may be especially important for legal, financial, health, safety, or other customer-impacting information.

Disclaimer Considerations

• Keep the disclaimer concise and understandable.
• Use wording relevant to the assistant's actual capabilities.
• Avoid claiming that the assistant provides guarantees or professional review unless those capabilities exist.
• Check that the disclaimer remains visible and readable in the selected Appearance and on smaller screens.

A disclaimer helps communicate limitations. It does not replace suitable agent configuration, access restrictions, authorization checks, or application safeguards.

Appearance

Appearance determines how the AI Agent conversation interface is presented on the Page.

Appearance	Behavior	Typical Use
Default	Displays the AI Agent as an in-page chat area.	Dedicated support, help, onboarding, or assistant sections.
Floating	Presents the AI Agent through a floating launcher.	An assistant that should remain accessible while users work with other Page content.

Default Appearance

Use Default when the conversation is an important part of the Page layout.

For example, a support Page might be organized as:

Support Page
  Heading (How can we help?)
  Text (Ask a question or explore help resources)
  AI Agent Widget (Default)
  Supporting links or contact information

With Default appearance, consider the size of the Page section containing the widget and how much space the conversation needs. Avoid placing a primary chat interface into a layout region that is too narrow for comfortable reading and message entry.

Floating Appearance

Use Floating when the AI Agent is a supporting experience rather than the Page's main content.

For example, an application dashboard can retain its usual layout while offering the assistant through a floating launcher.

In Floating appearance:

• Use a recognizable logo image for the launcher.
• Ensure that users can identify the launcher as an assistant or help control.
• Check the launcher against fixed navigation, forms, action buttons, and other interactive areas.
• Preview the expanded conversation interface as well as the launcher itself.

Do not assume that changing to Floating appearance changes the Agent's permissions, available knowledge, or conversation behavior. It changes how the interface is presented.

Responsive Presentation

Whether the widget uses Default or Floating appearance, preview it at desktop, tablet, and mobile widths.

Verify that:

• The title, conversation area, message box, and disclaimer remain readable.
• Users can access the available conversation controls.
• Long messages do not make the interface difficult to use.
• Floating content does not cover essential navigation or action controls.
• The Page remains usable when the on-screen keyboard is open on mobile devices.

Use the Page Editor's supported Design settings where adjustments are needed. See Element Settings.

Conversation Controls

Depending on the selected AI Agent and Project configuration, the AI Agent interface can provide controls such as:

Control	Purpose
New Chat	Starts a new conversation.
Refresh	Refreshes the current chat.
Available Chats	Lets the user access available conversations.
Prompt Library	Opens configured prompt choices when available.
Send Message	Submits a message to the AI Agent.

These are user-facing conversation controls, not additional widget settings listed under Element Settings.

The controls available to a particular user may depend on the Agent and Project configuration. Do not assume that every control appears in every widget configuration.

Testing Conversations

After configuring the widget:

1. Start a conversation and submit a representative question.
2. Verify that the response fits the selected Agent's intended purpose.
3. Try the available New Chat, Refresh, and chat-selection controls, where present.
4. Open the Prompt Library if the Agent has one configured and the interface exposes it.
5. Check the experience when the conversation contains multiple messages or longer responses.

Do not infer that conversation history is shared between different users, Pages, or widget instances unless the applicable Project behavior has been verified.

What the Widget Controls and What the Agent Controls

The distinction between Page-level presentation and AI Agent configuration is important when maintaining an application.

Configured in the AI Agent Widget

• The selected Project Agent.
• The title visible in the widget.
• The logo or launcher image.
• The Prompt Guide.
• The AI Disclaimer.
• Default or Floating appearance.

Configured in AI Agents

• Agent instructions and intended behavior.
• Knowledge Sources.
• Prompt Library entries.
• Available functions or actions.
• The capabilities the Agent is configured to use.

For example, if the assistant answers a question incorrectly because it lacks relevant knowledge, review the Agent's instructions and Knowledge Sources. Changing the widget's Title, logo, or Prompt Guide will not supply the missing knowledge.

For the underlying configuration areas, see AI Agents, Knowledge Sources, and Function Knowledge Sources.

AI Agent Widget and Page Flow

Page Flow provides browser-side application logic for a Page or Form. It can coordinate supported AI Agent interactions with the Page when the relevant integration is available.

For example, a Page may have information about the user's current activity or selected record. Where supported, Page Flow can provide relevant context so the conversation is more closely related to what the user is doing.

Possible context includes:

• The current Page or workflow step.
• A record the user has selected.
• A filter or category selected on the Page.
• Information about the current user that the application is permitted to use.

Example: Order Help in a Customer Portal

Consider a customer portal with an Orders Page and an AI Agent Widget.

The desired experience is for a customer to ask questions about an order they are currently viewing.

A supported implementation could follow this pattern:

1. The customer opens the Orders Page and selects an order.
2. Page Flow identifies the selected record and the context needed for the assistant.
3. Where supported, Page Flow supplies the relevant context to the AI Agent experience.
4. The customer asks a question through the widget.
5. The Agent responds based on its configured instructions, knowledge, functions, and permitted context.

This is an example of Page Flow coordination, not a claim that the widget automatically reads the Page's selected record or provides a particular context API.

If the Agent must retrieve sensitive order information or carry out a protected operation, access and authorization must be enforced through the appropriate Project data and Backend mechanisms.

When Page Flow Is Needed

Use Page Flow when the AI Agent is part of a larger Page interaction that requires supported browser-side coordination.

You do not need to add Page Flow merely to display an AI Agent Widget that uses an already configured Agent.

Avoid building additional Page Flow logic for behavior that is already handled by the selected AI Agent or its configured functions.

For related patterns, see Page Flow for Forms and Widgets.

Runtime Commands

The AI Agent Widget supports runtime commands for advanced Page Flow or client-side coordination. These are useful when the Page needs to provide context or hook into supported client-side behavior while the Page is running.

Common uses include:

• Passing request context from the current Page or selected record.
• Supplying prompt context through a callback.
• Registering supported hooks for advanced client-side behavior.
• Registering supported client operation hooks.

Supported commands include:

Command	Use It To
set-request-context	Provide Page-specific context for the AI Agent request.
set-prompt-context-cbFn	Provide prompt context through a callback function.
set-hook	Register a supported AI Agent Widget hook.
set-client-op-hook	Register a supported client operation hook.

Use them only when the Page experience needs runtime coordination beyond ordinary widget configuration.

For exact API details, see $io.ui.widgetCommand. For broader authoring patterns, see Page Flow and Custom Code.

Access, Security, and Privacy

An AI Agent Widget is a Page interface. It is not, by itself, an access-control or authorization mechanism.

Page Access

Configure Page access according to the intended audience, such as public visitors or authenticated Project Users.

A Page containing an AI Agent Widget may be public or restricted, depending on the application's requirements. Placing the widget on a restricted Page does not automatically establish authorization for every function or data source the Agent could use.

For Page access configuration, see Page Settings.

AI Agent Access

The selected Agent's Access (Security) settings control which client users and Project groups may access it through the AI Agent Widget. Configure both the Page and the Agent for the intended audience.

These Agent access settings apply to client access. They do not restrict trusted Cloud Flow modules from invoking the Agent. For example, a Web Hook applies its own Access (Security) settings to the incoming request and, after that check passes, can invoke the Agent regardless of the Agent's Widget access settings.

Agent and Page access do not authorize each underlying action. Functions, Database operations, Connections, and external tools still require their applicable server-side authorization and business-rule checks.

Agent Functions and Backend Authorization

When an Agent uses functions or interacts with Project data, ensure that the underlying operations enforce appropriate permissions.

For protected functionality:

• Configure only the Agent functions required for its purpose.
• Apply appropriate Database access rules where Project data is involved.
• Use trusted Backend processing, such as Cloud Flow, for operations that require protected credentials or server-side authorization.
• Validate authorization for sensitive operations independently of what the widget displays or what Page Flow supplies.
• Do not rely on Agent instructions, hidden controls, or a disclaimer as the sole protection for restricted operations.

Page Flow executes in the browser. It can coordinate interface behavior, but it should not be the sole enforcement mechanism for sensitive access or business rules.

For server-side behavior, see Cloud Flow.

Page Context and Sensitive Information

When passing context to an Agent through supported Page Flow operations:

• Provide only information necessary for the intended conversation.
• Confirm that the current user is allowed to access that information.
• Avoid including credentials, secrets, or unrelated personal information in browser-side context.
• Test how the Agent behaves when information is missing, unavailable, or outside the user's permissions.

The Agent's configured knowledge and functions should follow the same access expectations as the rest of the application.

Example: Building a Help Assistant

Consider an application that offers self-service help to its users.

1. Configure the Agent

In AI Agents, create or select an Agent intended to answer help questions. Configure relevant instructions and Knowledge Sources, and test the Agent's responses.

2. Add the Widget

Open the application's Help Page and add an AI Agent Widget from the Element Library.

Choose the configured Agent.

3. Configure the Interface

For example:

Setting	Example
Agent	The configured Help Agent.
Title	Help Assistant
Logo Image	A recognizable support icon from Project Media.
Prompt Guide	Ask a question about using this application.
AI Disclaimer	AI can make mistakes. Verify important information.
Appearance	Default

These values are illustrative. Use the actual Agent and presentation appropriate to your Project.

4. Test the Experience

In Preview, verify that users can submit messages and that the Agent responds to common questions. Try a question that the Agent should not be able to answer and verify that its behavior matches its configuration.

5. Consider Floating Access

If users should be able to reach the assistant while working elsewhere in the application, consider adding it in Floating appearance on the relevant Pages. Verify the appearance and behavior on each Page.

6. Publish and Verify

After saving and testing the Page, publish the Project when the changes are ready. Verify the experience in the published application using the intended user access context.

Saving or previewing changes does not, by itself, publish them. For the release workflow, see Publish Project.

Testing and Troubleshooting

Use the following checks when the widget is not behaving as intended:

Symptom	What to Check
Conversation cannot start	Confirm that Agent is selected and that the Agent is configured for the intended use.
Responses do not match the use case	Review Agent instructions, Knowledge Sources, and available functions rather than changing only widget text.
Incorrect or missing logo	Verify the Logo Image URL or selected Project Media item.
Prompt Guide is misleading	Adjust the guide to describe tasks the Agent actually supports.
Floating launcher is difficult to use	Preview its placement and expanded state at desktop, tablet, and mobile widths.
Expected conversation control is missing	Check whether that control is available for the selected Agent and Project configuration.
Page context is not reflected in the conversation	Verify the supported Page Flow coordination and the information being supplied.
A protected operation is denied or fails	Review the Agent's available functions and the applicable data access and Backend authorization rules.

Test both the normal path and common edge cases. For example, try empty or unclear requests, unsupported questions, and operations the current user should not be permitted to perform.

When Preview involves data access, Agent functions, or external services, consider whether those operations can affect actual Project data or connected systems.

Good Practices

• Configure the Agent first. Test its instructions, knowledge, and functions before placing the widget on a Page.
• Give the experience a clear purpose. Match the title and Prompt Guide to tasks the Agent actually supports.
• Choose appearance intentionally. Use Default for an embedded conversation and Floating for an assistant available alongside other Page content.
• Use recognizable imagery. Make the logo clear at the sizes where it will appear.
• Include an appropriate disclaimer. Set expectations for AI-generated responses without treating the disclaimer as a safeguard by itself.
• Keep Page Flow focused. Add browser-side coordination only where the experience requires it and the integration supports it.
• Limit contextual information. Pass only permitted, relevant information to the Agent.
• Enforce security in the correct layer. Protect sensitive data and operations through the applicable access rules and trusted Backend functionality.
• Test as the intended user. Verify the conversation, available controls, Page access, and responsive layout.
• Review the published experience. Test again after publishing changes to the Page or Agent configuration.

Common Mistakes

Avoid these patterns:

• Using Prompt Guide as instructions. Helper text in the message box does not configure what the Agent knows or is allowed to do.
• Expecting a widget to create the Agent. The Agent must already be selected and appropriately configured.
• Choosing the wrong Agent. A visually correct widget can still provide the wrong behavior if it points to an unrelated Agent.
• Using a detailed logo in Floating appearance. Small images can become difficult to recognize.
• Overloading the interface with disclaimers. Important limitations should be communicated clearly without overwhelming the message area.
• Assuming context is passed automatically. Page-specific information requires supported integration and deliberate configuration.
• Passing unnecessary sensitive data. Information in browser-side workflows should be minimized and access-appropriate.
• Treating Page restrictions as complete Agent authorization. Functions and data operations need their own appropriate security controls.
• Assuming every conversation control is always shown. Availability depends on the relevant Agent and Project configuration.
• Skipping mobile testing. Floating launchers and chat interfaces can interfere with other Page content on smaller screens.

The AI Agent Widget is most effective when the Page provides a clear conversational entry point, the AI Agent provides the intended knowledge and capabilities, and Page Flow and Backend controls are used only where the workflow requires them.

Related Topics

• Widgets
• Element Library
• Element Settings
• AI Agents
• Knowledge Sources
• Function Knowledge Sources
• Table Knowledge Sources
• Media
• Page Settings
• Page Flow for Forms and Widgets
• Cloud Flow
• Users
• User Groups