LegionWeb.AgentTracker behaviour (LegionWeb v0.5.0)

View Source

Query interface for a Legion agent activity tracker.

An implementation provides the dashboard's read model for agents and their events. The configured tracker is supervised by LegionWeb and called directly by the dashboard.

Built-in trackers

The telemetry tracker needs no configuration. To select another tracker, configure its module and startup options:

config :legion_web, :agent_tracker,
  {LegionWeb.AgentTracker.Postgres, store: MyApp.AgentStore}

A custom tracker must implement this behavior and provide a child specification so LegionWeb can supervise it. Implementations may use any process model, storage mechanism, or ingestion strategy as long as they return the records described by this interface.

Summary

Callbacks

Returns the tracked agent with the given ID, or nil when it is absent.

Returns an agent's events in chronological order.

Returns an agent's LLM usage entries in request order.

Lists up to limit tracked agents, newest first.

Types

agent()

agent_id()

@type agent_id() :: Legion.Store.agent_id()

event()

status()

@type status() :: :running | :idle | :waiting_for_human | :done | :error | :dead

timestamp()

@type timestamp() :: integer()

usage()

@type usage() :: map()

Callbacks

get_agent(agent_id)

@callback get_agent(agent_id()) :: agent() | nil

Returns the tracked agent with the given ID, or nil when it is absent.

get_events(agent_id)

@callback get_events(agent_id()) :: [event()]

Returns an agent's events in chronological order.

get_usage(agent_id)

@callback get_usage(agent_id()) :: [usage()]

Returns an agent's LLM usage entries in request order.

Each entry is the string-keyed usage map Legion records for one LLM request, including its "at" timestamp in milliseconds. Only the agent's own requests are included; a sub-agent's usage is tracked under the sub-agent.

list_agents(pos_integer)

@callback list_agents(pos_integer()) :: [agent()]

Lists up to limit tracked agents, newest first.