volcengine · yaozheng-fang · Jun 4, 2026 · Jun 4, 2026
diff --git a/docs/content/docs/framework/frontend/web-ui.en.mdx b/docs/content/docs/framework/frontend/web-ui.en.mdx
@@ -5,6 +5,16 @@ description: "A bundled React UI that renders agent-streamed A2UI, served alongs
 
 VeADK ships a React frontend that renders [A2UI](/en/docs/framework/frontend/a2ui) (agent-driven UI) streamed from an agent over the Google ADK API server. It talks to the same server process that `veadk frontend` launches, so there is **no separate backend to deploy**.
 
+## What it can do
+
+- **Chat**: multi-turn conversations that render streamed A2UI cards, plus thinking, tool calls, token usage and timing.
+- **Agent picker**: switch agents from the top-left; hover an agent to see its model and mounted tools.
+- **Session history**: auto-saved, time-sorted, reopen or delete.
+- **Smart search**: the *Session* source full-text-searches the current agent's history; the *Web* source calls the agent's mounted web-search tool live (using credentials from the server's environment variables).
+- **Add an AgentKit agent**: paste a URL + API key to connect a remote agent over the ADK protocol; it then appears in the picker.
+- **Tracing**: view the call flame graph for the current session.
+- **Login**: SSO (VeIdentity / GitHub / Google / any OIDC) or a local username.
+
 ## Run
 
 Build the UI once, then serve the UI and the agent API together with a single command:
@@ -39,7 +49,8 @@ cd frontend && npm run dev                    # http://localhost:5173 (proxies A
 | `--oauth2-user-pool` / `--oauth2-user-pool-client` | — | VeIdentity user pool / client **name**. Enables SSO when set. |
 | `--oauth2-user-pool-uid` / `--oauth2-user-pool-client-uid` | env `OAUTH2_USER_POOL_ID` / `OAUTH2_USER_POOL_CLIENT_ID` | Specify the pool / client by **UID** instead of name. |
 | `--oauth2-provider` / `--oauth2-provider-label` | `veidentity` | Login button provider id and display label. |
-| `--oauth2-redirect-uri` | `http://{host}:{port}/oauth2/callback` | OAuth2 callback URL. |
+| `--oauth2-redirect-uri` | `http://{host}:{port}/oauth2/callback` | OAuth2 callback URL (env `OAUTH2_REDIRECT_URI`). Set this when deploying behind a public host / runtime. |
+| Third-party / custom provider | see below | Connect GitHub / Google / any OIDC via env vars; see the Authentication section. |
 
 <Callout type="info">
   Outside dev mode, if the built frontend directory is not found, the command fails and asks you to run `npm run build` first (or use `--dev` with the Vite dev server).
@@ -66,6 +77,43 @@ protects the API while exempting the SPA shell and `GET /web/auth-config`, so th
 app loads and shows its own login page instead of being bounced to the IdP. The
 login button's label/icon is config-driven (`--oauth2-provider` / `-label`).
 
+**Third-party / custom OAuth2 (env vars)** — without a VeIdentity user pool, set
+`OAUTH2_CLIENT_ID` (and secret) to enable GitHub, Google, or any OAuth2/OIDC
+login. Endpoints are resolved in this order: a built-in preset
+(`OAUTH2_PROVIDER=github` / `google`) → OIDC discovery (set `OAUTH2_ISSUER`) →
+explicit endpoints (`OAUTH2_AUTHORIZE_URL`, etc.).
+
+| Env var | Description |
+| :-- | :-- |
+| `OAUTH2_PROVIDER` | Provider id: `github`, `google`, or a custom name. Drives the login button label and the preset. |
+| `OAUTH2_CLIENT_ID` / `OAUTH2_CLIENT_SECRET` | OAuth2 client credentials. **Setting `OAUTH2_CLIENT_ID` enables the generic provider.** |
+| `OAUTH2_ISSUER` | OIDC issuer base URL; endpoints are auto-discovered (e.g. `https://accounts.google.com`). |
+| `OAUTH2_AUTHORIZE_URL` / `OAUTH2_TOKEN_URL` / `OAUTH2_USERINFO_URL` | Explicit endpoints (for non-OIDC providers). |
+| `OAUTH2_SCOPE` | Override the requested scopes. |
+| `OAUTH2_PROVIDER_LABEL` | Override the login button text. |
+| `OAUTH2_REDIRECT_URI` | **Callback URL.** Set this when deploying behind a public host / runtime, and register the same value in your OAuth app; defaults to `http://{host}:{port}/oauth2/callback` locally. |
+
+GitHub (preset — only id/secret needed):
+
+```bash
+export OAUTH2_PROVIDER=github
+export OAUTH2_CLIENT_ID=<github-oauth-client-id>
+export OAUTH2_CLIENT_SECRET=<github-oauth-client-secret>
+export OAUTH2_REDIRECT_URI=http://127.0.0.1:8000/oauth2/callback
+veadk frontend --agents-dir examples
+```
+
+Google is the same with `OAUTH2_PROVIDER=google`; for any OIDC provider
+(Keycloak / Auth0 / Okta / …) set `OAUTH2_ISSUER` plus the client credentials. A
+full example lives at `examples/front_with_sso/`.
+
+<Callout type="info">
+  When deploying to a runtime / public host, the OAuth callback must point at an
+  externally reachable URL: set `OAUTH2_REDIRECT_URI` to the public callback URL
+  and register the same value in your OAuth app. The cookie `Secure` flag is
+  enabled automatically when that URL is HTTPS.
+</Callout>
+
 **No SSO (local username)** — without those flags, the login page asks for a
 username (letters + digits, ≤16), stored locally and used as the `user_id`.
 

diff --git a/docs/content/docs/framework/frontend/web-ui.mdx b/docs/content/docs/framework/frontend/web-ui.mdx
@@ -5,6 +5,16 @@ description: "内置 React 前端，用于渲染智能体流式返回的 A2UI，
 
 VeADK 自带一个 React 前端，用于渲染智能体经由 Google ADK API Server 流式返回的 [A2UI](/cn/docs/framework/frontend/a2ui)（智能体驱动 UI）。它与 `veadk frontend` 启动的是同一个服务进程，因此**无需单独部署后端**。
 
+## 功能一览
+
+- **对话**：与智能体多轮对话，渲染流式返回的 A2UI 卡片，并展示思考过程、工具调用、Token 与用时。
+- **Agent 选择器**：左上角切换 agent；悬停可查看该 agent 的模型与挂载的工具。
+- **历史会话**：自动保存、按时间排序，可重新打开或删除。
+- **智能搜索**：「会话」源在当前 agent 的历史消息中做全文检索；「网页」源调用该 agent 挂载的联网搜索工具实时检索（使用服务端环境变量里的凭据）。
+- **添加 AgentKit 智能体**：填入访问地址 + API Key，按 ADK 协议接入远程 agent，接入后出现在选择器中。
+- **Tracing 观测**：查看本次会话的调用火焰图。
+- **登录**：支持 SSO（VeIdentity / GitHub / Google / 任意 OIDC）或本地用户名。
+
 ## 运行
 
 先构建前端，再用一条命令同时提供 UI 与智能体 API：
@@ -39,7 +49,8 @@ cd frontend && npm run dev                    # http://localhost:5173（代理 A
 | `--oauth2-user-pool` / `--oauth2-user-pool-client` | — | VeIdentity 用户池 / 客户端**名称**。设置后启用 SSO。 |
 | `--oauth2-user-pool-uid` / `--oauth2-user-pool-client-uid` | 环境变量 `OAUTH2_USER_POOL_ID` / `OAUTH2_USER_POOL_CLIENT_ID` | 用 **UID** 代替名称指定用户池 / 客户端。 |
 | `--oauth2-provider` / `--oauth2-provider-label` | `veidentity` | 登录按钮的 provider 标识与显示文案。 |
-| `--oauth2-redirect-uri` | `http://{host}:{port}/oauth2/callback` | OAuth2 回调地址。 |
+| `--oauth2-redirect-uri` | `http://{host}:{port}/oauth2/callback` | OAuth2 回调地址（环境变量 `OAUTH2_REDIRECT_URI`）。部署到公网 / runtime 时需设置。 |
+| 第三方 / 自定义 provider | 见下文 | 通过环境变量接入 GitHub / Google / 任意 OIDC，详见「认证」一节。 |
 
 <Callout type="info">
   非开发模式下，若未找到已构建的前端目录，命令会报错提示先执行 `npm run build`（或改用 `--dev` 配合 Vite 开发服务器）。
@@ -60,6 +71,34 @@ veadk frontend --agents-dir examples \
 
 需要进程能拿到火山引擎凭证（AK/SK）。中间件保护 API、放行 SPA 外壳与 `GET /web/auth-config`，因此应用能加载并展示自己的登录页（而不是被直接重定向到 IdP）。登录按钮的文案/图标由配置驱动（`--oauth2-provider` / `--oauth2-provider-label`）。
 
+**第三方 / 自定义 OAuth2（环境变量）** —— 不依赖 VeIdentity 用户池时，只要设置 `OAUTH2_CLIENT_ID`（及密钥），即可接入 GitHub、Google 或任意 OAuth2/OIDC 登录。端点来源按以下顺序确定：内置预设（`OAUTH2_PROVIDER=github` / `google`）→ OIDC 自动发现（设置 `OAUTH2_ISSUER`）→ 显式端点（`OAUTH2_AUTHORIZE_URL` 等）。
+
+| 环境变量 | 说明 |
+| :-- | :-- |
+| `OAUTH2_PROVIDER` | provider 标识：`github`、`google` 或自定义名。决定登录按钮文案与内置预设。 |
+| `OAUTH2_CLIENT_ID` / `OAUTH2_CLIENT_SECRET` | OAuth2 客户端凭据。**设置 `OAUTH2_CLIENT_ID` 即启用通用 provider。** |
+| `OAUTH2_ISSUER` | OIDC issuer 基址，端点自动发现（如 `https://accounts.google.com`）。 |
+| `OAUTH2_AUTHORIZE_URL` / `OAUTH2_TOKEN_URL` / `OAUTH2_USERINFO_URL` | 显式端点（用于非 OIDC provider）。 |
+| `OAUTH2_SCOPE` | 覆盖请求的 scope。 |
+| `OAUTH2_PROVIDER_LABEL` | 覆盖登录按钮文案。 |
+| `OAUTH2_REDIRECT_URI` | **回调地址**。部署到公网 / runtime 时设为公网回调，并在 OAuth 应用中登记同一地址；本地默认 `http://{host}:{port}/oauth2/callback`。 |
+
+GitHub（预设，仅需 id/secret）：
+
+```bash
+export OAUTH2_PROVIDER=github
+export OAUTH2_CLIENT_ID=<github-oauth-client-id>
+export OAUTH2_CLIENT_SECRET=<github-oauth-client-secret>
+export OAUTH2_REDIRECT_URI=http://127.0.0.1:8000/oauth2/callback
+veadk frontend --agents-dir examples
+```
+
+Google 同理，把 `OAUTH2_PROVIDER` 换成 `google`；Keycloak / Auth0 / Okta 等任意 OIDC 则设 `OAUTH2_ISSUER` + 客户端凭据即可。完整示例见仓库 `examples/front_with_sso/`。
+
+<Callout type="info">
+  部署到 runtime / 公网时，OAuth 回调必须指向外部可访问的地址：把 `OAUTH2_REDIRECT_URI` 设为公网回调 URL，并在 OAuth 应用里登记同一地址。Cookie 的 `Secure` 标志会根据该地址是否为 HTTPS 自动开启。
+</Callout>
+
 **无 SSO（本地用户名）** —— 不传上述参数时，登录页会让用户输入一个用户名（字母 + 数字，≤16 位），保存在本地并作为 `user_id`。
 
 <Callout type="info">