Async First 实践

Agently 在运行时层面是 async-first。对普通开发者最重要的结论不是“框架也支持异步”，而是: 只要你已经进入服务端、流式输出或 TriggerFlow 编排场景，就应该把异步接口当成默认实践。

适合什么时候读

你准备把 Agently 接到 FastAPI、Worker、SSE、WebSocket 或其他异步运行环境
你要一边流式消费结果，一边继续做别的工作
你要在 TriggerFlow 中消费模型结果、发信号、推 runtime stream

你会学到什么

为什么 docs 在工程落地阶段推荐 Async First
什么场景仍然可以用同步写法，什么场景应该默认异步
为什么 get_async_generator(type="instant") + TriggerFlow 是高价值组合

Async First 的判断图

这张图想说明: 同步接口不是错误, 但它们更适合最小 demo 和一次性脚本。真正落地到系统时, Async First 才是推荐路径。

为什么推荐 Async First

更适合 Web 服务和并发请求
避免同步桥接层阻塞事件循环
更自然地把模型流、业务事件和 TriggerFlow runtime stream 串起来
在一个请求还没结束时，就能把已完成字段推给 UI 或下游 handler

不要把这个理解成“单次请求必然更快”。Async First 的主要收益是:

更好的并发与吞吐
更好的服务端集成质量
更自然的渐进式交互

最值得优先掌握的组合

这是当前最值得强调的组合: async_generator + instant + TriggerFlow。

原因很直接:

instant 给的是结构化节点，不是噪声 token
async_emit(...) 能把这些节点变成受控业务事件
runtime_stream 能把中间态继续推给 UI 或外部消费者

最小示例

python

import asyncio
from agently import Agently

agent = Agently.create_agent()


async def main():
    response = (
        agent
        .input("给我一个标题和两个要点")
        .output(
            {
                "title": (str, "标题"),
                "items": [(str, "要点")],
            }
        )
        .get_response()
    )

    async for item in response.get_async_generator(type="instant"):
        if item.is_complete:
            print(item.path, item.value)

    final_data = await response.async_get_data()
    print(final_data)


asyncio.run(main())

和 TriggerFlow 组合时怎么想

模型请求本身仍然是 Agently request
TriggerFlow 负责决定“什么时候跑、跑完往哪发信号、谁继续处理”
instant 提前暴露结构化字段
async chunk 用这些字段做 async_emit(...) 或 async_put_into_stream(...)

也就是说: TriggerFlow 不替代模型请求, 它只是把异步消费模型结果这件事组织得更清楚。

常见误区

进入 FastAPI 或 TriggerFlow 后，仍然优先写同步 getter 和同步 generator。
有结构化流式需求，却继续只消费 delta 文本。
在 TriggerFlow chunk 里直接对每个局部 token 无限扩散下游任务。

下一步去哪

想看 instant 的字段级流式消费: 看 Instant 结构化流式解析
想看流式事件选择: 看流式返回与事件类型
想看 instant 如何接入 TriggerFlow: 看从 Token 输出到实时信号
想看 runtime stream: 看运行时流与旁路输出

agently-model-response
agently-output-control
agently-triggerflow-model-integration

Async First 实践 ​

适合什么时候读 ​

你会学到什么 ​

Async First 的判断图 ​

推荐规则 ​

为什么推荐 Async First ​

最值得优先掌握的组合 ​

最小示例 ​

和 TriggerFlow 组合时怎么想 ​

常见误区 ​

下一步去哪 ​

Related Skills（可选） ​