new-project

使用 Olakai 构建新的 AI Agent 项目

本指南将带你创建一个与 Olakai 完全集成的新 AI Agent，用于分析、KPI 跟踪和治理。

前提条件

开始之前，请确保：

1. 已安装 Olakai CLI：npm install -g olakai-cli
2. CLI 已完成身份验证：olakai login
3. SDK 的 API 密钥（通过 CLI 为每个 Agent 生成 — 请参阅步骤 2.2）

为什么自定义 KPI 至关重要

Olakai 的核心价值在于跟踪 AI Agent 的业务专属 KPI。没有 KPI，你只能跟踪事件，却无法获得可采取行动的洞察。

KPI 可以衡量的内容：

• 业务结果（处理项数、成功率、收入影响）
• 运营数据（步骤数、重试率、执行时间）
• 质量指标（错误率、用户满意度信号）

未配置 KPI 时：

• 除基本令牌数外，没有仪表板 KPI
• 没有汇总的性能视图
• 没有告警阈值
• 无法计算 ROI

每个 Agent 都应有 2-4 个 KPI，用来回答：“我如何判断这个 Agent 是否表现良好？”

此处创建的 KPI 仅属于这个特定 Agent。 如果之后创建其他 Agent，每个 Agent 都需要自己的 KPI 定义 — KPI 不能跨 Agent 共享或复用。

了解 customData 到 KPI 的处理流程

开始实施之前，请先了解数据在 Olakai 中的流转方式：

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

工作原理

1. customData（SDK）：你随每个事件发送的原始 JSON
2. CustomDataConfig（平台）：定义要处理哪些字段的架构
3. 上下文变量：CustomDataConfig 字段可供公式使用
4. KPI 公式：用于计算值的表达式（例如，SuccessRate * 100）
5. kpiData（响应）：随每个事件返回的已计算 KPI 值

关键规则

规则	后果
只有 CustomDataConfig 字段会成为变量	未注册的 customData 字段不能用于 KPI
公式计算不区分大小写	stepCount、STEPCOUNT、StepCount 在公式中都有效
NUMBER 配置需要数值	不要发送 "5"（字符串），应发送 5（数值）
KPI 按 Agent 唯一归属	每个 KPI 只属于一个 Agent — 每个 Agent 都要单独创建

内置上下文变量（始终可用）

变量	类型	说明
Prompt	字符串	发送给大模型的提示词文本
Response	字符串	大模型的响应文本
Documents count	数字	附加文档的数量
PII detected	布尔值	是否检测到 PII
PHI detected	布尔值	是否检测到 PHI
CODE detected	布尔值	是否检测到代码
SECRET detected	布尔值	是否检测到机密信息

第 1 步：设计 Agent 架构

1.1 确定 Agent 类型

Agentic AI（多步骤自主工作流）：

• 研究 Agent、文档处理器、数据管道
• 将所有内部大模型调用汇总为单个事件进行跟踪
• 侧重工作流级 KPI（总令牌数、总耗时、成功/失败）

Assistive AI（交互式聊天机器人/副驾驶）：

• 客户支持 Agent、编码助手、问答系统
• 将每次交互作为独立事件进行跟踪
• 侧重对话级 KPI（每条消息的令牌数、响应质量）

1.2 设计 KPI 架构（至关重要）

在编写任何 SDK 代码之前，先设计好 KPI。 这样可以确保只发送和跟踪有意义的数据。

步骤 A：确定业务问题

利益相关方需要了解这个 Agent 的哪些情况？

• “它每次运行会处理多少项？”
• “成功率/失败率是多少？”
• “每次执行的效率如何？”

步骤 B：将问题映射到数据字段

业务问题	字段名称	类型	KPI 公式	聚合方式
吞吐量	ItemsProcessed	NUMBER	ItemsProcessed	SUM
可靠性	SuccessRate	NUMBER	SuccessRate * 100	AVERAGE
错误数	SuccessRate	NUMBER	IF(SuccessRate < 1, 1, 0)	SUM
相关性	ExecutionId	STRING	（仅用于筛选）	-

步骤 C：规划 customData 结构

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

  // Performance KPIs
  StepCount: number,       // Number of workflow steps

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

重要：只包含你将注册为 CustomDataConfigs 的字段。未注册的字段会被存储，但不能用于 KPI。

不要在 customData 中包含的内容

Olakai 平台会自动跟踪以下内容——请勿重复添加：

已跟踪	位置	不要作为 customData 发送
会话 ID	主载荷	sessionId
Agent ID	API 密钥关联	agentId
用户邮箱	userEmail 参数	email、userEmail
时间戳	事件元数据	timestamp、createdAt
请求时间	requestTime 参数	duration、latency
Token 数量	tokens 参数	tokenCount
模型	自动检测	model、modelName
提供商	客户端配置	provider

