AI Actors

An AI Actor is an LLM-driven monitoring agent attached to a single data source. Given high-level instructions (“monitor transactions for unusual activity”), it autonomously creates queries and subscriptions, analyzes results, refines its own monitoring over time, and flags findings for notification — with a human approval workflow gating its proposed changes.

Overview

What an AI Actor does:

Designs SQL monitoring queries against your data source schema based on your plain-English instructions
Creates Subscriptions so those queries run on a schedule
Runs a think cycle after subscription executions: analyzes recent results and decides whether to create, refine, or archive queries and subscriptions
Records every decision, action, token count, and cost in an execution history
Proposes plans — reviewable bundles of analysis + proposed actions — that a human approves, rejects, or sends back for revision

What an AI Actor cannot do:

Modify queries it doesn’t own — refinements only apply to queries created by that actor
Modify locked queries — locked query IDs are excluded in the prompt and hard-checked again at execution time
Exceed its configured limits (MaxQueries, MaxSubscriptionsPerQuery)

All LLM calls go through the configured provider (see AI Integration) and are metered — each actor tracks total tokens used and estimated cost.

Creating an Actor

Go to AI Actors in the React UI (/ai-actors) and create a new actor:

Field	Description	Default
Name	Display name for the actor	— (required)
Instructions	High-level monitoring goal, e.g. “monitor for failed payments”	— (required)
Data source	The single data source this actor monitors	— (required)
Additional context	Business rules, table hints, monitoring requirements	None
Max queries	Maximum queries the actor may create	10
Max subscriptions per query	Maximum subscriptions per query	3
Default recipients	Notification recipients for created subscriptions	None
Activate immediately	Run initial setup right away	Yes

When activated immediately, the actor runs an initial setup: the LLM reads the data source schema and your instructions, then creates a first set of monitoring queries and subscriptions. If setup fails, the actor moves to Failed status with the error recorded in its Last error field.

The REST endpoint is POST /beacon/api/ai-actors (one MediatR handler per endpoint, like the rest of the API).

Actor Statuses

Status	Meaning
`Draft`	Being configured, not yet active
`Active`	Will run a think cycle after its subscriptions execute
`Paused`	Temporarily suspended — no think cycles run
`Failed`	A think cycle or setup failed; the error is stored on the actor
`Archived`	Soft-deleted, no longer active

Pause, resume, and archive are available from the actor’s edit page and via POST /beacon/api/ai-actors/{id}/pause, /resume, and DELETE /beacon/api/ai-actors/{id}.

The Think Cycle

A think cycle is one autonomous reasoning pass. It is triggered:

Automatically — when a subscription owned by an Active actor finishes executing, a think cycle is enqueued as a background job so the subscription pipeline never blocks on LLM round-trips. Paused, draft, or failed actors are skipped.
Manually — via the actor detail page or POST /beacon/api/ai-actors/{id}/think.

Each cycle is persisted as an execution record that moves through these phases:

Phase	What happens
`Analyzing`	Gathers the data source schema, the actor’s existing queries, and recent subscription results
`Planning`	Sends the context to the LLM, which returns an analysis, findings, and a list of actions
`Executing`	Applies the actions (create/refine/archive queries and subscriptions)
`Notifying`	Records notification intent if the LLM flagged important findings
`Completed`	Cycle finished successfully
`Failed`	Cycle failed — the error is stored and the actor moves to `Failed` status

The actions an actor can take:

Action	Description
`CreateQuery`	Create a new monitoring query
`CreateSubscription`	Schedule an existing query via a subscription
`RefineQuery`	Update the SQL of a query the actor owns
`ArchiveQuery`	Retire an underperforming query
`ArchiveSubscription`	Retire a subscription that is no longer needed
`SendNotification`	Flag important findings for notification

Every execution stores the LLM’s decision summary, detailed analysis (markdown), key findings, per-action results, tokens used, estimated cost, and the model that generated it. The actor detail page shows this execution history along with cumulative think count, token, and cost totals.

Refining an Actor

You can steer an actor conversationally. From the actor’s edit page (or POST /beacon/api/ai-actors/{id}/refine), submit feedback such as:

“Focus on orders over $10,000 and check for duplicate payment attempts”

The feedback is stored in the actor’s conversation history, sent to the LLM together with the current schema and query context, and the actor adjusts its queries and subscriptions accordingly.

Plans and the Approval Workflow

Instead of acting silently, an actor can propose a plan: a reviewable record containing its analysis, key findings, and the exact actions it wants to take. Plans are the human-in-the-loop mechanism — a plan’s actions are executed only after a human approves it. While a plan is pending, nothing in it runs.

Each actor carries a Requires approval setting (on by default), shown on the actor detail page.

Plan contents

A plan stores:

The actor’s analysis of the current state (markdown)
Key findings (e.g. “Current query returns 0 results”)
Proposed actions with per-action reasoning — for query refinements this includes the current SQL, the proposed SQL, and whether the target query is locked
The user instruction that triggered it (if any), token usage, estimated cost, and the model used
A version number and a link to its parent plan when it is a revision

