Skip to content

Events

Other systems can hand work to PinionAI agents by posting events. An event is stored once, routed to an agent intent, and run by the event worker with retries, so the sender only has to post it.

Posting events

POST /events on the PinionAI API with the account's bearer token (see PinionAI_API):

{"type": "deal.changed", "key": "deal:123:7", "occurred_at": "2026-10-27T18:00:00Z", "payload": {"dealId": "123", "state": "Ordered"}}

or a batch, {"events": [ ... ]} (at most 500). type uses letters, digits and . _ : -; key is the sender's idempotency key: a key the account already posted is answered as a duplicate and not stored again, so senders can retry freely. payload must be a JSON object.

Routes

On the Events page (Data menu), a route maps an event type to an agent and one of its intents. The exact type wins; otherwise the route with the longest matching prefix (deal.*) is used. Each route has a max attempts (default 8). Intent names must not contain the words for, using, with or in (the worker triggers the intent as :<intent>).

A route may name a then type (0.4.12): once its intent succeeds, the worker posts the same payload again as that type (key <event key>><type>, so only once), and that type's own route runs it. This chains agents in order without the sender knowing: support.changed → the CRM sync agent, then support.triage → a triage agent that reads what the sync wrote. A route cannot hand an event on to its own type.

How an event runs

The worker (python -m tools.event_worker, its own container from the Studio image) claims due events and, for each:

  1. reuses one session per agent, with its history and variables reset;
  2. sets var.event (the payload), var.event_type, var.event_key, var.event_uid and var.stopOnError;
  3. runs the route's intent. Its flow runs all-or-nothing: the first failed API, MCP, merger, parser or prompt step (a prompt that returns no text) sets var.flow_error and the remaining steps do not run.

A failed event is retried after 30 s, 1 min, 2 min, … (at most an hour apart) and marked dead after the route's max attempts. An event with no route is unrouted. The Events page lists events by status with their payload and last error, and Retry puts failed, dead or unrouted events back in the queue.

Writing to other systems from an event

MCP steps are the usual way: an MCP whose Parameters JSON names a _tool calls that tool directly with the rendered arguments, without asking a model (see MCPs). PinionAI ships a CogMento CRM tool server (mcp_server/cogmento/) with idempotent CRM tools for exactly this.