Agently 文档

中文

English

中文

English

Appearance

Event Center ​

Event Center 是 Agently 的框架级运行时事件通道。模型请求、Session 应用、Action 调用、Execution Environment、TriggerFlow lifecycle 等运行事实，都会以 RuntimeEvent 的形态交给 hook、日志 sink 或 DevTools bridge。

它和 TriggerFlow 的 emit / when 分工不同：emit 会改变一个 flow execution 内的下一步走向；RuntimeEvent 只是记录发生了什么。

注册一个 hook ​

python
from agently import Agently

captured = []


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


Agently.event_center.register_hook(
    capture,
    event_types="runtime.info",
    hook_name="docs.capture",
)

emitter = Agently.event_center.create_emitter("Docs")
await emitter.async_info("hello")

Agently.event_center.unregister_hook("docs.capture")

event_types 可以是字符串、字符串列表或 None。传 None 时，hook 接收所有事件。同步函数也能注册；Event Center 会统一转成 async 调用。

自定义应用事件 ​

应用和插件可以用自己的命名空间发送事件：

python
emitter = Agently.event_center.create_emitter(
    "BillingWorker",
    base_meta={"tenant": "demo"},
)

await emitter.async_emit(
    "billing.invoice_created",
    message="invoice created",
    payload={"invoice_id": "inv-1"},
)

Agently 官方事件使用 model.*、request.*、action.*、tool.*、session.*、agent_turn.*、triggerflow.*、execution_environment.* 等 namespace。自定义事件不要伪装成官方事件，也不要指望 Agently core 消费它们。

高频事件用摘要投递 ​

模型流式增量这类事件频率很高。如果 hook 要把它们转发到远端日志或指标系统，可以给这个 hook 配摘要投递：

python
Agently.event_center.register_hook(
    capture,
    event_types="model.response.delta",
    hook_name="docs.summary_capture",
    delivery_policy={
        "mode": "summary",
        "dispatch": "await",
        "emit_interval": 0.1,
        "max_items": 20,
        "high_frequency_only": True,
    },
)

摘要投递只影响当前 hook，不改变生产者发出的 RuntimeEvent，也不影响其他要求 raw 事件的 hook。摘要事件会带 meta["coalesced"]、coalesced_count、first_event_id 和 last_event_id。

只有出口有明确 flush / close 回收点时，再考虑 dispatch="background"。短脚本或 CLI 结束前，可以调用：

python
await Agently.event_center.async_flush(hook_name)

这样可以排空摘要 buffer 和已跟踪的后台投递。

RuntimeEvent 结构 ​

RuntimeEvent 的顶层字段来自 agently.types.data.event.RuntimeEvent。DevTools bridge 会把它投影成 ObservationEvent，序列化结构保持一致。

字段含义
event_id事件 id，默认自动生成
event_type点路径，如 triggerflow.execution_started
source事件来源
levelDEBUG / INFO / WARNING / ERROR / CRITICAL
message人可读消息
payload结构化数据
error错误信息；异常会规范化为 ErrorInfo
runrun lineage，包括 run_id、parent_run_id、session_id、execution_id
meta附加元数据
timestamp毫秒时间戳

消费端关联请求、Session 或 TriggerFlow execution 时，优先读 run。不要从 message 文本里解析 id。

run 和 attempt 不要混 ​

agent_turn 表示一次 Agent 面向用户或调用方的回合。attempt_index 表示同一次模型请求内部的重试序号。DevTools 或日志系统展示时，要把这两件事分开：

  • 从 run.run_kind 渲染 agent_turn。
  • 从 model_request 事件的 payload.attempt_index 或 run.meta.attempt_index 读取模型重试 attempt。

这样排查问题时，才能看清是“用户发起了下一轮”，还是“同一轮里模型请求重试了一次”。

兼容事件 ​

新代码使用 RuntimeEvent。ObservationEvent 是 DevTools bridge 的通讯投影。emit_observation / async_emit_observation 继续作为兼容 alias 可用。

TriggerFlow 历史事件前缀也保留别名：订阅 workflow.execution_started 可以收到 triggerflow.execution_started，订阅 trigger_flow.signal 可以收到 triggerflow.signal。新文档和新代码写 triggerflow.*。

Action Runtime 使用 action.* 作为主 namespace。兼容旧 tools 时，会额外发配对的 tool.* 事件，并带上 meta.compat_event_alias=True、meta.compat_alias_for 和 meta.primary_event_id，方便消费者去重。

Execution Environment 使用 execution_environment.*。当前 manager 事件包括 declared、approval_required、ensuring、ready、unhealthy、releasing、released 和 failed。

运行进展与卡死诊断 ​

Event Center 是接收和分发层。liveness 进展会在高成本 hook 投递前更新，因此一个慢 hook 不应该挡住卡死诊断。

AgentExecution 会把诊断信息放在 async_get_meta()["diagnostics"]：

  • diagnostics["stages"]["events"]：最近 stage 进展。
  • diagnostics["last_progress"]：最后一次被接受的进展事件。
  • diagnostics["timeouts"]：硬截止超时。
  • diagnostics["stalls"]：idle 无进展卡死。

本地排查可以临时挂 hook，或打开 .set_settings("debug", True) / .set_settings("debug", "detail")。问题定位后，把临时 debug hook 和 debug settings 移走。

消费端要 fail open ​

RuntimeEvent 是可扩展协议。自定义消费者和 DevTools 都应该宽容处理：

  • 忽略未知顶层字段和未知 payload 字段。
  • 对未知 event_type 不报错。
  • 不把 payload 当作全局固定 schema。
  • 优先使用 run 做关联，不解析 message。

另见 ​