API Reference

トラッキングAPI

目的と概要

トラッキングAPIは、生成AIエージェントのパフォーマンスを最大化するためのデータ記録システムです。このAPIは、エージェント自身が応答を生成するのではなく、将来の応答生成時に参照される行動データを体系的に記録する役割を担います。

主要機能

時系列行動データの記録

  • ユーザーの行動履歴を時系列で捕捉し保存
  • Slack、LINE等の外部プラットフォームからのイベントを統一形式で記録
  • カスタムシステムからのアクションデータも同様に処理

ステート情報の管理

  • ユーザーごとの状態情報を更新・維持
  • セッションをまたいだコンテキスト情報の永続化
  • キーと値のペアで構造化されたデータの保持

コンテキスト基盤の構築

  • 単発的なスナップショットではなく、連続的な相互作用の記録
  • ユーザーの行動パターンや嗜好の蓄積
  • エージェントの「記憶システム」としての機能

生成AIの性能はコンテキストの質と量に大きく依存します。トラッキングAPIは、単なる現時点での情報だけでなく、時間軸を持った行動履歴という形で、より豊かなコンテキストをAIに提供します。

AIの「記憶」としての役割

トラッキングAPIによって記録されたデータは、エージェントが新たなアクションを起こす際の「記憶」として機能します。これにより、過去の対話や行動を踏まえた、より適切で一貫性のある応答が可能になります。

リクエスト情報

  • メソッド: POST
  • エンドポイント: /tracker/:trackerId/:platform

ヘッダー

KeyValue
Content-Typeapplication/json
X-API-Key{API Key} (トラッキングAPI用のAPIキー)

URLパラメータ

パラメータ説明型必須
trackerIdエージェントIDString○
platformプラットフォーム (現在"api"のみ利用可能)String○

リクエストボディ

{
  "event": "イベントデータ（文字列形式）",
  "userId": "ユーザー識別子",
  "state": {
    "key1": "value1",
    "key2": "value2"
  },
  "disableAiRecord": false
}
パラメータ説明型必須
eventイベントデータ（文字列形式）String○
userIdユーザー識別子String○
stateユーザーステートMap (String : String)
disableAiRecordAIによるトラッキング処理を無効化し、リクエスト内容をそのままトラッキングします。(default: false)Boolean

認証について

  • X-API-Keyヘッダーを使用して認証を行います

レスポンス情報

ステータスコード

ステータスコード説明
200リクエスト成功
400Bad Request（リクエストに問題あり）
401Unauthorized（認証エラー）
404Not Found（エージェントが存在しない）
500Internal Server Error（サーバーエラー）

レスポンスボディ

リクエスト成功時（200）:

{}

エラー時:

{
  "error": "エラーメッセージ"
}

使用例

リクエスト例

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {your-api-key}" \
  -d '{
    "event": "ユーザーがサブスクリプションを購入しました。(購入プラン: Standard)",
    "userId": "user_123456",
    "state": {
      "last_visited": "2023-03-26"
    }
  }' \
  https://api-mebo.dev/tracker/{trackerId}/custom

注意事項

  1. userId が空の場合、400エラーが返されます
  2. event が空の場合、400エラーが返されます
  3. プラットフォーム別の認証に失敗した場合、401エラーが返されます
  4. エージェントが存在しない場合、404エラーが返されます
  5. サーバー内部でエラーが発生した場合、500エラーが返されます

利用方法

具体的な利用用途や方法に関しては、下記の記事をご参照ください。

https://note.com/makunugi/n/n14fecc26e087?sub_rt=share_pb