VeADK Frontend

VeADK ships a production-grade React frontend — an enterprise agent-application workbench that talks to agents over the Google ADK API server: create, debug, manage, and use agents from the UI. veadk frontend is a self-contained launcher: in the default mode it serves this React UI and the agent API from a single process on the same origin, so there is no separate backend to deploy and no cross-origin setup.

What it can do

Create agents: use a conversational, custom, or template flow to produce a runnable VeADK project (agent.py, requirements.txt, and so on) that you can preview, edit, and download. The workflow entry is marked as coming soon and cannot be selected.
Manage agents: list AgentKit runtimes deployed through the workbench by the current user, inspect control-plane settings, resources, and primary-agent information, or remove an unused runtime.
Chat and debug: multi-turn conversations showing thinking, tool calls, token usage and timing; conversations also render the A2UI rich-UI cards an agent returns.
Agent topology: display sequential, parallel, loop, LLM, and A2A nodes and the transfer path during a conversation.
Agent picker: switch agents from the top-left; hover an agent to see its model and mounted tools.
Skill center: browse and discover reusable skills to use when creating agents.
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 and 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 or a local username.

Complete tool OAuth authorization

When an MCP or another tool needs OAuth credentials, Frontend displays an authorization card in the conversation. Starting authorization opens the identity provider in a new window. After the callback returns to Frontend, the current tool call resumes automatically without resending the message. If the page cannot capture the callback automatically, the UI asks for the complete callback URL. The callback URL registered with the identity provider must match the tool configuration and point to an address that reaches the current Frontend. If the browser blocks the authorization window, allow pop-ups for the site and retry.

Run

Build the UI once, then serve the UI and the agent API together from a single process.

Build the UI

cd frontend && npm install && npm run build

The build output is served as the UI by veadk frontend. When VeADK is installed via pip, a built UI is already bundled in the package, so you can run it directly.

Launch

veadk frontend --agents-dir examples
# open http://127.0.0.1:8000

Dev mode (hot reload)

