Building Your First Agentic KPI Workflow: A Practical Tutorial

In today's data-driven landscape, we're drowning in metrics. We have dashboards for sales, charts for user engagement, and spreadsheets for operational costs. Yet, for many teams, this data remains passive. It sits there, waiting for someone to manually check it, interpret its meaning, and decide what to do. This process is slow, error-prone, and a bottleneck to agile decision-making.

What if your metrics could act for themselves? What if your Key Performance Indicators (KPIs) weren't just numbers on a screen, but automated agents that monitor, analyze, and trigger actions in real-time?

This is the promise of an agentic KPI workflow, a core concept behind KPIs.do. By treating your metrics as code, you can build intelligent, automated services that drive continuous performance improvement.

In this tutorial, we will walk you through building your first agentic KPI workflow. We'll define a common business KPI, automate its tracking from a data source, and configure it to take action when performance changes—transforming a passive metric into an active agent for your business.

Why "Agentic"? From Passive Reports to Active Services

Before we dive in, let's clarify what we mean by an "agentic workflow."

• The Old Way (Passive): You write a SQL query, run it manually, paste the result into a spreadsheet, and share it in a weekly meeting or email. The data is static and its impact depends entirely on human intervention.
• The New Way (Agentic): You define your KPI's logic, targets, and desired actions as a version-controlled configuration file. The KPIs.do platform acts as an agent that:
  1. Observes: Automatically queries your data source on a schedule.
  2. Analyzes: Calculates the KPI value and compares it against pre-defined thresholds.
  3. Acts: Triggers a webhook, sends a Slack notification, creates a PagerDuty incident, or calls another API if a threshold is crossed.

This approach, which we call Performance as a Service, turns your business logic into a reliable, automated service that works for you 24/7.

Our Scenario: Tracking Daily User Sign-Up Velocity

Let's imagine we work for a growing SaaS company and we want to closely monitor our user acquisition engine. We'll create a KPI to track the number of new users signing up each day.

• KPI Name: daily-user-signup-velocity
• Goal: Ensure a healthy and consistent flow of new users.
• Target: An average of 100 new sign-ups per day.
• Agentic Actions:
  • Warning: If sign-ups drop below 75, send an alert to the #growth-team Slack channel.
  • Critical: If sign-ups drop below 50, create a high-priority incident in PagerDuty to wake up the on-call engineer.

Step 1: Define the KPI as Code

The first step is to codify our KPI's logic. With KPIs.do, you can do this in a simple YAML configuration file. This file becomes the single source of truth for this metric, and you can store it in your Git repository alongside your application code.

Create a file named signup-velocity.kpi.yaml:

# signup-velocity.kpi.yaml
name: daily-user-signup-velocity
description: "Tracks the number of new users signing up each day."

# Define the agent's schedule using a cron expression
schedule: "0 0 * * *" # Run every day at midnight UTC

# Connect to our data source
datasource:
  type: postgresql
  connectionString: "${env.DATABASE_URL}" # Use an environment variable for security
  query: |
    SELECT COUNT(id) as value
    FROM users 
    WHERE created_at >= CURRENT_DATE - INTERVAL '1 day' 
      AND created_at < CURRENT_DATE;

# Define the agentic behavior with thresholds and actions
thresholds:
  - level: warning
    condition: "value < 75"
    message: "⚠️ Daily sign-ups fell to {{value}}, below the warning threshold of 75."
    actions:
      - name: "notify-growth-slack"

  - level: critical
    condition: "value < 50"
    message: "🚨 CRITICAL: Daily sign-ups plummeted to {{value}}! This requires immediate attention."
    actions:
      - name: "alert-pagerduty-oncall"

In this file, we've defined everything our agent needs to know: what to measure (query), when to measure it (schedule), and what to do with the result (thresholds).

Step 2: Configure the Actions

Our KPI definition references two actions: notify-growth-slack and alert-pagerduty-oncall. These are reusable components you configure within the KPIs.do platform.

For example, the configuration for the Slack webhook might look like this in the platform's UI or another config file:

Action: notify-growth-slack

• Type: Webhook
• URL: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
• HTTP Method: POST
• Payload:

  {
    "text": "{{kpi.message}}"
  }
  

Here, {{kpi.message}} is a variable that will be replaced with the message from the triggered threshold in our YAML file. This simple but powerful integration is key to unlocking business intelligence automation.

Step 3: Deploy the Workflow and Interact via API

Once you commit and push this kpi.yaml file to your repository connected with KPIs.do (or upload it via the API), your agentic workflow is live. The platform will now automatically execute the query every day at midnight, evaluate the thresholds, and trigger actions if needed.

Your manual, repetitive reporting task is now a fully automated, data-driven service.

But it doesn't stop there. Because KPIs.do is API-first, this newly automated KPI is now an interactive endpoint. You can use our performance tracking API to query its status from anywhere.

For example, you could build an internal CLI tool or a small dashboard to check on the KPI's health:

import { kpis } from 'kpis.do';

async function checkSignupVelocity() {
  const result = await kpis.get({
    name: 'daily-user-signup-velocity',
  });

  console.log(`KPI: ${result.name}`);
  console.log(`Last Checked: ${result.lastCheckedAt}`);
  console.log(`Latest Value: ${result.latestValue}`); // e.g., 82
  console.log(`Status: ${result.status}`); // e.g., 'warning'
}

checkSignupVelocity();

The Result: Continuous Improvement, Automated

With just one configuration file, you have:

1. Tracked a vital business metric automatically.
2. Automated the analysis and alerting process.
3. Enabled a faster path to Improvement by ensuring the right people are notified at the right time.

You've moved beyond passive dashboards and created a proactive agent that actively participates in your operational excellence. This is the power of KPI automation. By treating your metrics with the same rigor as your application code, you build a more responsive, resilient, and data-aware organization.

Ready to stop chasing metrics and start putting them to work?

Explore the KPIs.do documentation to learn more, or sign up for free to build your first agentic workflow in minutes.