integrate

将 Olakai 集成到现有 AI 代码中

本技能将指导你以最少的代码改动，为现有 AI Agent 或大模型驱动的应用添加 Olakai 监控。

完整的 SDK 文档请参阅：https://app.olakai.ai/llms.txt

前置条件

• 已运行的 AI Agent/应用，使用 OpenAI、Anthropic 或其他大模型
• 已安装并完成身份验证的 Olakai CLI（npm install -g olakai-cli && olakai login）
• Agent 的 Olakai API 密钥（通过 CLI 获取：olakai agents get AGENT_ID --json | jq '.apiKey'）
• Node.js 18+（适用于 TypeScript）或 Python 3.7+（适用于 Python）

注意： 每个 Agent 都可以拥有自己的 API 密钥。使用 olakai agents create --name "Name" --with-api-key 创建密钥。

为什么自定义 KPI 至关重要

添加监控只是第一步。Olakai 的真正价值在于跟踪专为 Agent 的业务目标定制的 KPI。

未配置 KPI 时：

• 只能查看基本的令牌数量和请求数据
• 仪表板上没有汇总后的业务 KPI
• 无法设置提醒
• 无法跟踪投资回报率

配置 KPI 后：

• 自定义 KPI（已处理项目、成功率、质量评分）
• 趋势分析和性能仪表板
• 基于阈值的提醒
• 业务价值计算

请计划至少配置 2-4 个 KPI，以回答：“我如何判断这个 Agent 是否运行良好？”

每个 Agent 的 KPI 都是独立的。 如果要为某个 Agent 添加监控，且它需要与另一个已配置的 Agent 相同的 KPI，你仍须为此 Agent 创建新的 KPI 定义。KPI 不能在不同 Agent 之间共享或重复使用。

了解 customData 到 KPI 的处理流程

添加监控之前，请先了解自定义数据如何在 Olakai 中流转：

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

关键规则

规则	结果
只有 CustomDataConfig 字段会成为变量	未注册的 customData 字段不能用于 KPI
公式评估不区分大小写	公式中的 stepCount、STEPCOUNT、StepCount 都有效
NUMBER 配置需要数值	不要发送 "5"（字符串），应发送 5（数字）

重要： SDK 接受 customData 中的任意 JSON，但只有注册为 CustomDataConfigs 的字段才会被处理。未注册的字段会被存储，但不能用于 KPI。

快速入门（5 分钟完成集成）

TypeScript/JavaScript

1. 安装 SDK：

npm install @olakai/sdk

2. 在大模型调用后添加跟踪：

之前：

import OpenAI from "openai";
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: userMessage }],
});

之后：

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

olakaiConfig({ apiKey: process.env.OLAKAI_API_KEY });

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

const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: userMessage }],
});

// Track the interaction (fire-and-forget)
olakai("event", "ai_activity", {
  prompt: userMessage,
  response: response.choices[0].message.content,
  tokens: response.usage?.total_tokens,
  userEmail: user.email,
  task: "Customer Experience",
});

Python

1. 安装 SDK：

pip install olakai-sdk

2. 在大模型调用后添加跟踪：

之前：

from openai import OpenAI
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": user_message}],
)

之后：

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

olakai_config(os.getenv("OLAKAI_API_KEY"))
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": user_message}],
)

# Track the interaction
olakai("event", "ai_activity", OlakaiEventParams(
    prompt=user_message,
    response=response.choices[0].message.content,
    tokens=response.usage.total_tokens,
    userEmail=user.email,
    task="Customer Experience",
))

---

详细集成指南

步骤 1：确定集成模式

模式 A：单个大模型客户端 整个应用中使用一个 OpenAI/Anthropic 客户端。 每次生成完成后，使用即发即弃的 olakai() 调用。

模式 B：每个请求包含多次大模型调用 Agent 需要多次调用大模型才能完成一项任务。 使用手动事件跟踪，将多次调用汇总为一个事件。

