dsh-ag-ui
English | 简体中文
A community DeepSeek Harness Host plugin that exposes DSH Agents through the AG-UI protocol. It provides an authenticated HTTP/SSE Gateway, AG-UI thread-to-DSH Agent bindings, streamed text and Tool events, browser-owned Tools, and continuation of the same DSH turn after a browser Tool result returns.
This is a community project. It is not an official DeepSeek or AG-UI package.
Features
- Standard Cordis
Service plugin exposed as ctx.agUi
- Installable DSH Profile Bundle through
dsh plugin add
- Pinned AG-UI
0.0.58 protocol packages
- Authenticated BFF-to-Gateway requests with trusted tenant and user headers
- Process-local
(tenantId, userId, threadId) bindings to DSH Agents
- AG-UI text streaming and backend Tool result projection
- Agent-scoped browser Tools supplied by
RunAgentInput.tools
- Frontend Tool Promise parking and ToolMessage continuation across HTTP runs
- Run and message idempotency
- Bounded requests, context, Tool schemas, event buffers, threads, and run ledgers
- Complete Cordis disposal of routes, Agents, Tools, timers, and pending calls
Requirements
- Node.js
^22.19.0 or >=24.0.0
- A DSH Profile containing the standard Host services
- A registered DSH model provider and model
- An authenticated Backend-for-Frontend that keeps the Gateway secret away from browsers
Installation
Install the bundle into a DSH Profile:
dsh plugin --profile web add dsh-ag-ui
For the GitHub checkout before an npm release:
dsh plugin --profile web add github:CaiZongyuan/dsh-ag-ui
The bundle stays dormant until all required environment variables are present. This prevents an installation from breaking a Profile before the deployment chooses a model route and secret.
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
The bundle inserts two Host-plane rows:
ag-ui loads the Gateway service.ag-ui-invariant registers the package invariant companion.
Profile configuration
Environment variables are the shortest setup path. A Profile can instead override the bundle row in its own cordis.patch.yml:
- insert:
- id: ag-ui
name: dsh-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
- id: ag-ui-invariant
name: dsh-ag-ui/invariant
disabled: false
A later Profile patch replaces the bundle row's complete config; include every value that deployment needs.
Configuration
provider, model, and sharedSecret are required. sharedSecret must contain at least 16 UTF-8 bytes.
| Field | Default | Purpose |
|---|
path | /ag-ui | Exact Host HTTP route |
provider | required | Registered DSH model provider route |
model | required | Model ID owned by the provider |
sharedSecret | required | Bearer secret shared only with the trusted BFF |
tenantHeader | x-dsh-tenant-id | Trusted tenant identity header |
userHeader | x-dsh-user-id | Trusted user identity header |
allowNonLoopback | false | Permit a non-loopback Host bind explicitly |
maxRequestBytes | 262144 | Maximum request body bytes |
maxIdentityBytes | 256 | Maximum bytes per protocol or identity ID |
maxMessages | 256 | Maximum message count per request |
maxMessageBytes | 524288 | Maximum combined message JSON bytes |
maxContexts | 32 | Maximum context entry count |
maxContextBytes | 131072 | Maximum combined context JSON bytes |
maxTools | 32 | Maximum browser Tool count |
maxToolBytes | 131072 | Maximum browser Tool JSON bytes |
maxToolSchemaDepth | 16 | Maximum browser Tool schema depth |
maxForwardedPropsBytes | 65536 | Maximum forwardedProps JSON bytes |
maxStateBytes | 65536 | Maximum state JSON bytes |
A non-loopback DSH WebServer requires allowNonLoopback: true. Prefer a loopback Gateway behind a same-host authenticated BFF.
Architecture
Browser
-> authenticated application BFF
-> POST /ag-ui with Bearer secret and trusted identity headers
-> dsh-ag-ui Host Service
-> DSH Agent / Session / Tool runtime
-> model provider and backend Tools
The Gateway binding key is the exact (tenantId, userId, threadId) tuple. A browser-supplied identity, permission, patient ID, resource ID, context, or forwardedProps value never grants backend authority.
Backend Tools can derive the authenticated thread identity from the Agent:
const identity = ctx.agUi.identityFor(exec.agent)
if (identity === undefined) {
throw new Error('This Tool requires an authenticated AG-UI thread.')
}
const { principal, threadId } = identity
The application should map this tuple to its server-owned resource authorization state.
BFF proxy
The browser must not call the private Gateway directly. A BFF should authenticate the user, authorize the application resource, retain the browser request body exactly, and inject trusted identity headers.
app.post('/api/agent', async (c) => {
const user = await authenticateApplicationRequest(c.req.raw)
const body = new Uint8Array(await c.req.raw.arrayBuffer())
const upstream = await fetch('http://127.0.0.1:3080/ag-ui', {
method: 'POST',
headers: {
authorization: `Bearer ${process.env.DSH_AG_UI_SHARED_SECRET}`,
'content-type': 'application/json',
'x-dsh-tenant-id': user.tenantId,
'x-dsh-user-id': user.userId,
},
body,
})
return new Response(upstream.body, {
status: upstream.status,
headers: upstream.headers,
})
})
The BFF owns login, sessions, CSRF protection, tenant policy, resource authorization, audit, and rate limits. Do not treat the Gateway bearer secret as end-user authentication.
Browser client
Install the pinned official client in the frontend application:
pnpm add @ag-ui/client@0.0.58
Send page-specific browser Tools and current context on every run:
import { HttpAgent, randomUUID } from '@ag-ui/client'
const agent = new HttpAgent({
url: '/api/agent',
threadId: 'application-thread-123',
})
agent.addMessage({
id: randomUUID(),
role: 'user',
content: 'Review the current draft.',
})
await agent.runAgent({
runId: randomUUID(),
tools: browserTools,
context: [{
description: 'Current page state',
value: JSON.stringify(readPageSnapshot()),
}],
forwardedProps: {},
})
If the model calls a ui_* Tool, the current HTTP run finishes successfully while the DSH Tool Promise remains pending. The browser executes the Tool, appends one standard AG-UI ToolMessage with the same toolCallId, and starts another run. The Gateway resolves the original Promise and continues the same DSH turn.
Do not send ordinary browser Tool results through AG-UI resume[]; that field is reserved for explicit interrupt/HITL flows.
HTTP and run semantics
- Requests must be
POST application/json and match AG-UI RunAgentInput.
- A normal run accepts one new text user message.
- A continuation accepts one or more new frontend ToolMessages for one pending DSH turn.
- One DSH turn can cross multiple AG-UI HTTP runs.
- Each run emits one
RUN_STARTED and exactly one RUN_FINISHED or RUN_ERROR.
runId is an exact-request idempotency key. Completed identical requests replay retained events without driving DSH again.- One thread can have only one active HTTP run.
- V1 allows one frontend Tool call per DSH step.
Client-provided Tools
Browser Tool names must match:
ui_[a-z][a-z0-9_]*
Their parameters must use the object-rooted JSON Schema subset enforced by DSH Tools. The Gateway rejects collisions with inherited or global Tools and registers each accepted definition only in the exact Agent's Tool scope.
Backend Tool results are emitted as TOOL_CALL_RESULT. Frontend Tool results are not echoed on the AG-UI wire because the browser already added the ToolMessage; DSH still records the real durable tool/result.
Lifecycle
All effects belong to the Cordis plugin fiber. Route removal, idle expiry, timeout, and plugin disposal unregister browser Tools, reject pending calls, cancel active work, dispose Agent handles, and wait for quiescence.
An unexpected HTTP disconnect cancels the Gateway-owned DSH turn. HttpAgent@0.0.58 does not implement partial SSE reconnect. A frontend Tool handoff is an intentional completed run and does not cancel the parked turn.
Compatibility
| Component | Supported version |
|---|
| AG-UI core/client/encoder | 0.0.58 |
| Node.js | ^22.19.0 or >=24.0.0 |
| DeepSeek Harness | Developer preview packages listed in peerDependencies |
DSH is in developer preview and can introduce breaking changes. This package uses exact DSH peer versions until those APIs stabilize.
Model Experience
Injected AG-UI context
What the model sees
Each non-empty RunAgentInput.context becomes one user-role snapshot containing ordered ## <description> sections. The source is { kind: "plugin", plugin: "ag-ui", form: "snapshot", sections }.
Token effect
Conditional and retained. Every accepted normal or continuation run appends its bounded context snapshot to the DSH Session and later model history.
KV cache effect
Append-only context preserves earlier reusable history. Changed current context adds a new suffix; provider cache availability is outside this package.
Client-provided capabilities
What the model sees
The current Agent-scoped ui_* definitions join the ordinary DSH Tool schema list. Their names, descriptions, and validated parameter schemas come from the authenticated client request; execution remains browser-owned.
Token effect
Conditional and replacing. The visible Tool schema list is sent on every model request and changes when the page advertises a different capability set.
KV cache effect
An unchanged Tool set preserves the Tool-schema prefix. Adding, removing, or changing a Tool may invalidate provider reuse from that portion onward.
Known limitations
- Thread and run state is process-local.
- Host restart does not call
agents.resume() or recover a parked browser Tool.
- Only text user input, assistant text, and string Tool results are adapted.
- One frontend Tool call is allowed per DSH step.
- Partial SSE reconnect is not supported.
- AG-UI interrupt/HITL
resume[], multimodal messages, reasoning events, and state event families are not adapted yet.
Development
git clone https://github.com/CaiZongyuan/dsh-ag-ui.git
cd dsh-ag-ui
corepack enable
pnpm install
pnpm check
pnpm check runs lint, strict TypeScript checking, per-file coverage, runtime/type builds, and publint.
See CONTRIBUTING.md for contribution and release requirements.
License
MIT. Portions are adapted from DeepSeek Harness; see NOTICE.
