企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 框架
• 后端
• 多智能体
• RAG
• 工具调用
• Agent 记忆

本文将 VoltAgent 官方文档website/prompt-engineering-docs/usage.md中的提示词使用指南扩展为一份面向落地的技术手册，覆盖 API Key 配置、VoltOpsClient初始化、本地 Prompt 拉取（CLI Pull）、环境标签（Labels）、模板变量（Template Variables）、两级缓存策略、Chat Prompt、错误处理与调试等完整链路，并结合packages/core与packages/cli的源码实现，解释本地优先回退、缓存键生成、TTL 过期与逐请求覆盖等底层机制。

一、整体接入流程

将 VoltOps 提示词集成到 VoltAgent Agent 中，需要完成三步：

1. 在 VoltAgent 控制台注册项目，进入 Settings → Projects，复制项目的 public key（pk_前缀）与 secret key（sk_前缀）；
2. 将密钥写入环境变量；
3. 在代码中初始化VoltOpsClient，并通过 Agent 的instructions动态回调获取提示词。

VOLTAGENT_PUBLIC_KEY=pk_your_public_key_here VOLTAGENT_SECRET_KEY=sk_your_secret_key_here

import { VoltOpsClient } from "@voltagent/core"; const voltOpsClient = new VoltOpsClient({ publicKey: process.env.VOLTAGENT_PUBLIC_KEY, secretKey: process.env.VOLTAGENT_SECRET_KEY, });

从源码结构看，VoltOpsClient的构造器会先校验密钥形态：publicKey必须以pk_开头、secretKey必须以sk_开头且均非空（见 client.ts）。只有校验通过且prompts选项不为false时，才会实例化VoltOpsPromptManagerImpl提示词管理器；否则client.prompts保持为undefined，后续任何getPrompt调用都会抛出 "Prompt management is not enabled in VoltOpsClient" 错误。这意味着密钥配置错误时故障会出现在第一次取词调用上，而不是构造时——调试时应先检查密钥前缀与取值。

客户端还有两个值得注意的默认值（见 client.ts）：

• baseUrl默认为https://api.voltagent.dev，可通过baseUrl选项覆盖；
• promptCache默认配置为{ enabled: true, ttl: 300, maxSize: 100 }，用户传入的部分配置会与默认值合并（浅合并，逐项保留默认值）。

二、基础用法：在动态 instructions 中取词

VoltAgent 的 Agentinstructions支持动态回调形式，回调参数中的prompts是一个PromptHelper（其getPrompt接收PromptReference，见 types.ts）。最简用法：

import { openai } from "@ai-sdk/openai"; import { Agent, VoltAgent, VoltOpsClient } from "@voltagent/core"; const voltOpsClient = new VoltOpsClient({ publicKey: process.env.VOLTAGENT_PUBLIC_KEY, secretKey: process.env.VOLTAGENT_SECRET_KEY, }); const agent = new Agent({ name: "SupportAgent", model: openai("gpt-4o-mini"), instructions: async ({ prompts }) => { return await prompts.getPrompt({ promptName: "customer-support-prompt", }); }, }); new VoltAgent({ agents: { agent }, voltOpsClient: voltOpsClient, });

将voltOpsClient传给VoltAgent是推荐做法：它让框架为所有 Agent 统一提供promptshelper。

客户端挂载方式的两个等价选项

Agent 级 VoltOpsClient：不想依赖顶层VoltAgent配置时，也可以把 client 直接挂在单个 Agent 上：

const agent = new Agent({ name: "SupportAgent", model: openai("gpt-4o-mini"), instructions: async ({ prompts }) => { return await prompts.getPrompt({ promptName: "customer-support-prompt", }); }, voltOpsClient: voltOpsClient, });

直接调用 VoltOpsClient：在非 Agent 场景（脚本、CLI 工具）中可绕过promptshelper 直接访问：

const content = await voltOpsClient.prompts.getPrompt({ promptName: "customer-support-prompt", }); console.log("Prompt content:", content);

注意从源码看，createPromptHelper（client.ts）内部同样是转调this.prompts.getPrompt(reference)，因此三条路径最终都汇聚到同一个VoltOpsPromptManagerImpl.getPrompt实现，缓存与模板处理行为完全一致。

三、本地 Prompts：CLI 拉取与本地优先回退

对于离线开发或高频迭代场景，可以把 VoltOps 上的提示词拉取为本地 Markdown 文件，Agent 运行时优先读本地文件、命中失败再回退到线上 VoltOps。

拉取命令

# 1. 拉取到默认目录 .voltagent/prompts pnpm volt prompts pull # 2. 拉取到自定义目录 pnpm volt prompts pull --out ./.prompts

