{"id":51325780,"url":"https://github.com/fitchmultz/pi-zai-agents","last_synced_at":"2026-07-01T18:03:12.718Z","repository":{"id":365065971,"uuid":"1260526172","full_name":"fitchmultz/pi-zai-agents","owner":"fitchmultz","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-24T17:06:22.000Z","size":139,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-24T19:05:08.073Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fitchmultz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-05T15:30:13.000Z","updated_at":"2026-06-24T17:07:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fitchmultz/pi-zai-agents","commit_stats":null,"previous_names":["fitchmultz/pi-zai-agents"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/fitchmultz/pi-zai-agents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fitchmultz%2Fpi-zai-agents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fitchmultz%2Fpi-zai-agents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fitchmultz%2Fpi-zai-agents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fitchmultz%2Fpi-zai-agents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fitchmultz","download_url":"https://codeload.github.com/fitchmultz/pi-zai-agents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fitchmultz%2Fpi-zai-agents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35017091,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-01T18:03:11.984Z","updated_at":"2026-07-01T18:03:12.704Z","avatar_url":"https://github.com/fitchmultz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pi-zai-agents\n\nUnofficial pi extension package for Z.AI **Agent API** products:\n\n- GLM Slide/Poster Agent (`slides_glm_agent`)\n- Translation Agent (`general_translation`)\n- Video Effect Template Agent (`vidu_template_agent`)\n- Shared Agent API support: file upload, async result polling, and slide conversation/export retrieval\n\nThis package is intentionally separate from `pi-zai-mcp`. It does **not** register or manage Z.AI MCP servers.\n\n## Install\n\n```bash\npi install npm:pi-zai-agents\n```\n\nInstall directly from GitHub:\n\n```bash\npi install https://github.com/fitchmultz/pi-zai-agents\n```\n\nFrom a local clone:\n\n```bash\ngit clone https://github.com/fitchmultz/pi-zai-agents.git\ncd pi-zai-agents\nnpm install\npi install .\n```\n\nTry without installing permanently:\n\n```bash\nZ_AI_API_KEY=\"your_key\" pi -e .\n```\n\n## Configure\n\n| Variable | Required | Default | Purpose |\n| --- | --- | --- | --- |\n| `Z_AI_API_KEY` / `ZAI_API_KEY` | Yes | none | Z.AI API key sent as `Authorization: Bearer ...`. |\n| `Z_AI_AGENT_API_BASE_URL` | No | `https://api.z.ai/api` | Agent API base URL. |\n| `Z_AI_ACCEPT_LANGUAGE` | No | `en-US,en` | `Accept-Language` header. |\n| `Z_AI_AGENT_TIMEOUT_MS` | No | `300000` | Per-request timeout in ms. Applies to API and artifact download requests. |\n\nRun `/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.\n\n## Tools\n\nThe 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.\n\n| Tool | Purpose |\n| --- | --- |\n| `z_ai_agent_translate` | Calls `general_translation` for translation, streaming translation, glossary upload, or glossary-backed translation. `glossaryPath` is resolved relative to the current pi session cwd and supports a leading `@`. |\n| `z_ai_agent_slide` | Calls `slides_glm_agent` to create/refine slides/posters (`action=create`) or retrieve/download conversation exports (`action=conversation`). |\n| `z_ai_agent_video` | Calls `vidu_template_agent` to create video-template tasks (`action=create`) or retrieve/poll async results (`action=result`). Polling is clamped to 1-120 attempts and 1000-60000 ms intervals. |\n\nTUI 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.\n\nWhen `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.\n\n## Paid-call warning\n\nThese tools make real Z.AI Agent API calls. Z.AI pricing docs list:\n\n- GLM Slide/Poster Agent(beta): `$0.7 / MTok`\n- General-Purpose Translation: `$3 / MTok`\n- Popular Special Effects Video Templates: `$0.2 / video`\n\nFile upload docs state uploaded files are retained for 180 days. Do not upload sensitive files unless that retention is acceptable.\n\n## Integration contract\n\nEvidence inspected on 2026-06-05:\n\n- Docs index: \u003chttps://docs.z.ai/llms.txt\u003e\n- Slide/Poster guide: \u003chttps://docs.z.ai/guides/agents/slide\u003e\n- Translation guide: \u003chttps://docs.z.ai/guides/agents/translation\u003e\n- Video Template guide: \u003chttps://docs.z.ai/guides/agents/video-template\u003e\n- Agent API: \u003chttps://docs.z.ai/api-reference/agents/agent\u003e\n- File Upload API: \u003chttps://docs.z.ai/api-reference/agents/file-upload\u003e\n- Async Result API: \u003chttps://docs.z.ai/api-reference/agents/get-async-result\u003e\n- Slide Conversation API: \u003chttps://docs.z.ai/api-reference/agents/agent-conversation\u003e\n- HTTP/API auth guide: \u003chttps://docs.z.ai/guides/develop/http/introduction\u003e\n- Pricing: \u003chttps://docs.z.ai/guides/overview/pricing\u003e\n- Errors: \u003chttps://docs.z.ai/api-reference/api-code\u003e\n\n### Auth and base URL\n\n- Base server: `https://api.z.ai/api`\n- Auth: `Authorization: Bearer \u003capi key\u003e`\n- JSON calls also send `Content-Type: application/json` and `Accept-Language: en-US,en` by default.\n- File upload uses `multipart/form-data`.\n\n### Endpoints\n\n| Endpoint | Method | Used by | Notes |\n| --- | --- | --- | --- |\n| `/v1/agents` | POST | Translation, Slide/Poster, Video Template | Request shape differs by `agent_id`. |\n| `/paas/v4/files` | POST | File upload | Purpose must be `agent`. |\n| `/v1/agents/async-result` | POST | Video async polling | Documented for `vidu_template_agent`. |\n| `/v1/agents/conversation` | POST | Slide conversation/export | Docs say only `slides_glm_agent` is supported. |\n\n### Agent request contracts\n\n#### Translation Agent\n\n`agent_id: general_translation`\n\nRequest:\n\n```json\n{\n  \"agent_id\": \"general_translation\",\n  \"stream\": false,\n  \"messages\": [{ \"role\": \"user\", \"content\": [{ \"type\": \"text\", \"text\": \"...\" }] }],\n  \"custom_variables\": {\n    \"source_lang\": \"auto\",\n    \"target_lang\": \"zh-CN\",\n    \"glossary\": \"optional uploaded file id\",\n    \"strategy\": \"general\",\n    \"strategy_config\": {\n      \"general\": { \"suggestion\": \"optional style guidance\" },\n      \"cot\": { \"reason_lang\": \"to\" }\n    }\n  }\n}\n```\n\nStrategies 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.\n\nResponse includes `id`, `agent_id`, `status`, `choices`, and `usage` token counts. `finish_reason` may be `stop`, `tool_calls`, `length`, `sensitive`, or `network_error`.\n\n#### Slide/Poster Agent\n\n`agent_id: slides_glm_agent`\n\nRequest:\n\n```json\n{\n  \"agent_id\": \"slides_glm_agent\",\n  \"stream\": true,\n  \"conversation_id\": \"optional existing conversation\",\n  \"request_id\": \"optional caller id\",\n  \"messages\": [{ \"role\": \"user\", \"content\": [{ \"type\": \"text\", \"text\": \"...\" }] }]\n}\n```\n\nThe 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.\n\nUse `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.\n\n#### Video Effect Template Agent\n\n`agent_id: vidu_template_agent`\n\nRequest:\n\n```json\n{\n  \"agent_id\": \"vidu_template_agent\",\n  \"request_id\": \"optional caller id\",\n  \"messages\": [{\n    \"role\": \"user\",\n    \"content\": [\n      { \"type\": \"text\", \"text\": \"template prompt\" },\n      { \"type\": \"image_url\", \"image_url\": \"https://...\" }\n    ]\n  }],\n  \"custom_variables\": { \"template\": \"bodyshake\" }\n}\n```\n\nSupported templates from docs: `french_kiss`, `bodyshake`, `sexy_me`.\n\nInitial 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.\n\n#### File Upload\n\n`POST /paas/v4/files` with multipart form fields:\n\n- `purpose`: `agent`\n- `file`: binary file\n\nDocumented limits:\n\n- Max 100 files\n- Max 100 MB per file\n- Retained for 180 days\n- Formats: `pdf`, `doc`, `xlsx`, `ppt`, `txt`, `jpg`, `png`\n\nResponse includes `id`, `object`, `bytes`, `filename`, `purpose`, and `created_at`.\n\n### Failure semantics\n\nZ.AI documents two layers of errors:\n\n- HTTP status codes, such as 400 parameter errors, 401 auth errors, 429 rate/balance/concurrency errors, 435 file too large, and 500 server errors.\n- JSON body business errors under `error.code` and `error.message`.\n\nThis 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.\n\n## Examples\n\nTranslate text:\n\n```json\n{\n  \"action\": \"translate\",\n  \"text\": \"Two roads diverged in a wood.\",\n  \"sourceLang\": \"en\",\n  \"targetLang\": \"zh-CN\",\n  \"strategy\": \"general\"\n}\n```\n\nTranslate with an uploaded glossary in one call. Relative paths resolve from the current pi session cwd:\n\n```json\n{\n  \"action\": \"translate\",\n  \"text\": \"pi-zai-agents live validation is complete.\",\n  \"sourceLang\": \"en\",\n  \"targetLang\": \"zh-CN\",\n  \"glossaryPath\": \"./glossary.xlsx\"\n}\n```\n\nCreate a slide/poster:\n\n```json\n{\n  \"action\": \"create\",\n  \"prompt\": \"Create a five-slide product launch deck for a developer tool.\",\n  \"stream\": true\n}\n```\n\nRetrieve slide exports:\n\n```json\n{\n  \"action\": \"conversation\",\n  \"conversationId\": \"returned-conversation-id\",\n  \"includePdf\": true\n}\n```\n\nCreate and poll a video template task:\n\n```json\n{\n  \"action\": \"create\",\n  \"imageUrl\": \"https://example.com/input.png\",\n  \"template\": \"bodyshake\",\n  \"waitUntilComplete\": true,\n  \"pollIntervalMs\": 5000,\n  \"maxPolls\": 60\n}\n```\n\nPoll an existing video async result:\n\n```json\n{\n  \"action\": \"result\",\n  \"asyncId\": \"returned-async-id\",\n  \"waitUntilComplete\": true\n}\n```\n\n## What this package does not include\n\n- Z.AI MCP servers. Use `pi-zai-mcp` for Web Search, Web Reader, Zread, and Vision MCP.\n- Generic raw `/v1/agents` escape hatches. This package keeps a strict scope and only exposes the three verified product tools.\n- Z.AI GLM chat model provider support. Pi already has Z.AI model provider support through `ZAI_API_KEY`.\n\n## Verify this repo\n\n```bash\nnpm install\nnpm run ci\n```\n\nUse `npm run release:dry-run` after bumping to an unpublished version.\n\nLocal pi package smoke check:\n\n```bash\ntmpdir=\"$(mktemp -d)\"\ncd \"$tmpdir\"\nPI_SKIP_VERSION_CHECK=1 PI_OFFLINE=1 pi install -l --approve /path/to/pi-zai-agents\nPI_SKIP_VERSION_CHECK=1 PI_OFFLINE=1 pi list --approve\n```\n\n## Project map\n\n```text\nextensions/zai-agents.ts  # pi package entrypoint\nsrc/index.ts              # extension implementation\npackage.json              # npm + pi package manifest\nCHANGELOG.md              # release notes\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffitchmultz%2Fpi-zai-agents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffitchmultz%2Fpi-zai-agents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffitchmultz%2Fpi-zai-agents/lists"}