Acme Answers: a company knowledge Q&A page

The hello-world of Glean apps: one page, one input, one permission-aware cited answer — built two ways, with the Web SDK and with the Chat API.

~30 minBeginner

Problem

Every team has the same first Glean app: a single page where anyone can ask a company question and get a cited, permission-aware answer. There are two equally valid ways to build it — this recipe builds both, side by side, so you can pick the trade-off that fits your app.

Architecture

Acme Answers pagesingle input + answer card

Path A: Web SDKrenderChat — Glean owns the UI

Path B: Chat APIchat.create — you own the UI

Gleanpermission-aware answers with citations

Prerequisites

A Glean instance with content indexed

An OAuth access token or Glean API token with the CHAT scope

Node 20+ (Chat API path) or any static page (Web SDK path)

Steps

1

Pick a path

Path A (Web SDK) renders Glean's own chat UI for you — fastest to stand up, no backend code. Path B (Chat API) calls the Chat API directly from your own backend — you own every pixel of the UI and the request/response shape. Both reach the same place: a permission-aware, cited answer.

Web SDK

1

Scaffold the project

npx tiged --mode=git gleanwork/glean-cookbook/recipes/acme-answers/web-sdk acme-answers

2

Install dependencies

cd acme-answers && npm install

3

Credentials

Default SSO auth needs no configuration — the Web SDK relies on the user's existing browser session with Glean.

4

Run it

npm run dev

5

Verify

Open the printed local URL and ask "What's our PTO policy?" — confirm a real, cited answer renders inside Glean's chat UI.

Chat API

1

Scaffold the project

npx tiged --mode=git gleanwork/glean-cookbook/recipes/acme-answers/chat-api acme-answers

2

Install dependencies

cd acme-answers && npm install

3

Set credentials

Fill in GLEAN_API_TOKEN and GLEAN_INSTANCE — see the client-api-oauth-or-token auth section in cookbook-conventions for how to get a token.

cp .env.example .env

4

Run it

Leaves the server running so you can try it yourself at http://localhost:3000 — stop it (Ctrl-C) before the deterministic verify step below, which starts its own instance.

npm start

5

Verify

Starts the server itself, runs both demo queries for real, and asserts the response shape (non-empty answer, non-empty deduped citations with title+url) — exits non-zero on any failure. Do not report this recipe as done until this passes.

npm run verify

Take it further

Swap in a specific agent by passing its agentId — to the chat component for Path A, or in the chat.create request for Path B.

Stream responses instead of waiting for the full answer (both the Web SDK and the Chat API support streaming).

Add follow-up prompt suggestions from the Chat API response's followUpPrompts.

Scaffold starter code

Copies a prompt your AI assistant can build from.

At a glance

SurfacesClient API, API clients, Web SDK

StatusShowcase

Time~30 min

Required scopes

CHAT

Code assets

Web SDK variant — renderChat in a pageChat API variant — one chat.create call, citations rendered