Skip to main content
Trinity
Updated Nov 17, 2026main@87e21ff
Architecture/Event Subscriptions

Event Subscriptions

Lightweight pub/sub system for inter-agent event pipelines. Agents emit named events, and subscribing agents receive async tasks with the payload.

Concepts

•Event — A named occurrence emitted by an agent with a structured JSON payload. Stored in the agent_events table.
•Subscription — A rule that says "when agent X emits event type Y, send agent Z an async task with message template M". Stored in the agent_event_subscriptions table.
•Message Template — The target_message of a subscription. Supports {{payload.field}} interpolation. The subscriber's task message is built from the event payload.
•Permission-Gated — Uses existing agent_permissions. The subscribing agent must have permission to call the source agent. Trinity checks this when the subscription is created and again on every delivery, so withdrawing the permission stops deliveries at the next event. The subscription is kept, and granting the permission again resumes it. An agent subscribing to its own events needs no permission (except for the reserved agent.task.* namespace, below).

How It Works

1

Agent A emits an event: emit_event(event_type="report_ready", payload={"url": "...", "summary": "..."})

2

Trinity checks all subscriptions matching agent A + event type report_ready.

3

For each matching subscription, an async task is dispatched to the subscribing agent.

4

The task message is built from the subscription's template with payload fields interpolated. Each interpolated value is wrapped in ⟦ ⟧, credential-sanitized and capped at 4000 characters, and the message gets a line telling the subscriber that the marked text is data, not instructions. Event payloads are limited to 64 KiB.

5

Events are persisted and visible via API.

6

WebSocket broadcast provides real-time event visibility.

Delivery Limits

Two limits stop an event chain from running away:

•Chain depth. When an agent emits an event that matches a subscription, the subscriber's task counts as one more hop in the agent-to-agent call chain. Past the chain-depth limit (default 8) the emit is refused with 403 inter_agent_depth_exceeded before anything is stored, and emit_event returns it as a retryable: false result. See Agent Network → Chain-Depth Limit.
•Hourly dispatch cap. Trinity counts dispatches from one source agent to one subscriber agent per hour, across every subscription between the two. Past the cap (default 120, operator setting event_dispatch_max_fires_per_hour, 1–10,000) further dispatches from that source are skipped until the hour resets. The first skip in each hour raises one high-priority alert on the subscriber, saying a subscription may be looping. The event itself is still recorded. If Redis is unavailable, the cap is not enforced.

Task-Completion Events (System-Emitted)

Trinity deterministically emits agent.task.completed and agent.task.failed at every terminal of a task run of an agent — a schedule, a parallel=true delegation, a fan-out subtask, a Chat-tab, Session, Slack/Telegram or public-link turn, and the like. Only the backend's synchronous /chat route emits none: a sequential chat_with_agent call (parallel=false), unless the experimental pull-pilot routing sends it through the task path. These are system-emitted: the platform synthesizes them at the execution chokepoint with no agent in the loop. They ride the same subscription machinery as agent-emitted events.

The win: wake instead of poll. Subscribe to a worker's agent.task.completed (or agent.task.failed) and you get an automatic report-back task the moment that worker's execution finishes — no need to hold a call open or poll get_execution_result. This is the async-first alternative to chat_with_agent(parallel=true, async=true) followed by polling (see Agent Network). An agent that delegated the run is also woken without any subscription, by default (see Agent Network → Wake on Ending). When it holds a matching subscription as well, the subscription's report-back task is the one turn it gets for that ending. A subscription is still the way to hear about runs you did not start, such as a worker's scheduled runs.

subscribe_to_event(
  source_agent="research-worker",
  event_type="agent.task.completed",
  target_message="research-worker finished task {{payload.execution_id}} ({{payload.status}}): {{payload.summary_or_error}}"
)

Reserved Namespace

The agent.task.* namespace is reserved for the platform:

