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。

AgentTask action observation

AgentTask 可能会从 bounded execution 的 Action logs 投影 agent_task.action.started、agent_task.action.completed 和 agent_task.action.failed RuntimeEvent。DevTools 应把它们作为 AgentTask timeline 里的事实型 action observation 消费；当事件带有 iteration 元数据时，按任务轮次归组展示。

已恢复的 success 和 partial_success 记录应展示为 completed observation，即使它们携带 backend diagnostics。failed observation 只保留给失败、blocked、timeout 或未恢复 error 记录。

这些记录只用于展示、日志和运行后分析。不要把它们当作 route 决策、verifier 结果、质量评分、语义相关性判断或任务完成验收依据。未知字段应宽容忽略，大 payload 应保持摘要化或 ref-backed。

Model request usage

DevTools 应优先从 payload.model_request_telemetry.usage_summary 消费 model request usage；兼容情况下可回退到 model meta 或终态事件里的 provider usage 元数据。展示范围分两层：单次 model request，以及当前选中 run 分支向下聚合的 descendant model requests。

当 provider token 计数不可得时，token 字段展示为未知，例如 NaN，同时把输入/输出字符长度估算作为诊断信息展示。Usage telemetry 只属于 observation，不应成为框架预算卡控、retry 规则、route 决策、质量评分、verifier 结果或任务完成验收依据。

兼容边界

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。