Skip to main content

Interactive Widgets

Widgets in DronaHQ can be interactive, allowing users to trigger actions directly from the UI rendered by the agent. These interactions enable the widget to send structured responses back to the agent, which can then continue the conversation flow or perform additional actions.

Interactive widgets are especially useful when the agent needs user confirmation, choices, or actions before proceeding.

Examples include:

  • Approving or rejecting a request
  • Selecting an option
  • Confirming a workflow step
  • Triggering follow-up actions
  • Providing feedback to the agent

The submit Function​

Interactive widgets communicate with the agent using a function called submit.

This function is provided automatically through the widget props.

props.submit

The submit function acts as a callback to the agent. When called, it sends a structured response object back to the LLM so the agent can continue processing.

Function Signature​

submit(response: {
  title: string,
  message: string
}): void

Parameters​

ParameterTypeDescription
titlestringThe text that will be displayed in the chat window to the user.
messagestringThe message or prompt that will actually be passed back to the agent for processing.

The title controls what the user sees in the chat as their action, while message is used for the agent's workflow logic.

Example: Request Action Widget​

Consider a scenario where the agent shows a widget for handling a request. The user can choose to:

  • Ignore the request
  • Delete the request
  • Approve and proceed

Each action sends a different object back to the agent via submit, containing both the display title and the full message for the agent to process.

export default function RequestActionWidget({ submit, request }) {
  return (
    <div>
      <h3>User Request</h3>
      <p>{request}</p>

      <div style={{ display: "flex", gap: "8px" }}>
        <button
          onClick={() =>
            submit({
              title: "Ignore",
              message: "Don't need to do anything. Ignore the request."
            })
          }
        >
          Ignore
        </button>

        <button
          onClick={() =>
            submit({
              title: "Delete",
              message: "Delete this request from the system."
            })
          }
        >
          Delete
        </button>

        <button
          onClick={() =>
            submit({
              title: "Proceed",
              message: "Please proceed with the request and mark it as approved."
            })
          }
        >
          Proceed
        </button>
      </div>
    </div>
  )
}

Interaction Flow​

The interactive workflow now works as follows:

  1. The agent displays a widget to the user.
  2. The widget contains interactive elements such as buttons.
  3. The user performs an action.
  4. The widget calls props.submit({ title, message }).
  5. The title is displayed in the chat as the user's action, and the message is sent back to the agent's LLM.
  6. The agent continues the conversation or workflow based on that message.

Example Interaction​

Step 1 — Agent displays widget​

The agent shows a request approval widget.

Step 2 — User interacts​

User clicks Proceed.

Step 3 — Widget sends response​

submit({
  title: "Proceed",
  message: "Please proceed with the request and mark it as approved."
})

Step 4 — Agent continues processing​

The chat displays Proceed as the user's input, and the LLM receives the provided message to continue the workflow accordingly.

Best Practices​

When building interactive widgets:

  • Send clear and descriptive titles for chat display and detailed messages for the agent.
  • Use buttons or action elements for user interactions.
  • Ensure each action sends a distinct response object with both title and message.
  • Keep interaction flows simple and intuitive.

Example:

Good object:

{
  "title": "Approve",
  "message": "Approve the request and mark it as completed."
}

Less useful object:

{
  "title": "Yes",
  "message": "Yes"
}

Clear, distinct titles and messages help the agent understand exactly what action should be taken next, while the chat remains user-friendly.

Interactive widgets allow DronaHQ agents to support structured workflows, confirmations, and decision-based interactions, enabling richer user experiences beyond simple text conversations.

Last updated on