pi-zai-agents

Unofficial pi extension package for Z.AI Agent API products:

• GLM Slide/Poster Agent (slides_glm_agent)
• Translation Agent (general_translation)
• Video Effect Template Agent (vidu_template_agent)
• Shared Agent API support: file upload, async result polling, and slide conversation/export retrieval

This package is intentionally separate from pi-zai-mcp. It does not register or manage Z.AI MCP servers.

Install

pi install npm:pi-zai-agents

Install directly from GitHub:

pi install https://github.com/fitchmultz/pi-zai-agents

From a local clone:

git clone https://github.com/fitchmultz/pi-zai-agents.git
cd pi-zai-agents
npm install
pi install .

Try without installing permanently:

Z_AI_API_KEY="your_key" pi -e .

Configure

Run /zai-agents-status in pi to check local configuration. In TUI/RPC mode it uses Pi notifications; in print mode it writes the status text to stdout; in JSON mode it emits a custom message event.

Tools

The package intentionally exposes the minimum product-level surface: three tools, one per Z.AI Agent product. Shared helper behavior is folded into those tools to reduce tool count, prompt size, and agent confusion.

TUI output is compact by default and uses colored custom renderers. Long-running calls emit early progress updates so the tool card appears before the API call completes. Expand a tool result to show details. Large JSON responses and truncated summaries are saved to temp files when needed; streaming slide responses are always saved as raw JSON.

When file_url, image_url, or video_url values appear in a response, this extension downloads those artifacts into an OS temp directory and reports the local paths.

Native programmatic callers also receive the existing bounded outcome as {title, status, summary, artifacts, artifactWarnings, rawResponsePath?}. Artifact receipts contain sourceKey, local path and bytes, not remote URLs. Raw service responses remain existing private details or explicitly linked files. Paid-call intent guidance, billing notices, request IDs, upload/path checks, timeout/cancellation, polling and no-replay behavior are unchanged; native model image generation does not replace these services.

Paid-call warning

These tools make real Z.AI Agent API calls. Z.AI pricing docs list:

• GLM Slide/Poster Agent(beta): $0.7 / MTok
• General-Purpose Translation: $3 / MTok
• Popular Special Effects Video Templates: $0.2 / video

File upload docs state uploaded files are retained for 180 days. Do not upload sensitive files unless that retention is acceptable.

Integration contract

Evidence inspected on 2026-06-05:

• Docs index: https://docs.z.ai/llms.txt
• Slide/Poster guide: https://docs.z.ai/guides/agents/slide
• Translation guide: https://docs.z.ai/guides/agents/translation
• Video Template guide: https://docs.z.ai/guides/agents/video-template
• Agent API: https://docs.z.ai/api-reference/agents/agent
• File Upload API: https://docs.z.ai/api-reference/agents/file-upload
• Async Result API: https://docs.z.ai/api-reference/agents/get-async-result
• Slide Conversation API: https://docs.z.ai/api-reference/agents/agent-conversation
• HTTP/API auth guide: https://docs.z.ai/guides/develop/http/introduction
• Pricing: https://docs.z.ai/guides/overview/pricing
• Errors: https://docs.z.ai/api-reference/api-code

Auth and base URL

• Base server: https://api.z.ai/api
• Auth: Authorization: Bearer <api key>
• JSON calls also send Content-Type: application/json and Accept-Language: en-US,en by default.
• File upload uses multipart/form-data.

Endpoints

Agent request contracts

Translation Agent

agent_id: general_translation

Request:

{
  "agent_id": "general_translation",
  "stream": false,
  "messages": [{ "role": "user", "content": [{ "type": "text", "text": "..." }] }],
  "custom_variables": {
    "source_lang": "auto",
    "target_lang": "zh-CN",
    "glossary": "optional uploaded file id",
    "strategy": "general",
    "strategy_config": {
      "general": { "suggestion": "optional style guidance" },
      "cot": { "reason_lang": "to" }
    }
  }
}

Strategies exposed: general, paraphrase, two_step, three_step, reflection, cot. The guide lists COT as a strategy. The OpenAPI enum omits cot, but a live probe on 2026-06-05 returned HTTP 200 for strategy: "cot", so this package exposes it.

Response includes id, agent_id, status, choices, and usage token counts. finish_reason may be stop, tool_calls, length, sensitive, or network_error.

Slide/Poster Agent

agent_id: slides_glm_agent

Request:

{
  "agent_id": "slides_glm_agent",
  "stream": true,
  "conversation_id": "optional existing conversation",
  "request_id": "optional caller id",
  "messages": [{ "role": "user", "content": [{ "type": "text", "text": "..." }] }]
}

The API docs list stream default true; this tool follows that default. A live streaming probe confirmed text/event-stream frames shaped as data: {...} and terminated by data: [DONE]. Frames include fields such as id, agent_id, conversation_id, choices, messages, phase, and text deltas.

