SDK customData → CustomDataConfig (Schema) → Context Variable → KPI Formula → kpiData

// ONLY include fields you'll register as CustomDataConfigs
customData: {
  // Business metrics (will become KPIs)
  ItemsProcessed: number,  // Count of items handled
  SuccessRate: number,     // 0-1 success ratio

  // Performance metrics (will become KPIs)
  StepCount: number,       // Number of workflow steps

  // Identification (for filtering, not KPIs)
  ExecutionId: string,     // Correlation ID
}

customData: {
  sessionId: session.id,       // ❌ Already tracked
  agentId: agentConfig.id,     // ❌ Already tracked
  userEmail: user.email,       // ❌ Pass via userEmail param instead
  timestamp: Date.now(),       // ❌ Already tracked
  ItemsProcessed: 10,          // ✅ Needed for KPI
}

customData: {
  ItemsProcessed: 10,          // ✅ Used in KPI formula
  SuccessRate: 1.0,            // ✅ Used in KPI formula
  ExecutionId: uuid,           // ✅ For correlation/filtering
}

# Create the workflow first
olakai workflows create --name "Your Workflow Name" --json

# Save the workflow ID for agent association
# Output: { "id": "wfl_xxx...", "name": "Your Workflow Name" }

# Create the agent associated with the workflow
olakai agents create \
  --name "Your Agent Name" \
  --description "What this agent does" \
  --workflow WORKFLOW_ID \
  --with-api-key \
  --json

# Returns agent details including apiKey for SDK use:
# {
#   "id": "cmkbteqn501kyjy4yu6p6xrrx",
#   "name": "Your Agent Name",
#   "workflowId": "wfl_xxx...",
#   "apiKey": "sk_agent_xxxxx..."   <-- Use this in your SDK
# }

# To retrieve an existing agent's API key:
olakai agents get AGENT_ID --json | jq '.apiKey'

Workflow: "Customer Support Pipeline"
├── Agent: "Ticket Classifier"
├── Agent: "Response Generator"
└── Agent: "Quality Checker"

Workflow: "Document Processing"
└── Agent: "Document Summarizer"  ← Even single agents need a workflow

# Replace YOUR_AGENT_ID with the actual agent ID from step 2.1

# For numeric metrics (can be used in KPI calculations)
olakai custom-data create --agent-id YOUR_AGENT_ID --name "ItemsProcessed" --type NUMBER --description "Count of items processed per run"
olakai custom-data create --agent-id YOUR_AGENT_ID --name "SuccessRate" --type NUMBER --description "Success ratio 0-1"
olakai custom-data create --agent-id YOUR_AGENT_ID --name "StepCount" --type NUMBER --description "Number of workflow steps executed"

# For string metrics (for filtering/grouping, not calculations)
olakai custom-data create --agent-id YOUR_AGENT_ID --name "ExecutionId" --type STRING --description "Correlation ID for the execution"

# Verify all configs are created for this agent
olakai custom-data list --agent-id YOUR_AGENT_ID

# Simple variable KPIs
olakai kpis create \
  --name "Items Processed" \
  --agent-id YOUR_AGENT_ID \
  --calculator-id formula \
  --formula "ItemsProcessed" \
  --unit "items" \
  --aggregation SUM

# Calculated KPIs
olakai kpis create \
  --name "Success Rate" \
  --agent-id YOUR_AGENT_ID \
  --calculator-id formula \
  --formula "SuccessRate * 100" \
  --unit "%" \
  --aggregation AVERAGE

# Conditional KPIs
olakai kpis create \
  --name "Error Count" \
  --agent-id YOUR_AGENT_ID \
  --calculator-id formula \
  --formula "IF(SuccessRate < 1, 1, 0)" \
  --unit "errors" \
  --aggregation SUM

# Validate formulas before creating
olakai kpis validate --formula "ItemsProcessed" --agent-id YOUR_AGENT_ID

npm install @olakai/sdk openai

import { OlakaiSDK } from "@olakai/sdk";
import OpenAI from "openai";

// Initialize Olakai
const olakai = new OlakaiSDK({
  apiKey: process.env.OLAKAI_API_KEY!,
  debug: process.env.NODE_ENV === "development",
});
await olakai.init();

