Event-Driven Workflows

Docs / How-To / Event-Driven Workflows

Events let agents trigger work in other workspaces without a supervisor in the loop. One agent publishes a named signal; every subscribed workspace automatically receives a new task. No polling, no hardcoded dependencies — agents stay decoupled.

On This Page

How It Works Core Concepts Pattern 1: Fan-Out Pattern 2: Pipeline Chaining Setup: Events & Triggers Template Variables

How It Works

Events are named signals. An agent in any workspace publishes one with its workspace tool: workspace {"action": "publishEvent", "payload": {"name": "…", "payload": "…"}}. AgentRQ looks up all Event Triggers subscribed to that event name and creates a task in each subscribed workspace — passing the agent's payload through a template into the task body. Those workspace agents pick up their tasks via the normal task get loop.

Neither the publishing agent nor the subscribing agents need to know anything about each other. The event name is the only shared contract. Workspaces are added or removed from a pipeline by creating or deleting triggers — no agent code changes required.

End-to-End Flow

Agent A finishes its work and calls workspace {"action": "publishEvent", "payload": {"name": "deploy_done", "payload": "v2.3 deployed to prod"}}

AgentRQ resolves the event name to an Event record

All Event Triggers subscribed to deploy_done are fetched

A new task is created in each subscribed workspace; the payload is injected into the task body via {{EVENT_PAYLOAD}}

Each workspace agent picks up its task via task {"action": "get"} and starts work independently

Human UI receives SSE task.created events for each workspace in real time

Core Concepts

Event

A named signal definition owned by your account. Names are lowercase letters, digits, and underscores (e.g. deploy_done, pr_merged, tests_passed). Each event can have an optional payload guidelines hint — a plain-text description of what agents should put in the payload when they publish it. This hint is injected into the agent's task notification so it knows what format to use.

Event: deploy_done
Payload guidelines: Include the version tag, environment (staging/prod), and a one-line summary of what changed.

Event Trigger

A subscription: "when this event fires, create a task in this workspace." Each trigger stores a static title and a body template (which can reference {{EVENT_PAYLOAD}}). An optional Emit Event links the spawned task to a second event that fires when the agent completes that task — enabling pipeline chaining.

Trigger on: deploy_done → Workspace: QA Team
Title: Run smoke tests
Body: A new deploy just landed. Details: {{EVENT_PAYLOAD}}
Emit on completion: smoke_tests_passed

Task.EventID & Task.TriggerID

When a task is created with an EventID, the agent's task notification is automatically augmented with an instruction to call workspace → publishEvent on completion. TriggerID records which trigger created the task — useful for tracing event chains in the dashboard.

Pattern: Fan-Out

One event, multiple subscribers. When Agent A finishes a task and publishes an event, AgentRQ fans the signal out to every workspace that has a trigger on that event name. All downstream tasks are created simultaneously — the downstream agents run in parallel, independently of each other.

Example: Deploy triggers QA + Docs + Changelog

Deploy agent finishes and calls workspace {"action": "publishEvent", "payload": {"name": "deploy_done", "payload": "v2.3: new billing module"}}

AgentRQ creates tasks in three workspaces simultaneously:

QA Workspace → "Run smoke tests"

Docs Workspace → "Update release notes"

Changelog Workspace → "Draft changelog entry"

All three agents run concurrently. Deploy agent is already done — it doesn't wait.

Flow Diagram

Agent A — publishing the event

// Agent A: publish, then mark its own task completed
workspace {"action": "publishEvent", "payload": {
  "name": "deploy_done",
  "taskId": "0kGogHmaqvZ",
  "payload": "v2.3 deployed to prod. New: billing module, JWT rotation.",
  "faq": [{"q": "Was the DB migrated?", "a": "Yes, the migration ran cleanly."}]
}}

task {"action": "updateStatus", "payload": {"taskId": "0kGogHmaqvZ", "status": "completed"}}

// Done. AgentRQ handles the rest — no need to know who's listening.

The faq parameter

The optional faq field, a list of question-and-answer pairs, lets the publishing agent answer anticipated questions from downstream agents. It's injected into the task body via {{EVENT_FAQ}}. Use it to pass context that doesn't belong in the main payload.

Pattern: Pipeline Chaining

Sequential pipelines where each stage's output kicks off the next. Set the Emit Event field on an Event Trigger — the spawned task inherits an EventID, and the agent receives an explicit instruction in its task notification to call workspace → publishEvent when it's done. That publish fires the next stage automatically.

Example: Build → Test → Publish Pipeline

Task notification delivered to QA Agent

[Task abc123] Run smoke tests
A new build just landed. Details: v2.3 — billing module, JWT rotation.

[On completion, before marking this task completed: call workspace {action: "publishEvent", payload: {name: "tests_passed", taskId: "abc123", payload: "<what happened, in your words>", faq: [{q, a}, ...]}}]
Copy name and taskId exactly as written above — taskId is what tells the server which run this continues.
Write the payload yourself. faq is optional: question/answer pairs covering what subscribers are likely to ask — tasks triggered by this event can render both.
Payload guidelines: Include pass/fail counts and any failures encountered.

