> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# KPI Monitoring & Reporting

> Build intelligence layers using search-chat-history to monitor and report on agent performance

## Overview

The `searchChatHistory` tool transforms your agent executions into a queryable data warehouse. Every agent run creates a permanent record that can be analyzed, aggregated, and reported on by other agents.

## How Search-Chat-History Works

### Technical Implementation

```typescript theme={null}
searchChatHistory({
  query: "daily-sales-collector revenue metrics",  // Text search query
  sort: "recent" | "relevant"                      // Sort preference
})

// Returns:
{
  messages: [/* AI assistant messages */],
  documents: [/* Uploaded documents */],
  count: { messages: 20, documents: 5, total: 25 },
  results: "Formatted markdown string of results"
}
```

### Search Capabilities

1. **Full-text search** across all agent outputs
2. **Semantic matching** - finds conceptually related content
3. **Time-based filtering** - recent vs relevant sorting
4. **Execution context** - can filter by specific scheduler IDs
5. **Multi-format** - searches both messages and documents

## KPI Monitoring Patterns

### Pattern 1: Daily Aggregation

```yaml theme={null}
Hourly-Metrics-Collector:
  Schedule: Every hour
  Steps:
    1. Pull current metrics from database
    2. Calculate hourly KPIs
    3. Save results with timestamp

Daily-KPI-Reporter:
  Schedule: Daily at 6 PM
  Steps:
    1. Search chat history: "Hourly-Metrics-Collector KPIs today"
    2. Aggregate 24 hourly reports into daily summary
    3. Generate trend analysis and email to stakeholders
```

### Pattern 2: Exception Monitoring

```yaml theme={null}
Transaction-Processor:
  Schedule: Every 15 minutes
  Steps:
    1. Process pending transactions
    2. Log any failures or anomalies
    3. Continue processing

Anomaly-Detector:
  Schedule: Every hour
  Steps:
    1. Search: "Transaction-Processor failures OR anomalies"
    2. If count > threshold, trigger alerts
    3. Compile root cause analysis
```

### Pattern 3: Performance Benchmarking

```yaml theme={null}
API-Performance-Monitor:
  Schedule: Every 5 minutes
  Steps:
    1. Test API endpoints
    2. Record response times
    3. Log: "Endpoint: /api/users, Time: 145ms, Status: healthy"

Performance-Analyzer:
  Schedule: Daily
  Steps:
    1. Search: "API-Performance-Monitor response times"
    2. Calculate percentiles (p50, p95, p99)
    3. Compare against SLA thresholds
    4. Generate performance report
```

## Advanced Search Strategies

### 1. Structured Output Parsing

Train your agents to output structured data for easier parsing:

```javascript theme={null}
// Metrics agent output format
"METRICS_REPORT_START
Date: 2024-01-15
Revenue: $45,231
Orders: 156
Conversion: 3.2%
TopProduct: Widget-A
METRICS_REPORT_END"

// Search query
"METRICS_REPORT_START Revenue Orders between METRICS_REPORT_END"
```

### 2. Tag-Based Organization

Use consistent tags for categorization:

```javascript theme={null}
// Agent output
"#SALES-KPI #Q1-2024 #REGION-WEST
Revenue increased 15% to $2.3M
New customers: 45
Churn rate: 2.1%"

// Search queries
"#SALES-KPI #Q1-2024"  // All Q1 sales KPIs
"#REGION-WEST churn"   // Western region churn data
```

### 3. Hierarchical Reporting

Build reporting chains that progressively summarize:

```
Level 1: Raw data collectors (every 5 min)
    ↓ (hourly aggregation)
Level 2: Hourly summarizers
    ↓ (daily rollup)
Level 3: Daily reporters
    ↓ (weekly analysis)
Level 4: Weekly trend analyzer
    ↓ (monthly executive summary)
Level 5: Monthly board report
```

## Real-World KPI Monitoring Examples

### Example 1: E-commerce Operations Dashboard

```yaml theme={null}
Order-Monitor (runs every 10 min):
  1. Check new orders in Shopify
  2. Log: "Orders: 12, Revenue: $1,847, Avg: $154"
  3. Flag any orders over $500

Inventory-Checker (runs hourly):
  1. Scan low-stock items
  2. Log: "Low stock alerts: 3 items below threshold"
  3. Create reorder recommendations

Customer-Satisfaction-Tracker (runs daily):
  1. Pull NPS scores and reviews
  2. Log: "NPS: 72, Reviews: 4.3/5, Complaints: 2"
  3. Identify trending issues

Operations-Dashboard-Compiler (runs every 4 hours):
  1. Search: "Order-Monitor Orders Revenue"
  2. Search: "Inventory-Checker low stock"
  3. Search: "Customer-Satisfaction-Tracker NPS"
  4. Compile into dashboard update
  5. Post to Slack #ops-metrics channel
```

### Example 2: Sales Team Performance Tracking

