Agently 文档

中文

EN

中文

EN

Appearance

Agently Output Format 语法 ​

Output Format 的作用不是把文本包一层 JSON 外壳，而是把“系统真正需要什么结果”提前定义清楚。

适合什么时候读 ​

  • 你已经能得到模型回答，但字段不稳定
  • 你要把结果交给程序、UI 或下游流程消费
  • 你准备开始用 ensure_keys 或结构化流式输出

你会学到什么 ​

  • output() 如何定义结构化输出契约
  • 标量、列表、对象这些常见结构怎么写
  • 为什么字段说明不是注释，而是约束的一部分

输出契约是怎么工作的 ​

这张图想说明: output() 不只是最终解析格式，它同时影响生成过程和后续消费方式。

最小示例 ​

python
from agently import Agently

agent = Agently.create_agent()

response = (
    agent
    .input("解释递归，并给出两个练习题")
    .output(
        {
            "解释": (str, "概念解释"),
            "示例代码": [(str, "示例代码")],
            "练习题": [
                {
                    "题目": (str, "练习题问题"),
                    "答案": (str, "参考答案"),
                }
            ],
        }
    )
    .get_response()
)

print(response.result.get_data())

常见结构写法 ​

  • 标量: (str, "说明")、(int, "说明")、(bool, "说明")
  • 标量列表: [(str, "说明")]
  • 对象列表: [{ "key": (str, "说明") }]
  • 嵌套对象: { "key": { "sub_key": (str, "说明") } }

结构越明确，模型越容易对齐你的目标。

字段说明怎么写才有用 ​

描述语句不是给人看的注释，而是给模型看的约束。不要只写“说明”，要写“你真正想拿到什么”。

对比一下:

  • 弱描述: "结果": (str, "说明")
  • 强描述: "结果": (str, "一句话结论，不要超过 20 个字")

一个实用判断标准 ​

如果你把这个字段交给另一个开发者，他无法仅凭字段名知道该填什么，那就说明字段描述还不够清楚。

常见误区 ​

  • 结构已经是列表，却仍然让模型输出一大段混合文本。
  • 字段名很清楚，但字段描述几乎没有约束力。
  • 还没定义输出结构，就急着做 streaming UI 或手写 parser。

下一步去哪 ​

相关案例 ​

  • agently-output-control