模式 C：流式响应 向用户流式传输大模型响应。 在流结束后，使用完整的累积响应进行跟踪。

模式 D：第三方大模型（非 OpenAI/Anthropic） 使用 Perplexity、Groq、本地模型等。 通过 olakai() 或 olakai_event() 手动跟踪事件。

步骤 2：安装并配置

TypeScript 设置

// lib/olakai.ts - Initialize once at app startup
import { olakaiConfig } from "@olakai/sdk";

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

Python 设置

# lib/olakai.py - Initialize once at app startup
import os
from olakaisdk import olakai_config

olakai_config(
    api_key=os.getenv("OLAKAI_API_KEY"),
    debug=os.getenv("DEBUG") == "true"
)

步骤 3：在调用中添加上下文

添加用户信息

TypeScript：

olakai("event", "ai_activity", {
  prompt: userMessage,
  response: aiResponse,
  userEmail: user.email,
  task: "Customer Experience",
});

Python：

olakai("event", "ai_activity", OlakaiEventParams(
    prompt=user_message,
    response=ai_response,
    userEmail=user.email,
    task="Customer Experience",
))

按对话分组事件（chatId）

对于辅助型 AI（聊天机器人/副驾驶），使用 chatId 将一次对话中的多轮消息归为一组。分析完整对话的 CHAT 作用域 KPI 需要此设置。

olakai("event", "ai_activity", {
  prompt: userMessage,
  response: aiResponse,
  chatId: conversationId,  // groups turns in the same conversation
  userEmail: user.email,
});

何时使用 chatId： 如果 Agent 处理多轮对话，且你希望 KPI 评估整个对话（例如，情绪评分、满意度），请在所有轮次中传入一致的 chatId。

添加自定义数据

重要：仅发送已注册为 CustomDataConfigs 的字段（步骤 5.3）。未注册的字段会被存储，但无法用于 KPI。

仅发送会用于 KPI 或筛选的数据。 不要重复发送平台已跟踪的字段（会话 ID、Agent ID、用户电子邮件、时间戳、令牌数、模型、提供方——这些都会自动跟踪）。

TypeScript：

olakai("event", "ai_activity", {
  prompt: userMessage,
  response: aiResponse,
  userEmail: user.email,
  customData: {
    // Only include fields registered as CustomDataConfigs
    Department: user.department,
    ProjectId: currentProject.id,
    Priority: ticket.priority,
  },
});

步骤 4：处理 Agent 工作流

如果你的 Agent 每个任务会进行多次大模型调用，请将这些调用聚合为一个事件。

taskExecutionId——对多 Agent 工作流至关重要。 如果多个 Agent 协作完成同一任务，编排器必须生成一个 taskExecutionId 并传递给所有 Agent。Olakai 通过它将跨 Agent 的工作关联为一个逻辑任务。

async function processDocument(doc: Document): Promise<string> {
  const startTime = Date.now();
  let totalTokens = 0;

  // Step 1: Extract
  const extraction = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: `Extract from: ${doc.content}` }],
  });
  totalTokens += extraction.usage?.total_tokens ?? 0;

  // Step 2: Analyze
  const analysis = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: `Analyze: ${extraction.choices[0].message.content}` }],
  });
  totalTokens += analysis.usage?.total_tokens ?? 0;

  const result = analysis.choices[0].message.content ?? "";

  // Track the complete workflow as ONE event
  olakai("event", "ai_activity", {
    prompt: `Process document: ${doc.title}`,
    response: result,
    tokens: totalTokens,
    requestTime: Date.now() - startTime,
    taskExecutionId: crypto.randomUUID(),
    task: "Data Processing & Analysis",
    customData: {
      DocumentType: doc.type,
      StepCount: 2,
      Success: 1,
    },
  });

  return result;
}

步骤 5：配置自定义 KPI（对发挥价值至关重要）

