From 34b0ab939f07cc4ed5e986a231d38027eb8d88c2 Mon Sep 17 00:00:00 2001 From: "fangyaozheng@bytedance.com" Date: Tue, 16 Dec 2025 23:03:45 +0800 Subject: [PATCH 1/3] feat: support cozeloop prompt manager --- docs/docs/agent/prompt.md | 49 +++++++++++++ .../images/agents/cozeloop_prompt_mgr.png | Bin 0 -> 237554 bytes docs/docs/optimization.md | 17 +++-- docs/mkdocs.yml | 1 + veadk/agent.py | 23 +++++-- veadk/prompts/prompt_manager.py | 65 ++++++++++++++++++ 6 files changed, 144 insertions(+), 11 deletions(-) create mode 100644 docs/docs/agent/prompt.md create mode 100644 docs/docs/assets/images/agents/cozeloop_prompt_mgr.png create mode 100644 veadk/prompts/prompt_manager.py diff --git a/docs/docs/agent/prompt.md b/docs/docs/agent/prompt.md new file mode 100644 index 00000000..ab7df0f5 --- /dev/null +++ b/docs/docs/agent/prompt.md @@ -0,0 +1,49 @@ +# Prompt 管理 + +在实际生产过程中,Prompt 需要进行版本管理与动态下发,VeADK 提供了 Prompt 管理模块,用户可以通过 Prompt 管理功能来进行 Prompt 的模板化与热更新,在运行时动态切换 Prompt 版本。 + +## CozeLoop 提示词管理 + +在使用 CozeLoop 进行提示词管理前,您需要安装 Python 版本的 `cozeloop` SDK: + +```bash +pip install cozeloop +``` + +您可以通过 CozeLoop 云端提示词管理功能来对接您的 Agent 系统提示词。例如: + +```python title="agent.py" linenums="1" hl_lines="4 6-11 13" +import asyncio + +from veadk import Agent, Runner +from veadk.prompts.prompt_manager import CozeloopPromptManager + +prompt_manager = CozeloopPromptManager( + cozeloop_workspace_id="", # CozeLoop workspace ID + cozeloop_token="", # CozeLoop token + prompt_key="main_agent", # 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) +``` + +!!! note "提示" + CozeLoop 会在本地进行 Prompt 缓存,**更新时间为 1 分钟**。当获取 Prompt 失败时,会返回 VeADK 默认的 Agent 系统提示词。 + +您可以在日志中看到,每次处理用户请求之前,都会执行 `CozeloopPromptManager` 中的 `get_prompt` 方法,来获取最新的 Prompt 模板内容。效果如下: + +![img](../assets/images/agents/cozeloop_prompt_mgr.png) + +更加详细的说明,请参考 [CozeLoop 提示词管理](https://loop.coze.cn/open/docs/cozeloop/what-is-prompt)。 + +## 实现您自己的 Prompt Manager + +若您想实现更高阶的 Prompt 模板或变量组合,您可以继承 `PromptManager` 类,实现自定义的 Prompt 管理逻辑。 + +在实现自定义 Prompt Manager 时,您需要实现 `get_prompt` 方法,该方法会在每次处理用户请求之前被调用,用于获取最新的 Prompt 模板内容。 diff --git a/docs/docs/assets/images/agents/cozeloop_prompt_mgr.png b/docs/docs/assets/images/agents/cozeloop_prompt_mgr.png new file mode 100644 index 0000000000000000000000000000000000000000..552d00251da70f250f7ae8409b05df8ef9166ffc GIT binary patch literal 237554 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