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

DevTools ​

agently-devtools 是可选 companion package。它消费 Agently 的观测事件，提供本地运行可视化、场景评估和交互式 wrapper。它帮助开发和排错，但不替代应用自己的业务状态、TriggerFlow definition 或 execution snapshot。

安装与启动 ​

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

默认本地端点：

用途默认地址
DevTools consolehttp://127.0.0.1:15596/
Observation ingesthttp://127.0.0.1:15596/observation/ingest
Interactive wrapper UIhttp://127.0.0.1:15365/

如果服务部署在远端，把 ingest endpoint 配到自己的环境变量或配置层里，避免在代码中写死本地地址。

ObservationBridge：把运行事件送进 DevTools ​

最小形态：

python
from agently import Agently

bridge = Agently.create_observation_bridge(
    app_id="support-agent",
    group_id="local-debug",
)
bridge.watch(Agently)

try:
    # run agent / TriggerFlow / Dynamic Task here
    ...
finally:
    bridge.unregister()

bridge.watch(...) 可以监听全局 Agently 对象，也可以监听某个 agent、model request/response、TriggerFlow、TriggerFlow execution、Dynamic Task / TaskDAG selector、Skill execution、tool function，或 {"target_type": ..., "target_name": ...} mapping。

短脚本如果马上退出，而你需要确保缓冲事件都上传，可以在结束前 flush：

python
await bridge.flush()

ObservationBridge 会通过后台队列上传，并合并 model.streaming 这类高频 observation event，避免被动观测拖慢请求和输出。

EvaluationBridge：把场景变成可重复检查 ​

EvaluationBridge 适合稳定场景回归，比如“工单分诊是否给出团队、优先级和理由”。典型用法是：

  • 用 EvaluationBinding 绑定一个 Agent、TriggerFlow 或 callable。
  • 准备多个 EvaluationCase。
  • 用 EvaluationRunner 执行并查看结果。

它适合开发期和发布前检查，不适合把每一次线上请求都塞进实时 evaluation。

选择 eval 样例时，先覆盖正常输入、边界输入、高风险输入和历史回归输入。字段类问题用确定性断言，语义质量用结构化 model judge，人工验收结论也应和输入、输出、运行记录一起保存。

InteractiveWrapper：给本地调试一个界面 ​

InteractiveWrapper 可以包三类对象：

对象适合
普通 callable / generator快速给函数做交互界面
Agently Agent本地试 prompt、输出结构和工具调用
TriggerFlow看 runtime stream、阶段进度和 close snapshot

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

python
async def validate(data):
    await data.async_put_into_stream({"stage": "validate", "ok": True})
    await data.async_set_state("validated", True)


flow.to(validate)

DevTools 和生产观测怎么配合 ​

场景推荐
本地看一次运行到底发生了什么DevTools + ObservationBridge
服务要把进度推给用户TriggerFlow runtime stream
生产日志、指标、审计Event Center hook
发布前做固定场景回归EvaluationBridge

DevTools 不应成为业务事实来源。业务最终结果仍然来自 Agent result、TriggerFlow state、close snapshot 或应用数据库。

兼容边界 ​

DevTools 消费端应该 fail open：

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

发布线兼容以 Agently framework 声明的 runtime protocol 和 compatibility manifest 为准。包版本范围只是升级建议；对于没有 manifest 的历史版本，应视为兼容性未验证，而不是默认兼容。

另见 ​