customData 仅用于：

1. KPI 变量——将在公式计算中使用的字段
2. 标记/筛选——将在查询中用于筛选的字段

步骤 2：配置 Olakai 平台

2.1 创建工作流（必需）

每个 Agent 都必须属于一个工作流，即使该工作流中只有这一个 Agent。

olakai workflows create --name "Your Workflow Name" --json
# Output: { "id": "wfl_xxx...", "name": "Your Workflow Name" }

2.2 在 Olakai 中创建 Agent

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

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

Agent-工作流层级结构：

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

Workflow: "Document Processing"
└── Agent: "Document Summarizer"  ← single-agent workflows are valid

2.3 创建自定义数据配置（在编写 SDK 代码之前）

此步骤必须在步骤 3（SDK 集成）之前完成。 只有在此处注册的字段才能用于 KPI 公式。

仅为将在 KPI 中使用或用于筛选的数据创建配置。 不要为已自动跟踪的数据创建配置。

# For numeric fields (can be used in KPI calculations)
olakai custom-data create --agent-id YOUR_AGENT_ID --name "ItemsProcessed" --type NUMBER
olakai custom-data create --agent-id YOUR_AGENT_ID --name "SuccessRate" --type NUMBER
olakai custom-data create --agent-id YOUR_AGENT_ID --name "StepCount" --type NUMBER

# For string fields (for filtering/grouping, not calculations)
olakai custom-data create --agent-id YOUR_AGENT_ID --name "ExecutionId" --type STRING

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

2.4 创建 KPI 定义

使用模板快速入门

无需从头编写公式，可使用预定义的分类器模板：

# List available templates
olakai kpis templates

# Create a classifier KPI from a template
olakai kpis create --name "User Satisfaction" \
  --calculator-id classifier --template-id sentiment_scorer \
  --scope CHAT --agent-id $AGENT_ID

# Create a time-saved estimator
olakai kpis create --name "Time Saved" \
  --calculator-id classifier --template-id time_saved_estimator \
  --scope CHAT --agent-id $AGENT_ID

自定义公式 KPI

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

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

# Conditional counting
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

步骤 3：实现 SDK 集成

3.1 TypeScript 实现

安装依赖项：

npm install @olakai/sdk openai

初始化并跟踪：

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

// Initialize Olakai
olakaiConfig({
  apiKey: process.env.OLAKAI_API_KEY!,
  debug: process.env.NODE_ENV === "development",
});

// Create LLM client
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

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

手动跟踪事件的 Agent 工作流：

taskExecutionId——跨 Agent 任务关联。 每个任务生成一个 taskExecutionId，并在多 Agent 工作流中让所有 Agent 共享该 ID。这样可以将不同 Agent 的事件关联为一个用于分析的逻辑任务。

async function runAgent(input: string): Promise<string> {
  const startTime = Date.now();
  const executionId = crypto.randomUUID();
  const taskExecutionId = 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: Process 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
    // Only send fields that have CustomDataConfigs (from Step 2.3)
    olakai("event", "ai_activity", {
      prompt: input,
      response: finalResponse,
      tokens: totalTokens,
      requestTime: Date.now() - startTime,
      taskExecutionId,
      task: "Data Processing & Analysis",
      customData: {
        ExecutionId: executionId,
        StepCount: stepCount,
        ItemsProcessed: itemsProcessed,
        SuccessRate: 1.0,
      },
    });

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

3.2 Python 实现

安装依赖项：

pip install olakai-sdk openai

初始化并跟踪：

import os
from olakaisdk import olakai_config, olakai, OlakaiEventParams
from openai import OpenAI

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

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

Agent 工作流：

import time
import uuid

def run_agent(input_text: str) -> str:
    start_time = time.time()
    execution_id = str(uuid.uuid4())
    task_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-4o",
            messages=[{"role": "user", "content": input_text}]
        )
        total_tokens += response.usage.total_tokens
        final_response = response.choices[0].message.content

        # Track successful execution
        olakai("event", "ai_activity", OlakaiEventParams(
            prompt=input_text,
            response=final_response,
            tokens=total_tokens,
            requestTime=int((time.time() - start_time) * 1000),
            taskExecutionId=task_execution_id,
            task="Data Processing & Analysis",
            customData={
                "ExecutionId": execution_id,
                "StepCount": step_count,
                "ItemsProcessed": items_processed,
                "SuccessRate": 1.0,
            }
        ))

        return final_response

    except Exception as e:
        olakai("event", "ai_activity", OlakaiEventParams(
            prompt=input_text,
            response=f"Error: {str(e)}",
            tokens=total_tokens,
            requestTime=int((time.time() - start_time) * 1000),
            taskExecutionId=task_execution_id,
            task="Data Processing & Analysis",
            customData={
                "ExecutionId": execution_id,
                "StepCount": step_count,
                "ItemsProcessed": items_processed,
                "SuccessRate": 0,
            }
        ))
        raise

