dsh-agnes-tools

dsh plugin --profile web add dsh-agnes-tools

dsh-agnes-tools

Agnes AI image & video generation as native DeepSeek Harness tools.

agnes_image · agnes_edit_image · agnes_video · agnes_video_status · agnes_models

[English](#english) · [中文](#中文)

---

English

A small, tool-only plugin: it adds five tools to the agent and nothing else — no UI panel,

no settings page, no runtime dependencies beyond the Schemastery peer DSH already ships.

Why this one

Five Agnes plugins already exist, so here is the honest difference:

• Video jobs are resumable. agnes_video submits, polls, and downloads — but when the

in-call wait runs out it returns the video_id instead of losing the job. agnes_video_status

picks it up later and downloads the mp4. On a queue that is regularly full

(503 video_queue_full), that is the difference between a lost render and a finished one.

• agnes_models lists the models your key can actually reach, so you can tell a bad key

from a bad model name in one call.

• Free-tier aware. Retries with backoff on 503/429, 6 s polling to stay under 20 RPM,

and tolerance for the ~20 s window after submission where a status query wrongly reports 404.

• Tool-only, zero runtime deps. If you work in the chat and do not want a floating panel.

Install

From the DSH plugin market, once listed — then restart dsh web.

<details>

<summary>Manual install (verified on Windows)</summary>

Add the package to your web profile and register it as a bundle:

// $DSH_HOME/profiles/web/package.json
{
  "dependencies": {
    "dsh-agnes-tools": "file:/path/to/dsh-agnes-tools"   // or: "github:zuihouye/dsh-agnes-tools"
  },
  "dsh": {
    "profile": {
      "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-agnes-tools"]
    }
  }
}

cd "$DSH_HOME/profiles/web" && pnpm install

Then restart dsh web. Host-side plugins are loaded at startup — there is no hot reload.

Two traps worth knowing: dsh plugin --profile web install can answer "Already up to date"

without installing anything, so run pnpm install in the profile yourself. And the hoisted

linker copies file: dependencies, so re-run pnpm install after editing the source.

</details>

Configure

cordis.patch.yml holds the defaults; override any key in your profile's

cordis.patch.yml or plugin settings.

Key · Default · Notes

apiKeyRef · AGNES_API_KEY · Name of the DSH credential holding your key. Recommended.

apiKey · (empty) · Inline key. Takes precedence over apiKeyRef. Not recommended.

baseURL · https://api.agnes-ai.cn/v1 · Mainland endpoint. International: https://apihub.agnes-ai.com/v1.

imageModel · agnes-image-2.5-flash ·

videoModel · agnes-video-2.5-flash ·

outputDir · agnes-output · Absolute, or relative to the dsh process working directory.

pollTimeoutMs · 300000 · How long agnes_video waits inside a single tool call.

pollIntervalMs · 6000 · Do not lower it: the free tier allows 20 requests/minute.

The key is resolved in this order: apiKey → the DSH credential named by apiKeyRef →

process.env[apiKeyRef].

Tools

Tool · Required · Optional

agnes_image · prompt · ratio (1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9), size (1K/2K/3K/4K), save_path

agnes_edit_image · prompt, images · ratio, size, save_path — images accepts local absolute paths, public URLs, or data URIs

agnes_video · prompt · seconds ("4"–"12", default "5"), aspect_ratio, mode (text/keyframe/reference), first_frame, last_frame, images (≤5), save_path

agnes_video_status · video_id · save_path

agnes_models · — · —

Files land in outputDir as 20261018-015926-jvic-agnes-video.mp4.

Generated images are also attached to the reply when the host supports attachments.

API quirks the code already handles

1. size is a tier, not a pixel size. Agnes takes 1K/2K/3K/4K plus ratio — not 1024x768.

2. Images must come back as base64. On the international endpoint the returned image URL

lives on storage.googleapis.com, which is unreachable from mainland China. The plugin always

asks for base64 instead.

3. The video queue is often full — 503 video_queue_full. Retried with backoff (up to 6

attempts, 8 s → 30 s).

4. A status query within ~20 s of submission reports 404 "task not found". The poll loop

tolerates it.

5. The free tier allows 20 requests/minute; exceeding it returns 429. Hence the 6 s interval.

6. Video size is always "720P"; the real pixel size follows aspect_ratio

(16:9 → 1280x704).

Development

npm install && npm test        # loads the plugin with a mock context and checks every tool

Add node_modules to your profile and point dsh-agnes-tools at your checkout to iterate.

License

MIT

---

中文

把 Agnes AI 的生图 / 生视频接成 DeepSeek Harness 的原生工具，一共 5 个，

纯工具型：没有悬浮面板、没有设置页，除 DSH 自带的 Schemastery 外没有运行时依赖。

和已有的 Agnes 插件有什么不一样

Agnes 生图生视频的插件市面上已经有 5 个，所以这里只说真实差异：

• 长视频任务可以续查。 agnes_video 会一次调用内提交 + 轮询 + 下载；但等待超时后它

返回 video_id 而不是把任务丢掉，之后用 agnes_video_status 接着查、完成后自动下载 mp4。

视频队列经常满（503 video_queue_full），这条差异决定了你是白等一场还是拿到成片。

• agnes_models 列出当前 Key 真能访问的模型，一次调用区分「Key 不对」还是「模型名不对」。
• 为免费额度调过参。 503/429 退避重试、6 秒轮询卡在 20 RPM 以内、

容忍提交后约 20 秒内状态查询误报 404。

• 纯工具、零运行时依赖。 如果你就在对话里干活、不需要悬浮面板，这个更干净。

安装

插件市场上架后可直接安装，装完重启 dsh web。

<details>

<summary>手动安装（Windows 上已实测）</summary>

在 web profile 里登记依赖和 bundle：

// $DSH_HOME/profiles/web/package.json
{
  "dependencies": {
    "dsh-agnes-tools": "file:/你的路径/dsh-agnes-tools"   // 或 "github:zuihouye/dsh-agnes-tools"
  },
  "dsh": {
    "profile": {
      "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-agnes-tools"]
    }
  }
}

cd "$DSH_HOME/prof

…(truncated)