CLI 输出成功信息时会提示同步设置运行时变量（见 prompts.ts）：

# 3. 让运行时指向同一目录 export VOLTAGENT_PROMPTS_PATH="./.prompts"

第 4 步，Agent 侧代码无需任何改动：

instructions: async ({ prompts }) => { return await prompts.getPrompt({ promptName: "customer-support-prompt" }); };

拉取指定版本或标签

要在本地保留多个版本，可以按版本号或标签定向拉取，文件会存储为.voltagent/prompts/<promptName>/<version>.md：

pnpm volt prompts pull --names support-agent --prompt-version 4 pnpm volt prompts pull --names support-agent --label production

对应的 CLI 参数定义（见 prompts.ts）：

运行时按版本或标签请求：

instructions: async ({ prompts }) => { return await prompts.getPrompt({ promptName: "support-agent", version: 4, }); };

instructions: async ({ prompts }) => { return await prompts.getPrompt({ promptName: "support-agent", label: "production", }); };

本地优先、线上回退的解析机制

官方文档声明 "If a local prompt is found, it is used first. If not, VoltOps is used as the fallback"。这个行为可以从本地提示词加载器中得到印证（见 local-prompts.ts）：

• 目录解析优先级（resolveLocalPromptsPath）：显式传入的basePath> 环境变量VOLTAGENT_PROMPTS_PATH（兼容旧变量VOLTAGENT_PROMPTS_DIR）> 默认目录.voltagent/prompts；目录不存在时返回null，即视为本地不可用，直接走线上；
• 候选文件：<name>.md单文件与<name>/<version>.md目录下所有.md文件都会被收集，且做了路径穿越防护（文件名以..逃逸基目录会直接抛错）；
• 版本选择（selectPromptFile）：指定version时精确匹配 frontmatter 或文件名中的版本号；指定label时匹配 frontmatter 的labels数组，label === "latest"未命中时会回退到全部候选；两者都不传时优先选带latest标签的最高版本，否则选最高版本文件；
• Frontmatter 结构：本地文件使用 gray-matter 解析 YAML frontmatter，支持name、version、labels、tags、type（text/chat）等字段；type: chat的正文必须是一个 JSON 消息数组，与线上返回的 chat 结构一致；
• 失败语义：本地文件存在但找不到匹配的版本/标签时抛出带LOCAL_PROMPT_NOT_FOUND错误码的LocalPromptNotFoundError，上层凭此错误类型区分"本地无此词、需要回退线上"与真正的加载失败。

本地路径下模板变量同样生效——applyTemplateToPrompt会调用与线上一致的简单模板引擎对text或每条 chat 消息内容做变量替换。

四、环境标签（Labels）

标签用于把不同环境的流量指向不同版本的提示词，是最常见的多环境发布手段：

const agent = new Agent({ name: "ProductionAgent", model: openai("gpt-4o-mini"), instructions: async ({ prompts }) => { const label = process.env.NODE_ENV === "production" ? "production" : "development"; return await prompts.getPrompt({ promptName: "customer-support-prompt", label: label, }); }, });

内置标签

此外可以使用自定义标签（如beta、canary、region-eu）实现金丝雀或区域化发布。从本地解析逻辑看（local-prompts.ts），标签匹配基于 frontmatter 中labels数组的精确成员判断；latest享有特殊地位——即使没有文件显式标注latest标签，也会自动回退到所有候选中的最高版本，这解释了为什么"拉了多个版本文件但不带任何标签"时请求latest依然能取到词。

五、模板变量与 Agent Context

variables参数用于把动态值替换进提示词模板：

const agent = new Agent({ name: "DynamicAgent", model: openai("gpt-4o-mini"), instructions: async ({ prompts, context }) => { return await prompts.getPrompt({ promptName: "customer-support-prompt", label: "production", variables: { companyName: "VoltAgent Corp", userName: context.get("userName") || "Guest", tier: context.get("subscriptionTier") || "free", }, }); }, });

context是DynamicValueOptions中的Map<string | symbol, unknown>（见 types.ts），通过agent.generateText的context选项注入：

const userContext = new Map(); userContext.set("userName", "Alice"); userContext.set("subscriptionTier", "premium"); const response = await agent.generateText("I need help", { context: userContext, });

从实现看，模板处理由VoltOpsPromptManagerImpl.processPromptContent完成（prompt-manager.ts）：text类型处理整段文本，chat类型逐条处理消息内容，但仅对字符串内容做替换、复杂 part 数组原样透传；模板引擎处理失败时会静默返回原文并记录 error 日志，不会中断 Agent 运行。另外要注意：模板替换发生在缓存读取之后——缓存存储的是未渲染的原始模板，variables每次请求都会重新代入，因此同一模板配合不同变量不会互相污染缓存。

