dsh-ag-ui
Authenticated AG-UI HTTP and SSE gateway plugin for DeepSeek Harness 适合需要通过HTTP和SSE网关接入并管理AG-UI及浏览器工具的用户。
インストール
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:CaiZongyuan/dsh-ag-uiドキュメント
README 全文を読む ↗Profile configuration
Environment variables are the shortest setup path. A Profile can instead override the bundle row in its own cordis.patch.yml:
- 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
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 | Base Host HTTP route for runs and files |
provider | required | Registered DSH model provider route |
model | required | Model ID owned by the provider |
workspaceRoot | /workspaces | Root for per-thread workspace directories, named by durable session id |
agentPreset | none | Deployment-default agent preset id composed into every thread |
tenantPresets | {} | Per-tenant preset ids taking precedence over agentPreset |
selectableAgentPresets | {} | Canonical preset ids each authenticated tenant may select for a blank thread |
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 |
maxFileBytes | 104857600 | Maximum bytes per uploaded file or deliverable download |
maxIdentityBytes | 256 | Maximum bytes per protocol or identity ID |
maxMessages | 256 | Maximum message count per request |
maxMessageBytes | 524288 | Maximum combined message JSON bytes |
maxFilesPerMessage | 8 | Maximum non-text parts in one user message |
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 |
maxThreads | 100 | Maximum process-local live threads |
threadIdleMs | 1800000 | Idle thread lifetime |
frontendToolTimeoutMs | 300000 | Maximum browser Tool result wait |
humanInteractionTimeoutMs | 300000 | Maximum wait for each native human request; integer from 1 to 2147483647 ms |
maxPendingInterrupts | 16 | Maximum live human requests per thread |
maxRunEvents | 4096 | Maximum events retained per run |
maxRunEventBytes | 2097152 | Maximum retained event bytes per run |
maxRunsPerThread | 32 | Maximum retained run ledger entries and, separately, waiting requests per thread |
agentPreset composes each thread's agent from the host's agent-presets roster (mount the roster plugin before this Gateway); an unresolvable id fails Gateway activation loudly, a per-tenant entry overrides the deployment default for that tenant's threads, and a resumed thread keeps the composition its own durable session recorded. Without agentPreset, threads keep the host composition unchanged.
Each thread uses / as its DSH working directory. The directory is named by the durable session id, so client thread ids stay off disk. When the Host provides workspaceRegistry, the Gateway registers new workspaces for DSH Web.
File routes require the official fileUploads and attachments services, already mounted by @deepseek-ai/dsh-web-app. POST /threads//files streams the raw body with content-length, optional content-type, and percent-encoded x-file-name. Harness owns streamed storage, content hashes, temporary-file cleanup, and staged receipts. The response retains its AG-UI URL source and filename/size/sha256 metadata.
Clients must preserve the returned URL query when changing a proxy prefix. The gateway signs the native file reference and receipt for the authenticated session. GET verifies the signature and principal/thread mapping before calling the official streamed reader. Same-name uploads keep their display name and receive distinct receipt URLs. Downloads remain authorized after cold resume; rotating the shared secret invalidates old URLs. Pre-native unsigned upload URLs require a fresh upload.
User messages accept ordered text and signed thread-file URL parts. Images use official image admission; other files become native file content parts. Harness owns receipt binding, successful admission retirement, and rollback when queue delivery fails. Rejected admission can retry its still-staged receipt. A consumed, explicitly retired, or cold unsent receipt returns FILE_NOT_STAGED and requires re-upload; the gateway never restores expired authority. MESSAGES_SNAPSHOT preserves the exact accepted AG-UI parts. Shared-state and frontend Tool admission are revalidated after asynchronous file processing, before publishing those parts. Inline data parts are not accepted.
For multiple presets within one tenant, the host can grant selection with selectableAgentPresets: { "tenant-1": ["alpha", "beta"] }. A run may then request forwardedProps: { agentPreset: "beta" }. The Gateway validates grants against the roster at activation and calls native agentPresets.select under the thread's run reservation before its first turn. The roster alone grants no authority, and the BFF must still authenticate the tenant and authorize access to its application features.
Selection is optional. Omitting it preserves the current composition; repeating the effective canonical id is a no-op, including after restart. A different ungranted id fails with HTTP 403 PRESET_NOT_ALLOWED; a granted change after the first turn fails with HTTP 409 PRESET_LOCKED. A history-only request never selects a preset, so a session created by a history read can still choose one on its first work run. The native session log owns the selected composition and restores it after restart. Tool names are validated against the selected composition before SSE starts. A successful selection remains recorded if that validation rejects the run or its client disconnects; no user turn is started, and the blank session can select again.
maxRunEvents must retain at least the mandatory opening and terminal events. maxRunEventBytes bounds the complete retained Run record, including RUN_STARTED and its terminal event, and must be large enough for the configured maximum identity length. A non-loopback DSH WebServer requires allowNonLoopback: true. Prefer a loopback Gateway behind a same-host authenticated BFF.
Opening and final durable history snapshots both count toward this bound. Buffer overflow ends the HTTP run and cancels only its currently claimed native turn. An overflowing history-only read does not cancel another active turn. Completed duplicate requests still replay the exact retained events.