// Wrap your LLM client
const openai = olakai.wrap(
  new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
  {
    provider: "openai",
    defaultContext: {
      task: "Your Task Category", // e.g., "Data Processing & Analysis"
    },
  }
);

// Use wrapped client - monitoring happens automatically
const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: userPrompt }],
});

async function runAgent(input: string): Promise<string> {
  const startTime = Date.now();
  const executionId = crypto.randomUUID();
  let totalTokens = 0;
  let stepCount = 0;
  let itemsProcessed = 0;

  try {
    // Step 1: Planning
    stepCount++;
    const plan = await openai.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: `Plan: ${input}` }],
    });
    totalTokens += plan.usage?.total_tokens ?? 0;

    // Step 2: Execution (example: process multiple items)
    const items = parseItems(plan.choices[0].message.content);
    for (const item of items) {
      stepCount++;
      const result = await openai.chat.completions.create({
        model: "gpt-4o",
        messages: [{ role: "user", content: `Process: ${item}` }],
      });
      totalTokens += result.usage?.total_tokens ?? 0;
      itemsProcessed++;
    }

    // Step 3: Summarize
    stepCount++;
    const summary = await openai.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Summarize results" }],
    });
    totalTokens += summary.usage?.total_tokens ?? 0;

    const finalResponse = summary.choices[0].message.content ?? "";

    // Track the complete workflow as a single event
    // ⚠️ IMPORTANT: Only send fields that have CustomDataConfigs (from Step 2.2)
    olakai.event({
      prompt: input,
      response: finalResponse,
      tokens: totalTokens,
      requestTime: Date.now() - startTime,
      task: "Data Processing & Analysis",
      customData: {
        // Only include fields registered in Step 2.2
        ExecutionId: executionId,
        StepCount: stepCount,
        ItemsProcessed: itemsProcessed,
        SuccessRate: 1.0,
        // ❌ DON'T add unregistered fields - they can't be used in KPIs
      },
    });

    return finalResponse;
  } catch (error) {
    // Track failed execution - same fields, different values
    olakai.event({
      prompt: input,
      response: `Error: ${error instanceof Error ? error.message : "Unknown"}`,
      tokens: totalTokens,
      requestTime: Date.now() - startTime,
      task: "Data Processing & Analysis",
      customData: {
        ExecutionId: executionId,
        StepCount: stepCount,
        ItemsProcessed: itemsProcessed,
        SuccessRate: 0,  // 0 indicates failure
      },
    });
    throw error;
  }
}

pip install olakai-sdk openai

import os
from olakaisdk import olakai_config, instrument_openai, olakai_context, olakai_event, OlakaiEventParams
from openai import OpenAI

# Initialize Olakai
olakai_config(os.getenv("OLAKAI_API_KEY"))
instrument_openai()

# Create OpenAI client (automatically instrumented)
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

# For assistive AI - use context manager
with olakai_context(userEmail="user@example.com", task="Customer Support"):
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": user_message}]
    )

import time
import uuid

def run_agent(input_text: str) -> str:
    start_time = time.time()
    execution_id = str(uuid.uuid4())
    total_tokens = 0
    step_count = 0
    items_processed = 0

    try:
        # Your workflow steps here...
        step_count += 1
        response = client.chat.completions.create(
            model="gpt-4",
            messages=[{"role": "user", "content": input_text}]
        )
        total_tokens += response.usage.total_tokens

        final_response = response.choices[0].message.content

        # Track successful execution
        # ⚠️ Only send fields registered as CustomDataConfigs
        olakai_event(OlakaiEventParams(
            prompt=input_text,
            response=final_response,
            tokens=total_tokens,
            requestTime=int((time.time() - start_time) * 1000),
            task="Data Processing & Analysis",
            customData={
                "ExecutionId": execution_id,
                "StepCount": step_count,
                "ItemsProcessed": items_processed,
                "SuccessRate": 1.0,
            }
        ))

        return final_response

    except Exception as e:
        # Track failed execution - same fields, different values
        olakai_event(OlakaiEventParams(
            prompt=input_text,
            response=f"Error: {str(e)}",
            tokens=total_tokens,
            requestTime=int((time.time() - start_time) * 1000),
            task="Data Processing & Analysis",
            customData={
                "ExecutionId": execution_id,
                "StepCount": step_count,
                "ItemsProcessed": items_processed,
                "SuccessRate": 0,  # 0 indicates failure
            }
        ))
        raise

