zk-data-agent/docs/openwebui-integration.md

Open WebUI integration

中文 · English

Responsibility split

Open WebUI is the product shell. It owns account registration, login sessions, RBAC, administrator approval, conversation history, and rendering. K1412 does not fork those responsibilities into a second authentication or chat database.

K1412 Runtime owns the only user-facing Agent loop: context selection, durable memory, planning, tool schemas, scheduling, parallel reads, child Agents, evidence gating, experiments, and run-event persistence. Workspace Gateway owns identity-bound execution policy and Docker lifecycle.

This split makes the expensive experimental surface small. A new scheduler or context policy changes Runtime, not the account system or entire frontend.

Tool and progress rendering

Open WebUI natively understands tool-call and reasoning detail blocks. It also has a richer live status mechanism for loops that execute inside its own backend. K1412 Runtime is an external OpenAI-compatible provider, so it cannot mutate Open WebUI's internal socket status objects directly.

K1412 therefore emits Open WebUI-compatible completed tool detail blocks. Each tool appears once with:

• a localized action name;
• sanitized arguments (file contents and patches are omitted);
• success or failure state;
• concise plain output instead of the internal JSON envelope.

K1412 deliberately does not expose hidden chain-of-thought. The UI shows execution progress, tool evidence, completion checks, and concise Agent summaries. This is enough to inspect behavior without treating private model reasoning as a product API.

The earlier implementation appended one unfinished and one completed <details> element for every tool call. Since standard provider streaming is append-only, Open WebUI rendered them as duplicate cards. Runtime now emits only the completed card; the normal generation indicator covers the active wait.

Patches and upgrade cost

Open WebUI is pinned to v0.9.6 and an exact commit. The web image applies a small patch set during a reproducible build. Product-specific Svelte components and the authenticated workspace router live under docker/web/.

Upgrading Open WebUI requires:

1. updating the tag and commit pin;
2. replaying every patch with git apply;
3. building the Svelte production bundle;
4. running authentication, Agent-loop, isolation, and file-browser E2E tests;
5. reviewing upstream license changes.

The K1412 Agent loop is not embedded into Open WebUI, so most Agent experiments do not incur this upgrade cost.