English mirror
This English page is generated from the current Chinese documentation so every route, anchor, code sample, and language switch stays available on agently.tech. Human-edited English copy can replace this generated body page by page.
Prompt 管理
Prompt 不应该是一整段越写越长的字符串。项目稍微复杂一点,就会遇到几个问题:固定规则和本次输入混在一起,背景事实难以 diff,输出结构藏在自然语言里,团队 review 只能看 Python 代码。
Agently 把 prompt 拆成命名槽位。槽位可以在 agent 级长期生效,也可以只在一次 execution 里生效。
常用槽位
| 槽位 | 放什么 | 生命周期 |
|---|---|---|
role / system | 角色、能力边界、硬性规则 | 通常 agent 持久 |
info | 背景事实、枚举、产品资料、检索片段 | 持久或单次 |
instruct | 任务步骤、回答风格、处理规则 | 持久或单次 |
input | 本次调用的实际 payload | 单次 |
output | 期望返回结构 | 单次或 prompt 文件 |
固定不变的内容不要每次写进 input。每次变化的 payload 也不要放进 info(always=True)。
Agent 级和 execution 级
Agent 级内容每次请求都带:
agent = (
Agently.create_agent()
.role("你是 Agently 客服助手。", always=True)
.info({"product": "Agently 4.x"}, always=True)
)单次 execution 内容只影响本轮:
result = (
agent
.instruct(["回复不超过 80 字。", "不要编造产品名。"])
.input("怎么配置一个模型?")
.output({"answer": (str, "answer", True)})
.get_result()
)不传 always=True 时,槽位只属于当前 execution draft。
配置文件写法
Prompt 文件适合团队 review。YAML 示例:
$ensure_all_keys: true
.agent:
system: 你是一个工单分流助手。
info:
severities: ["P0", "P1", "P2", "P3"]
.execution:
instruct: 对工单文本分类。
output:
$format: json
severity:
$type: str
$desc: P0/P1/P2/P3 之一
$ensure: true
rationale:
$type: str
$desc: 一行说明原因
$ensure: true加载:
agent = Agently.create_agent().load_yaml_prompt("prompts/triage.yaml")
result = (
agent
.create_execution()
.set_execution_prompt("input", "EU 区域所有用户登录失败。")
.get_result()
)load_json_prompt(...) 是 JSON 版本。两者都接受文件路径或原始字符串。大文件里有多个 prompt 时,可以用 prompt_key_path="demo.output_control" 选择其中一份。
.execution 表示单次 execution。旧 prompt 文件里的 .turn 和 .request 继续作为兼容 alias。
Output 也属于 prompt
output 不只是 parser 配置。它会被渲染给模型,也会用于解析和校验:
output:
summary:
$type: str
$desc: 一句话摘要
$ensure: true顶层 $ensure_all_keys: true 会让所有叶子都必填。output 块里的 $format 对应 .output(..., format=...),支持 auto、json、flat_markdown、hybrid、xml_field、yaml_literal。
继续读:Schema as Prompt、输出控制
看模型实际收到什么
写 prompt 文件时,最好定期看渲染结果:
print(agent.get_yaml_prompt())
print(agent.get_json_prompt())
print(agent.get_prompt_text())get_prompt_text() 能帮助确认“我以为我发给模型的内容”和“框架实际渲染的内容”是否一致。
占位符
prompt 中有两类常见引用:
{name}:引用另一个槽位的 key。${name}:加载时由mappings={"name": "value"}替换。
agent.load_yaml_prompt(
yaml_text,
mappings={"product_name": "Agently"},
)注意:settings 层的 ${ENV.OPENAI_API_KEY} 是环境变量替换,不是 prompt mappings。
${INPUT.customer}、${INFO.policy}、${INSTRUCT.step} 是渲染时的 slot 引用,会变成 prompt 段落指针,不是把另一个 slot 的值复制进来。${OUTPUT} 是 [OUTPUT REQUIREMENT] 的别名。
常见误用
- 把所有内容拼成一个长字符串。
- 固定背景和本次 payload 都塞进
input。 - 每次请求都重复写相同 role / info。
- 不看
get_prompt_text(),只凭代码猜模型看到什么。 - 把
${ENV.*}当 prompt mapping 使用。它属于 settings。 - 在 prompt 文件里继续使用
$default。当前推荐写法不支持它。
下一步
- 结构化输出写法:Schema as Prompt
- 输出校验和 retry:输出控制
- 项目目录:项目结构
- 上下文放哪里:Context Engineering