integrate

既存の AI コードに Olakai を統合する

このスキルでは、既存の AI エージェントまたは LLM を利用するアプリケーションに、最小限のコード変更で Olakai の監視機能を追加する方法を説明します。

SDK の完全なドキュメントについては、https://app.olakai.ai/llms.txt を参照してください。

前提条件

• OpenAI、Anthropic、またはその他の LLM を使用する、既存の動作する AI エージェント／アプリケーション
• Olakai CLI がインストールされ、認証済みであること（npm install -g olakai-cli && olakai login）
• エージェント用の Olakai API キー（CLI で取得：olakai agents get AGENT_ID --json | jq '.apiKey'）
• Node.js 18 以降（TypeScript の場合）または Python 3.7 以降（Python の場合）

注： エージェントごとに独自の API キーを設定できます。olakai agents create --name "Name" --with-api-key で作成してください。

カスタム KPI が不可欠な理由

監視機能の追加は第一歩にすぎません。Olakai の真の価値は、エージェントのビジネス上の目的に特化したカスタム KPI を追跡することで得られます。

KPI を設定していない場合：

• 基本的なトークン数とリクエストデータのみ
• ダッシュボードに集計されたビジネス KPI が表示されない
• アラート機能がない
• ROI を追跡できない

KPI を設定した場合：

• カスタム KPI（処理した項目数、成功率、品質スコア）
• 傾向分析とパフォーマンスダッシュボード
• しきい値に基づくアラート
• ビジネス価値の計算

「このエージェントのパフォーマンスが良好だと、どうすれば判断できるか？」に答える KPI を、少なくとも 2～4 個設定してください。

KPI はエージェントごとに固有です。 すでに設定済みの別のエージェントと同じ KPI が必要なエージェントに監視機能を追加する場合でも、そのエージェント用の新しい KPI 定義を作成する必要があります。KPI をエージェント間で共有したり再利用したりすることはできません。

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. LLM 呼び出しの後にトラッキングを追加します：

変更前：

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. LLM 呼び出しの後にトラッキングを追加します：

変更前：

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：単一の LLM クライアント アプリ全体で使用する OpenAI／Anthropic クライアントが 1 つあります。 各補完処理の後に、結果を待たずに実行する olakai() 呼び出しを使用します。

パターン B：リクエストごとに複数の LLM 呼び出し エージェントは 1 つのタスクを完了するために、複数回 LLM を呼び出します。 手動のイベント追跡を使用して、呼び出しを 1 つのイベントに集約します。

パターン C：ストリーミング応答 LLM の応答をユーザーにストリーミングします。 ストリームが完了した後、蓄積した応答全体を使って追跡します。

パターン D：サードパーティの LLM（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 を使用する場合： エージェントが複数ターンの会話を処理し、会話全体を評価する KPI（感情スコアリング、満足度など）を必要とする場合は、すべてのターンで一貫した chatId を渡してください。

カスタムデータの追加

重要：CustomDataConfigs として登録したフィールドのみを送信してください（ステップ 5.3）。未登録のフィールドも保存されますが、KPI では使用できません。

KPI で使用するデータ、またはフィルタリングに使用するデータのみを送信してください。 プラットフォームですでに追跡されているフィールド（セッション ID、エージェント 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：エージェント型ワークフローを処理する

エージェントがタスクごとに複数の LLM 呼び出しを行う場合は、それらを 1 つのイベントに集約してください。

taskExecutionId — 複数エージェントのワークフローで重要です。 複数のエージェントが同じタスクで連携する場合、オーケストレーターは 1 つの taskExecutionId を生成し、すべてのエージェントに渡す必要があります。これにより、Olakai はエージェント間の処理を 1 つの論理タスクとして関連付けます。

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 エージェントを登録する

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

5.2.1 エージェントにワークフローがあることを確認する

エージェントが 1 つだけの場合でも、すべてのエージェントはワークフローに属している必要があります。

# 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 はエージェント単位で設定されます。

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 Routes

// 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：テストイベントを生成する

アプリケーションを実行し、少なくとも 1 回 LLM 呼び出しが発生するようにします。

ステップ 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)
null の処理	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},
))