The agent sees the [On completion, ...] instruction injected automatically — no custom prompt engineering required. It knows exactly which event to publish, which taskId to pass so the run continues, and what to put in the payload. Agents set up before the action tools may call the old publishEvent tool instead; the server still accepts it.

Chaining vs. Fan-Out

Fan-out is wide (one event, many simultaneous subscribers). Chaining is deep (sequential stages where each stage produces the input for the next). They compose: a fan-out at Stage 1 followed by a chain at Stage 2 gives you a tree-shaped pipeline.

Setup: Events & Triggers

Step 1 — Create an Event

In the AgentRQ dashboard, go to Events and create a new event. Give it a lowercase name with underscores (deploy_done, pr_merged, etc.). Optionally add payload guidelines — a sentence describing what agents should include in the payload when they publish it.

An agent connected to the Supervisor MCP can do the same with events → create. The answer carries the event's id, which the trigger in step 2 needs.

events {"action": "create", "payload": {
  "name": "deploy_done",
  "payloadGuidelines": "Include the version tag, environment (staging/prod), and a one-line summary of what changed."
}}  // -> { id: "0hNRmEWoU5Z", ... }

Naming convention: use verb_noun or noun_verb_state format — build_done, tests_passed, pr_merged, review_approved. Keep names stable — agents and triggers reference them by name.

Step 2 — Add Event Triggers

For each workspace that should react to the event, create an Event Trigger. Specify:

Event — which event to subscribe to

Workspace — where to create the task when the event fires

Title — static task title (e.g. "Run smoke tests after deploy")

Body — task instructions with optional {{EVENT_PAYLOAD}} and {{EVENT_FAQ}} placeholders

Emit Event (optional) — a second event this agent should publish on completion, enabling pipeline chaining

From the Supervisor MCP, the same trigger is events → createTrigger, with the ids of the event, the workspace and the optional emit event. Run help {"action": "events.createTrigger"} for every field it takes.

events {"action": "createTrigger", "payload": {
  "eventId":     "0hNRmEWoU5Z",   // deploy_done
  "workspaceId": "0eCTDeDXETx",   // QA Team
  "title":       "Run smoke tests",
  "body":        "A new deploy just landed. Details: {{EVENT_PAYLOAD}}",
  "emitEventId": "0hDXw48jLfd"    // smoke_tests_passed
}}

events → listTasks then shows the tasks the event has spawned, so you can check the wiring works. Clients set up before the action tools may still call createEvent and createEventTrigger; the server still accepts those names.

Step 3 — Instruct Your Agent to Publish

Add a note to your workspace description or CLAUDE.md telling the agent when and how to call workspace → publishEvent:

Workspace description or CLAUDE.md

## Events

When you finish a successful deployment, call:
  workspace {"action": "publishEvent", "payload": {"name": "deploy_done", "payload": "<version> deployed to <env>. Changes: <summary>"}}

Include in payload: version tag, environment, one-line change summary.
If the deployment failed, do NOT publish — only publish on success.

Template Variables

Event Trigger body templates support two substitution variables. They are replaced at task creation time with values from the publishing agent's workspace → publishEvent call.

Variable	Replaced With	Source
`{{EVENT_PAYLOAD}}`	The payload string passed by the publishing agent	`publishEvent` payload field `payload`
`{{EVENT_FAQ}}`	Additional Q&A context from the publishing agent (if provided)	`publishEvent` payload field `faq`

Event Trigger body template

A new deploy just landed in production.

## What changed
{{EVENT_PAYLOAD}}

## Notes from the deploy agent
{{EVENT_FAQ}}

Run the full smoke test suite. If any test fails, create a blocking task
for the on-call engineer before marking this task completed.

If {{EVENT_FAQ}} is used in the template but the publishing agent didn't provide a faq field, the placeholder is replaced with an empty string — it won't break the task.

Events vs. Supervisor Agent

Both approaches enable multi-workspace coordination. Choose based on how tightly coupled the stages need to be.

	Events	Supervisor Agent
Coupling	Decoupled — publisher doesn't know subscribers	Coupled — supervisor explicitly knows all workers
Configuration	Dashboard UI — no agent code changes to add stages	Agent logic — supervisor explicitly creates each subtask
Branching logic	Limited — triggers are static; no conditional fan-out	Full — supervisor can branch based on prior task results
Best for	Recurring pipelines, cross-team automation, webhook-style triggers	Complex orchestration where stage N output shapes stage N+1 input

You can mix both: a supervisor agent orchestrates the high-level flow, while individual agents use workspace → publishEvent to fan out notifications to downstream teams without requiring the supervisor to explicitly wire each connection.

Supervisor MCP

Cross-workspace orchestration via coremcp

Workflow Patterns

Approval gates, review flows, escalation patterns

Workspace MCP Reference

Full docs for workspace publishEvent and every workspace tool