Observation Agents

How Observation Works

Observation agents connect to each integrated tool via OAuth and periodically poll for metadata. They operate in read-only mode and never modify data in your systems. Each agent runs in an isolated container with access only to its assigned tool.

Configuration Options

Polling Frequency

Controls how often the agent checks for new data. Higher frequency provides more granular timeline data but increases API usage against your tool's rate limits.

Data Scope

Define which parts of each tool the agent should observe. By default, agents observe all accessible data within the granted OAuth scope. You can narrow this to specific channels, projects, or repositories.

{
  "type": "observation",
  "tool": "slack",
  "config": {
    "pollingFrequency": "standard",
    "scope": {
      "channels": ["#engineering", "#product", "#general"],
      "excludeChannels": ["#random", "#social"],
      "includeDMs": false
    },
    "lookbackDays": 90
  }
}

Lookback Period

When an agent first connects, it pulls historical data to establish baseline patterns. The lookback period controls how far back it reaches. Longer lookback periods provide better baselines but take longer to process.

• 30 days: Quick setup, limited baseline (not recommended)
• 90 days: Good balance of speed and baseline quality (default)
• 180 days: Comprehensive baseline, recommended for seasonal businesses
• 365 days: Full year baseline, useful for annual cycle analysis

Privacy Filters

Observation agents apply privacy filters at the point of collection. You can configure additional filters to exclude specific data:

• Channel exclusions: Exclude sensitive channels from observation
• User exclusions: Exclude specific users (e.g., executive leadership)
• Keyword filters: Drop any metadata records containing specified keywords
• Time windows: Only observe during business hours

Monitoring

Each observation agent reports health metrics to the dashboard:

• Connection status: Connected, disconnected, or rate-limited
• Data points collected: Running count of metadata records
• Last poll time: When the agent last successfully checked for data
• Error rate: Percentage of failed API calls in the last 24 hours

Next: Diagnosis Engine — how collected data is analyzed for patterns.