Gemini AI Assistants

The Assistants workspace turns a File Store-or a filtered slice of it-into a branded, document-grounded support experience for any website.

Because a File Store can contain multiple saved website and repository imports, one Assistant can answer across an entire product ecosystem instead of forcing customers to choose the right site first. Canonical Source URLs still take each citation back to the owning page, and server-enforced metadata scope can narrow a broadly shared corpus for a specific product, audience or version.

Each named Assistant owns its:

• visitor-facing identity and suggested questions;
• server-enforced document scope;
• behavior template, private system prompt, and optional Gemini model;
• theme, typography, panel, and launcher appearance;
• allowed website origins and request limit;
• deployment ID and publish state; and
• retained customer conversations.

The widget is rendered in a Shadow DOM, isolating it from the host page's CSS. It also traps its keyboard events so global website shortcuts do not fire while a visitor is typing.

Configure an Assistant​

1. Identity, behavior, and document scope​

Start with the visitor experience:

• Name identifies the Assistant in the dashboard and must be unique within the store.
• Title and Description appear in the widget header.
• Welcome message appears when a new thread opens.
• Suggested questions are editable single-line rows; press Enter or + to add another.

Then define how it should answer:

Choose Concise, Balanced, or Detailed, require grounded answers, enable citations, and customize the fallback and conversation-review notice. Require retrieved evidence adds a server-enforced citation threshold: when Gemini returns fewer than Minimum citations, the Assistant returns the configured fallback instead of exposing an unsupported answer. Strict grounding defaults to one citation and buffers streaming answers until evidence is checked. A custom Gemini model can be selected per Assistant; leaving it unset uses the server default.

Assistants open only when initiated by default. They can instead open after page load or when the visitor reaches the bottom of the page. Open with Ctrl/⌘+K is enabled for new Assistants and opens and focuses the widget independently of the automatic trigger.

Finally, restrict retrieval by category, doc type, status, locale, product, version, or tag. These filters and the private system prompt are applied by the server: they are not embedded in the public JavaScript and cannot be changed by the host website.

2. Design the widget​

Choose Auto, Light, Dark, Nord, Matrix, or Soft Pink. Auto first follows a light or dark value in the host page's color-scheme localStorage key, then the visitor's prefers-color-scheme, and uses your independently saved Light or Dark customizations.

Every theme is a preset, not a locked skin. Override and reset individual values for:

• assistant and user bubble backgrounds, borders, and text;
• accent, panel, and conversation backgrounds;
• panel and focus borders;
• primary, muted, link, error, and warning text; and
• a per-theme CSS font-family stack.

Only explicit overrides are saved. Reset theme appearance restores the complete preset, while the reset action beside a value restores only that variable. The live preview uses the same SVG icons, layout, and CSS variables as the real widget.

3. Customize the launcher and hosting rules​

The launcher can appear bottom-left or bottom-right. Configure its size, icon size, corner radius, shadow, border width, border color, background, and icon color. Choose Sparkles, Chat, or Help, or provide a PNG, JPEG, GIF, WebP, or SVG Data URI for a custom icon.

Leave Allowed origins empty to allow the Assistant on any website, or enter one exact HTTP(S) origin per line:

https://docs.example.com
https://*.example.com
http://localhost:5173

An exact origin includes its scheme and port. A wildcard matches subdomains but not the apex, so add https://example.com separately when both are needed. The requests-per-minute setting applies a rolling per-client limit to public chat requests.

4. Save, publish, and embed​

Use Save draft while configuring. Publish makes the deployment available and produces a stable embed snippet:

<script
  src="https://app.example.com/chat/ext/gemini/public/assistants/widget.js?g=abc123"
  async>
</script>

The deployment identifier is on the g query string. The public endpoint merges the saved configuration with the static widget and Markdown renderer, then returns a self-contained classic script. The /chat segment is AI Chat's default RoutePrefix; use your configured prefix when AI Chat is mounted somewhere else.

The host page may override presentation choices without changing retrieval behavior:

