Prompt 管理

在生产环境中，系统提示词往往需要版本管理与动态下发。VeADK 的 Prompt 管理模块让你在运行时模板化并热更新提示词，而无需修改代码或重启服务。

每次处理用户请求前，VeADK 都会调用 Prompt Manager 的 get_prompt 方法获取最新的提示词内容，并将其作为该 Agent 的系统提示词。

CozeLoop 提示词管理

VeADK 内置 CozeloopPromptManager，可将 Agent 的系统提示词对接到 CozeLoop 云端提示词管理。

准备

安装 Python 版本的 cozeloop SDK：

pip install cozeloop

获取所需属性：

获取 CozeLoop Workspace ID
获取 CozeLoop Token / API Key
在 CozeLoop 的「Prompt 开发」板块获取 Prompt Key，如下图所示：

CozeLoop Prompt Key

使用方法

将凭证通过环境变量提供，避免在代码中硬编码：

export COZELOOP_WORKSPACE_ID="<你的 Workspace ID>"
export COZELOOP_TOKEN="<你的 CozeLoop Token>"

agent.py

import asyncio
import os

from veadk import Agent, Runner
from veadk.prompts.prompt_manager import CozeloopPromptManager

prompt_manager = CozeloopPromptManager(
    cozeloop_workspace_id=os.environ["COZELOOP_WORKSPACE_ID"],
    cozeloop_token=os.environ["COZELOOP_TOKEN"],
    prompt_key="your_prompt_key",  # CozeLoop 中创建的 Prompt Key
    label="production",            # CozeLoop 中创建的 Prompt 标签
)

agent = Agent(name="test_prompt_mgr", prompt_manager=prompt_manager)

runner = Runner(agent=agent)
response = asyncio.run(runner.run(messages="你的任务是什么？"))
print(response)

提示

CozeLoop 会在本地缓存 Prompt，更新间隔为 1 分钟。当获取 Prompt 失败时，会回退到 VeADK 默认的系统提示词。

每次处理用户请求前，CozeloopPromptManager.get_prompt 都会执行，从而拉取最新的 Prompt 模板内容：

CozeLoop Prompt Manager

实现自定义 Prompt Manager

若你想从自有的配置中心、数据库或文件加载提示词，可以继承 BasePromptManager 并实现 get_prompt 方法。该方法在每次处理用户请求前被调用，返回的字符串将作为该 Agent 的系统提示词。

custom_prompt_manager.py

import asyncio

from google.adk.agents.readonly_context import ReadonlyContext
from veadk import Agent, Runner
from veadk.prompts.prompt_manager import BasePromptManager


class FilePromptManager(BasePromptManager):
    """从本地文件读取系统提示词的 Prompt Manager。"""

    def __init__(self, prompt_path: str) -> None:
        super().__init__()
        self.prompt_path = prompt_path

    def get_prompt(self, context: ReadonlyContext, **kwargs) -> str:
        # 每次请求前重新读取文件，实现热更新。
        # context.agent_name 可用于按 Agent 区分提示词。
        with open(self.prompt_path, encoding="utf-8") as f:
            return f.read()


agent = Agent(
    name="custom_prompt_agent",
    prompt_manager=FilePromptManager(prompt_path="instruction.txt"),
)

runner = Runner(agent=agent)
response = asyncio.run(runner.run(messages="你的任务是什么？"))
print(response)

get_prompt 通过 context（ReadonlyContext）获取运行时信息，例如用 context.agent_name 为不同 Agent 返回不同提示词。建议在加载失败时返回一个安全的默认提示词，避免请求中断。

Prompt 管理

CozeLoop 提示词管理

准备

使用方法

实现自定义 Prompt Manager

本页导航