Agently 文档

中文

EN

中文

EN

Appearance

配置化 Prompt：YAML/JSON ​

当 Prompt 已经不再是“一句临时提示词”，而是需要多人协作、版本管理和频繁迭代的资产时，就应该配置化。

适合什么时候读 ​

  • 你要把 Prompt 从业务代码中拆出来
  • 你希望 Prompt 可以单独审阅、回滚、迭代
  • 你需要变量映射或只加载某一段模板

你会学到什么 ​

  • 为什么 Prompt 配置值得单独放进文件
  • YAML / JSON Prompt 的基本结构
  • load_yaml_prompt()、mappings、prompt_key_path 的典型用法

核心心智模型 ​

这张图强调的是配置文件并不会绕开 Prompt 系统，而是进入同一套 Agent / Request 结构里。

最小示例 ​

先写一份 YAML:

yaml
.agent:
  system: 你是一个严谨的技术文档助手。
  developer: 请遵循 Markdown 输出规范。

.request:
  input: 请解释 {topic}，并给出两个提示。
  output:
    解释:
      $type: str
      $desc: 一句话解释
    提示:
      - $type: str
        $desc: 简短提示

再在代码里加载:

python
from agently import Agently

agent = Agently.create_agent()

agent.load_yaml_prompt(
    "prompts/recursion.yaml",
    mappings={"topic": "递归"},
)

print(agent.start())

只加载某一段 ​

如果你只想复用 .request 或某个子路径，可以用 prompt_key_path:

python
agent.load_yaml_prompt(
    "prompts/recursion.yaml",
    prompt_key_path=".request",
    mappings={"topic": "递归"},
)

这在“公共 Agent 规则 + 场景化 Request 模板”并存的项目里很有用。

$system 这种写法是什么意思 ​

以下写法等价于 .agent 下的对应字段:

yaml
$system: 你是一个严谨的技术文档助手。
$developer: 请遵循 Markdown 输出规范。
input: 请解释 {topic}。

适合小文件，但当模板复杂起来时，显式的 .agent / .request 结构更容易维护。

什么时候该配置化 ​

  • Prompt 需要频繁改文案，但业务代码不该跟着频繁发布
  • 你要让产品、运营或标注同学参与 Prompt 迭代
  • 你要把同一套模板复用到多个场景

如果 Prompt 还是一次性脚本里的几行逻辑，先别急着配置化。

常见误区 ​

  • 把所有业务逻辑都塞进模板，导致代码层和 Prompt 层边界不清。
  • 还没想清楚变量边界，就先做一大堆 mappings。
  • 文件里已经配置了输出契约，代码里又手写一遍，形成双源。

下一步去哪 ​

  • agently-prompt-management
  • agently-prompt-config-files