Agently 文档

中文

EN

中文

EN

Appearance

结果数据与对象 ​

同一次模型请求往往要被不同层复用: UI 想拿文本，业务层想拿结构化数据，日志和监控还想拿 meta。结果对象就是为了把这些消费统一起来。

适合什么时候读 ​

  • 你已经在使用 get_response()
  • 你想从同一次请求里读取 text、data、meta
  • 你不想为了不同消费方式重复发请求

你会学到什么 ​

  • get_text()、get_data()、get_data_object()、get_meta() 的区别
  • parsed、original、all 这些数据视图分别适合什么场景
  • 为什么推荐统一通过 response.result 消费结果

结果对象怎么组织 ​

这张图要说明的是: 结果读取和流式读取属于同一个结果对象，不应该被当成彼此独立的两套接口。

最小示例 ​

python
from agently import Agently

agent = Agently.create_agent()

response = (
    agent
    .input("Please explain recursion with a short example.")
    .output(
        {
            "definition": (str, "Short definition"),
            "example": (str, "Simple example"),
        }
    )
    .get_response()
)

text = response.result.get_text()
data = response.result.get_data()
data_object = response.result.get_data_object()
meta = response.result.get_meta()

print(text)
print(data)
print(data_object)
print(meta)

get_data() 有哪几种视图 ​

python
parsed = response.result.get_data(type="parsed")
original = response.result.get_data(type="original")
all_data = response.result.get_data(type="all")
  • parsed: 解析后的结构化结果，默认最常用
  • original: provider 原始结果，适合排错或保底分析
  • all: 包含 text、parsed、original、meta 等完整快照

如果你在做线上排错，all 往往最有价值。

get_data_object() 适合什么场景 ​

当你更喜欢类型化对象而不是字典时，可以用:

python
result_obj = response.result.get_data_object()
print(result_obj)

这更适合属性访问、校验和更严格的下游逻辑。

get_meta() 里通常有什么 ​

meta 常见会包含:

  • token usage
  • model 信息
  • finish reason
  • 其他请求级元数据

它适合日志、监控、计费和问题排查，而不是直接拿来驱动业务结果。

关键字段保障仍然可以叠加 ​

python
data = response.result.get_data(
    type="parsed",
    ensure_keys=["definition", "example"],
    max_retries=2,
)

这说明 ensure_keys 并不只属于 start()，你在结果消费阶段仍然可以要求关键字段补齐。

异步版本 ​

如果你在并发场景里工作，可以使用异步版本:

python
text = await response.result.async_get_text()
data = await response.result.async_get_data()
data_object = await response.result.async_get_data_object()
meta = await response.result.async_get_meta()

常见误区 ​

  • 为了拿不同结果视图，多次重新发起相同请求。
  • 需要排错时只保留 parsed data，丢掉 original 和 meta。
  • 把 get_data_object() 当成必选项，实际上很多场景字典已经够用。

下一步去哪 ​

  • agently-model-response
  • agently-output-control