变量清洗，防止提示注入

用户可控的变量值在代入模板前应做清洗：

instructions: async ({ prompts, context }) => { const sanitizedUserName = context.get("userName")?.replace(/[<>]/g, "")?.substring(0, 50) || "Guest"; return await prompts.getPrompt({ promptName: "personalized-greeting", variables: { userName: sanitizedUserName }, }); };

示例采用"剥离 HTML 尖括号 + 截断长度"的组合，实际项目中应结合白名单、转义与业务边界（如最大长度、允许字符集）一并处理。

六、缓存：全局配置、逐请求覆盖与策略建议

VoltOps 提供两级缓存以降低 API 调用次数。缓存管理器VoltOpsPromptManagerImpl（prompt-manager.ts）基于内存Map实现，核心机制如下：

• 缓存键：getCacheKey生成`${promptName}:${version}`，未指定版本时以latest参与键——因此同名提示词的不同版本互不干扰；
• TTL 过期：条目记录fetchedAt与毫秒化 TTL，读取时超期即删除该条目并重新拉取；
• 容量上限：写入前若cache.size >= maxSize，会按插入顺序逐出最早的条目（evictOldestEntry）；
• 逐请求覆盖：getPrompt内部先合成有效缓存配置——enabled与ttl取请求参数优先、否则用全局值，而maxSize始终是全局值（见 prompt-manager.ts）。

全局缓存配置

