pi-provider-volcengine-agent-plan

简体中文

Unofficial Pi provider extension for Volcengine Ark Agent Plan at https://ark.cn-beijing.volces.com/api/plan/v3.

This community package is not affiliated with or endorsed by Volcengine.

Features

• Native Pi provider registration and /login integration.
• Static catalog for the 11 current Agent Plan chat models.
• Image input for the 7 vision-capable models; text-only routing for DeepSeek V4 Flash/Pro, GLM 5.3, and Doubao Seed 2.1 Turbo.
• Tier-aware availability for Small, Medium, Large, and Max plans.
• OpenAI Responses by default, with Chat Completions routing for Kimi K2.7 Code.
• Streaming, reasoning, and tool-call support tested through the Agent Plan gateway.
• Documented reasoning.effort compatibility mapping per model family; GLM 5.3 stays limited to low/high/max.
• Zero-inference API key validation before Pi persists a login credential.

Requirements

• Node.js 22.19 or newer.
• Pi and @earendil-works/pi-ai 0.84.0 or newer.
• A dedicated Ark Agent Plan API key. A regular Volcengine Ark API key does not work with the Plan endpoint.

Install

pi install npm:@woyxiang/pi-provider-volcengine-agent-plan

Restart Pi or run /reload, then verify the catalog:

pi --list-models volcengine-agent-plan

Login and credentials

Interactive login

Run:

/login volcengine-agent-plan

Pi prompts for the dedicated Agent Plan API key and the subscribed tier. The login flow sends an authenticated, intentionally incomplete Responses request. A valid key reaches MissingParameter; an invalid or unauthorized key returns 401/403 and is requested again. This validation does not start model inference.

Pi stores the API key and selected tier in its standard credential file, normally ~/.pi/agent/auth.json. The package does not read a custom key file.

Environment variables

Interactive login is recommended. Ambient credentials remain available for automated environments:

export ARK_AGENT_PLAN_API_KEY='...'
export ARK_AGENT_PLAN_TIER='medium'

VOLCENGINE_ARK_PLAN_API_KEY is also accepted as an API key fallback. Supported tier values are small, medium, large, and max; the default is medium when no tier is configured.

Models and tiers

The current catalog contains:

• Doubao Seed 2.0 Mini, Lite, and Evolving
• Doubao Seed 2.1 Turbo
• DeepSeek V4 Flash and Pro
• MiniMax M3
• GLM 5.3 Flash and GLM 5.3
• Kimi K2.7 Code and Kimi K3

Small exposes 10 models. Kimi K3 currently requires Medium or higher. Medium, Large, and Max expose all 11 current models.

Compatibility

Kimi K2.7 Code uses Chat Completions because its Agent Plan Responses tool-call path returned repeated server errors during compatibility testing. Other catalog entries use Responses.

Kimi K2.7 Code does not support disabling thinking through the current gateway. Selecting Pi's off level therefore avoids sending an unsupported disable control but cannot guarantee that the model stops internal reasoning.

Kimi K3 inherits only model-intrinsic capabilities from Pi's Moonshot catalog. Agent Plan continues to own its protocol, limits, compatibility settings, and plan rules. Its available Pi thinking levels are low, high, and max.

Reasoning effort follows Volcengine's documented reasoning.effort compatibility mapping. Doubao Seed models close thinking for none/minimal and collapse xhigh/max to high; DeepSeek V4 Flash/Pro additionally collapse medium to low. Every model card keeps all seven Pi levels selectable and Pi sends the mapped effort value.

GLM 5.3 cannot disable thinking. Official Z.ai/Zhipu docs only allow low, high, and max effort, so those are the Pi thinking levels this card exposes. Pi sends OpenAI reasoning.effort and does not rewrite the request to Zhipu thinking.type.

GLM 5.3 Flash accepts all seven effort levels, but thinking cannot be fully disabled: none falls back to low, medium/high become high, and xhigh/max become max.

Cost reporting

The catalog retains public pay-as-you-go API reference rates in USD per million tokens, allowing Pi to estimate session cost from actual token usage. Models with an existing Pi upstream card selectively inherit its rates; the Doubao models use API estimates normalized from Volcengine's public price table. Doubao Seed 2.1 Turbo has no published pay-as-you-go reference rate yet, so its cost is a zero placeholder and Pi reports no spend for it.

This value compares session resource usage; it is not the Agent Plan bill. Volcengine still calculates the subscription price, AFP usage, and remaining quota separately.

Security

Pi's standard auth.json is protected by filesystem permissions but is not an operating-system keychain. Do not commit credentials, paste them into issue reports, or place them in project configuration.

The API key validation request never logs the key or response body. Temporary network or service failures let the user retry, cancel, or explicitly save without validation.

Development

pnpm check
pi --no-extensions -e . --list-models volcengine-agent-plan
npm pack --dry-run --json .

Unit tests use mocked credentials and fetch responses. Real-key contract tests are intentionally excluded from normal CI.

Limitations

Agent Plan does not expose a usable /models endpoint, so the catalog and model metadata are versioned statically. Volcengine may change aliases, protocol behavior, limits, or tier availability before this package is updated.

The catalog declares image input for the 7 vision-capable models (Doubao Seed 2.0 Mini/Lite/Evolving, MiniMax M3, Kimi K2.7 Code/K3, and GLM 5.3 Flash). DeepSeek V4 Flash/Pro, GLM 5.3, and Doubao Seed 2.1 Turbo remain text-only. Extreme context windows, maximum-length output, concurrency, rate limits, and subscription quota reporting are not covered.

License

MIT