new-project

Olakai で新しい AI エージェントプロジェクトを構築する

このスキルでは、分析、KPI トラッキング、ガバナンスのために Olakai と完全に統合された新しい AI エージェントの作成方法を説明します。

前提条件

開始する前に、以下を確認してください。

1. Olakai CLI がインストールされていること：npm install -g olakai-cli
2. CLI で認証済みであること：olakai login
3. SDK 用の API キーがあること（CLI でエージェントごとに生成します。手順 2.2 を参照）

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

Olakai の中核的な価値は、AI エージェントのビジネス固有の KPI を追跡することです。KPI がなければ、実用的なインサイトを得られないままイベントを追跡することになります。

KPI で測定できること：

• ビジネス成果（処理した項目数、成功率、収益への影響）
• 運用データ（ステップ数、再試行率、実行時間）
• 品質指標（エラー率、ユーザー満足度の指標）

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

• 基本的なトークン数以外のダッシュボード KPI がありません
• 集計されたパフォーマンスビューがありません
• アラートのしきい値がありません
• ROI の計算ができません

すべてのエージェントには、「このエージェントが適切に機能しているか、どうすれば分かるか？」に答える 2～4 個の KPI が必要です。

ここで作成する KPI は、この特定のエージェントにのみ属します。 後でエージェントを追加作成する場合は、それぞれに独自の KPI 定義が必要です。KPI をエージェント間で共有したり再利用したりすることはできません。

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 はエージェントごとに固有です	各 KPI はちょうど 1 つのエージェントに属します。それぞれのエージェント用に個別に作成してください

組み込みコンテキスト変数（常に使用可能）

変数	型	説明
Prompt	string	LLM に送信されたプロンプトテキスト
Response	string	LLM の応答テキスト
Documents count	number	添付されたドキュメントの数
PII detected	boolean	PII が検出されたかどうか
PHI detected	boolean	PHI が検出されたかどうか
CODE detected	boolean	コードが検出されたかどうか
SECRET detected	boolean	シークレットが検出されたかどうか

手順 1：エージェントのアーキテクチャを設計する

1.1 エージェントの種類を決める

エージェント型 AI（複数ステップの自律型ワークフロー）：

• リサーチエージェント、ドキュメント処理ツール、データパイプライン
• 内部のすべての LLM 呼び出しを集約し、単一のイベントとして追跡します
• ワークフローレベルの KPI（トークン総数、合計時間、成功／失敗）に重点を置きます

支援型 AI（対話型チャットボット／コパイロット）：

• カスタマーサポートエージェント、コーディングアシスタント、Q&A システム
• 各インタラクションを個別のイベントとして追跡します
• 会話レベルの KPI（メッセージごとのトークン数、応答品質）に重点を置きます

1.2 KPI スキーマを設計する（重要）

SDK コードを書く前に KPI を設計してください。 これにより、意味のあるデータのみが送信され、追跡されるようになります。

ステップ A：ビジネス上の疑問を特定する

関係者は、このエージェントについて何を知る必要がありますか？

• 「1 回の実行で何件の項目を処理するか？」
• 「成功率／失敗率はどのくらいか？」
• 「各実行の効率はどのくらいか？」

ステップ 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
エージェント ID	API キーとの関連付け	agentId
ユーザーのメールアドレス	userEmail パラメーター	email、userEmail
タイムスタンプ	イベントメタデータ	timestamp、createdAt
リクエスト時間	requestTime パラメーター	duration、latency
トークン数	tokens パラメーター	tokenCount
モデル	自動検出	model、modelName
プロバイダー	クライアント設定	provider

customData は、次の用途にのみ使用します。

1. KPI 変数 — 数式計算に使用するフィールド
2. タグ付け／フィルタリング — クエリでフィルタリングするフィールド

ステップ 2：Olakai プラットフォームを設定する

2.1 ワークフローを作成する（必須）

各エージェントは、たとえそのワークフローに含まれるエージェントが 1 つだけでも、必ずワークフローに所属する必要があります。

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

2.2 Olakai でエージェントを作成する

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

エージェントとワークフローの階層：

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 }],
});

手動でイベントを追跡するエージェント型ワークフロー：

taskExecutionId — エージェント間タスクの相関。 タスクごとに taskExecutionId を 1 つ生成し、マルチエージェントワークフロー内のすべてのエージェントで共有します。これにより、異なるエージェントからのイベントを分析用の単一の論理タスクとして関連付けられます。

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"))

エージェント型ワークフロー：

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

テストデータを使ってエージェントを実行し、少なくとも 1 件のイベントを生成します。

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"

誤り — null 値： 以下を確認して修正します。

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
null の処理	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},
))