Use widgets in your agent

Once you've saved a widget, the next step is wiring it into a v3 agent so it shows up in real conversations.

Before you start

• Make sure your bot has v3 agents enabled. Widgets only render in v3 conversations. If you're not sure, open AI Agent → Configuration and check that Routing logic appears as a sub-page — that's a quick v3 indicator.
• Save the widget first. You'll be picking it from a list, so it must already exist.

Two ways to attach a widget

In v3 there are two places to wire a widget:

Surface	When to use
Agent profile → Lifecycle → Rich Media	The widget belongs to this agent's flow and should be available whenever the agent is in control. Add the widget once at the agent level; the agent decides when to emit it during its turn.
Workflow node Rich Media	The widget is rendered at a specific step of a multi-step workflow that the agent triggers as a tool. Bind the widget at that workflow node.

For most v3 bots, the agent-level Rich Media path is the simpler one — you attach the widget alongside other rich media (Quick Replies, Schedule Picker, etc.) and let the agent decide when to show it.

Path A: Attach at the agent level

Step A1: Open the agent's profile

AI Agent → Agents → <your agent>. Scroll to the Lifecycle section. You'll see a Rich Media row with chips for any rich-media items already attached (e.g. Quick Replies, Schedule Picker).

Step A2: Add the widget

Click + Add on the Rich Media row. The picker lists rich-media types, including any widgets you've saved. Pick yours by name. The agent stores the widget's slug, so renaming the widget later won't break the link.

Step A3: Reference the widget from Agent instructions

Mention the widget in the agent's Agent instructions so the agent knows when to render it. Example: "When the user is ready to pick a test-ride slot, render the @TestRideSlotPicker widget. Read the chosen slot from the widget output and confirm back to the user."

The @-mention chip stays linked to the widget's slug across renames.

Path B: Attach inside a workflow node

Use this when the widget appears at a specific step in a multi-step workflow tool — typically a structured-input step inside a booking, onboarding, or compare-and-choose journey.

Step B1: Open the workflow

Go to the workflow editor (Studio → Build → Flows) and open the workflow where you want the widget to render.

Step B2: Add a rich-media node

Add (or open) a message / prompt node that has a Rich Media sub-section. Choose Widget as the media type, then pick your saved widget from the list. The node stores the widget's slug.

There's usually a quick "open in editor" link that jumps back to Widget Builder for that widget — handy when you find a bug while testing.

Step B3: Bind schema inputs

Remember the schema you wrote when you built the widget? This is where it pays off.

The workflow node prompts you to bind each schema input. You can:

• Bind to a workflow variable (e.g. {{user.name}} for userName).
• Bind to a static value (e.g. an array of available time slots).
• Bind to a previous tool result (e.g. data fetched from an API call earlier in the workflow).

If you skipped required in your schema, the editor won't warn you about missing inputs. Mark your required fields properly to save yourself the headache.

Step B4: Read the widget's output downstream

When the user submits the widget, your output keys become available as workflow variables. The next node in the workflow can read them — usually as {{widgetOutput.selectedSlot}} or similar (the exact reference matches the keys you defined in the widget's Output pane).

Use these to:

• Branch on user choice in subsequent nodes.
• Pass data into the next API call.
• Update the user's session or profile.
• Confirm what they picked back to them.

Test the widget in the Playground

Both paths share the same test surface — the Playground on each agent's profile.

1. Open the agent that will trigger the widget (AI Agent → Agents → <agent>) and click the play (▶) icon in the title bar.
2. Send a message that should cause the agent to render the widget (for Path A) or that triggers the workflow with the widget node (for Path B).
3. The widget renders inline inside the Playground chat. Interact with it like a real user — fill the form, click the button.
4. When you submit, the widget's output flows back into the conversation. Watch the agent's next reply to confirm it read the output correctly.

If the widget doesn't render:

• Confirm you're on a v3 bot.
• For Path A — confirm the agent's instructions reference the widget by @-mention so the agent knows to render it.
• For Path B — confirm the workflow node was actually triggered.
• Confirm any required schema inputs are satisfied — a missing required input will block render.

If the agent doesn't react to the widget output:

• Re-send the same prompt and watch what the agent says — if it never acknowledges the submission, the agent isn't reading the right output key.
• For Path A — sharpen the agent's instructions to say what to do with the widget's output keys.
• For Path B — confirm the downstream workflow node is reading the right keys.

What about voice channels?

Widgets can be triggered from voice workflows too. The widget engine has voice integration, but you need to design for it:

• Provide a voice-friendly fallback for any UI-only affordance (a button with no spoken equivalent will confuse a voice user).
• Keep the same output shape for voice and chat — the agent shouldn't need to branch on channel to read your widget output.

Streaming widget messages

Widget messages can stream — meaning the widget can update progressively while the bot is still producing its response. If your widget depends on partial state, write your JSX to handle missing or undefined values gracefully during the stream. Otherwise mid-stream renders may flash an empty state.

Best practices

• Always test the widget end-to-end inside an agent run. The widget might look perfect in the builder's preview but break on a real schema input you forgot to handle.
• Pre-warn workflow owners before changing a live widget's schema. A schema change can break every workflow that wires the widget.
• Save a copy before risky changes. Widget Builder doesn't version content — saving overwrites. For a major redesign, save it under a new name first, validate, then switch workflows over.
• Re-send the same prompt to debug. "Why didn't the agent read my output?" is usually a mismatched output key or instructions that don't tell the agent what to do with the submission.

Common issues at a glance

Symptom	Likely cause
Widget never renders	Bot isn't v3, or required schema input is missing.
Workflow node shows "schema mismatch"	Widget schema changed after wiring — re-bind inputs.
Output keys missing in the next prompt	Widget output shape doesn't match what was actually emitted. Check the trace for the real payload.
Widget looks fine in builder but breaks in agent run	A required schema input wasn't satisfied at the call site.

Continue to: Best Practices.