In dev mode veadk frontend serves only the agent API and allows CORS from the Vite dev server (http://localhost:5173); the UI runs separately under Vite with hot reload.

veadk frontend --dev --agents-dir examples   # API only, CORS for Vite
cd frontend && npm run dev                    # http://localhost:5173, proxies API

The `veadk frontend` command

Option	Default	Description
`--agents-dir`	`.`	Directory of agent apps; each subdirectory exposes a `root_agent`.
`--frontend-dir`	packaged build, falling back to `./frontend/dist`	Override the built React UI directory. Priority: the explicitly passed directory, then the packaged UI, then `./frontend/dist` relative to the current directory.
`--host`	`127.0.0.1`	Address to bind.
`--port`	`8000`	Port to bind.
`--dev`	off	Dev mode: serve the API only and allow CORS from the Vite dev server (`http://localhost:5173`).
`--oauth2-user-pool`	—	VeIdentity User Pool name. Enables SSO when set together with the client.
`--oauth2-user-pool-client`	—	VeIdentity User Pool client name.
`--oauth2-user-pool-uid`	env `OAUTH2_USER_POOL_ID`	Specify the pool by UID instead of name.
`--oauth2-user-pool-client-uid`	env `OAUTH2_USER_POOL_CLIENT_ID`	Specify the client by UID instead of name.
`--oauth2-redirect-uri`	`http://{host}:{port}/oauth2/callback`	OAuth2 callback URL (env `OAUTH2_REDIRECT_URI`). Set this when deploying behind a public host or runtime.
`--oauth2-provider`	`veidentity` when a user pool is configured	SSO provider id (env `OAUTH2_PROVIDER`). One of `veidentity`, `github`, `google`, or a custom name.
`--oauth2-provider-label`	provider’s built-in label	Display label for the login button (env `OAUTH2_PROVIDER_LABEL`).
`--auth-mode`	`frontend`	Identity source. `frontend` runs OAuth2 login in the app; `gateway` trusts JWT identity forwarded by an upstream gateway. Environment variable: `VEADK_FRONTEND_AUTH_MODE`.
`--open` / `--no-open`	`--no-open`	Whether to open the default browser when the service is ready. Ignored in development mode.

Outside dev mode, if the built UI directory is not found, the command fails and asks you to run npm run build first (or use --dev with the Vite dev server).

Authentication

Sessions and memory are scoped by the ADK user_id, which comes from the signed-in user. On startup the command loads a .env file from the current directory or its parents, so the environment variables below can be placed in .env. SSO — enable by passing the pool and client. The UI shows a login page and redirects through the identity provider, then uses the user identifier returned by the userinfo endpoint as the user_id. The pool and client can be given either by name or by UID.

veadk frontend --agents-dir examples \
--oauth2-user-pool "your-user-pool-name" --oauth2-user-pool-client "your-user-pool-client-name"
# or by UID (env OAUTH2_USER_POOL_ID / OAUTH2_USER_POOL_CLIENT_ID)
# --oauth2-user-pool-uid <id> --oauth2-user-pool-client-uid <id>

Enabling VeIdentity SSO requires the process to have access to Volcengine credentials. The middleware protects the API while exempting the UI shell, /web/auth-config, /favicon.ico, /assets, and /skillhub, so the app loads and shows its own login page instead of being bounced to the identity provider. The login button’s label and icon are config-driven. Third-party / custom OAuth2 (env vars) — without a VeIdentity user pool, set OAUTH2_CLIENT_ID (and the secret) to enable GitHub, Google, or any OIDC login. Endpoints are resolved in this order: a built-in preset (OAUTH2_PROVIDER=github or google), then OIDC discovery (set OAUTH2_ISSUER), then 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 a non-OIDC provider.
`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 or runtime, and register the same value in your OAuth app; defaults to `http://{host}:{port}/oauth2/callback` locally.

The GitHub preset only needs the client credentials:

export OAUTH2_PROVIDER=github
export OAUTH2_CLIENT_ID="your-github-oauth-client-id"
export OAUTH2_CLIENT_SECRET="your-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, and so on) set OAUTH2_ISSUER plus the client credentials. A full example lives at examples/front_with_sso/.

When deploying to a runtime or 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.

No SSO (local username) — without those flags, the login page asks for a username (letters and digits, up to 16 characters), stored locally and used as the user_id. In this case the server always reports an unauthenticated state and an empty provider list, and the app renders its local username login.

Login state is cached: SSO via the veadk_session cookie, local mode via localStorage. The session itself is created lazily on the first message, not on page load. Logout is a local logout — it clears the session and returns to the login page.

Security restrictions in 1.0.4

VeADK Frontend can be deployed on a public endpoint. Version 1.0.4 applies the following restrictions to user-controlled addresses and paths:

The project-creation flow no longer executes code submitted by the browser. Test generated code in a controlled local environment before deployment.
The remote AgentKit proxy requires an API key and accepts only HTTPS volceapi.com hosts.
AgentKit deployment files must remain inside the current project directory. Absolute paths and relative paths that escape it are rejected.
Static files can be read only from the built UI directory; path traversal cannot read other host files.

These restrictions do not replace authentication. Public deployments should still enable SSO or a trusted upstream gateway and use least-privilege cloud credentials. When you need only creation and management features, use the Studio agent workbench.

Rendering flow

The frontend talks to the Google ADK API server: it lists available agents, creates a session, and receives the agent’s output as a live stream. When the agent returns an A2UI message, the frontend parses its UI instructions, creates and incrementally updates the corresponding surface, then renders the matching React components by type. A registry maps each component type to a renderer, so adding a new component type only requires registering a renderer for it.

Adding a custom (enterprise) component

A custom component has two halves that share one catalog id. For the backend half, see A2UI; the frontend half is below. Frontend half — drop in a new directory; it auto-registers, with no central edit:

src/a2ui/components/RevenueChart/
├── RevenueChart.tsx
└── index.ts

src/a2ui/components/RevenueChart/index.ts

import { register } from "../../registry";
import { RevenueChart } from "./RevenueChart";
register("RevenueChart", RevenueChart);

src/a2ui/components/RevenueChart/RevenueChart.tsx

import type { ComponentRendererProps } from "../../registry";

export function RevenueChart({ node, ctx }: ComponentRendererProps) {
  const series = ctx.resolve(node.series as any);
  return <div className="corp-chart">{/* render series */}</div>;
}

A newly added component directory is discovered and registered automatically, with no central configuration file to edit.

Unknown components with no registered renderer fall back to a collapsible JSON view, so a catalog/renderer mismatch never crashes the UI.

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

What it can do

Complete tool OAuth authorization

Run

Dev mode (hot reload)

The `veadk frontend` command

Authentication

Security restrictions in 1.0.4

Rendering flow

Adding a custom (enterprise) component

​What it can do

​Complete tool OAuth authorization

​Run

​Dev mode (hot reload)

​The veadk frontend command

​Authentication

​Security restrictions in 1.0.4

​Rendering flow

​Adding a custom (enterprise) component

What it can do

Complete tool OAuth authorization

Run

Dev mode (hot reload)

The `veadk frontend` command

Authentication

Security restrictions in 1.0.4

Rendering flow

Adding a custom (enterprise) component