Skip to content

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 调三次模型,只是为了分别拿文本、结构化数据和 metadata。这样不仅浪费成本,还会让三次结果不一致。

Agently 的推荐方式是 result-first:先拿一次 result facade,再从同一次响应里读取不同视图。

推荐消费方式

先拿 get_result(),再从同一次响应里读取需要的视图:

python
result = (
    agent
    .input("抽取工单字段。")
    .output({
        "summary": (str, "一句话摘要", True),
        "priority": (str, "high / medium / low", True),
    })
    .get_result()
)

data = result.get_data()
text = result.get_text()
meta = result.get_meta()

第一次读取会触发模型请求,并缓存结果。后续读取同一个 result 的其他视图,不会重新发请求。

读什么,用哪个方法

需要什么方法适合场景
完整文本get_text()展示、日志、调试、纯文本任务
结构化数据get_data()业务系统保存、分支、校验、表单填充
Pydantic 对象get_data_object().output(...) 使用 BaseModel
metadataget_meta()usage、模型信息、耗时、诊断
token 流get_generator(type="delta")打字机效果、CLI
字段级流get_generator(type="instant")UI 按字段渐进更新

这些方法都有 async 版本:async_get_text()async_get_data()async_get_data_object()async_get_meta()get_async_generator(...)

一个请求,多个读取视图

python
result = (
    agent
    .input("把用户反馈整理成产品团队可以处理的记录。")
    .output({
        "problem": (str, "用户遇到的问题", True),
        "impact": (str, "影响范围", True),
        "suggested_owner": (str, "建议负责团队", True),
    })
    .get_result()
)

record = result.get_data()
raw_text = result.get_text()
meta = result.get_meta()

save_feedback(record)
logger.info({"model_text": raw_text, "meta": meta})

这段代码里,模型只调用一次。record 用于业务保存,raw_text 用于排查,meta 用于成本和运行信息。

流式读取怎么选

delta:看见原始文本增长

python
for delta in agent.input("讲一个递归例子。").get_generator(type="delta"):
    print(delta, end="", flush=True)

如果只是终端或页面里显示“正在生成”,用 delta 就够了。

instant:看见结构化字段增长

python
result = (
    agent
    .input("把事故记录整理成状态卡片。")
    .output({
        "status_summary": (str, "一句话状态", True),
        "risk_flags": [(str, "风险点", True)],
        "next_update": (str, "下一次更新时间", True),
    })
    .get_result()
)

for item in result.get_generator(type="instant"):
    if item.delta:
        print(item.path, item.delta)
    if item.is_complete:
        print(item.path, "done")

final_data = result.get_data()

instant 的 item 通常包含:

  • path:字段路径,比如 risk_flags[0]
  • wildcard_path:数组归一化路径,比如 risk_flags[*]
  • delta:这次新增的文本片段。
  • value:当前字段值。
  • is_complete:这个字段是否已经关闭。

流式事件适合更新 UI。最终保存和业务判断仍然用 get_data()async_get_data()

服务端优先 async

服务、SSE、WebSocket 和 TriggerFlow 场景应使用 async:

python
async def stream_card(ticket_text: str):
    result = (
        agent
        .input(ticket_text)
        .output({
            "status_summary": (str, "状态", True),
            "customer_reply": (str, "客户回复", True),
        })
        .get_result()
    )

    async for item in result.get_async_generator(type="instant"):
        if item.delta:
            yield {"path": item.path, "delta": item.delta}

    final = await result.async_get_data()
    yield {"final": final}

同步 generator 更适合脚本、notebook 和本地调试。

Reasoning 和原始事件

有些 provider 会提供 reasoning 字段,有些 reasoning 模型会把外层 <think>...</think> 放进普通 content。Agently 会在结构化解析前把它归一成 reasoning 事件:

  • reasoning_delta / reasoning_done:推理文本。
  • delta / done:answer payload。
  • original_delta / original_done:provider 原始内容。

如果只是写业务代码,通常不需要直接消费原始事件。调试 provider 行为时,可以看 type="specific"type="original"type="all"

兼容入口

get_response() 作为旧代码兼容别名保留,并返回同一个 result facade。新代码推荐用 get_result(),因为它更准确表达“读取这次执行结果”,也和 AgentExecution / Dynamic Task 等结果语义更一致。

常见误用

  • 为了读 textdatameta 重复调用同一个 prompt。
  • 在流式 UI 里把 instant patch 当最终业务数据保存。
  • 服务端仍然用同步 generator,导致后续 SSE / WebSocket 接入别扭。
  • get_response() 当新项目推荐入口。旧代码可维护,新代码用 get_result()
  • 只读 get_text(),然后自己解析 JSON。需要结构化数据时,用 .output(...).get_result().get_data()

下一步