const voltOpsClient = new VoltOpsClient({ publicKey: process.env.VOLTAGENT_PUBLIC_KEY, secretKey: process.env.VOLTAGENT_SECRET_KEY, prompts: true, promptCache: { enabled: true, ttl: 300, // 秒，缓存有效期 maxSize: 100, // 最大缓存条目数 }, });

以上三个值恰好与源码默认值一致（enabled: true、ttl: 300秒、maxSize: 100），即不传promptCache时也享有同等缓存行为。

逐 Prompt 缓存覆盖

// 本次取词禁用缓存 return await prompts.getPrompt({ promptName: "customer-support-prompt", promptCache: { enabled: false }, }); // 稳定提示词使用更长 TTL return await prompts.getPrompt({ promptName: "system-instructions", promptCache: { ttl: 3600, enabled: true }, });

PromptReference.promptCache类型中maxSize虽被保留用于签名一致性，但按源码注释它不适用于逐请求场景（types.ts），容量只在客户端级别生效。

清空缓存与缓存统计

voltOpsClient.prompts.clearCache();

此外管理器还提供getCacheStats()返回{ size, entries }（当前缓存条目数与键列表），可用于健康检查或调试面板展示（见 prompt-manager.ts）。

缓存策略建议

// 高频提示词：短 TTL await prompts.getPrompt({ promptName: "chat-greeting", promptCache: { ttl: 60, enabled: true }, }); // 稳定提示词：长 TTL await prompts.getPrompt({ promptName: "system-instructions", promptCache: { ttl: 3600, enabled: true }, }); // 动态提示词：不走缓存 await prompts.getPrompt({ promptName: "personalized-prompt", promptCache: { enabled: false }, variables: { userId: dynamicUserId }, });

启动时预加载

关键提示词可在应用启动阶段并发预取，把网络延迟移出首请求路径：

const criticalPrompts = ["welcome-message", "error-handler", "main-agent"]; await Promise.all(criticalPrompts.map((name) => prompts.getPrompt({ promptName: name })));

preload在实现层同样存在（VoltOpsPromptManagerImpl.preload即对多个引用做Promise.all(getPrompt)），预取结果会写入缓存供后续请求直接命中。

七、Chat Prompt：多消息结构化提示词

Chat 提示词定义带角色结构的多消息对话，适用于需要固定开场白或 few-shot 示例的场景：

const agent = new Agent({ name: "ChatAgent", model: openai("gpt-4o-mini"), instructions: async ({ prompts }) => { return await prompts.getPrompt({ promptName: "chat-support-prompt", variables: { agentRole: "customer support specialist", companyName: "VoltAgent Corp", }, }); }, });

其返回结构与 text 提示词不同（convertApiResponseToPromptContent按response.type区分，见 prompt-manager.ts）：

{ type: "chat", messages: [ { role: "system", content: "You are a customer support specialist." }, { role: "user", content: "Hello, I need help." }, { role: "assistant", content: "Hello! How can I assist you today?" } ] }

所有返回内容都附带metadata（name、version、labels、tags、source，线上来源为online、本地为local-file），可用于运行时日志与灰度审计。本地 chat 文件的正文即消息数组的 JSON 文本，解析逻辑与线上结构对齐（local-prompts.ts）。

八、错误处理与调试

网络失败与提示词缺失的兜底

instructions: async ({ prompts }) => { try { return await prompts.getPrompt({ promptName: "primary-prompt", timeout: 5000, }); } catch (error) { console.error("Prompt fetch failed:", error); return "You are a helpful assistant."; // Fallback } };

常见错误对照

提示词未找到（Prompt 'weather-prompt' not found）：先在控制台核实提示词名是否存在，并始终保留兜底 instructions：

instructions: async ({ prompts }) => { try { return await prompts.getPrompt({ promptName: "weather-prompt" }); } catch (error) { console.error("Prompt fetch failed:", error); return "Fallback instructions"; } };

缺少变量（Variable 'userName' not found in template）：为所有模板变量提供默认值：

return await prompts.getPrompt({ promptName: "greeting-prompt", variables: { userName: context.get("userName") || "Guest", currentTime: new Date().toISOString(), }, });

认证失败（Authentication failed）：验证环境变量是否按pk_/sk_前缀正确配置：

console.log("Public Key:", process.env.VOLTAGENT_PUBLIC_KEY?.substring(0, 8) + "..."); console.log("Secret Key:", process.env.VOLTAGENT_SECRET_KEY ? "Set" : "Missing");

结合前述构造器校验逻辑可知，前缀不合法时 prompt 管理器根本不会被初始化，报错会表现为 "Prompt management is not enabled"，因此前缀检查是第一排查点。

缓存过期（更新后仍在用旧版本）：三种处理手段按侵入性递增——

// 方案 1：主动清空缓存 voltOpsClient.prompts.clearCache(); // 方案 2：本次取词临时禁用缓存 return await prompts.getPrompt({ promptName: "urgent-prompt", promptCache: { enabled: false }, }); // 方案 3：等待 TTL 自然过期

独立调试取词

脱离 Agent 单独验证取词链路，能快速区分"网络/认证问题"与"Agent 配置问题"：

const voltOpsClient = new VoltOpsClient({ publicKey: process.env.VOLTAGENT_PUBLIC_KEY, secretKey: process.env.VOLTAGENT_SECRET_KEY, }); try { const prompt = await voltOpsClient.prompts.getPrompt({ promptName: "test-prompt", }); console.log("Success:", prompt); } catch (error) { console.error("Failed:", error); }

九、完整示例

将标签、变量、缓存与错误兜底组合起来的生产级写法：

import { openai } from "@ai-sdk/openai"; import { Agent, VoltAgent, VoltOpsClient } from "@voltagent/core"; const voltOpsClient = new VoltOpsClient({ publicKey: process.env.VOLTAGENT_PUBLIC_KEY, secretKey: process.env.VOLTAGENT_SECRET_KEY, prompts: true, promptCache: { enabled: true, ttl: 300, }, }); const supportAgent = new Agent({ name: "SupportAgent", model: openai("gpt-4o-mini"), instructions: async ({ prompts, context }) => { const environment = process.env.NODE_ENV === "production" ? "production" : "development"; try { return await prompts.getPrompt({ promptName: "customer-support-agent", label: environment, variables: { companyName: "VoltAgent Corp", userName: context.get("userName") || "Guest", tier: context.get("subscriptionTier") || "free", supportHours: "9 AM - 6 PM EST", }, }); } catch (error) { console.error("Failed to fetch prompt:", error); return "You are a helpful customer support agent. Assist users with their questions."; } }, }); new VoltAgent({ agents: { supportAgent }, voltOpsClient: voltOpsClient, });

十、API 参考速查

getPrompt 选项（PromptReference）

PromptCache 选项

相关仓库资源

小结

VoltAgent 的提示词体系围绕"线上 VoltOps + 本地 Markdown 双源"设计：prompts.getPrompt在动态 instructions 回调中统一取词，本地文件优先、线上回退；标签与版本号支持多环境灰度发布；模板变量与 context 打通实现个性化渲染且与缓存解耦；内存缓存支持全局 TTL/maxSize 配置与逐请求覆盖，并可通过clearCache与getCacheStats运维。配套的pnpm volt prompts pull让离线开发与快速迭代成为可能。遵循本文的缓存策略表与错误兜底模板，可以把提示词管理从"写死在代码里"升级为可版本化、可灰度、可观测的工程能力。

• 人工智能
• AI Agent
• Agent 框架
• 后端
• 多智能体
• RAG
• 工具调用
• Agent 记忆