> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webless.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Studio and Agentic mode

> Enable Agentic mode, design agents in Agent Studio, publish to production, and install the hosted Agent or a custom UI.

<Callout icon="sparkles" color="#5B21F5">
  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`.
</Callout>

## How Agentic mode fits together

```mermaid theme={null}
flowchart LR
  setup["Setup: Agentic mode"] --> publish["Publish to production"]
  publish --> studio["Agent Studio"]
  studio --> publishAgain["Publish updates"]
  publish --> tag["Hosted Agent script"]
  publish --> sdk["@webless/agent SDK"]
  tag --> visitors["Live visitors"]
  sdk --> visitors
```

| Mode | What visitors see | Install options in Setup |
| - | - | - |
| Agentic mode **off** | Classic Webless search widget | JavaScript, headless SDK, REST API, Google Tag Manager |
| Agentic mode **on** | Agent chat from Agent Studio | JavaScript and Agent SDK only |

<Info>
  The REST API path in [Build a custom
  frontend](/guides/custom-frontend) targets the **search widget** experience.
  [Install the Webless tag](/guides/tag-installation) covers script placement
  for the classic tag. When **published** production traffic uses Agentic mode,
  install with the production script or `@webless/agent` instead.
</Info>

## Enable Agentic mode

<Steps>
  <Step title="Open Setup for your index" icon="settings">
    In the Webless Console, open your index and go to **Setup**.
  </Step>

  <Step title="Turn on Agentic mode" icon="toggle-right">
    In the **Agentic mode** card, enable the switch and choose **Save**.
  </Step>

  <Step title="Publish to production" icon="rocket">
    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.
  </Step>

  <Step title="Design in Agent Studio" icon="palette">
    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.
  </Step>

  <Step title="Publish Studio changes" icon="refresh-cw">
    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.
  </Step>
</Steps>

## Install the hosted Agent

When Agentic mode is on, the **Install** section on Setup shows **JavaScript**
and **SDK** tabs.

<Steps>
  <Step title="Copy the production script" icon="file-code">
    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](/guides/tag-installation) for
    placement and verification tips.
  </Step>

  <Step title="Deploy and verify" icon="badge-check">
    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.
  </Step>
</Steps>

## 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.

<Steps>
  <Step title="Install the package" icon="package">
    ```bash theme={null}
    npm i @webless/agent
    ```

    Use the package from the browser only. Server-side rendering of the chat
    surface is not required for a basic integration.
  </Step>

  <Step title="Wire React with useAgentChat" icon="react">
    ```javascript theme={null}
    import { useAgentChat } from "@webless/agent/react";

    export function AgentChat() {
      const { state, submit } = useAgentChat({
        indexId: "YOUR_INDEX_ID",
        customerId: "YOUR_ORGANIZATION_ID",
        runtimeOrigin: "https://runtime.webless.ai",
      });

      return (
        <div>
          {state.messages.map((message) => (
            <p key={message.id}>{message.text}</p>
          ))}
          {state.streamingText ? <p>{state.streamingText}</p> : null}
          <button type="button" onClick={() => submit("How does this work?")}>
            Ask
          </button>
        </div>
      );
    }
    ```

    Copy exact `indexId`, `customerId`, and `runtimeOrigin` values from the **SDK**
    tab in Setup after Agentic mode is enabled.
  </Step>

  <Step title="Or use createAgentClient" icon="braces">
    ```javascript theme={null}
    import { createAgentClient } from "@webless/agent";

    const agent = createAgentClient({
      indexId: "YOUR_INDEX_ID",
      customerId: "YOUR_ORGANIZATION_ID",
      runtimeOrigin: "https://runtime.webless.ai",
    });

    await agent.sendTurn("How does this work?", {
      handlers: {
        onDelta(text) {
          // append streamed text
        },
      },
    });
    ```
  </Step>
</Steps>

<Warning>
  Publish Agentic mode to production before pointing real visitors at either the
  hosted script or `@webless/agent`. Preview grants and unpublished drafts are
  not a substitute for the live deployment.
</Warning>

## Switch back to the search widget

<Steps>
  <Step title="Disable Agentic mode" icon="toggle-left">
    On **Setup**, turn off **Agentic mode**, save, and publish when prompted.
  </Step>

  <Step title="Use widget install paths" icon="plug">
    Setup shows the full install panel again: JavaScript, `@webless/headless`,
    REST API, and Google Tag Manager for the classic search experience.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Agent Studio is locked or missing" icon="lock">
    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.
  </Accordion>

  <Accordion title="Install still shows API or GTM tabs" icon="list">
    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.
  </Accordion>

  <Accordion title="Custom UI connects but returns errors" icon="triangle-alert">
    Check that:

    * `indexId` and `customerId` match the values in Setup.
    * `runtimeOrigin` matches the environment Webless provisioned for your org.
    * You published to production after your latest Agent Studio changes.
  </Accordion>

  <Accordion title="Preview works but production does not" icon="eye">
    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.
  </Accordion>
</AccordionGroup>

## 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.