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.

Read the Chinese source 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