DeepSeek Harness (DSH) adopts an “everything is a plugin” architecture. When building model agent applications, developers often need to expose DSH Agents to front ends through the AG-UI protocol or implement cross-process invocation of browser tools. This involves complex logic around HTTP/SSE gateways, authentication, state synchronization, and resource management.

dsh-ag-ui is a community-maintained DeepSeek Harness Host plugin. Acting as a gateway for the AG-UI protocol, it provides authenticated HTTP/SSE interfaces, binds DSH Agents to AG-UI threads, and handles text streaming, tool events, and proxying for browser tools. The plugin is maintained by CaiZongyuan and is released under the MIT license.

Core Features

The plugin provides the following core capabilities:

  • Standard Cordis Service plugin: Exposed as a standard service plugin, accessible through ctx.agUi.
  • Browser tool proxying: Provides transport-agnostic, agent-scoped browser tool proxies, accessible through ctx.browserTools.
  • Authenticated gateway: Provides authenticated BFF-to-gateway requests using trusted tenant and user headers.
  • Thread binding: Binds AG-UI threads to DSH Agents using process-local (tenantId, userId, threadId) bindings.
  • Bidirectional shared state: Supports bidirectional shared state through RunAgentInput.state, ag_ui_update_state, and STATE_SNAPSHOT.
  • Tool cards: Provides demonstration cards for backend tool calls as versioned dsh:tool:view custom events.
  • State continuation and promise parking: Supports parking frontend tool Promises and continuing ToolMessage execution across HTTP runs.
  • Resource limits and cleanup: Enforces bounds on requests, context, tool schemas, event buffers, threads, and run logs, while ensuring complete cleanup by Cordis of routes, agents, tools, timers, and pending calls.
  • Run and message idempotency: Ensures idempotency for runs and messages.

Installation and Activation

Installing this plugin requires the following environment: Node.js version ^22.19.0 or >=24.0.0.

Install the plugin from the DSH Profile:

dsh plugin --profile web add dsh-ag-ui

Install from the GitHub repository (for local development before release):

dsh plugin --profile web add github:CaiZongyuan/dsh-ag-ui

Configuration and Usage

After installing the plugin, environment variables are the shortest path to configuring the AG-UI gateway. Required variables include provider, model, and sharedSecret (sharedSecret must contain at least 16 UTF-8 bytes).

export DSH_AG_UI_PROVIDER='openai'
export DSH_AG_UI_MODEL='gpt-5.6-sol'
export DSH_AG_UI_SHARED_SECRET="$(openssl rand -hex 32)"
export DSH_AG_UI_PATH='/ag-ui' # Optional

dsh --profile web

It can also be configured through cordis.patch.yml in the Profile, which allows overriding the plugin mount lines:

- id: ag-ui
  disabled: false
  config:
    provider: openai
    model: gpt-5.6-sol
    sharedSecret: !!js process.env.DSH_AG_UI_SHARED_SECRET
    path: /ag-ui
    maxThreads: 100
    frontendToolTimeoutMs: 300000

Use Cases and Considerations

  • Use cases: Developers who need to expose DSH Agents as AG-UI services, integrate browser tools, or manage complex Agent state synchronization.
  • Prerequisites: Before installation, ensure that the DSH Profile includes standard Host services, registered DSH model providers and models, and an authenticated Backend-for-Frontend (BFF).
  • Ecosystem components: The plugin itself does not include React renderers or embedding adapters; these features are provided by the separate dsh-ag-ui-cards and dsh-ag-ui-adapter packages.
  • Community nature: This is a community project, not an official package from DeepSeek or AG-UI.

Summary

dsh-ag-ui addresses core engineering challenges in AG-UI protocol integration within the DSH environment, providing full-pipeline support from Agent execution to front-end presentation. Developers can quickly enable gateway functionality through simple command-line installation and environment variables or YAML configuration.

  • GitHub: https://github.com/CaiZongyuan/dsh-ag-ui
  • Catalog: https://www.skillhub.cn/plugins/CaiZongyuan/dsh-ag-ui