要从 Olakai 获得实际价值，必须完成此步骤。 如果没有 KPI，你只能跟踪事件，无法获得可执行的洞察。

5.1 安装 CLI（如果尚未安装）

npm install -g olakai-cli
olakai login

5.2 注册你的 Agent

olakai agents create \
  --name "Document Processor" \
  --description "Processes and summarizes documents" \
  --workflow WORKFLOW_ID \
  --with-api-key

5.2.1 确保 Agent 具备工作流

每个 Agent 都必须属于一个工作流，即使它是唯一的 Agent。

# Check if agent has a workflow
olakai agents get YOUR_AGENT_ID --json | jq '.workflowId'

# If null, create a workflow and associate:
olakai workflows create --name "Your Workflow Name" --json
olakai agents update YOUR_AGENT_ID --workflow WORKFLOW_ID

5.3 首先创建自定义数据配置

重要：为 customData 中发送的所有字段创建配置。只有已注册的字段才能用于 KPI。CustomDataConfigs 按 Agent 作用域配置。

olakai custom-data create --agent-id YOUR_AGENT_ID --name "DocumentType" --type STRING
olakai custom-data create --agent-id YOUR_AGENT_ID --name "StepCount" --type NUMBER
olakai custom-data create --agent-id YOUR_AGENT_ID --name "Success" --type NUMBER

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

5.4 创建 KPI

olakai kpis create \
  --name "Documents Processed" \
  --agent-id YOUR_AGENT_ID \
  --calculator-id formula \
  --formula "IF(Success = 1, 1, 0)" \
  --aggregation SUM

olakai kpis create \
  --name "Avg Steps per Document" \
  --agent-id YOUR_AGENT_ID \
  --calculator-id formula \
  --formula "StepCount" \
  --aggregation AVERAGE

5.5 更新 SDK 代码以保持一致

创建配置后，请确保 SDK 代码发送的字段名称与配置完全一致：

customData: {
  DocumentType: doc.type,     // Matches CustomDataConfig "DocumentType"
  StepCount: 2,               // Matches CustomDataConfig "StepCount"
  Success: true ? 1 : 0,      // Matches CustomDataConfig "Success"
}

特定框架集成

Next.js API 路由

// app/api/chat/route.ts
import { NextRequest, NextResponse } from "next/server";
import { olakai } from "@olakai/sdk";
import { auth } from "@/auth";

export async function POST(req: NextRequest) {
  const session = await auth();
  if (!session?.user) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { message } = await req.json();

  const response = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: message }],
  });

  olakai("event", "ai_activity", {
    prompt: message,
    response: response.choices[0].message.content,
    userEmail: session.user.email!,
    task: "Customer Experience",
  });

  return NextResponse.json({ reply: response.choices[0].message.content });
}

FastAPI（Python）

from fastapi import FastAPI, Depends
from olakaisdk import olakai_config, olakai, OlakaiEventParams

app = FastAPI()

@app.on_event("startup")
async def startup():
    olakai_config(os.getenv("OLAKAI_API_KEY"))

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

@app.post("/chat")
async def chat(message: str, user: User = Depends(get_current_user)):
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": message}]
    )

    olakai("event", "ai_activity", OlakaiEventParams(
        prompt=message,
        response=response.choices[0].message.content,
        userEmail=user.email,
        task="Customer Experience",
    ))

    return {"reply": response.choices[0].message.content}

处理边缘情况

流式响应

流结束后，使用完整响应进行跟踪：

const stream = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: userMessage }],
  stream: true,
});

let fullResponse = "";
for await (const chunk of stream) {
  fullResponse += chunk.choices[0]?.delta?.content ?? "";
  res.write(chunk.choices[0]?.delta?.content ?? "");
}

// Track after stream completes
olakai("event", "ai_activity", {
  prompt: userMessage,
  response: fullResponse,
  userEmail: user.email,
});

