Agently Docs

English

中文

English

中文

Appearance

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 等结果语义更一致。

常见误用 ​

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

下一步 ​