Event Center

Languages: English · 中文

The Event Center is Agently’s framework-level observation channel. It carries observation events: model requests, Session application, TriggerFlow lifecycle, Action calls, and similar framework activity can be forwarded to DevTools or to a custom log sink through this channel.

It is separate from TriggerFlow emit / when: emit / when changes control flow inside a flow; observation events only observe what happened.

Naming compatibility:

ObservationEvent is the preferred name for new code.
RuntimeEvent is the historical name and remains a compatible alias through the Agently 4.1.x line.
Agently 4.2 is the intended replacement line for deprecated event naming.
Existing emit_runtime / async_emit_runtime code continues to work; new code may use emit_observation / async_emit_observation.

Register a hook

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 can be a string, a list of strings, or None. With None, the hook receives every event. Sync callbacks are accepted too; Event Center normalizes them to async calls.

Emit an observation event

The usual path is an emitter:

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"},
)

You can also emit a dict directly:

await Agently.event_center.async_emit({
    "event_type": "runtime.info",
    "source": "Docs",
    "message": "direct event",
})

For top-level convenience APIs:

await Agently.async_emit_observation({
    "event_type": "runtime.info",
    "source": "Docs",
    "message": "preferred observation API",
})

# 4.1.x compatibility alias:
await Agently.async_emit_runtime({
    "event_type": "runtime.info",
    "source": "Docs",
    "message": "legacy runtime API",
})

Event shape

The top-level fields come from agently.types.data.event.ObservationEvent. RuntimeEvent has the same shape and remains a 4.1.x compatibility alias:

Field	Meaning
`event_id`	event id, generated by default
`event_type`	dotted name such as `triggerflow.execution_started`
`source`	where the event came from
`level`	`DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL`
`message`	human-readable message
`payload`	event-specific structured data
`error`	error information; exceptions are normalized to `ErrorInfo`
`run`	run lineage, including `run_id`, `parent_run_id`, `session_id`, `execution_id`, and related ids
`meta`	additional metadata
`timestamp`	millisecond timestamp

TriggerFlow event aliases

Event Center keeps compatibility with historical TriggerFlow event prefixes. A subscription to workflow.execution_started can receive triggerflow.execution_started; a subscription to trigger_flow.signal can receive triggerflow.signal. Documentation and new code should prefer triggerflow.*.

Action compatibility events

Action Runtime lifecycle events use action.* as the primary namespace. When the current Action Runtime branch is tool-compatible, Agently also emits paired tool.* compatibility events for existing subscribers and old examples:

Primary event	Tool compatibility event
`action.loop_started`	`tool.loop_started`
`action.plan_ready`	`tool.plan_ready`
`action.loop_failed`	`tool.loop_failed`
`action.loop_completed`	`tool.loop_completed`

Paired compatibility events include meta.compat_event_alias=True, meta.compat_alias_for, and meta.primary_event_id so consumers can deduplicate them from the primary action.* event.

Concrete action execution continues to use action.started, action.completed, and action.failed. For tool-backed actions, payload.action_type may be "tool"; that does not change the event family.

Execution environment events

Execution Environment lifecycle uses execution_environment.*. Providers and DevTools consumers should treat this namespace as extensible. Current manager events include declared, approval_required, ensuring, ready, unhealthy, releasing, released, and failed. unhealthy means a ready handle failed the health check before reuse; the manager releases it and ensures a fresh handle.

Compatibility rules

Observation events are an observation protocol. Agently-DevTools and custom consumers should fail open:

Ignore unknown top-level fields and unknown payload fields.
Do not fail on unknown event_type values.
Do not treat payload as a closed schema; it can grow per event type.
When correlating a request, Session, or TriggerFlow execution, prefer run fields over parsing message.

Agently Docs