Agently 文档

中文

English

中文

English

Appearance

观测概览 ​

模型应用上线后，团队通常想看三类信息：模型请求有没有发出去，流程跑到哪一步了，用户界面能不能实时看到进度。Agently 把这三类信息分在不同通道里，避免业务控制流和观测日志混在一起。

四条通道先分清 ​

通道解决什么问题不做什么
Event Center / RuntimeEvent记录框架运行事实：模型请求、Action、Session、TriggerFlow lifecycle不改变业务流程走向
TriggerFlow emit / when改变一次 execution 内的控制流不给外部 UI 当日志流
TriggerFlow runtime stream把 chunk 推出的进度或增量交给 UI / SSE / wrapper不决定 flow 图怎么走
Product eventWeb UI、IM、通知和业务操作台消费的稳定进度事件不直接等同于 RuntimeEvent 或 parser path
DevTools消费观测事件，提供本地可视化、评估和交互 wrapper不替代 flow definition 或 execution state

一个客服工单服务里，可能同时用到这些通道：

  • 分类模型请求发出和返回，进入 Event Center。
  • 分类完成后 emit("Classified")，触发后续审批分支。
  • 生成回复时 async_put_into_stream(...)，SSE 把增量推给前端。
  • service 层把 stream item 映射成 ticket_created、waiting_for_approval 这类产品事件。
  • 本地调试时 DevTools 展示这次 execution 的观察记录。

进入生产治理时，再补两类证据：固定场景 eval 和发布前回归。它们不属于 runtime stream，也不应该塞进业务控制流；更适合由 DevTools EvaluationBridge、应用测试或模型 judge 统一管理。

什么时候看 Event Center ​

Event Center 是框架级运行时事件通道。它适合接日志、指标、审计、DevTools bridge：

python
from agently import Agently

events = []


async def capture(event):
    events.append(event)


Agently.event_center.register_hook(
    capture,
    event_types=["model.request.started", "action.completed"],
    hook_name="ops.capture",
)

hook 观察发生了什么，不应该在里面决定业务下一步。业务分支仍然写在 Agent、Action 或 TriggerFlow 里。

什么时候看 TriggerFlow stream ​

UI 要实时进度时，用 TriggerFlow runtime stream：

python
async def draft_reply(data):
    await data.async_put_into_stream({"type": "status", "text": "开始生成"})
    await data.async_put_into_stream({"type": "delta", "text": "您好，"})
    await data.async_set_state("reply", "您好，我们已经收到您的问题。")


execution = flow.create_execution(auto_close=False)
await execution.async_start(input_data)

async for item in execution.get_async_runtime_stream(timeout=None):
    send_to_client(item)

stream item 是产品界面能消费的 live data。Event Center 事件则更适合运维和诊断。

如果产品界面、IM 网关或通知系统需要长期协议，不建议直接暴露 parser path、内部 chunk 名或 RuntimeEvent。先在 service / workflow 层映射成稳定产品事件，并带上 task_id、execution_id、stage、status、artifact_ref 等字段。见 交互层与主动任务 Playbook。

什么时候打开 DevTools ​

DevTools 适合开发和排错：

  • 看一次 Agent / TriggerFlow 运行的观察记录。
  • 把场景绑定成 evaluation case，反复跑。
  • 用 InteractiveWrapper 给一个 Agent 或 TriggerFlow 做本地交互入口。

它是可选 companion package。生产服务可以只接 Event Center hook 和 runtime stream，不一定部署 DevTools UI。

选择表 ​

想做的事读
把模型请求、Action 调用、TriggerFlow 生命周期写进日志Event Center
让 flow 内一个信号触发另一个 chunkTriggerFlow 事件与流
把生成进度推给前端TriggerFlow 事件与流
设计产品过程事件、IM 回推或主动任务交互层与主动任务 Playbook
本地查看运行过程、做评估、包一层交互 UIDevTools
给 coding agent 提供当前框架用法指引Coding Agents
上线前组织 eval、trace、成本和安全检查生产治理 Playbook

另见 ​