```yaml theme={null}
Call-Logger (triggered by each sales call):
  1. Log call duration and outcome
  2. Record: "Rep: John, Duration: 23min, Result: Qualified"
  3. Update CRM

Daily-Activity-Summarizer (runs at 5 PM):
  1. Search: "Call-Logger Rep Duration today"
  2. Calculate per-rep metrics
  3. Log: "Team totals: 145 calls, 23 qualified, 15.8% rate"

Weekly-Performance-Analyzer (runs Monday morning):
  1. Search: "Daily-Activity-Summarizer Team totals past week"
  2. Calculate week-over-week changes
  3. Identify top and bottom performers
  4. Generate coaching recommendations
  5. Email sales managers
```

### Example 3: DevOps Monitoring Chain

```yaml theme={null}
Health-Checker (every 2 min):
  1. Ping all services
  2. Log: "API: 99.9% uptime, DB: 100%, CDN: 99.7%"
  3. Check error rates

Deploy-Monitor (on each deployment):
  1. Log deployment details
  2. Record: "Version 2.3.1 deployed, 0 rollbacks"
  3. Monitor post-deploy metrics

Incident-Detector (every 15 min):
  1. Search: "Health-Checker uptime below 99.5"
  2. Search: "Deploy-Monitor rollbacks"
  3. Correlate issues with recent deploys
  4. Create incident reports if needed

SLA-Reporter (monthly):
  1. Search: "Health-Checker uptime" for entire month
  2. Calculate aggregate SLA compliance
  3. Generate customer-facing SLA report
  4. Identify improvement areas
```

## Building Effective KPI Search Queries

### Query Construction Tips

1. **Be Specific with Agent Names**

   ```
   ✓ "sales-tracker revenue Q1"
   ✗ "revenue Q1"  (might return unrelated results)
   ```

2. **Use Consistent Terminology**

   ```
   # All agents should use same terms
   Revenue (not Sales/Income/Earnings)
   Conversion Rate (not Conversion/CVR/Conv%)
   ```

3. **Include Time Markers**

   ```
   "performance-monitor response time 2024-01-15"
   "cost-analyzer spending #week-03"
   ```

4. **Leverage Natural Language**
   ```
   "customer-feedback negative sentiment about shipping"
   "error-logger critical failures in payment processing"
   ```

## Visualization and Reporting

### Creating Report Agents

```yaml theme={null}
Visual-Report-Generator:
  Steps:
    1. Search multiple KPI sources
    2. Transform data into chart-friendly format
    3. Generate HTML report with charts
    4. Save to shared drive
    5. Email link to stakeholders

Example Output Structure:
{
  "title": "Weekly Operations Report",
  "metrics": {
    "revenue": {
      "current": 125000,
      "previous": 115000,
      "change": "+8.7%"
    },
    "orders": {
      "current": 856,
      "previous": 798,
      "change": "+7.3%"
    }
  },
  "charts": [
    {"type": "line", "data": [...], "title": "Revenue Trend"},
    {"type": "bar", "data": [...], "title": "Order Volume"}
  ]
}
```

### Integration with BI Tools

```yaml theme={null}
BI-Data-Exporter:
  Schedule: Daily at 2 AM
  Steps:
    1. Search all KPI agents from past 24h
    2. Format data for BI tool (CSV/JSON)
    3. Upload to data warehouse
    4. Trigger BI tool refresh
    5. Log: "Exported 1,247 KPI records to BigQuery"
```

## Performance Optimization

### 1. Search Query Optimization

* Use specific agent names to narrow search scope
* Leverage time-based sorting for recent data
* Limit result size when only need latest values

### 2. Data Structure Standardization

```javascript theme={null}
// Standardized KPI format all agents should follow
{
  "metric_type": "revenue|orders|users|performance",
  "timestamp": "ISO-8601",
  "value": number,
  "unit": "USD|count|ms|percentage",
  "dimensions": {
    "region": "west",
    "product": "widget-a"
  }
}
```

### 3. Caching Strategies

```yaml theme={null}
KPI-Cache-Builder:
  Schedule: Every hour
  Steps: 1. Search and aggregate frequent KPIs
    2. Store in knowledge base with TTL
    3. Other agents check cache first
```

## Best Practices

1. **Consistent Naming Convention**

   * Use descriptive agent names: `region-west-sales-tracker`
   * Include metric type in output: `METRIC:revenue VALUE:12000`

2. **Time Window Management**

   * Always include timestamps in outputs
   * Use consistent time zones (UTC recommended)
   * Plan for time-based aggregations

3. **Error Handling**

   * Log both successes and failures
   * Include error context for debugging
   * Build separate error-monitoring agents

4. **Data Retention**
   * Consider search performance vs history depth
   * Archive old data before deletion
   * Plan for compliance requirements

## Related Documentation

* [Micro-Agent Concepts](micro-agent-concepts) - Core architecture and chaining patterns
* [Context Management](micro-agent-context-verification) - How context flows between agents
* [Multi-User Verification](micro-agent-multi-user-verification) - Distributed approval workflows
* [Advanced Use Cases](micro-agent-use-cases-tips) - Creative applications and optimization tips

***

*Need help setting up KPI monitoring? Check our [agent creation guide](/agents/creating) or contact [support](/support/contact).*