---
title: "Event-Driven Workflows | AgentRQ Docs"
url: https://agentrq.com/docs/howto-events
description: "Use AgentRQ Events to build decoupled, event-driven multi-agent pipelines. One agent publishes a named event; other agents in any workspace automatically receive tasks in response."
---

[Docs](https://agentrq.com/docs/) / How-To / Event-Driven Workflows

Event-Driven Workflows

# 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](https://agentrq.com/docs/howto-events#how-it-works) [Core Concepts](https://agentrq.com/docs/howto-events#core-concepts) [Pattern 1: Fan-Out](https://agentrq.com/docs/howto-events#pattern-fanout) [Pattern 2: Pipeline Chaining](https://agentrq.com/docs/howto-events#pattern-chaining) [Setup: Events & Triggers](https://agentrq.com/docs/howto-events#setup) [Template Variables](https://agentrq.com/docs/howto-events#templates)

## How It Works

Events are named signals. An agent in any workspace calls `publishEvent(name, payload)` via the MCP tool. 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 `getTask()` 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 `publishEvent("deploy_done", "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 `getTask()` 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 `publishEvent` on completion. `TriggerID` records which trigger created the task — useful for tracing event chains in the dashboard.

1

## 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 `publishEvent("deploy_done", "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: finish work, then publish
updateTaskStatus(myTaskId, "completed")

publishEvent(
  "deploy_done",
  "v2.3 deployed to prod. New: billing module, JWT rotation.",
  faq: "Was the DB migrated? Yes — migration ran cleanly."
)

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

The `faq` parameter

The optional `faq` argument 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.

2

## 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 `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: call publishEvent("tests_passed", "<your output payload>")]
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 and what to put in the payload.

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.

**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

### 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 `publishEvent`:

Workspace description or CLAUDE.md

```
## Events

When you finish a successful deployment, call:
  publishEvent("deploy_done", "<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 `publishEvent` call.

| Variable | Replaced With | Source |
| --- | --- | --- |
| `{{EVENT_PAYLOAD}}` | The payload string passed by the publishing agent | `publishEvent(name, payload)` |
| `{{EVENT_FAQ}}` | Additional Q&A context from the publishing agent (if provided) | `publishEvent(name, payload, 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` argument, 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 `publishEvent` to fan out notifications to downstream teams without requiring the supervisor to explicitly wire each connection.

## Related Pages

[Supervisor MCP Cross-workspace orchestration via coremcp](https://agentrq.com/docs/supervisor-mcp) [Workflow Patterns Approval gates, review flows, escalation patterns](https://agentrq.com/docs/howto-workflows) [Workspace MCP Reference Full docs for publishEvent and all MCP tools](https://agentrq.com/docs/mcp-tools)