<script
  src="https://app.example.com/chat/ext/gemini/public/assistants/widget.js?g=abc123"
  data-theme="dark"
  data-position="bottom-left"
  data-accent="#7c3aed"
  data-icon="chat"
  async>
</script>

Mounting the launcher inside your own layout​

By default the launcher is a floating button anchored to a corner of the viewport. Set a Mount element CSS selector in the Assistant's Appearance settings, or data-mount on the script tag, to render the launcher inside an element you control instead - a nav bar, toolbar, or sidebar:

<nav>
  <a href="/docs">Docs</a>
  <span id="assistant-slot"></span>
</nav>

<script
  src="https://app.example.com/chat/ext/gemini/public/assistants/widget.js?g=abc123"
  data-mount="#assistant-slot"
  async>
</script>

The launcher becomes an inline element inside the target, so it participates in that container's layout like any other button, and the panel is anchored to it - opening below the launcher, or above it when the viewport has more room there. The panel itself is always rendered from document.body, so it overlays the page without affecting its layout, and it cannot be trapped inside a mount container that establishes a containing block (a transform, filter, or backdrop-filter ancestor, common in sticky headers).

data-mount on the script tag wins over the saved Mount element setting; pass data-mount="none" to force the floating launcher on a page whose layout has no slot for it. If the selector is invalid or matches nothing the widget writes a console warning and falls back to the floating launcher.

The Search widget accepts the same Mount element setting and data-mount attribute, so a documentation site can place a ⌘K search button and an Ask AI button side by side in its header while both dialogs still overlay the page. Invalid or unavailable deployments return JavaScript that writes a useful error to the browser console rather than a JSON response that fails silently.

The widget supports:

• streaming Markdown responses with plain-text fallback;
• citation links and source titles;
• suggested questions and a configurable welcome message;
• smooth fly-in/out animation from the launcher;
• maximized full-screen reading;
• a scrollable conversation thread;
• clearing the current thread without confirmation; and
• browser-local session continuity across page loads.

When an Assistant and Search widget share a page, Search uses Ctrl/⌘+K and the Assistant automatically uses Ctrl/⌘+Shift+K, avoiding competing global shortcuts.

Review customer conversations​

Authoritative conversations and messages are retained server-side so support teams can understand what visitors ask, identify missing coverage, and improve documentation.

Open View Conversations on a saved Assistant. The sidebar counts user messages, and each conversation shows its exact originating page. Expand the user-message navigator to jump directly to the corresponding Assistant response. Responses render as Markdown and retain their source citations.

The conversation count appears in View/Hide Conversations, making new activity visible while you work. The review view and selected conversation are deep-linkable.

Assistant lifecycle​

Run diagnostics checks deployment state, public store access, active and failed Gemini documents, model selection, origins, and the widget URL.

Deleting a File Store is broader: it removes the remote Gemini store, local and remote documents, local Search sections, Search widgets, query and click analytics, saved imports and runs, Assistants, conversations, and messages. Its dedicated impact summary and typed store-name confirmation are intentionally difficult to bypass.

Configuration reference​

Every setting below is stored per Assistant and served with the widget. The private prompt, model, document scope, origin policy, and rate limit stay on the server; the public embed contains only presentation and endpoint configuration.

Behavior templates​

The template seeds the specialist prompt only; the server always adds its shared RAG rules.

Changing the template replaces the prompt with that template's text, so save a customized prompt elsewhere before switching.

Grounding controls​

Choosing the model​

Leave Model unset to use the server default, or select any compatible Google chat model to override it per Assistant. The server default is gemini-flash-latest and can be changed for every Assistant at once from the App's environment:

GEMINI_ASSISTANT_MODEL=gemini-flash-latest

A models/ prefix is accepted and stripped. An unrecognized value is ignored in favor of the default rather than failing the deployment.

Appearance and hosting​

The document scope uses the fields described in Metadata & Source URLs - test the equivalent filters in Explore & Ask before publishing. To add a model-free search experience on the same page, see Website Search.