3.3 直接集成 REST API

适用于其他语言或自定义集成：

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
    }
  }'

步骤 4：测试-验证-迭代循环

始终通过运行测试并检查实际事件数据来验证你的实现。

4.1 运行你的 Agent

使用测试数据运行你的 Agent，至少生成一个事件。

4.2 获取并检查事件

olakai activity list --agent-id YOUR_AGENT_ID --limit 1 --json
olakai activity get EVENT_ID --json

4.3 验证各个组件

检查 customData 是否存在且正确：

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

检查 KPI 是否为数值（而非字符串）：

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

正确——数值：

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

错误——字符串值（公式无法正常工作）：

{
  "Items Processed": "itemsProcessed"
}

修复方法：olakai kpis update KPI_ID --formula "YourVariable"

错误——空值： 通过以下方式检查并修复：

1. 确认 CustomDataConfig 存在：olakai custom-data list --agent-id ID
2. 确认字段名称大小写完全一致（区分大小写）
3. 确认 SDK 确实在 customData 中发送了该字段

4.4 验证流程

1. Run agent (generate event)
           ↓
2. Fetch event: olakai activity get ID --json
           ↓
3. Check customData present? NO → Fix SDK code
           ↓
4. Check kpiData numeric? NO → Fix formula
           ↓
5. Check kpiData not null? NO → Create CustomDataConfig or fix field name
           ↓
✅ All validations pass — implementation complete

第 5 步：生产环境检查清单

部署到生产环境之前：

• 将 API 密钥安全地存储在环境变量中
• 为所有 LLM 调用添加错误处理
• 执行失败时仍报告事件（SuccessRate: 0）
• 所有自定义数据字段都有对应的 CustomDataConfig 条目
• KPI 公式已验证，且显示数值（而非字符串）
• 为 SDK 配置了适当的重试次数和超时时间
• 如有需要，启用敏感数据脱敏

KPI 公式参考

支持的运算符

类别	运算符
算术	+、-、*、/
比较	<、<=、=、<>、>=、>
逻辑	AND、OR、NOT
条件	IF(condition, true_val, false_val)、MAP(value, match1, out1, default)
数学	ABS、MAX、MIN、AVERAGE、TRUNC
空值处理	ISNA(value)、ISDEFINED(value)、NA()

常用公式模式

--formula "ItemsProcessed"                              # passthrough
--formula "SuccessRate * 100"                            # percentage (0-1 to 0-100)
--formula "IF(SuccessRate < 1, 1, 0)"                    # conditional counting
--formula "IF(PII detected, 1, 0)"                       # built-in variable
--formula "IF(ISDEFINED(MyField), MyField, 0)"           # null-safe
--formula "IF(AND(StepCount > 5, SuccessRate < 0.9), 1, 0)"  # compound conditions

聚合类型

聚合方式	适用场景	示例
SUM	总计、计数	所有运行中处理的项目总数
AVERAGE	比率、百分比	平均成功率

任务类别参考

task 字段使用以下预定义任务类别：

类别	使用示例
研究与情报	竞争情报、市场研究
数据处理与分析	数据提取、统计分析
内容创作	博客撰写、技术文档编写
内容润色	编辑、校对
客户体验	投诉处理、工单分类
软件开发	代码生成、代码审查、调试
战略规划	路线图制定、情景规划

快速参考

# CLI Commands
olakai login                                              # Authenticate
olakai workflows create --name "Name" --json              # Create workflow
olakai agents create --name "Name" --workflow ID --with-api-key  # Register 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

// TypeScript SDK
import { olakaiConfig, olakai } from "@olakai/sdk";
olakaiConfig({ apiKey: process.env.OLAKAI_API_KEY });

olakai("event", "ai_activity", {
  prompt: "input",
  response: "output",
  tokens: 1500,
  task: "Data Processing & Analysis",
  customData: { StepCount: 3, Success: 1 },
});

# Python SDK
from olakaisdk import olakai_config, olakai, OlakaiEventParams
olakai_config(os.getenv("OLAKAI_API_KEY"))

olakai("event", "ai_activity", OlakaiEventParams(
    prompt="input",
    response="output",
    tokens=1500,
    task="Data Processing & Analysis",
    customData={"StepCount": 3, "Success": 1},
))