Agently 文档

中文

EN

中文

EN

Appearance

导出与版本化 ​

适用版本：4.0.8.1+

在 v4.0.8.1+ 中，Prompt 导出与加载能力由 ConfigurePromptExtension 提供。

如果你使用默认 Agently.create_agent()，该扩展已内置，可直接调用：

  • agent.get_json_prompt()
  • agent.get_yaml_prompt()
  • agent.load_json_prompt(...)
  • agent.load_yaml_prompt(...)

1. 为什么导出 Prompt ​

工程化场景里，导出快照通常用于：

  • 回放某次线上行为（审计）
  • 将 Prompt 交给配置中心管理（版本化）
  • 在多环境（dev/staging/prod）做差异对比

2. 导出分层快照（推荐） ​

python
json_snapshot = agent.get_json_prompt()
yaml_snapshot = agent.get_yaml_prompt()

print(json_snapshot)

导出结构包含两层：

  • .agent：Agent 级长期提示
  • .request：当前请求级提示

这比“纯文本拼接”更适合版本管理与回放。

3. 落盘保存与版本标记 ​

python
from datetime import datetime

snapshot = agent.get_yaml_prompt()
file_name = f"prompt_snapshot_{datetime.now().strftime('%Y%m%d_%H%M%S')}.yaml"

with open(file_name, "w", encoding="utf-8") as f:
    f.write(snapshot)

建议配套保存：

  • 模型配置（OpenAICompatible）
  • 关键 settings
  • 业务版本号（app_version）

4. 重新加载（字符串 / 文件） ​

load_yaml_prompt / load_json_prompt 同时支持：

  • 文件路径
  • 原始字符串内容

并支持：

  • encoding
  • prompt_key_path（从大对象中抽取子路径）
  • mappings（变量映射）
python
agent.load_yaml_prompt("./prompts/customer_support.yaml")

agent.load_json_prompt(
    "./prompt_bundle.json",
    prompt_key_path="scenes.refund",
    mappings={"brand_name": "AgentEra"},
)

5. 推荐流程：代码生成 -> 配置固化 -> 配置回灌 ​

  1. 在开发阶段用代码构建 Prompt
  2. 导出 YAML/JSON 快照并进入版本库
  3. 在运行时按场景加载配置并注入映射变量

这样能把“策略迭代”从代码发布中解耦。

6. 常见问题 ​

6.1 为什么没有 prompt.to_yaml_prompt(...) ​

这是旧接口习惯。v4.0.8.1+ 推荐用 agent.get_yaml_prompt()/get_json_prompt()。

6.2 如何只加载大 JSON 中某一段 ​

使用 prompt_key_path，例如：prompt_key_path="flows.refund"。

6.3 加载后没生效 ​

检查：

  • 是否加载到了正确 key path
  • 是否有 mappings 变量未替换
  • 是否被后续 agent.input()/agent.system() 覆盖