人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载本文以 VoltAgent 模型路由器的google-vertex-anthropic/model提供方为讲解主线介绍如何在voltagent/core的Agent中通过 Google Cloud Vertex AI 的 Anthropic 合作伙伴模型通道运行 Claude 系列模型并深入说明底层注册表与适配器的实现原理。读完本文你将掌握该提供方的环境变量配置、快速接入方式、可用的 9 个模型标识、默认 Base URL 覆盖方法以及模型 ID 路由的底层解析逻辑。一、提供方概览Vertex AI 上的 Claude 合作伙伴模型VoltAgent 的模型路由器以provider/model形式统一寻址模型其中google-vertex-anthropic是专用于 Google Cloud Vertex AI 上Anthropic Claude 合作伙伴模型的提供方前缀官方资料可见于 Vertex AI 合作伙伴模型 Claude 文档。在 模型提供方目录 中它与google-vertex对应 Gemini 原生模型并列存在二者在仓库自动生成的注册表中各自登记为独立条目提供方名称模型前缀Provider 包环境变量Vertexgoogle-vertexai-sdk/google-vertexGOOGLE_VERTEX_PROJECT、GOOGLE_VERTEX_LOCATION、GOOGLE_APPLICATION_CREDENTIALSVertex (Anthropic)google-vertex-anthropicai-sdk/google-vertexGOOGLE_VERTEX_PROJECT、GOOGLE_VERTEX_LOCATION、GOOGLE_APPLICATION_CREDENTIALS关键事实两个前缀共用一个 Provider 包ai-sdk/google-vertex和同一组环境变量。区别仅在注册表条目 IDgoogle-vertex-anthropic以及模型列表Claude 系列不同见 注册表生成文件。二、快速开始创建基于 Claude 的 Agent在Agent的model字段中使用google-vertex-anthropic/model格式指定模型即可import { Agent } from voltagent/core; const agent new Agent({ name: google-vertex-anthropic-agent, instructions: You are a helpful assistant, model: google-vertex-anthropic/claude-3-5-haiku20241022, });要点说明model字符串中的/之前的google-vertex-anthropic被识别为提供方 ID之后的部分为模型 ID只要环境中配置好 Vertex AI 凭据上述 Agent 即可直接使用无需手动import或实例化 Provider模型标识中的20241022等时间戳后缀是 Claude 的版本化命名应与所选模型一一对应。若需要与完整运行时结合使用可参考仓库中的 with-google-vertex-ai 示例该示例使用google-vertex/gemini-2.0-flash将前缀换为google-vertex-anthropic/并选用下文模型列表中的任一 Claude 标识即可得到等价的 Claude 版本示例还展示了如何组合Memory、voltagent/libsql存储与voltagent/server-hono服务端。三、环境变量与 Google Cloud 凭据google-vertex-anthropic提供方需要以下三个环境变量环境变量用途GOOGLE_VERTEX_PROJECTGoogle Cloud 项目 ID用于定位 Vertex AI 资源GOOGLE_VERTEX_LOCATIONVertex AI 区域region如us-central1GOOGLE_APPLICATION_CREDENTIALS指向服务账号 JSON 凭据文件的路径Application Default Credentials配置方式以examples/with-google-vertex-ai为例可npm create voltagent-applatest -- --example with-google-vertex-ai获取模板cp .env.example .env然后在.env中填写GOOGLE_VERTEX_PROJECTmy-gcp-project GOOGLE_VERTEX_LOCATIONus-central1 GOOGLE_APPLICATION_CREDENTIALS/path/to/service-account-key.json注意Google 原生服务通常使用GOOGLE_CLOUD_PROJECT/GOOGLE_CLOUD_LOCATION而 VoltAgent 注册表约定的Vertex 提供方变量名为GOOGLE_VERTEX_PROJECT与GOOGLE_VERTEX_LOCATION见 模型提供方注册表。请以本仓库文档为准。确保服务账号具备访问 Vertex AI 所需的权限Vertex AI User 角色等。四、Provider 包与底层适配4.1 依赖包该提供方对应的 npm 包是ai-sdk/google-vertex即 Vercel AI SDK 的 Vertex AI Provider。VoltAgent 通过动态import(config.npm)按需加载它因此你需要在项目中安装npm install ai-sdk/google-vertex4.2 适配器实现注册表为ai-sdk/google-vertex绑定了专用适配器buildGoogleVertexProvidermodel-provider-registry.ts。其工作方式从包中获取createVertex工厂函数或vertex导出通过环境变量名模式匹配填充参数project来自匹配/PROJECT/i的环境变量即GOOGLE_VERTEX_PROJECTlocation来自匹配/LOCATION/i的环境变量即GOOGLE_VERTEX_LOCATION可选地支持GOOGLE_VERTEX_API_KEY作为 API Key 方式与 ADC 凭据方式二选一调用createVertex({ project, location, apiKey })得到 Provider 实例。由于google-vertex与google-vertex-anthropic共用同一个 Provider 包二者都会命中这个适配器差异只在注册的模型 ID 集合。从这里可以推断google-vertex-anthropic前缀本身不改变网络端点Claude 模型仍经由相同的 Vertex AI SDK 通道发起请求。4.3 模型 ID 解析与加载模型 ID 的解析发生在ModelProviderRegistry中splitModelIdmodel-provider-registry.ts把google-vertex-anthropic/claude-3-5-haiku20241022拆分为提供方 ID 与模型 ID同时也支持provider:model冒号分隔形式resolveLanguageModelmodel-provider-registry.ts按提供方 ID 查表加载 Provider 包后返回LanguageModel加载过程有单例缓存与进行中 Promise 去重getProviderEntry同一提供方不会被重复初始化非生产环境下注册表还会每 30 分钟自动刷新一次模型清单startAutoRefresh默认间隔30 * 60 * 1000毫秒并在~/.voltagent/model-registry/provider-registry.json缓存快照同时把生成的类型文件写入dist/registries。五、默认 Base URL 与覆盖方式google-vertex-anthropic在注册表中没有列出默认 Base URLapi字段为空端点由ai-sdk/google-vertex的 SDK 依据项目与区域自行推导。若需覆盖可设置环境变量GOOGLE_VERTEX_ANTHROPIC_BASE_URLhttps://your-proxy-or-regional-endpoint底层逻辑位于resolveBaseUrlmodel-provider-registry.ts优先检查环境变量名中带ENDPOINT/BASE_URL/BASEURL的变量其次按惯例读取${PROVIDER_ID}_BASE_URL——将提供方 ID 转大写、连字符替换为下划线即GOOGLE_VERTEX_ANTHROPIC_BASE_URL最后回落到注册表的api字段此处为空。因此对于该提供方覆盖 Base URL 的标准做法就是设置GOOGLE_VERTEX_ANTHROPIC_BASE_URL可用于接入代理网关或自定义区域端点。六、可用模型清单以下 9 个 Claude 模型标识在注册表中与google-vertex-anthropic前缀绑定见 模型提供方类型该文件由 models.dev 注册表 自动生成模型可能随上游更新模型 IDgoogle-vertex-anthropic/前缀之后部分备注claude-3-5-haiku20241022快速、低延迟小模型claude-3-5-sonnet20241022上一代主力 Sonnetclaude-3-7-sonnet20250219支持扩展思维的 Sonnetclaude-haiku-4-520251001Haiku 4.5 系列claude-opus-4-120250805Opus 4.1 系列claude-opus-4-520251101Opus 4.5 系列claude-opus-420250514Opus 4 系列claude-sonnet-4-520250929Sonnet 4.5 系列claude-sonnet-420250514Sonnet 4 系列使用方式示例// 高吞吐低成本场景 model: google-vertex-anthropic/claude-haiku-4-520251001, // 复杂推理场景 model: google-vertex-anthropic/claude-opus-4-520251101,注意模型 ID 需要严格匹配列表中的完整字符串包括时间戳后缀注册表生成的 TypeScript 类型ModelRouterModelId会在编译期校验provider/model组合是否合法从 模型提供方类型生成逻辑 可以推断拼写错误会在类型检查阶段被捕获。七、常见问题排查提示安装包缺失Failed to load provider google-vertex-anthropic from ai-sdk/google-vertex—— 请先执行npm install ai-sdk/google-vertex注册表按需加载时要求包已安装model-provider-registry.ts。凭据缺失/认证失败确认GOOGLE_VERTEX_PROJECT、GOOGLE_VERTEX_LOCATION、GOOGLE_APPLICATION_CREDENTIALS均已正确设置且服务账号拥有 Vertex AI 调用权限。模型 ID 不存在核对模型标识是否属于上表时间戳后缀不可省略。需要自定义端点设置GOOGLE_VERTEX_ANTHROPIC_BASE_URL覆盖默认端点。八、结语google-vertex-anthropic是 VoltAgent 在 Google Cloud 生态中接入 Anthropic Claude 模型的统一入口只需三个环境变量加一个ai-sdk/google-vertex依赖就能以google-vertex-anthropic/claude-...形式在Agent.model中直接使用 Claude 系列模型。其底层由 ModelProviderRegistry 负责按需加载、适配与缓存模型清单随 models.dev 注册表自动同步Base URL 可通过惯例命名的环境变量灵活覆盖。更多提供方接入方式可参见 模型提供方目录。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐ADK Claude模型集成Vertex AI上的Anthropic模型使用指南ADK Claude模型集成Vertex AI上的Anthropic模型使用指南 ADKAgent Development Kit是一款开源的代码优先Py文档AI AgentVoltAgent 接入 Anthropic Claude 模型Provider 配置、模型路由与完整示例解析VoltAgent 接入 Anthropic Claude 模型Provider 配置、模型路由与完整示例解析 本文基于 VoltAgent 官方配方文档 w人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音CC Switch 本地路由实战让 Codex 通过 Anthropic Messages 上游运行 Claude 模型CC Switch 本地路由实战让 Codex 通过 Anthropic Messages 上游运行 Claude 模型 本文基于 CC Switch 3.1AI 应用开发者工具桌面应用上一篇Hivemind教育资源学习AI代理协作的终极指南与课程推荐下一篇Firefox Profiler完全指南从入门到精通的Firefox性能分析神器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考