Agently 文档

中文

EN

中文

EN

Appearance

变量映射与模板化 ​

变量映射解决的不是“怎么替换字符串”，而是“怎么让同一套 Prompt 模板在不同数据场景里稳定复用”。

适合什么时候读 ​

  • 你的 Prompt 里开始出现产品名、用户名、工单信息这类动态字段
  • 你想把模板和业务数据解耦
  • 你已经在用 YAML Prompt，准备做跨场景复用

你会学到什么 ​

  • 占位符应该怎么写
  • mappings 可以在加载模板和直接写 Prompt 时怎么用
  • 什么时候该做模板化，什么时候直接写死更简单

变量映射的最小心智模型 ​

这张图强调的重点是: 模板和数据应该分开管理，替换发生在装配阶段，而不是把变量值直接写死到模板里。

最小示例 ​

yaml
.request:
  input: 请为 ${product_name} 写一句定位。
  instruct: 语气风格: ${tone}
python
from agently import Agently

agent = Agently.create_agent()

agent.load_yaml_prompt(
    "prompts/positioning.yaml",
    mappings={
        "product_name": "Agently",
        "tone": "专业、克制",
    },
)

print(agent.start())

在代码里直接用 mappings ​

如果你暂时还不想把模板抽成文件，也可以直接在代码里写:

python
agent.set_request_prompt(
    "input",
    "请为 ${product_name} 写一句定位。",
    mappings={"product_name": "Agently"},
)

这样依然保留了“模板和数据分离”的好处。

什么时候模板化最有价值 ​

  • 数据来自数据库、API、表单或日志
  • 同一类任务会在多个产品、多个团队或多个租户之间复用
  • 你希望业务文案和代码发布节奏解耦

如果只是一次性脚本里的固定任务，先别把事情复杂化。

常见误区 ​

  • 占位符很多，但没有定义清晰的数据来源。
  • 模板里混入太多业务分支逻辑，导致读不懂也难维护。
  • 文件模板里已经做了变量映射，代码里又手工拼一遍字符串。

下一步去哪 ​

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