dsh-agnes-media

Readme

# dsh-agnes-media

English | [中文](README.zh.md)

[Agnes AI](https://platform.agnes-ai.com/) image and video generation for DeepSeek Harness, as two model-facing tools:

| Tool | Endpoint | Purpose |
|---|---|---|
| `agnes_image` | `POST /v1/images/generations` | Text-to-image, image-to-image, multi-image composition |
| `agnes_video` | `POST /v1/videos` + `GET /agnesapi` | Asynchronous tasks: text-to-video, keyframes, multimodal reference |

## Why a plugin rather than an LLM route

The harness LLM seam speaks chat protocols only (completions / responses / messages). Agnes' text models make a fine `llm-pi-ai` route, but image and video are **generation endpoints** that return no conversation — so they are tools, not models. The two coexist: text on a route, media through this plugin.

## Install

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

Or declare it as a bundle in the profile `package.json`:

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

Restart the harness afterwards.

## Credentials

No secret is stored by the plugin. Each call resolves `apiKeyEnv` (default `AGNES_API_KEY`) through the harness credential seam:

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

An unconfigured reference fails with an error naming it, rather than sending a request that is certain to 401.

## Configuration

Override by id from the profile patch layer:

```yaml
- 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
```

| Field | Default | Meaning |
|---|---|---|
| `baseURL` | `https://apihub.agnes-ai.com/v1` | International service. China is `https://api.agnes-ai.cn/v1`; the international alternate is `https://apihub.agnes-ai.cn/v1` |
| `apiKeyEnv` | `AGNES_API_KEY` | Credential reference resolved per call |
| `imageModel` | `agnes-image-2.5-flash` | Used when a call names no model |
| `videoModel` | `agnes-video-2.5-flash` | Defaults to the **free** tier so an unconfigured call cannot silently spend money |
| `outputDir` | `agnes-media` | Relative to the calling workspace; an absolute `outputPath` bypasses it |

## Where artifacts land

By default, under the **calling agent session's workspace**:

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

Extensions come from sniffing the downloaded bytes, not from a fixed table. Pass `outputPath` to override — relative paths resolve against the workspace, absolute paths are used as given.

Agnes also returns a URL it hosts (the result's `sourceUrl`), and **that URL may expire**, so the plugin downloads the bytes; the local file is authoritative.

## Free tiers

Per the Agnes pricing page: every resolution tier of all three image models is currently free; `agnes-video-v2.0` and `agnes-video-2.5-flash` are currently `$0/second`; `agnes-video-2.5` is billed per second. The free tier is rate-limited per account.

## Implementation notes: where the API differs from its documentation

Each of these was observed against the live endpoint and each one affects correctness, so they are documented rather than left in code comments:

- **The video result URL is at the top level (`url`)**, not at the documented `metadata.url` — a completed response carried no `metadata` object at all. The plugin prefers the observed shape and keeps the documented one as a fallback.
- **Task status uses spellings the documentation does not list** — live responses returned `pending` where the docs say `queued`. Status is therefore read as a **terminal-state check** (`completed` / `failed`), never an enumeration of in-progress values.
- **Polling returns 429** even at the documented 1–2 second cadence. The plugin backs off instead of reporting a rate limit as a generation failure.
- **Creation returns 503 `video_queue_full`.** Also retried with backoff. A generic 500 is deliberately **not** retried: it cannot be told apart from a task that was created before the failure, and retrying would bill for a duplicate.
- **The result URL rejects the bearer token** — attaching it yields 401. Downloads are unauthenticated.
- **Images accept data URIs**, so a local image can be inlined without an upload step.
- **Video media must be a public URL**: Agnes fetches it server-side and cannot reach this machine's filesystem.

## Limitations

- Image input support relies on Agnes accepting data URIs (verified), which is not true of every OpenAI-compatible gateway.
- The video tool is long-running: it polls for up to 30 minutes by default, declares a matching `timeoutMs`, and observes `exec.signal` throughout for cooperative cancellation.
- Agnes' image and video **model catalog is not discovered** from the endpoint; model names are configuration.

## License

MIT