•Agents cannot emit into agent.task.* themselves (emit_event rejects it). Only Trinity produces these events.
•Agents cannot self-subscribe to agent.task.*. Subscribing is cross-agent only — you subscribe to another agent's completions.
•Subscriptions stay permission-gated: the subscriber must be permitted to call the source agent (same rule as every other subscription, see Agent Permissions).

Payload Fields

Interpolate these into your message template:

FieldMeaning
{{payload.execution_id}}The execution that terminated (correlation key)
{{payload.status}}success or failed
{{payload.triggered_by}}What triggered the source execution (schedule, chat, event, ...)
{{payload.summary_or_error}}The worker's response text on success, or the error on failure (credential-sanitized, truncated)
{{payload.duration_ms}}Wall-clock duration of the source execution
{{payload.cost}}Cost of the source execution
{{payload.fan_out_id}} / {{payload.loop_id}}Set when the source execution was part of a fan-out or loop

Delivery Caveat

Delivery is best-effort. The report-back task wakes a subscriber whose container is running. If the subscriber agent is stopped, the wake is dropped — the event is still recorded in agent_events, but no task is dispatched. This is not a durable queue; do not rely on it for guaranteed hand-off between stopped agents.

Additive and Inert

With zero matching subscriptions, nothing happens: no event row is written and no task is dispatched. There is no new config, endpoint, or flag — task-completion events reuse the existing event-subscription tools below (subscribe_to_event / list_event_subscriptions / delete_event_subscription), passing event_type="agent.task.completed" or "agent.task.failed".

Reporting Back to the Person Who Asked

Subscriptions wake an agent. Independently of them, a job that started from a conversation and finished later — because the agent delegated it to another agent, or kicked off background work — reports its outcome back to the conversation it came from, success and failure alike. For agent-to-agent delegation this holds when the agent hands the work off with chat_with_agent(..., parallel=true, async=true), which reports back by default (pass execution_id="manual" to keep one call quiet); a plain sequential delegation is not guaranteed to report back separately, since the agent answers with the reply itself. Four places can receive that report:

Where the job startedWhere the outcome lands
A Slack channel or threadA note in that channel/thread — see Slack
A Telegram chatA reply threaded to your message, from the bot you talked to — see Telegram
A Workspace chatA message from the agent in that chat. It is filed under the agent you were talking to and names the agent that did the work when that differs; it opens with Finished or Didn't finish and the status, so a failure never vanishes. The chat moves to the top of the sidebar as any new message would, and the report waits up to two minutes for a reply already in progress before landing
A scheduled run addressed to someoneThat person's Main chat — see Scheduling

An ordinary turn that already answered inline is never reported a second time. Each finished job reports at most once, and a report is never sent to a conversation the work was not started from. The Workspace does not push the report while you watch: it is there on the next load or chat switch.

MCP Tools

ToolDescription
emit_event(event_type, payload)Emit a named event with data
subscribe_to_event(source_agent, event_type, target_message)Create a subscription. Needs an agent-scoped key: the caller is the subscriber
list_event_subscriptions(direction?)List the calling agent's subscriptions: subscriber (events it listens for), source (others listening to it), or both (default)
delete_event_subscription(subscription_id)Remove a subscription (the subscribing agent's owner only)

API Endpoints

EndpointMethodDescription
/api/agents/{name}/event-subscriptionsPOSTCreate subscription
/api/agents/{name}/event-subscriptionsGETList subscriptions
/api/event-subscriptions/{id}GETGet by ID
/api/event-subscriptions/{id}PUTUpdate
/api/event-subscriptions/{id}DELETEDelete
/api/eventsPOSTEmit event (agent-scoped)
/api/agents/{name}/emit-eventPOSTEmit for specific agent
/api/agents/{name}/eventsGETEvent history for one agent you can access
/api/eventsGETEvents from the agents you can access (admins see all). Filters: source_agent, event_type, limit (up to 500). A source_agent you cannot access returns 403