ensure_keys 关键字段保障

ensure_keys 用来解决一个很具体的问题：结构已经定义了，但关键字段偶尔缺失，导致下游不敢直接用。

适合什么时候读

• 你已经会用 output()
• 你遇到过字段偶发缺失
• 你希望“尽量稳定返回可用结果”，而不是每次都自己补救

你会学到什么

• ensure_keys 应该保哪些字段
• 路径写法、重试次数和失败策略如何选择
• 什么情况适合配合输出顺序一起设计

最小示例

from agently import Agently

agent = Agently.create_agent()

result = (
    agent
    .input("解释递归，并给出练习题")
    .output(
        {
            "解释": (str, "概念解释"),
            "练习题": [
                {
                    "题目": (str, "练习题问题"),
                    "答案": (str, "参考答案"),
                }
            ],
        }
    )
    .start(
        ensure_keys=["练习题[*].题目", "练习题[*].答案"],
    )
)

路径是怎么定位字段的

这张图放在正文里，是为了说明：ensure_keys 盯的是结构路径，而不是自然语言里的“看起来像有提到”。

路径风格

默认使用 dot，也可以显式指定：

.start(
    ensure_keys=["练习题[*].题目", "练习题[*].答案"],
    key_style="dot",
)

重试与失败策略

.start(
    ensure_keys=["练习题[*].题目", "练习题[*].答案"],
    max_retries=2,
    raise_ensure_failure=False,
)

推荐经验：

• 真正驱动下游流程的字段才列进 ensure_keys
• max_retries 一般控制在 1~3
• 如果业务允许“尽量返回”，可设 raise_ensure_failure=False

常见误区

• 把所有字段都塞进 ensure_keys，导致重试成本过高。
• 结构本身没设计好，就希望 ensure_keys 解决全部稳定性问题。
• 忽略字段顺序，导致后置字段依赖前置字段时仍不稳定。

下一步去哪

• 想让字段顺序更合理：看 输出顺序与依赖控制
• 想回到总览：看 输出控制概览

Related Skills（可选）

• agently-output-control