---
name: rtie-action-engine
description: Configure the RTIE Action Engine — ingest signals, author rules, and trigger real-time cross-product actions in under 350ms.
version: "0.1.0"
---

# RTIE Action Engine

The Action Engine is a **cross-product intelligence layer** that converts signals (from ML models, agents, rules, or events) into real-time in-session actions in <350ms end-to-end.

It subscribes to every module's events and can trigger actions in any of them.

## Core concepts

```
Signal → Rule evaluation → Action dispatch → In-session effect
```

- **Signal**: a structured event with a type, source, payload, and optional confidence score
- **Rule**: a tenant-defined condition set + action to take when conditions match
- **Action types**: `agent_trigger`, `ui_event`, `module_call`, `state_update`

## Sending a signal

```typescript
// Via @rtie/sdk
await rtie.actions.ingest({
  signal_type: "churn_risk",
  source: "ml_model",            // "ml_model" | "rule" | "agent" | "webhook" | "user"
  payload: {
    score: 0.87,
    userId: "usr_abc123",
    sessionId: "sess_xyz",
  },
  confidence: 0.87,
});
```

MCP: `ingest_signal(signal_type, source, payload, confidence?)`

## Signal types (build your own)

Signal types are free-form strings. Use a namespaced convention:

```
churn_risk          — user about to leave
bid_velocity        — auction bidding pace change
low_inventory       — item almost sold out
session_idle        — participant inactive
user_intent         — intent classified by ML
fraud_detected      — fraud signal from risk model
```

## Writing rules

Rules are stored per tenant. Use `set_rules` to replace all rules atomically (it's destructive — always read current rules first):

```typescript
// 1. Read current rules
const { rules } = await rtie.actions.getRules();

// 2. Append or modify
const newRule = {
  name: "Show retention offer on churn risk",
  signalType: "churn_risk",
  conditions: [
    { field: "confidence", op: "gte", value: 0.8 },
    { field: "payload.sessionId", op: "exists" },
  ],
  actionType: "ui_event",
  actionConfig: {
    event: "show_retention_offer",
    target: "session",             // "session" | "user" | "room" | "broadcast"
    payload: { discount: "10%" },
  },
  priority: 10,                   // higher = evaluated first
  enabled: true,
};

// 3. Write back
await rtie.actions.setRules([...rules, newRule]);
```

MCP: `get_rules()` then `set_rules(rules)` — both exposed in the MCP server.

## Rule condition operators

| op | Meaning |
|---|---|
| `eq` | equals |
| `neq` | not equals |
| `gt`, `gte` | greater than, ≥ |
| `lt`, `lte` | less than, ≤ |
| `in` | value in list |
| `exists` | field is present |
| `matches` | regex match |

Fields are dot-path into `signal.payload` or top-level signal fields (`confidence`, `source`, `signal_type`).

## Action types

### `ui_event` — push a UI event to connected clients

```json
{
  "actionType": "ui_event",
  "actionConfig": {
    "event": "show_retention_offer",
    "target": "user",
    "payload": { "discount": "10%" }
  }
}
```

### `agent_trigger` — invoke an AI agent

```json
{
  "actionType": "agent_trigger",
  "actionConfig": {
    "agentId": "agt_auctioneer",
    "message": "Bidding has slowed. Generate an excitement prompt."
  }
}
```

### `module_call` — call a RTIE module API

```json
{
  "actionType": "module_call",
  "actionConfig": {
    "module": "chat",
    "method": "POST",
    "path": "/v1/rooms/{roomId}/messages",
    "body": { "body": "Going once, going twice..." }
  }
}
```

### `state_update` — update SpacetimeDB room state

```json
{
  "actionType": "state_update",
  "actionConfig": {
    "key": "auction_urgency",
    "value": "high"
  }
}
```

## Querying the action log

```typescript
const log = await rtie.actions.getLog({ limit: 100 });
// → [{ signalType, ruleId, actionType, result, latencyMs, createdAt }, ...]
```

MCP: `get_action_log(limit?)`

## How to use the Action Engine with AI agents

The Action Engine is the recommended integration point for ML models and AI agents that need to affect live sessions:

1. Your ML model classifies intent → calls `ingest_signal`
2. Action Engine evaluates rules in <100ms
3. Matching action fires (UI event, agent trigger, module call)
4. All events appear in the action log for debugging

For agentic rule authoring: an AI agent can call `get_rules()`, analyze them, then call `set_rules()` with an improved ruleset. The Action Engine Rule Builder UI in the tenant console provides the same interface visually.

Full docs: https://docs.rtie.ai/modules/actions