pi-agnes-tools

The single Agnes AI plugin for pi: text model catalog (selectable via /model) plus image/video generation as custom tools + skill. No model switch needed for media — the agent just calls a tool.

Quick start

pi install npm:pi-agnes-tools

Export an API key, then use it:

export AGNES_API_KEY=sk-...          # international endpoint
export AGNES_CN_API_KEY=cn-sk-...    # China endpoint (optional)

# Text chat via the Agnes model catalog
pi --model agnes/agnes-2.5-flash "hello"

# Image / video: just ask in any pi session — the agnes-media skill teaches
# the model to call the agnes_image / agnes_video tools.
pi "Generate a 2-second video of a red apple falling off a wooden table, photorealistic"

# For a specific aspect ratio, set size + ratio — not prompt text:
pi "Generate a moody anime city at night"   # agnes_image { size: "2K", ratio: "16:9" }
# -> native 2624x1472. 16:9 in the prompt does NOT resize; it letterboxes.

Or run /login once and pi stores the key in ~/.pi/agent/auth.json for you.

What it registers

1. Text models (in /model)

Only text/LLM models are registered. Image/video are not selectable models — they live in the tools + skill. Both regions:

Seed text models: agnes-2.0-flash, agnes-2.5-flash, agnes-2.5-pro, agnes-2.5-pro-alpha, agnes-3.0-flash. Live /v1/models discovery adds newer text models automatically (image/video entries are filtered out).

agnes-cn only appears once a CN key is configured (env var or a key stored under agnes-cn in auth.json).

2. Media tools + skill (any chat model)

Two ways to generate media — no /model switch:

• Tools — agnes_image, agnes_video callable by any model.
• Skill — agnes-media (auto-loaded) teaches the model how to call the tools: prompt shaping, reference-image handling, endpoint choice, defaults.

Defaults: image agnes-image-2.5-flash, video agnes-video-2.5-flash. Output: .pi/generated-images/, .pi/generated-videos/ (project-relative).

Native aspect ratios (image)

agnes_image takes size + ratio as request-body fields (not as prompt text) to pick a concrete pixel grid. Without them the default is 1024×1024. Supported matrix (from the official docs):

For exact display canvases (1920×1080, 2560×1440 …) request the nearest tier + ratio and crop/resize downstream.

Do not put “16:9 widescreen” in the prompt. Prompt-level aspect language has no effect on output dimensions and measurably degrades composition (verified: ~18% of prompt-only widescreen requests return letterboxed bars; 0% via size+ratio). Pass the pair instead.

Install sources

pi install npm:pi-agnes-tools
pi install git:github.com/DraconDev/pi-agnes-tools

Listed in the pi.dev/packages gallery — it auto-indexes npm packages tagged with the pi-package keyword (this package has it, plus pi-extension / pi-skill), and carries an image field in its pi manifest for a visual preview card.

Replaces pi-agnes. This plugin owns the agnes / agnes-cn providers outright. Uninstall pi-agnes if you have it — two registrations would overwrite each other.

Auth

Resolution order: AGNES_API_KEY / AGNES_CN_API_KEY env vars → /login-stored key in ~/.pi/agent/auth.json.

Notes

• executionMode: parallel for image (fast, stateless); sequential for video (long-running poll, up to 30 min).
• Video model availability is per-distributor. In practice agnes-video-v2.0 is the reliable text-to-video model (5s / 720p clip, completed payload carries the video at a top-level url — with metadata.url as a fallback; the tool handles both). agnes-video-2.5-flash may require a mode field this tool does not send, and agnes-video-2.5 can be unavailable under some plans ("No available channel"). If the default 2.5-flash fails, call the tool with model: "agnes-video-v2.0".
• num_frames / frame_rate are only sent when explicitly provided — some video routes reject those request fields and apply their own defaults.
• Debug: PI_AGNES_TOOLS_DEBUG=1 logs registration + request decisions to stderr.
• MIT licensed. Source: github.com/DraconDev/pi-agnes-tools.