Web console¶

A single-page operator console served by the same FastAPI front door as the API (AEP-019). It is a transport over AgentGateway — the same pipeline Slack and Google Chat use — not a second implementation of the agent. No agent, plugin, or guardrail logic changes when the console changes.

It is off by default. A browser-facing chat surface amplifies any auth gap, so it only appears when you deliberately turn it on.

What it is for¶

adk web is a developer debugger: raw events, function-call payloads, session plumbing. This console is the operator surface — hold a conversation, see which specialist ran which tool, approve a guarded action, and check whether the environment is actually wired. Both coexist; neither replaces the other.

Enabling it¶

make run-api          # builds the bundle and serves it at http://localhost:8000

That is make web-build (Vite → serving/static/) plus make run-api. Mint a token in another terminal and paste it into the console:

make dev-token ROLE=operator

In a deployment, set:

The Docker image builds the bundle in a node: stage and copies it into the Python runtime, so the runtime image stays Node-free.

Authentication¶

The console holds no trust of its own. The static shell carries no secrets; a bearer token rides the Authorization header on every API call, and the server verifies it, resolves the role via RBAC, and enforces everything — the console's role badge is decoration.

There are two ways to obtain that token. Which one applies is deployment configuration, and the console renders only the matching sign-in surface.

SSO (recommended)¶

Set VITE_OIDC_ISSUER at build time and the console runs OpenID Connect Authorization Code with PKCE. It is provider-agnostic — the same build works against Keycloak, Authentik, Auth0, Okta, Entra ID, or Google — and uses a public client with no secret, which is the correct pattern for a browser SPA.

The server side needs no new code — point it at the provider's JWKS:

JWT_ALGORITHM=RS256
JWT_JWKS_URL=https://idp.example.com/realms/orrery/protocol/openid-connect/certs
JWT_AUDIENCE=orrery-console
JWT_ISSUER=https://idp.example.com/realms/orrery
JWT_ROLE_CLAIM=realm_access.roles

The access token is held in memory and renewed silently, so it is not sitting in localStorage for any script on the origin to read. Signing out ends the provider session too — a local-only sign-out would silently sign the same user straight back in, which is not what anyone means by signing out of a shared machine.

Pasted token (default, and for CI)¶

With VITE_OIDC_ISSUER unset the console shows the token gate: paste a JWT, e.g. from make dev-token. This keeps CI, offline work, and quick local runs usable with no identity provider running.

Signing out clears the token and any keys an earlier build wrote. Transcripts are no longer among them: history lives in the session store and is fetched with the signed-in user's own token, so a shared browser can only ever show the current user's conversations.

Trying SSO locally¶

A throwaway Keycloak ships under the sso compose profile:

make up PROFILES=sso  # Keycloak on :8081, realm "orrery" pre-imported
make run-api SSO=1    # builds the console with SSO, serves it on :8000

Three demo users, password same as username: viewer, operator, admin — enough to see the RBAC tiers behave differently in the browser. make down stops it.

What you get¶

Chat with a visible tool timeline¶

The Tool calls tab lists every recorded call — which specialist, which tool, which arguments, what status — so a multi-agent sweep reads as orchestration rather than an opaque paragraph. While a turn is in flight the timeline is polled every 2.5 s, so specialists appear as they finish. (Token-by-token streaming is AEP-009; until then, this is the progress signal.)

A turn can be stopped. A triage sweep fans out to five specialists and can run for a minute; the Stop button abandons the wait. The server keeps working — this stops the client waiting, it does not cancel the run.

A failed turn offers Retry, which replays the same message without duplicating it in the transcript. A rate-limited turn says so, with the wait.

Approve / deny for guarded tools¶

When a @confirm or @destructive tool is gated, the console renders the pending action and two buttons. The buttons send the literal decision words through POST /chat — the frontend decides nothing. The requester-verified gate is the only authority on who may approve, and it refuses a decision from anyone but the requester, or one that predates the action it would authorize.

Conversation history that follows the user¶

The sidebar is a view of the session store, not of the browser. On load the console asks GET /sessions for the caller's conversations and fetches a transcript (GET /session/{id}) only for the one it opens, so a long history costs one request. Deleting a conversation deletes the session.

Consequences worth knowing, since the console used to keep this in localStorage:

• History is the same on every machine, and clearing site data loses nothing. Previously the sidebar was the only index of which sessions belonged to whom, so a different browser left the transcripts unreachable in the store.
• Long threads are no longer truncated. The browser copy was capped at 200 messages per conversation, which made the visible transcript disagree with what the agent still remembered.
• Titles come from the server, written into session state on a conversation's first turn. A session opened by another transport (Slack, the CLI) has none and renders as "New chat".

Triage view¶

Run triage sends a canned prompt to the incident_triage_agent. The result renders as a severity banner (healthy / degraded / critical) from the recorded incident_severity — the machine-readable verdict, not a parse of the prose — with the full report below and a chip per system that was actually consulted.

System tab — the environment check¶

The single most useful thing here for a new user. Check my environment runs, concurrently and read-only:

• a one-token round-trip against the configured provider and model, and
• each specialist's cheapest read-only tool (Kafka cluster health, K8s cluster info, Elasticsearch cluster health, Prometheus targets, docker ps).

Each row is green or red with the reason and, when red, what to configure. This exists because nearly every first-run failure is "a credential or endpoint was never wired" — and the only feedback used to be a stack trace buried in a tool result several turns into a conversation.

The tab also shows the server-resolved role and the active autonomy level (L2/L3/L4), so a viewer understands up front why mutating tools are unavailable rather than discovering it when one is refused.

# The same check over the API
curl -X POST -H "Authorization: Bearer $TOKEN" localhost:8000/onboarding/selftest

Probes must stay read-only: the self-test does not consult RBAC, so anything with side effects does not belong in that list. Deployments register their own via create_app(integration_probes=...) — core has no dependency on any agent package.

Endpoints the console uses¶

Session-scoped endpoints pin user_id to the verified subject, so another user's session id resolves to a plain 404 — indistinguishable from one that never existed.

Developing¶

make install   # npm ci
make run-web   # Vite dev server with HMR (expects the API on :8000)
make test-web  # lint + format + typecheck + tests + build (mirrors CI)

web/ is a separate toolchain, deliberately outside the uv workspace: make test never needs Node, and the Python contributor path stays intact. The API contract and its consumer live in the same commit, so an endpoint change and its frontend update land together.