Event-Driven Harness Architectures

One-Line Summary: An event-driven harness reacts to events — file changes, GitHub webhooks, build completions, schedule triggers — by invoking the agent loop without a user typing anything; this architecture turns a user-driven harness into an autonomous service and is the substrate for background workers, autopilot, and federated coordination.

Prerequisites: Hooks and lifecycle events, background worker pattern, continuous execution loops

What Is an Event-Driven Harness?

A user-driven harness waits for the user to type. An event-driven harness has multiple input streams:

User input (still supported).
System events: file modifications, process exits, schedule fires.
External events: GitHub PR opened, Slack message received, alert from monitoring.
Internal events: another agent finished, a worker found something, a budget threshold was crossed.

Each event can trigger an agent invocation. The harness is now structurally a service — its inputs are events, its outputs are actions, its loop is continuous.

This is the architectural shape behind ruflo's autopilot + workers + federation, and behind any harness deployment that runs 24/7 against a stream of work.

How It Works

An event-driven harness has:

Event sources: Each one a connection to an external system. Webhooks for GitHub/Slack; cron for schedules; filesystem watches for local changes.
Router: An event lands; the router decides which handler runs. Pattern: event type → handler agent.
Handlers: Agents (or sub-agents) configured for specific event types.
Resource governor: Concurrency limits, rate limits, budget.
Outbox: For events the harness emits to other systems (PR comments, Slack messages, status updates).

The event-driven harness is essentially a message-bus + agent runtime combination. Cloud-native deployments often use SQS / Kafka / NATS as the bus.

Why It Matters

Event-driven is what unlocks the harness's most autonomous behaviors:

Background workers are subscribers to system events.
Autopilot is a loop driven by internal events ("plan stage finished, start next").
Federation is event-driven by definition (peer messages are events).
Continuous integration / deployment with agents is event-driven (PR events trigger reviewers).

A harness without event-driven architecture is fundamentally interactive; one with event-driven scales into infrastructure.

Key Technical Details

At-least-once vs. exactly-once delivery: Most event sources guarantee at-least-once. Handlers must be idempotent.
Event ordering: Events can arrive out of order. Critical for correctness in some workflows; usually addressable via per-key ordering.
Backpressure: When the agent runtime can't keep up with the event rate, queues grow. Apply rate limits or shed load gracefully.
Dead-letter queues: Events that repeatedly fail to process should land in a DLQ for manual review.
Event-driven debugging is harder: A bug in event-driven systems can compound silently. Observability discipline matters more here.
Webhooks are the easiest external source: They push to a URL the harness exposes. Outbound polling is simpler but adds latency and cost.
Schema evolution: Event schemas evolve. Treat event types like API contracts; version them carefully.

How Harnesses & Frameworks Implement This

Harness / Framework	Event-driven support
Claude Code	Limited — `SessionStart` and tool hooks
Claude Agent SDK	DIY — bring your own event source
ruflo	First-class — workers + autopilot + federation all event-driven
LangGraph	LangGraph Cloud supports event triggers
AutoGen	DIY
CrewAI	Limited
OpenAI Agents SDK	DIY
Codex CLI / Cursor	Session-bound

Connections to Other Concepts

hooks-and-lifecycle-events.md — Hooks are local lifecycle events; this concept generalizes to external events.
background-worker-pattern.md — Workers' triggers are events.
continuous-execution-loops.md — The runtime model.
cross-machine-agent-federation.md — Federation is fundamentally event-driven.