错误处理

try {
  const response = await openai.chat.completions.create({
    model: "gpt-4o",
    messages,
  });
  return response.choices[0].message.content;
} catch (error) {
  // Track the failed attempt
  olakai("event", "ai_activity", {
    prompt: messages[messages.length - 1].content,
    response: `Error: ${error instanceof Error ? error.message : "Unknown"}`,
    task: "Software Development",
    customData: { Success: 0 },
  });
  throw error;
}

非 OpenAI 提供方

对于 Anthropic、Perplexity 或其他提供方，请使用手动跟踪：

import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

async function callClaude(prompt: string): Promise<string> {
  const startTime = Date.now();

  const response = await anthropic.messages.create({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    messages: [{ role: "user", content: prompt }],
  });

  const content = response.content[0].type === "text" ? response.content[0].text : "";

  olakai("event", "ai_activity", {
    prompt,
    response: content,
    tokens: response.usage.input_tokens + response.usage.output_tokens,
    requestTime: Date.now() - startTime,
    task: "Content Development",
  });

  return content;
}

测试—验证—迭代循环

切勿假设集成已经正常工作。务必通过生成测试事件并检查实际数据来进行验证。

步骤 1：生成测试事件

运行应用程序，至少触发一次大模型调用。

步骤 2：获取并检查事件

olakai activity list --limit 1 --json
olakai activity get EVENT_ID --json

步骤 3：验证各个组件

检查 customData 是否存在：

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

检查 KPI 是否为数值（而不是字符串或 null）：

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

正确：

{ "My KPI": 42 }

错误（公式以字符串形式存储）：

{ "My KPI": "MyVariable" }

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

错误（值为 null）：

{ "My KPI": null }

请确保：

1. CustomDataConfig 已存在：olakai custom-data create --agent-id ID --name "MyVariable" --type NUMBER
2. 字段名称的大小写完全一致（区分大小写）
3. SDK 确实在 customData 中发送了该字段

验证流程

1. Trigger LLM call (generate event)
           ↓
2. Fetch: olakai activity get ID --json
           ↓
3. Event exists? NO → Check API key, SDK init, debug mode
           ↓
4. customData correct? NO → Fix SDK customData parameter
           ↓
5. kpiData numeric? NO → olakai kpis update ID --formula "X"
           ↓
6. kpiData not null? NO → Create CustomDataConfig, check field name case
           ↓
✅ Integration validated

KPI 公式参考

支持的运算符

类别	运算符
算术	+、-、*、/
比较	<、<=、=、<>、>=、>
逻辑	AND、OR、NOT
条件	IF(condition, true_val, false_val)
空值处理	ISNA(value)、ISDEFINED(value)

常见公式模式

--formula "StepCount"                          # passthrough
--formula "SuccessRate * 100"                  # percentage conversion
--formula "IF(Success = 1, 1, 0)"              # conditional counting
--formula "IF(PII detected, 1, 0)"             # built-in variable
--formula "IF(ISDEFINED(MyField), MyField, 0)" # null-safe

聚合类型

聚合	用途
SUM	总计、计数
AVERAGE	费率、百分比

快速参考

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

// Track any interaction
olakai("event", "ai_activity", {
  prompt: "input",
  response: "output",
  tokens: 1500,
  requestTime: 5000,
  userEmail: "[email protected]",
  chatId: "conversation-id",
  taskExecutionId: "uuid-shared-across-agents",
  task: "Data Processing & Analysis",
  customData: { StepCount: 3, Success: 1 },
});

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

# Track any interaction
olakai("event", "ai_activity", OlakaiEventParams(
    prompt="input",
    response="output",
    tokens=1500,
    requestTime=5000,
    userEmail="[email protected]",
    chatId="conversation-id",
    taskExecutionId="uuid-shared-across-agents",
    task="Data Processing & Analysis",
    customData={"StepCount": 3, "Success": 1},
))