Agents & Runs

Overview

Agents are autonomous analysers that produce insights from document feeds. Each agent is assigned to one or more feeds and, when triggered, processes the documents within those feeds to generate inferences and signals. Agents can be triggered manually, on document upload, or on a cron schedule.

The platform supports multiple agent types — from single-feed analysts to cross-feed synthesisers and compliance checkers. Agents are defined declaratively (type, focus, sensitivity, schedule) and executed by the data plane's research agent service, producing a traceable history of runs.

Key Concepts

• Agent types — feed_analyst (analyses a single feed in depth), cross_feed (synthesises across multiple feeds), compliance (checks documents against rules), anomaly (detects outliers and changes).
• Feed assignments — Agents are assigned to feeds with a role: primary (drives analysis) or monitor (provides background context).
• Sensitivity — Controls LLM temperature and threshold decisions. low produces fewer, higher-confidence findings; high casts a wider net.
• Schedule types — manual (user-triggered), on_document (fires when new documents arrive in assigned feeds), cron (runs on a schedule via cronExpression).
• Runs — Each execution is a separate agent_run record with status tracking, timing, and output metrics.

Data Model

agents

agent_feed_assignments

Primary key: (agentId, feedId)

agent_runs

How It Works

1. Agent created — A user (or the agent suggestion system) defines an agent with a type, focus, and sensitivity.
2. Feeds assigned — The agent is linked to one or more feeds via agent_feed_assignments, each with a role of primary or monitor.
3. Trigger fires — The agent is triggered by its schedule type: the user clicks "Run", a new document arrives in an assigned feed, or the cron expression matches.
4. Run created — An agent_run record is created with status queued. The run transitions to running when the worker picks it up.
5. Documents analysed — The research agent service loads documents from assigned feeds, prioritising primary feeds over monitor feeds.
6. Inferences produced — The agent generates inferences — analytical findings with evidence, confidence scores, and significance levels.
7. Signals evaluated — The signal worker checks whether any inferences trigger signal rules, producing signals if conditions are met.
8. Run completed — The run record is updated with completedAt, inferencesCreated, signalsRaised, and a summary.

Why It Works This Way

Feed Assignment Roles

The primary/monitor distinction lets an agent weight its data sources. A "Market Analysis" agent might have a "Competitor Reports" feed as primary and a "News" feed as monitor. The primary feed drives the analysis agenda; the monitor feed provides supplementary context. This avoids the noise problem where too many equally-weighted sources dilute analytical focus.

Sensitivity as a Dial, Not a Prompt

The sensitivity field adjusts LLM temperature and confidence thresholds without changing the agent's prompt text. This means the same agent definition can be tuned to produce fewer high-confidence findings (low) or more exploratory findings (high) without rewriting instructions. It keeps the configuration surface small for users who are not prompt engineers.

Runs as a Separate Entity

Separating agent definitions from run records gives you a traceable history. You can see how the same agent's findings have changed over time, compare runs triggered by different events, and debug failures without losing the agent's configuration. It also enables retry semantics — a failed run can be re-queued without modifying the agent.

Agent Suggestion System

The platform can suggest agents based on the feeds and documents in a space. This uses the same pattern as feed suggestion — the AI analyses the content landscape and proposes agents with appropriate types, focus areas, and feed assignments. The agentsGeneratedAt field on spaces tracks when this last ran.

Code Reference

Relationships

• Spaces — Every agent belongs to a space; agentsEnabled must be true
• Feeds — Agents are assigned to feeds via agent_feed_assignments
• Inferences & Signals — Agent runs produce inferences, which may trigger signals
• Surfaces & Experiences — Agent run outputs can be rendered as surfaces