ExAgent.Event (ExAgent v0.2.0)

Copy Markdown View Source

Versioned, serializable event envelope — ExAgent's UI/runtime contract.

ExAgent.Event is what LiveView, CLI frontends, channels, product logs and flow tests subscribe to. It is deliberately distinct from :telemetry, which stays the channel for technical observability (metrics, OTel, dashboards) and may be emitted in parallel.

Events flow through ExAgent.PubSub. A subscriber receives messages shaped as {:exagent_event, %ExAgent.Event{}} on topics such as "exagent:agent:<agent_id>" (see agent_topic/1) and "exagent:session:<session_id>" (see session_topic/1).

Fields

  • version — envelope schema version (currently 1).
  • id — unique event id ("evt_...").
  • seq — monotonic sequence within the emitting source (per agent).
  • type — one of the event types listed below.
  • source — :run, :server, :session, :coordination, …
  • occurred_at — DateTime.utc_now/0 at emission.
  • correlation — run_id, request_id, agent_id, session_id,
                `participant_id` (any may be `nil`).
  • payload — JSON-encodable map with event-specific data.
  • metadata — free-form, JSON-encodable map.

Event types

Loop / run:

:run_started · :run_finished · :run_failed
:run_step_started · :run_step_finished
:text_delta · :thinking_delta
:tool_call_started · :tool_call_finished
:usage_updated

Server runtime:

:server_request_queued · :server_request_cancelled
:approval_requested

Session / coordination (Phase 3+):

:session_started · :participant_joined · :participant_left
:session_turn_changed · :shared_state_updated · :session_closed

Compaction (Phase 5):

:compaction_started · :compaction_finished

Summary

Types

source()
t()

Functions

agent_topic(agent_id)

Recommended PubSub topic for an agent ("exagent:agent:<id>").

new(opts)

Build a new event, filling id/occurred_at/version defaults.

session_topic(session_id)

Recommended PubSub topic for a session ("exagent:session:<id>").

Types

source()

@type source() :: :run | :server | :session | :coordination | atom()

t()

@type t() :: %ExAgent.Event{
  agent_id: String.t() | nil,
  id: String.t(),
  metadata: map(),
  occurred_at: DateTime.t(),
  participant_id: String.t() | nil,
  payload: map(),
  request_id: String.t() | nil,
  run_id: String.t() | nil,
  seq: non_neg_integer(),
  session_id: String.t() | nil,
  source: source() | nil,
  type: atom(),
  version: pos_integer()
}

Functions

agent_topic(agent_id)

@spec agent_topic(String.t() | nil) :: String.t()

Recommended PubSub topic for an agent ("exagent:agent:<id>").

new(opts)

@spec new(keyword()) :: t()

Build a new event, filling id/occurred_at/version defaults.

:type and :seq are required (enforced); everything else is optional with sensible defaults. payload/metadata default to empty maps.

session_topic(session_id)

@spec session_topic(String.t() | nil) :: String.t()

Recommended PubSub topic for a session ("exagent:session:<id>").