DevTools

语言：English · 中文

agently-devtools 是可选的 companion package（配套包）。它消费 Agently 的 observation event（观测事件），提供本地观测、评估和交互式 UI。它不是 workflow 结构的事实来源；TriggerFlow definition（定义）和 execution（执行实例）仍然是事实来源。

安装与 listener

pip install -U agently agently-devtools
agently-devtools start

默认本地端点来自 examples/devtools/README.md：

接口	默认值
DevTools console	`http://127.0.0.1:15596/`
Observation ingest	`http://127.0.0.1:15596/observation/ingest`
Interactive wrapper UI	`http://127.0.0.1:15365/`

ObservationBridge

对应示例是 examples/devtools/01_observation_bridge_local.py。它通过 Agently 的 LazyImport helper 创建 bridge，监听全局 runtime，运行一个 TriggerFlow，然后注销：

from agently import Agently

bridge = Agently.create_observation_bridge(
    app_id="agently-main-examples",
    group_id="devtools-local-demo",
)
bridge.watch(Agently)

try:
    ...
finally:
    bridge.unregister()

只想上传指定对象时，用 Agently.create_observation_bridge(target, ...) 或 bridge.watch(target)；见 02_observation_bridge_selective_watch.py。bridge.watch(...) 支持全局 Agently 对象、agent、model request/response、TriggerFlow、TriggerFlow execution、Dynamic Task / TaskDAG selector、Skill execution、tool function，或 {"target_type": ..., "target_name": ...} mapping。

如果需要一个把 agently_devtools import 保持在 Agently LazyImport facade 后面的最小示例，见 07_agently_observe_lazy_bridge.py。

也可以直接使用 DevTools 包的构造期绑定：

from agently import Agently
from agently_devtools import ObservationBridge

bridge = ObservationBridge(Agently)
bridge.watch(agent)

旧的 bridge = ObservationBridge(...); bridge.register(Agently) 写法继续兼容，但会发出废弃提示。

ObservationBridge 会通过后台队列上传，并在发送到 listener 前合并 model.streaming 这类高频 observation event，避免被动观测进入请求/输出的同步路径。短脚本如果在运行结束后马上退出，而你需要确保缓冲事件全部上传，可以在退出前调用 await bridge.flush()。

EvaluationBridge

03_scenario_evaluations.py 会构建一个小 TriggerFlow，用 EvaluationBinding 绑定，再通过 EvaluationRunner 跑多个 EvaluationCase。它适合可重复的场景检查，不适合当作应用请求内的实时校验。

InteractiveWrapper

InteractiveWrapper 可以包：

普通 callable 或 generator：04_interactive_wrapper_basic.py
Agently Agent：05_interactive_wrapper_agent.py
会 stream 阶段更新的 TriggerFlow：06_interactive_wrapper_trigger_flow.py

TriggerFlow 场景下，用 data.async_put_into_stream(...) 推进度；wrapper 消费 runtime stream，最后展示 close snapshot。

兼容边界

DevTools 消费端应 fail open（宽容失败）：

忽略未知 observation event type 和未知 payload 字段
关联运行链路时优先使用 run 字段，不要解析 message
TriggerFlow 图应从 flow definition 和 runtime metadata 派生，不维护第二份手写图

发布管理上，包版本只能解决一部分问题。未发布分支之间的协作应以 Agently 在 agently/compatibility.py 中声明的 runtime protocol 为第一判断依据，包版本范围只作为升级建议。已发布历史版本的分版本 manifest 位于 Agently 主仓库的 compatibility/releases/<framework_version>.json。对于已经发布、但早于这套 manifest 机制的 4.1.0.2 到 4.1.1，DevTools 可以回退到内置的 legacy protocol 映射；超出这段历史窗口，如果仍然没有 manifest，就应视为“兼容性未被验证”，而不是默认兼容。

observation event schema 和 TriggerFlow 事件别名规则见 Event Center。