Agentic mode replaces the classic search widget with a conversational Agent
experience. Configure agents in the Webless Console, publish from Setup, then
install with the production script or
@webless/agent.How Agentic mode fits together
The REST API path in Build a custom
frontend targets the search widget experience.
Install the Webless tag covers script placement
for the classic tag. When published production traffic uses Agentic mode,
install with the production script or
@webless/agent instead.Enable Agentic mode
Open Setup for your index
In the Webless Console, open your index and go to Setup.
Turn on Agentic mode
In the Agentic mode card, enable the switch and choose Save.
Publish to production
On Setup, confirm your build is ready and choose Publish to
production.Your first successful publish with Agentic mode saved unlocks Agent
Studio for that index. Publishing also binds the current Studio draft to
the production build visitors receive.
Design in Agent Studio
Open Agent Studio from the index navigation. Configure agents, design,
tools, and preview conversations.Preview uses your latest saved Studio draft. Live traffic uses the
deployment from your most recent publish with Agentic mode on.
Publish Studio changes
After you change agents or design in Studio, return to Setup and publish
again so production picks up the draft you want visitors to see.
Install the hosted Agent
When Agentic mode is on, the Install section on Setup shows JavaScript and SDK tabs.Copy the production script
Open the JavaScript tab and copy the production snippet shown for your
index.Add it near the start of your site
<body>, the same way you would install
the classic tag. See Install the Webless tag for
placement and verification tips.Deploy and verify
Deploy your site, open a production page, and confirm:
- The script loads without console errors.
- The Agent launcher or panel appears where you configured it in Agent Studio.
- A test question returns a streamed Agent reply.
Build a custom Agent UI
Use@webless/agent when you want to own layout, branding, and surrounding
product chrome while still calling the Webless Agent runtime.
Install the package
Wire React with useAgentChat
indexId, customerId, and runtimeOrigin values from the SDK
tab in Setup after Agentic mode is enabled.Or use createAgentClient
Switch back to the search widget
Disable Agentic mode
On Setup, turn off Agentic mode, save, and publish when prompted.
Use widget install paths
Setup shows the full install panel again: JavaScript,
@webless/headless,
REST API, and Google Tag Manager for the classic search experience.Troubleshooting
Agent Studio is locked or missing
Agent Studio is locked or missing
Confirm Agentic mode is saved on Setup and that your workspace has access to
Agent Studio. You may need a successful publish with Agentic mode enabled
before Studio reflects production state.
Install still shows API or GTM tabs
Install still shows API or GTM tabs
With Agentic mode enabled, Setup keeps those tabs visible for reference and
shows an amber banner on API and Google Tag Manager that they apply
to the classic widget experience. Use JavaScript or the Agent SDK
tab for Agentic install guidance.
Custom UI connects but returns errors
Custom UI connects but returns errors
Check that:
indexIdandcustomerIdmatch the values in Setup.runtimeOriginmatches the environment Webless provisioned for your org.- You published to production after your latest Agent Studio changes.
Preview works but production does not
Preview works but production does not
Preview exercises the unpublished Studio draft. Production serves the
deployment bound at publish time. Publish again from Setup after saving
Studio changes you want visitors to receive.
Best practices
- Save Agent Studio changes before you publish; publishing materializes the current draft.
- Re-test the production script after template, CSP, or consent-banner changes.
- Keep one integration path per environment: hosted script or custom SDK UI, not both fighting for the same page real estate unless you design for it.
Need help?
Contact the Webless team with:- Your index ID and production site URL
- Whether Agentic mode is enabled and the time of your last publish
- The install path you use (hosted script or
@webless/agent) - Screenshots of browser console errors, if any