# ⚠️ customData fields must match registered CustomDataConfigs exactly
curl -X POST "https://app.olakai.ai/api/monitoring/prompt" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "prompt": "User input here",
    "response": "Agent response here",
    "app": "your-agent-name",
    "task": "Data Processing & Analysis",
    "tokens": 1500,
    "requestTime": 5000,
    "customData": {
      "ExecutionId": "abc-123",
      "StepCount": 5,
      "ItemsProcessed": 10,
      "SuccessRate": 1.0
    }
  }'

// Run your agent
const result = await runAgent("Test input for validation");
console.log("Agent completed, checking Olakai...");

# List recent activity for your agent
olakai activity list --agent-id YOUR_AGENT_ID --limit 1 --json

# Get the full event details including customData and kpiData
olakai activity get EVENT_ID --json

olakai activity get EVENT_ID --json | jq '.customData'

{
  "ExecutionId": "abc-123",
  "StepCount": 5,
  "ItemsProcessed": 10,
  "SuccessRate": 1.0
}

olakai activity get EVENT_ID --json | jq '.kpiData'

{
  "Items Processed": 10,
  "Success Rate": 100
}

{
  "Items Processed": "itemsProcessed",
  "Success Rate": "SuccessRate"
}

olakai kpis update KPI_ID --formula "YourVariable"

┌─────────────────────────────────────────────────────────┐
│  1. Run agent (generate event)                          │
│                    ↓                                    │
│  2. Fetch event: olakai activity get ID --json          │
│                    ↓                                    │
│  3. Check customData present?                           │
│     NO → Fix SDK code, goto 1                           │
│                    ↓                                    │
│  4. Check kpiData numeric (not strings)?                │
│     NO → Fix formula: olakai kpis update ID --formula   │
│          goto 1                                         │
│                    ↓                                    │
│  5. Check kpiData not null?                             │
│     NO → Create CustomDataConfig or fix field name      │
│          goto 1                                         │
│                    ↓                                    │
│  ✅ All validations pass - implementation complete      │
└─────────────────────────────────────────────────────────┘

# 1. Run your agent (generates event)
$ node my-agent.js "Test task"
Agent completed successfully

# 2. Get the latest event
$ olakai activity list --agent-id cmkxxx --limit 1 --json | jq '.prompts[0].id'
"cmkeyyy"

# 3. Inspect the event
$ olakai activity get cmkeyyy --json | jq '{customData, kpiData}'
{
  "customData": {
    "StepCount": 3,
    "ItemsProcessed": 5,
    "SuccessRate": 1
  },
  "kpiData": {
    "Steps Executed": 3,        # ✅ Numeric
    "Items Processed": 5,       # ✅ Numeric
    "Success Rate": 100         # ✅ Numeric (formula: SuccessRate * 100)
  }
}

# ✅ All good! Implementation is correct.

# Simple variable passthrough
--formula "ItemsProcessed"

# Percentage conversion (0-1 to 0-100)
--formula "SuccessRate * 100"

# Conditional counting (count failures)
--formula "IF(SuccessRate < 1, 1, 0)"

# Boolean to number conversion
--formula "IF(PII detected, 1, 0)"

# Null-safe with default value
--formula "IF(ISDEFINED(MyField), MyField, 0)"

# Compound conditions
--formula "IF(AND(StepCount > 5, SuccessRate < 0.9), 1, 0)"

# CLI Commands
olakai login                           # Authenticate
olakai agents create --name "Name"     # Create agent
olakai custom-data create --agent-id ID --name X --type NUMBER  # Create custom field
olakai kpis create --formula "X" --agent-id ID    # Create KPI
olakai activity list --agent-id ID     # View events

# SDK Initialization (TypeScript)
const olakai = new OlakaiSDK({ apiKey: process.env.OLAKAI_API_KEY });
await olakai.init();
const openai = olakai.wrap(new OpenAI({ apiKey }), { provider: "openai" });

# SDK Initialization (Python)
olakai_config(os.getenv("OLAKAI_API_KEY"))
instrument_openai()