人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载Z.AI Coding Plan 是 Z.AI智谱面向编码场景提供的模型服务计划其 API 遵循 OpenAI 兼容协议。本文基于 VoltAgent 模型路由器的官方文档讲解如何通过zai-coding-plan/model形式在Agent中启用该服务覆盖环境变量、默认 Base URL 及其覆盖方式、可用模型清单并结合voltagent/core源码说明注册表加载与适配器构建的底层原理。读完本文你将能在自己的 VoltAgent 应用中快速接入 Z.AI Coding Plan并掌握排查 API Key 缺失、Base URL 覆盖等常见问题的方法。Z.AI Coding Plan 在 VoltAgent 中的定位VoltAgent 内置了一个模型路由器Model Router它把所有受支持的模型提供商统一抽象为provider/model这种提供商前缀 模型名的字符串格式。zai-coding-plan就是其中的一个提供商前缀代表 Z.AI Coding Plan 服务其注册信息可以在 model-provider-registry.generated.ts 中直接看到zai-coding-plan: { id: zai-coding-plan, name: Z.AI Coding Plan, npm: ai-sdk/openai-compatible, api: https://api.z.ai/api/coding/paas/v4, env: [ZHIPU_API_KEY], doc: https://docs.z.ai/devpack/overview, },这段由注册表快照生成的配置包含四个关键字段id提供商 ID也就是模型字符串中的前缀部分zai-coding-planname提供商显示名称npm驱动该提供商的适配器 npm 包这里是ai-sdk/openai-compatible说明 Z.AI Coding Plan 走的是 OpenAI 兼容适配器api默认 API 端点即默认 Base URLenv所需的环境变量列表即ZHIPU_API_KEY。与之并列的还有zaiZ.AI 标准服务端点为https://api.z.ai/api/paas/v4和zhipuai智谱开放平台端点为https://open.bigmodel.cn/api/paas/v4三者共享ZHIPU_API_KEY但 Coding Plan 走的是专门的coding/paas/v4端点。完整提供商目录见 overview.md。快速开始一个可运行的 Agent官方文档给出了最简洁的接入方式——在Agent构造参数中直接使用zai-coding-plan/glm-4.5作为modelimport { Agent } from voltagent/core; const agent new Agent({ name: zai-coding-plan-agent, instructions: You are a helpful assistant, model: zai-coding-plan/glm-4.5, });当 Agent 拿到形如zai-coding-plan/glm-4.5的模型 ID 时模型路由器会按以下步骤处理按/分割模型 ID解析出提供商 IDzai-coding-plan与模型名glm-4.5。splitModelId的实现位于 model-provider-registry.ts它还兼容provider:model冒号分隔写法从注册表含内置静态注册表与本地缓存的动态注册表中查找zai-coding-plan的配置项按配置中的npm字段动态加载适配器包并调用对应的 Provider Adapter 构建语言模型实例将构建好的模型注入 Agent 的对话、工具调用等运行时。环境变量ZHIPU_API_KEY使用 Z.AI Coding Plan 只需要一个环境变量ZHIPU_API_KEYZ.AI / 智谱开放平台的 API Key。运行时注册表会在加载提供商之前校验 API Key。requireApiKey的实现会扫描配置中名称匹配KEY|TOKEN|SECRET的环境变量见 model-provider-registry.ts如果ZHIPU_API_KEY未设置或为空字符串会抛出明确的错误信息Missing API key for zai-coding-plan. Set process.env.ZHIPU_API_KEY.因此在本地运行示例前请先导出环境变量export ZHIPU_API_KEYyour-zai-api-keyProvider 包与 OpenAI 兼容适配器文档明确指出该提供商的承载包为ai-sdk/openai-compatible使用的是 OpenAI 兼容适配器。这也是整个voltagent/core中大量第三方 OpenAI 兼容服务共用的接入方式——注册表通过PACKAGE_ADAPTERS把ai-sdk/openai-compatible映射到buildOpenAICompatibleProvider适配器见 model-provider-registry.ts。该适配器model-provider-registry.ts的构建逻辑如下const buildOpenAICompatibleProvider: ProviderAdapter (config, moduleExports) { const createFn getModuleFunction(moduleExports, createOpenAICompatible); // ...校验 apiKey 与 baseURL... const provider createFn({ name: config.id, baseURL, apiKey: apiKeyMatch.value, supportsStructuredOutputs: true, }); return provider as ModelProviderEntry; };几个值得注意的细节适配器会优先查找createOpenAICompatible工厂函数并以注册表配置提供商名、Base URL、API Key作为参数完成初始化supportsStructuredOutputs: true被显式开启表示该服务支持结构化输出Structured Outputs可用于要求模型按 JSON Schema 返回结果的场景Provider 包采用运行时动态import(config.npm)加载见 model-provider-registry.ts。如果你的运行环境中尚未安装ai-sdk/openai-compatible会收到类似 Failed to load provider ... Install the package and try again 的提示此时只需在项目中安装该依赖即可。默认 Base URL 与覆盖方式Z.AI Coding Plan 的默认 Base URL 为https://api.z.ai/api/coding/paas/v4该默认值来自注册表配置中的api字段。同时VoltAgent 支持通过环境变量覆盖默认端点变量名为ZAI_CODING_PLAN_BASE_URL这个变量名并非凭空约定而是由注册表的resolveBaseUrl逻辑自动推导出来的model-provider-registry.tsconst resolveBaseUrl (config: ModelProviderRegistryEntry): string | undefined { const envNames config.env ?? []; const override resolveEnvValue( envNames.filter((name) /ENDPOINT|BASE_URL|BASEURL/i.test(name)), )?.value; if (override) { return override; } const conventional getEnvValue(${envKeyForProvider(config.id)}_BASE_URL); if (conventional) { return conventional; } return config.api; };解析优先级依次为配置的env列表中名称包含ENDPOINT、BASE_URL、BASEURL的显式环境变量对zai-coding-plan而言其env只有ZHIPU_API_KEY因此这一层不命中约定俗成的PROVIDER_ID_BASE_URL变量其中提供商 ID 会转换为大写并把连字符替换为下划线即zai-coding-plan→ZAI_CODING_PLAN最终得到ZAI_CODING_PLAN_BASE_URL以上均未设置时回落到注册表配置中的api默认值。典型的覆盖用法例如把请求转发到自建代理或网关export ZAI_CODING_PLAN_BASE_URLhttps://your-gateway.example.com/coding/v4说明website/models-docs/providers/zai-coding-plan.md由 generate-model-docs.js 自动生成其中的 Base URL 与覆盖变量名正是按上述formatEnvList、baseUrlEnv逻辑输出与运行时行为保持一致。可用模型清单当前注册表快照中zai-coding-plan提供商下共有 7 个模型见 model-provider-types.generated.ts模型 ID说明zai-coding-plan/glm-4.5GLM-4.5 通用模型zai-coding-plan/glm-4.5-airGLM-4.5 轻量版低延迟、低成本zai-coding-plan/glm-4.5-flashGLM-4.5 高速版zai-coding-plan/glm-4.5vGLM-4.5 视觉多模态模型zai-coding-plan/glm-4.6GLM-4.6 通用模型zai-coding-plan/glm-4.6vGLM-4.6 视觉多模态模型zai-coding-plan/glm-4.7GLM-4.7 通用模型模型列表以注册表快照为准且会被类型系统约束。ModelRouterModelId类型会把每个提供商的模型 ID 拼接为${provider}/${model}的字面量联合类型见 model-provider-registry.ts这意味着 TypeScript 编译器可以直接校验你写的模型字符串是否真实存在——写错模型名会在编译期报错而不会等到运行时才暴露。从源码结构看该模型列表来源于 models.dev并支持调用refreshRegistry()主动拉取最新数据、startAutoRefresh()以默认 30 分钟间隔自动刷新model-provider-registry.ts。因此模型清单会随上游快照演进文档页面中的列表属于生成时的快照状态。从其他模型迁移到 Z.AI Coding Plan如果你已有运行中的 Agent切换到 Z.AI Coding Plan 只需三步确认环境变量设置ZHIPU_API_KEY或按需设置ZAI_CODING_PLAN_BASE_URL覆盖端点确认依赖确保运行环境可加载ai-sdk/openai-compatible包修改模型字符串把model字段改为上表中的任一zai-coding-plan/model值例如const agent new Agent({ name: zai-coding-plan-agent, instructions: You are a helpful assistant, model: zai-coding-plan/glm-4.7, });由于路由发生在 Agent 配置层切换提供商不需要改动业务逻辑如果希望在同一应用中按场景切换模型也可以把模型 ID 提取为配置项或环境变量运行时再传给Agent。小结Z.AI Coding Plan 通过zai-coding-plan/model前缀接入 VoltAgent 模型路由器底层由ai-sdk/openai-compatible的createOpenAICompatible适配器驱动唯一必需的环境变量是ZHIPU_API_KEY缺失时注册表会给出明确的报错指引默认 Base URL 为https://api.z.ai/api/coding/paas/v4可通过ZAI_CODING_PLAN_BASE_URL覆盖解析优先级在 resolveBaseUrl 中有明确实现当前快照提供 7 个 GLM 系列模型模型名受到 TypeScript 类型系统约束写错会在编译期暴露相关注册表数据可从 model-provider-registry.generated.ts 与 model-provider-types.generated.ts 中查阅提供商全景目录见 overview.md。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐Tiled自动化映射深度解析如何实现高效地图绘制的完整指南Tiled自动化映射深度解析如何实现高效地图绘制的完整指南 Tiled地图编辑器的自动化映射Automapping功能是游戏地图制作中的革命性工具它通过人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音VoltAgent 接入 Fireworks AI 提供方实战模型字符串路由、环境变量与完整模型清单VoltAgent 接入 Fireworks AI 提供方实战模型字符串路由、环境变量与完整模型清单 本篇指南聚焦 VoltAgent 模型路由器中 Fire人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音CodexBar 中的 z.ai / GLM ProviderAPI 区域路由、Token 回退链与 Coding Plan 配额解析全解CodexBar 中的 z.ai / GLM ProviderAPI 区域路由、Token 回退链与 Coding Plan 配额解析全解 CodexBarAI 应用桌面应用开发工具上一篇G0DM0D3自定义触发词教程如何定义你自己的红队敏感词列表下一篇Laravel Search String在电商项目中的实际应用商品筛选系统的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考