Skip to main content

Triggers

The Triggers screen lets you start an agent run each time a business event is published on a subject, optionally only when the event payload matches a filter, and delete these triggers. Portal path: /agents/triggers. Developers, application owners and tenant administrators wire their agents to events. The screen is drawn by portal/src/screens/agents.tsx.

What the screen shows​

  • Triggers table, read with GET /v1/triggers (every trigger of the tenant in one call, oldest first). Columns: Id, Subject, Agent id, Filter, Enabled.
  • When the list is empty: No trigger, with the hint Start agents from business events. and the button New trigger.
  • The row menu View details shows every field of the row in a side panel.
  • New trigger opens a side panel with the fields Subject (required, example erp.invoice.created), Agent id (required) and Filter (example type=invoice && currency!=USD, help path=value && path!=value).

Actions​

Button or actionWhat it doesAPI callRoles
Refresh (icon)Reloads the list.GET /v1/triggersAny tenant member
New triggerCreates the trigger after checking the subject and the filter.POST /v1/triggerstenant_admin, developer, application_owner
Row menu View detailsShows the row in a side panel.NoneAny tenant member
Row menu DeleteOpens Confirm a destructive action; type the trigger id, then Confirm.GET /v1/lineage/graph, then DELETE /v1/triggers/{trigger_id}tenant_admin, developer, application_owner
Retry (error state)Sends the failed read again.Same callSame roles

The filter grammar (services/control-plane/src/eai/domains/agents/scheduler.py) is a list of path=value or path!=value clauses joined by &&; the path is dotted into the event payload. With the filter below, an event starts the agent only when type is invoice and currency is not USD:

type=invoice && currency!=USD

The subject follows the NATS rules; a trigger subject may use the wildcards * (one token) and > (the rest). Applications publish events with POST /v1/events/publish.

Roles​

The portal hides no button. Create and delete check WRITE_ROLES (tenant_admin, developer, application_owner) in services/control-plane/src/eai/domains/agents/routes.py; the list only needs a tenant. Publishing an event checks OPS_ROLES (tenant_admin, developer, agent). platform_admin passes every role check.

Typical tasks​

Start an agent when an invoice is created​

  1. Choose the subject. The subject is the name of the event the ERP connector or the application publishes. Agree on it with the publisher, for example erp.invoice.created. Expected result: one subject per kind of event. If it fails: a subject with spaces or empty tokens is refused with invalid_subject.
  2. Create the trigger. The trigger links the subject to the agent. Click New trigger, fill Subject and Agent id, add a Filter when only some events matter, then click Create. Expected result: the toast Created and a new row. If it fails: invalid_filter (422) means a clause has no = or !=, or an empty path.
  3. Check the first run. The next matching event starts a run. After an event is published, open the Runs screen. Expected result: a run of the agent appears. If it fails: compare the payload of the event with the filter; a path missing from the payload fails an = clause, and values are compared as text.

Remove a trigger​

  1. Delete it. A deleted trigger no longer starts runs. In the row menu, click Delete, type the trigger id, then click Confirm. Expected result: the toast Done and the row disappears. If it fails: trigger_not_found (404) means it was already deleted; click Refresh.

Troubleshooting​

SymptomCauseFix
invalid_subject (422): "Invalid event subject ..."The subject is not a valid NATS subject.Use dot separated tokens without spaces, such as erp.invoice.created.
invalid_filter (422): "Invalid trigger filter."A clause has neither = nor !=, or its path is empty.Write clauses path=value or path!=value joined by &&.
agent_not_found (404) on CreateAgent id names no agent of the tenant.Copy the id or the name from the Registry.
trigger_not_found (404) on DeleteThe trigger no longer exists.Click Refresh.
forbidden (403) with required_rolesYour roles are not tenant_admin, developer or application_owner.Ask a tenant administrator for one of these roles.
Events are published but no run startsThe filter does not match the payload, or the agent is not active.Check the payload paths and the status of the agent.