Local Web UI

agentengine web starts a local browser UI for invoking and debugging an agent project. It is the local development UI, not the hosted AgentEngine dashboard.

The pip-installed KsADK wheel already bundles static UI assets, so end users do not need Node.js. Node.js is only required when developing the UI source.

Start The UI

From a project directory:

Default start (opens a browser automatically):
```
agentengine web .
```
Do not open a browser:
```
agentengine web . --no-open
```
Use a specific port:
```
agentengine web . --port 7860
```
Override the configured model for one debugging session:
```
agentengine web . --model my-model
```

What The UI Is For

Use the local Web UI to:

send messages to the selected agent.
test streaming and non-streaming behavior.
inspect file and image input flows when supported by the runner.
keep a browser-based debug loop while editing the project.
verify how the local runtime serializes requests into OpenAI-compatible shapes.
inspect sessions, run events, feedback state, and workspace file previews when those local runtime features are enabled.

Runtime Relationship

The UI calls the local KsADK runtime, which in turn calls the configured framework runner. The UI does not call a model provider directly.

Web UI runtime relationship

Local State

The local UI creates state under the project directory:

sessions.sqlite

State under .agentengine/ is useful for development but is not source code and should not be committed. Delete .agentengine/ to reset local UI sessions.

Independent UI Repository

The editable Web UI source is planned as a separate repository kingsoftcloud/ksadk-web, the shared Web UI repository for both:

the local static UI consumed by ksadk-python.
the hosted UI build consumed by internal hosted deployments.

The Python SDK should embed generated static assets and record the source version it consumed. Hosted-only deployment files, private routing, Helm values, and generated hosted bundles must not be published as part of the SDK wheel.

See Web UI Repository for the repository split and release contract.

Development Mode

UI contributors need Node.js. The source repository should provide:

Build the static bundle consumed by the Python SDK

npm run build:ksadk

Build the hosted-routed bundle

npm run build:hosted

Custom UI Bundle

New in 0.6.7

agentengine web auto-detects research-ui/dist/index.html under the project root. When detected, it starts in custom profile and loads that directory as the custom UI bundle; otherwise it falls back to the built-in static UI.

You can also declare the custom profile explicitly in agentengine.yaml to override auto-detection:

agentengine.yaml

ui_profile: custom
ui_bundle_path: research-ui/dist
ui_path: /

Path rewrite

Under custom profile, the UI's /chat endpoint is automatically rewritten to /. No manual route change is needed inside the bundle.

Remote serverless deployments automatically inject the following environment variables into the pod env, for the custom UI bundle to read:

KSADK_UI_PROFILE
KSADK_UI_PATH
KSADK_UI_URL
KSADK_UI_BUNDLE_PATH

Streaming Fixes (0.6.6)

New in 0.6.7

0.6.6 fixed the following streaming issues:

Streaming messages disappeared during consecutive Q&A.
When rapidly switching or creating sessions, the previous stream was still written back to the new session.
Streaming Markdown tables failed to render.

Common Failures

Symptom	Check
Browser does not open	run with `--no-open` and open the printed URL manually.
Port already in use	pass `--port <free-port>`.
Agent cannot load	run `agentengine run . -i` first to isolate project detection and model config.
Model calls fail	verify `.env`, `OPENAI_BASE_URL`, `OPENAI_MODEL_NAME`, and provider compatibility.
old session data appears	remove `.agentengine/ui/` for a clean local state.
Custom UI bundle not taking effect	confirm `research-ui/dist/index.html` exists; or check `ui_profile`/`ui_bundle_path`/`ui_path` in `agentengine.yaml` and ensure the bundle is built.

Local Web UI

On this page