Depending on how it was generated, a plan can represent the actor’s initial setup, a reaction to a subscription execution, or a response to a user instruction.

Plan statuses

Status	Meaning
`PendingApproval`	Awaiting human review — no actions have run
`Executing`	Approved; actions are currently being applied
`Executed`	Approved and fully executed
`Rejected`	Declined by the reviewer (also set if execution fails after approval)
`Expired`	Expired before review (e.g. context changed)
`RevisionRequested`	Reviewer asked for changes — a new revision is generated

Reviewing a plan

Pending plans for an actor are listed via GET /beacon/api/ai-actors/{id}/pending-plans; a single plan (with its full analysis and proposed actions) via GET /beacon/api/ai-actors/plans/{id}. The actor detail page shows the pending plan count.

The reviewer has three options:

Approve — POST /beacon/api/ai-actors/plans/{id}/approve (optional comment)

The plan moves to Executing, the reviewer and timestamp are recorded, and an execution record is created and linked to the plan. Actions run one by one; refinements targeting locked queries are skipped and recorded as failed actions. On success the plan becomes Executed; if execution throws, the execution is marked Failed and the plan is marked Rejected.

Reject — POST /beacon/api/ai-actors/plans/{id}/reject (reason required)

The plan moves to Rejected with the reviewer, timestamp, and reason recorded. No actions are executed.

Request revision — POST /beacon/api/ai-actors/plans/{id}/request-revision (feedback required)

The actor generates a fresh plan through a new LLM call that incorporates your feedback. The revision gets an incremented version number, links back to the original plan, and enters PendingApproval again.

Only plans in PendingApproval can be approved, rejected, or revised — any other status returns an error.

Query Change Approvals

Separate from actor plans, Beacon has a general query change approval workflow for edits to query SQL. When the approval workflow is enabled in configuration (EnableApprovalWorkflow() / the ApprovalWorkflow options on BeaconConfiguration), any change to a query’s SQL is intercepted:

Instead of applying the edit, Beacon creates a new query version in PendingApproval status — the live query keeps running unchanged.
An approval request appears at Approvals in the React UI (/approvals), showing the change summary and who requested it.
A reviewer opens the request (/approvals/{id}), compares the current active version with the proposed one, and approves or rejects with an optional comment.
Approve archives the current active version and activates the proposed one. Reject leaves the active version untouched.

The REST endpoints are GET /beacon/api/approvals/pending, GET /beacon/api/approvals/{id}, and POST /beacon/api/approvals/{id}/approve / /reject. Approve and reject require the Admin role.

This workflow also protects you when an AI Actor’s changes touch queries governed by versioning — every SQL change is versioned, so you can always see what changed and roll back through query versions. See Queries for the versioning model.

Real-Time Updates (`ApprovalUpdated`)

Approval decisions are pushed in real time over the SignalR hub at /beacon/api/hub. When a query change approval is approved or rejected, the server sends an ApprovalUpdated event:

{ "approvalId": 42, "status": "approved" }

Delivery is targeted, not broadcast: only the reviewer (so their other open tabs update) and the requester (so they see the decision live) receive the event. In the React shell, ApprovalUpdated invalidates the approvals cache, so the approvals list and detail pages refresh automatically without a manual reload. Events missed during a transient disconnect are reconciled when the connection comes back.

Cost Tracking

Every LLM interaction is metered:

Per execution / per plan — tokens used, estimated cost, and the model that generated it
Per actor — cumulative TotalTokensUsed and TotalCost across all think cycles, shown on the actor detail page

Use the actor’s limits (MaxQueries, MaxSubscriptionsPerQuery) plus the global LLM rate limits described in AI Integration to keep costs bounded.

Troubleshooting

Actor is in Failed status — A think cycle or initial setup threw an error — check the Last error field on the actor detail page. Fix the underlying issue (often LLM configuration or data source connectivity), then resume the actor.

“Plan is not pending approval” error — The plan was already approved, rejected, revised, or expired. Only PendingApproval plans accept decisions — fetch the actor’s pending plans for the current revision.

A refinement in an approved plan failed with “Query is locked” — Locked queries cannot be modified by AI. This is by design — the rest of the plan still executes, and the skipped action is recorded with its error message.

Actor never thinks automatically — Automatic think cycles fire only for Active actors, and only after one of the actor’s own subscriptions executes. Verify the actor is active and its subscriptions are scheduled and running.

Approvals page doesn’t update in real time — ApprovalUpdated is delivered only to the reviewer and requester of that approval. Other users see updates on their next page load or query refetch.

AI Integration — LLM provider configuration, rate limits, cost estimation, and data privacy considerations
Queries — the query and versioning model actors build on
Subscriptions — scheduling and notification pipeline used by actor-created subscriptions
Notifications — how findings reach recipients
Data Sources — connect the data source an actor monitors