Use z_ai_agent_slide with action=conversation and the returned conversation_id to retrieve export metadata. Conversation requests support custom_variables.include_pdf and optional page descriptors with position, width, and height. Conversation responses can include file_url and image_url artifacts.

Video Effect Template Agent

agent_id: vidu_template_agent

Request:

{
  "agent_id": "vidu_template_agent",
  "request_id": "optional caller id",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "template prompt" },
      { "type": "image_url", "image_url": "https://..." }
    ]
  }],
  "custom_variables": { "template": "bodyshake" }
}

Supported templates from docs: french_kiss, bodyshake, sexy_me.

Initial response includes status, agent_id, and async_id. Poll /v1/agents/async-result with agent_id and async_id; status can be pending, success, or failed. Successful async result choices can include MP4 video_url artifacts.

File Upload

POST /paas/v4/files with multipart form fields:

• purpose: agent
• file: binary file

Documented limits:

• Max 100 files
• Max 100 MB per file
• Retained for 180 days
• Formats: pdf, doc, xlsx, ppt, txt, jpg, png

Response includes id, object, bytes, filename, purpose, and created_at.

Failure semantics

Z.AI documents two layers of errors:

• HTTP status codes, such as 400 parameter errors, 401 auth errors, 429 rate/balance/concurrency errors, 435 file too large, and 500 server errors.
• JSON body business errors under error.code and error.message.

This extension throws tool errors for non-2xx HTTP responses, top-level error objects, and status: "failed". Streaming failures may arrive inside SSE frames and are surfaced as tool errors when present.

Examples

Translate text:

{
  "action": "translate",
  "text": "Two roads diverged in a wood.",
  "sourceLang": "en",
  "targetLang": "zh-CN",
  "strategy": "general"
}

Translate with an uploaded glossary in one call. Relative paths resolve from the current pi session cwd:

{
  "action": "translate",
  "text": "pi-zai-agents live validation is complete.",
  "sourceLang": "en",
  "targetLang": "zh-CN",
  "glossaryPath": "./glossary.xlsx"
}

Create a slide/poster:

{
  "action": "create",
  "prompt": "Create a five-slide product launch deck for a developer tool.",
  "stream": true
}

Retrieve slide exports:

{
  "action": "conversation",
  "conversationId": "returned-conversation-id",
  "includePdf": true
}

Create and poll a video template task:

{
  "action": "create",
  "imageUrl": "https://example.com/input.png",
  "template": "bodyshake",
  "waitUntilComplete": true,
  "pollIntervalMs": 5000,
  "maxPolls": 60
}

Poll an existing video async result:

{
  "action": "result",
  "asyncId": "returned-async-id",
  "waitUntilComplete": true
}

What this package does not include

• Z.AI MCP servers. Use pi-zai-mcp for Web Search, Web Reader, Zread, and Vision MCP.
• Generic raw /v1/agents escape hatches. This package keeps a strict scope and only exposes the three verified product tools.
• Z.AI GLM chat model provider support. Pi already has Z.AI model provider support through ZAI_API_KEY.

Automatic npm releases (maintainers)

After a reviewed change merges into main, the shared release procedure prepares a new version and publishes matching npm and GitHub releases after compatibility checks and candidate-tarball qualification. Complete applicable package-specific release evidence for the candidate before publication. Existing releases are not overwritten.

Failed/unpublished candidates can retry daily at 12:17 UTC or via manual dispatch of npm release on main, without another bump. Set repository variable NPM_RELEASE_ENABLED to anything other than true to stop new release plans; cancel pending runs separately when needed. Workflow validation is not evidence of a completed real OIDC publication.

Verify this repo

The supported Pi floor is documented with its qualification evidence. Host peers remain optional wildcards rather than hard pins. Required qualification targets are the latest stable official Pi and latest maintained fork main, resolving version/commit once per workflow run and retaining exact SDK/CLI evidence. Locked development dependencies are reproducible snapshots, not validation targets. Use the shared qualifier with --host official --target latest and separately with the packed latest fork revision; it selects each complete host graph before running npm run check:compat with an empty HOME/agent profile. Plain npm ci --ignore-scripts only installs the locked development snapshot. This runs types, existing HTTP timeout/SSE tests, dry-run packing, and a native Pi tool loop that verifies translation request shaping, result delivery, and reload without replay against a loopback HTTP fixture. It never calls the paid Z.ai service; live translation, slides, video, auth, and all-platform qualification remain separate.

npm install
npm run ci

Run npm run release:dry-run on the prepared, unpublished release candidate.

Local pi package smoke check:

tmpdir="$(mktemp -d)"
cd "$tmpdir"
PI_SKIP_VERSION_CHECK=1 PI_OFFLINE=1 pi install -l --approve /path/to/pi-zai-agents
PI_SKIP_VERSION_CHECK=1 PI_OFFLINE=1 pi list --approve

Project map

extensions/zai-agents.ts  # pi package entrypoint
src/index.ts              # extension implementation
package.json              # npm + pi package manifest
CHANGELOG.md              # release notes