dsh-agnes-media: Agnes AI Image and Video Generation Plugin

Introduction¶

DeepSeek Harness (DSH) LLM endpoints mainly handle text conversations. However, image and video generation services like Agnes return media files, not chat messages. The dsh-agnes-media plugin fills this gap by providing the agnes_image and agnes_video tools, integrating media generation capabilities into DSH’s tool ecosystem.

Plugin Overview¶

dsh-agnes-media is a plugin for Agnes AI image and video generation tools, containing two core tools: agnes_image and agnes_video. It is maintained by zlforward.

Core Features¶

agnes_image: supports text-to-image, image-to-image, and multi-image composition.
agnes_video: supports text-to-video, keyframes, and multimodal references (asynchronous tasks).

Installation and Enablement¶

Install the plugin using the official command:

dsh plugin --profile <profile> add dsh-agnes-media

Or declare the bundle in the profile’s package.json:

{
  "dsh": { "profile": { "bundles": ["dsh-agnes-media"] } }
}

After installation, restart the DSH process.

Typical Usage¶

Set the API key in credentials.yaml:

# $DSH_HOME/.credentials.yaml
refs:
  AGNES_API_KEY: sk-...

Override the configuration in the profile’s patch layer:

- id: agnes-media
  config:
    baseURL: https://apihub.agnes-ai.com/v1
    apiKeyEnv: AGNES_API_KEY
    imageModel: agnes-image-2.5-flash
    videoModel: agnes-video-2.5-flash
    outputDir: agnes-media
    requestTimeoutMs: 300000
    imageTimeoutMs: 360000
    videoTimeoutMs: 1800000
    videoPollIntervalMs: 3000

Output path: By default, generated files are saved in the workspace of the agent session:

<workspace>/agnes-media/image-<UTC timestamp>.png
<workspace>/agnes-media/video-<UTC timestamp>.mp4

Use Cases and Caveats¶

This plugin is suitable for scenarios that require directly invoking image and video generation capabilities within an agent workflow.

Key management: The plugin does not store secrets; it resolves credentials using the environment variable AGNES_API_KEY. Unconfigured references cause an error rather than failing silently.
Result authoritativeness: Hosted URLs returned by Agnes may expire. The plugin downloads the byte stream and saves it as a local file; the local file is the authoritative source.
Video task characteristics: agnes_video is a long-running task (up to about 30 minutes), involving polling and asynchronous processing, so the default timeout is long.
Input limitations: Video media must be public URLs and cannot directly access the local file system; images support data URIs without an upload step.
Error handling: The plugin includes retries for 429 (rate limiting) and 503 (service unavailable) responses, and handles the video_queue_full error.
API discrepancies: The video result URL structure is at the top level (url) instead of metadata.url in the documentation; task status spellings (such as pending) are inconsistent with the documentation, and the plugin has adapted to them.
Model configuration: Model names (such as agnes-image-2.5-flash) must be specified in the configuration and cannot be auto-discovered from the endpoint.

Conclusion¶

dsh-agnes-media solves the problem that DSH LLM routing cannot handle non-conversational generation requests. By providing standard tool interfaces and local file handling capabilities, it offers reliable underlying support for building multimodal agents.