APIリファレンス

認証

すべてのAPI呼び出しには、プロジェクトAPIキーによるBearer認証が必要です。

Authorization: Bearer YOUR_PROJECT_API_KEY

API Reference

スキーマ、リクエスト/レスポンス例、インタラクティブな試用パネルを含む完全なエンドポイントリファレンスは /docs/en/api でご覧いただけます。各オペレーションはライブ OpenAPI spec から自動生成された専用ページを持ちます。

生の仕様（Postman、コードジェネレーター、カスタムツール向け）

ライブ OpenAPI 3.1 JSON + YAML は公開ホスティングされており、認証不要でデプロイごとに再生成されます：

https://api.sonz.ai/docs/openapi.json
https://api.sonz.ai/docs/openapi.yaml

curl -sL https://api.sonz.ai/docs/openapi.json -o openapi.json

REST API

エージェントライフサイクル、リアルタイムエージェントインタラクション、プロアクティブ配信のためのパブリックHTTPエンドポイント。記憶、ムード、関係性、コンテキスト管理の内部処理はプラットフォームが行います。

エージェントライフサイクル

エージェントの作成

POST /api/v1/agents

新しいエージェントを作成します。プラットフォーム生成のUUID付きエージェントを返します。

パラメーター:

• name (string): エージェント名（必須）
• personality_prompt (string): カスタムシステムプロンプト（任意）
• big5 (object): ビッグファイブスコア: openness, conscientiousness, extraversion, agreeableness, neuroticism (0.0-1.0)
• speech_patterns (string[]): 発話パターン（任意）
• true_interests (string[]): エージェントの興味（任意）
• project_id (string): エージェントを割り当てるプロジェクトUUID（任意）
• language (string): ISO言語コード、例: "en"（任意）

レスポンス: { "agent_id": "uuid", "name": "...", ... }

エージェント一覧

GET /api/v1/agents

エージェント一覧を取得。project_idクエリパラメーターでフィルタリング。

パラメーター:

• project_id (string): プロジェクトでフィルタリング（クエリパラメーター、任意）

レスポンス: エージェントオブジェクトの配列

エージェント取得

GET /api/v1/agents/{agentId}

IDでエージェントを取得。

レスポンス: パーソナリティ、ムード、プロフィールを含むエージェントオブジェクト

チャット

ストリームチャット

POST /api/v1/agents/{agentId}/chat

SSEストリーミングでエージェントとチャット。Server-Sent Eventsを返します。

パラメーター:

• messages (CEChatMessage[]): 会話メッセージ
• user_id (string): ユーザー識別子

レスポンス: チャット完了チャンクのSSEストリーム

プロアクティブ通知

通知一覧

GET /api/v1/agents/{agentId}/notifications

保留中のプロアクティブメッセージ一覧。

パラメーター:

• status (string): ステータスでフィルタリング: pending | consumed（デフォルト: pending、クエリパラメーター）
• user_id (string): ユーザーでフィルタリング（任意、クエリパラメーター）
• limit (int): 最大結果数（デフォルト: 50、最大: 500、クエリパラメーター）

レスポンス: message_id, agent_id, user_id, check_type, intent, generated_message, status, created_atを含むプロアクティブメッセージのリスト

通知の消費

POST /api/v1/agents/{agentId}/notifications/{messageId}/consume

配信後に通知を消費済みとしてマーク。

レスポンス: 確認

通知履歴

GET /api/v1/agents/{agentId}/notifications/history

すべてのステータスの通知一覧。

レスポンス: 完全な通知履歴

エージェントライフサイクル（詳細）

CreateAgent

パーソナリティ設定で新しいエージェントを作成します。パーソナリティプロンプト、発話パターン、感情的傾向を生成します。

リクエスト:

• user_id (string): オーナーユーザー識別子
• agent_name (string): エージェント表示名
• gender (string): "male", "female", または "non_binary"
• bio (string): エージェントの経歴（任意）
• avatar_url (string): アバター画像URL（任意）
• big5 (CEBig5Scores): ビッグファイブパーソナリティスコア (0.0-1.0)
• language (string): プライマリ言語
• equipped_outfit (string): 初期衣装ID（任意）
• skills (CESkillLevel[]): 初期スキルレベル（任意）
• model_tier (int32): LLMモデルティア（任意）
• project_id (string): エージェントを割り当てるプロジェクト（任意）
• agent_id (string): 決定的エージェント用の呼び出し元指定ID（任意）
• personality_prompt (string): カスタムシステムプロンプト（任意）
• generate_goals (bool): 作成後に目標を自動生成（任意）
• provided_goals (string[]): これらの目標を直接保存（任意）
• speech_patterns (string[]): 発話パターン（任意）
• true_interests (string[]): エージェントの興味（任意）
• true_dislikes (string[]): エージェントの嫌いなもの（任意）
• user_display_name (string): オーナー表示名（任意）
• generate_avatar (bool): 作成時にAIアバターを自動生成（デフォルト: true、1クレジット消費）。スキップするにはfalseに設定。

レスポンス: agent_id (UUID), status ('completed' または 'in_progress')

GetAgent

パーソナリティ、ムード、プロフィールを含むエージェントの現在の状態を取得します。

リクエスト:

• agent_id (string): エージェントUUID

レスポンス: Agent ID, name, bio, gender, avatar_url, Big5 scores, owner, created_at

UpdateAgent

エージェントのフィールドを更新します（名前、経歴、アバター、パーソナリティ、興味、発話パターン）。

リクエスト:

• agent_id (string): エージェントUUID
• name (string): 新しい名前（任意）
• bio (string): 新しい経歴（任意）
• avatar_url (string): 新しいアバターURL（任意）
• big5 (CEBig5Scores): 更新されたBig5スコア（任意）
• true_interests (string[]): 更新された興味（任意）
• true_dislikes (string[]): 更新された嫌いなもの（任意）
• speech_patterns (string[]): 更新された発話パターン（任意）
• personality_prompt (string): 更新されたシステムプロンプト（任意）

レスポンス: success (bool)

DeleteAgent

エージェントと関連するすべてのデータ（記憶、ムード、関係性）を完全に削除します。

リクエスト:

• agent_id (string): エージェントUUID

レスポンス: success (bool)

RegenerateAvatar

エージェントのAI生成アバターを生成または再生成します。LLMを使用してパーソナリティデータから画像プロンプトを作成し、画像を生成・アップロードします。1クレジット消費。アバターは無効にしない限り、エージェント作成時に自動生成されます。

リクエスト:

• agent_id (string): エージェントUUID（URLパラメーター）
• style (string): 任意のスタイルヒント（例: 'watercolor anime', 'realistic portrait'）

レスポンス: success (bool), avatar_url (string), prompt (string), generation_time_ms (int64)

UpdateAgentPersonality

プロダクトが意図的にエージェント設計を変更する場合に、エージェントの著者設定のBig5パーソナリティ設定を更新します。

リクエスト:

• agent_id (string): エージェントUUID
• big5 (CEBig5Scores): 信頼度付きの更新されたビッグファイブスコア

レスポンス: success (bool)

プロアクティブ動作

ScheduleWakeup

遅延後にエージェントがユーザーにプロアクティブに連絡するようスケジュールします。

リクエスト:

• agent_id (string): エージェントUUID
• user_id (string): ユーザー識別子
• check_type (string): チェックタイプ: check_in, follow_up, mood_driven
• intent (string): エージェントが連絡を取りたい理由
• delay_hours (int32): ウェイクアップまでの遅延時間

レスポンス: wakeup_id (string), scheduled_at (Timestamp)

GetPendingWakeups

エージェントの保留中のウェイクアップイベントを取得します。

リクエスト:

• agent_id (string): エージェントUUID

レスポンス: PendingWakeupのリスト (wakeup_id, user_id, check_type, intent, scheduled_at)

ストリーミングチャット

主要なパブリック会話RPC。エージェント、ユーザー、アプリケーションコンテキスト、メッセージ履歴を送信します。プラットフォームがコンテキスト組み立てと状態更新を自動的に処理します。

StreamChat

エージェントインタラクションのAIレスポンスをストリーミングし、プラットフォームが内部の記憶と状態更新をバックグラウンドで処理します。

リクエスト:

• agent_id (string): エージェントUUID
• user_id (string): ユーザー識別子
• session_id (string): 一意のセッションID
• backend_context (BackendContext): アプリケーション状態コンテキスト
• messages (CEChatMessage[]): 会話メッセージ
• continuation_token (string): 前のレスポンスから再開（任意）
• request_type (string): "chat", "guide", または "outing"
• capabilities (string[]): アンロックされた機能（任意）
• language (string): ISO言語コード（任意）
• interaction_role (string): "owner" または "non_owner"
• skill_levels (map<string, int32>): スキルレベル（任意）
• max_turns (int32): リクエストあたりのアシスタントターンの最大数（任意）

レスポンス: StreamChatEventのストリーム (delta | message_boundary | complete | side_effects | error)

StreamChatEventは以下のイベントタイプを持つoneofです：

StreamChatDelta (delta)

• content (string): AIからのテキストチャンク
• message_index (int32): マルチメッセージレスポンスでのインデックス
• is_follow_up (bool): これがフォローアップメッセージかどうか
• replacement (bool): trueの場合、前のすべてのコンテンツを置換

StreamChatComplete (complete)

• full_content (string): 完全なレスポンステキスト
• finish_reason (string): "stop", "length", または "content_filter"
• continuation_token (string): 会話を続けるためのトークン
• message_count (int32): レスポンス内のメッセージ数

StreamChatError (error)

• message (string): エラーメッセージ
• code (string): エラーコード

AI生成

経歴、目標、パーソナリティ、日記エントリ、画像のプラットフォーム管理AIコンテンツ生成。

GenerateBio

パーソナリティとコンテキストに基づいてAIを使用してエージェントの経歴を生成または書き換えます。

リクエスト:

• agent_id (string): エージェントUUID
• user_id (string): ユーザー識別子
• current_bio (string): 書き換え用の現在の経歴（任意）
• style (string): スタイル: casual, formal, poetic など（任意）

レスポンス: bio (string), tone (string), confidence (double)

GenerateGoals

特性、興味、記憶に基づいてエージェントのパーソナリティ駆動の目標を生成します。

リクエスト:

• agent_id (string): エージェントUUID
• agent_name (string): エージェント表示名
• big5 (CEBig5Scores): Big5スコア
• true_interests (string[]): エージェントの興味
• true_dislikes (string[]): エージェントの嫌いなもの
• speech_patterns (string[]): 発話パターン
• recent_memories (CERecentMemory[]): コンテキスト用の最近の記憶
• current_goals (CEGoalSummary[]): 重複を避けるための既存の目標
• max_goals (int32): 生成する最大目標数
• model_config (CEModelConfig): LLMモデル設定（任意）
• custom_context (map<string, string>): アプリケーション固有のコンテキスト（任意）

レスポンス: CEGeneratedGoalのリスト (type, title, description, priority, related_traits), reasoning

GeneratePersonality

テンプレートとBig5スコアから発話パターンと興味を生成します。

リクエスト:

• template_id (string): テンプレート識別子
• base_prompt (string): ベースパーソナリティプロンプト
• big5 (CEBig5Scores): Big5スコア
• agent_name (string): エージェント名
• gender (string): エージェントの性別

レスポンス: speech_patterns (string[]), true_interests (string[]), used_fallback (bool)

GenerateDiary

会話メッセージやアプリケーションイベントから日記エントリを生成します。

リクエスト:

• agent_id (string): エージェントUUID
• user_id (string): ユーザー識別子
• date (string): YYYY-MM-DD形式の日付
• agent_name (string): エージェント表示名
• language (string): 生成コンテンツの言語
• messages (CEDiaryMessage[]): 会話メッセージ (role, content, time)
• trigger_type (string): daily_summary, achievement, milestone, breakthrough
• trigger_context (CEDiaryTriggerContext): イベントトリガーコンテキスト（任意）
• model (string): LLMモデルのオーバーライド（任意）
• temperature (double): Temperatureのオーバーライド（任意）
• timezone (string): 日付処理のタイムゾーン（任意）

レスポンス: user_id, date, diary (title, body_lines, tags), generation_time_ms

GenerateImage

テキストプロンプトから画像を生成し、クラウドストレージに保存します。

リクエスト:

• prompt (string): 画像生成プロンプト
• negative_prompt (string): ネガティブプロンプト（任意）
• model (string): 使用するモデル（任意）
• provider (string): 使用するプロバイダー（任意）
• output_bucket (string): 出力用GCSバケット（任意）
• output_path (string): バケット内の出力パス（任意）
• cdn_domain (string): パブリックURL用CDNドメイン（任意）

レスポンス: success, image_id, gcs_uri, public_url, mime_type, generation_time_ms, error

ボイス＆メディア

ボイスマッチング、テキスト読み上げ、ボイスチャット、リフレクション機能。

VoiceMatch

パーソナリティ特性に基づいて適切なTTSボイスにエージェントをマッチングします。

リクエスト:

• big5 (CEBig5Scores): マッチング用Big5スコア
• preferred_gender (string): 希望のボイス性別（任意）
• agent_id (string): エージェントUUID（big5なしで提供された場合、自動ルックアップ）

レスポンス: voice_id, voice_name, match_score, reasoning

TextToSpeech

感情コンテキスト認識を備えたGoogle Geminiボイスによるテキスト読み上げ。

リクエスト:

• text (string): 変換するテキスト
• voice_name (string): Geminiボイス名
• language (string): 言語コード（任意）
• emotional_context (CEEmotionalContext): 感情テーマとトーン（任意）

レスポンス: audio (bytes), content_type, voice_name

VoiceChat

シングルターンボイスチャット: 音声を書き起こし、AIレスポンスを生成し、TTS音声を返します。

リクエスト:

• agent_id (string): エージェントUUID
• user_id (string): ユーザー識別子
• audio (bytes): 生の音声データ
• audio_format (string): 音声フォーマット (opus, pcm, wav)
• voice_name (string): TTSボイス名
• continuation_token (string): 前のターンから再開（任意）
• language (string): 言語コード（任意）
• application_id (string): アプリケーション識別子（任意）

レスポンス: transcript, response (text), audio (bytes), content_type, continuation_token, side_effects_json

ListVoices

利用可能なGemini TTSボイスの一覧。オプションで性別フィルタリング。

リクエスト:

• gender (string): 性別でフィルタリング（任意）

レスポンス: CEGeminiVoiceのリスト (name, gender)

Reflect

機能アンロック、マイルストーン、その他のイベントに関するAIリフレクションを生成します。

リクエスト:

• agent_id (string): エージェントUUID
• user_id (string): ユーザー識別子
• reflection_type (string): "capability_unlock", "milestone" など
• capability (string): 機能名
• capability_source (string): 機能のソース
• context (string): 追加コンテキスト文字列（任意）
• new_capabilities_json (bytes): 新しい機能JSON（任意）
• session_id (string): 自動コンテキストビルド用セッションID（任意）
• interaction_role (string): "owner" または "non_owner"（デフォルト: "owner"）

レスポンス: success (bool), reflection (string), side_effects_json (bytes)

ストリーミングボイスチャット

サーバーサイドVAD（音声活動検出）を備えた双方向ストリーミングボイスチャット。クライアントは音声チャンクを連続的にストリーミングし、サーバーが音声検出、書き起こし、AIレスポンス、TTSを処理します。

StreamVoiceChat

双方向ストリーミング: クライアントがinit＋音声チャンクを送信し、サーバーがトランスクリプトとTTS音声を返します。手動停止ボタンは不要です。

リクエスト:

• init (VoiceChatInit): 最初のメッセージ: セッション初期化
• audio_chunk (VoiceAudioChunk): 後続メッセージ: 生の音声データ

レスポンス: イベントストリーム: ready | vad | transcript | response_delta | audio | turn_complete | error

VoiceChatInit

• agent_id (string): エージェントUUID
• user_id (string): ユーザー識別子
• audio_format (string): "opus", "pcm", "wav"（デフォルト: "opus"）
• sample_rate (int32): サンプルレート（Hz）（デフォルト: opus用48000）
• voice_name (string): TTSボイス名
• language (string): 言語コード（デフォルト: "en"）
• application_id (string): アプリケーション識別子
• continuation_token (string): 前のセッションから再開（任意）

VoiceAudioChunk

• audio (bytes): 生の音声データ（例：Opusフレーム）
• end_of_speech (bool): 任意のクライアントサイドVADヒント

サーバーレスポンスイベント：

VoiceStreamReady

• session_id (string): 割り当てられたセッションID

VoiceStreamVAD

• speaking (bool): true = 発話開始, false = 発話終了

VoiceStreamTranscript

• text (string): トランスクリプトテキスト
• is_final (bool): true = この発話の最終トランスクリプト

VoiceStreamAudio

• audio (bytes): 音声データチャンク
• content_type (string): 例: "audio/opus", "audio/wav"

VoiceStreamTurnComplete

• continuation_token (string): セッションを継続するためのトークン
• side_effects_json (bytes): JSONシリアライズされたAgentSideEffects（任意）

VoiceStreamError

• message (string): エラーメッセージ
• code (string): "vad_error", "stt_error", "llm_error", "tts_error"
• fatal (bool): trueの場合、セッションを閉じる必要あり

分析＆検索

AIを活用した会話分析、要約、グラウンデッド検索。

AnalyzeConversation

会話を分析して副作用（パーソナリティ変化、習慣、記憶など）を抽出します。

リクエスト:

• agent_id (string): エージェントUUID
• agent_name (string): エージェント表示名
• user_id (string): ユーザー識別子
• messages (CEAnalyzeConversationMessage[]): 分析するメッセージ (role, content)
• is_final (bool): これがメッセージの最終バッチかどうか

レスポンス: success, side_effects_json (bytes), summary, latency_ms

SummarizeConversation

トピック抽出を含む会話の簡潔な要約を生成します。

リクエスト:

• messages (CESummarizeConversationMessage[]): メッセージ (role, content, time)
• agent_name (string): エージェント名
• user_name (string): ユーザー表示名
• max_summary_length (int32): 要約の最大文字数

レスポンス: summary (string), topics (string[]), message_count (int)

GenerateSearchQuery

トピックとカテゴリからWeb検索用の最適化された検索クエリを生成します。

リクエスト:

• topic (string): 検索するトピック
• category (string): コンテキスト用カテゴリ

レスポンス: query (string), context (string)

GroundedSearch

複数のクエリでグラウンデッドWeb検索を実行し、ソース付きの要約結果を返します。

リクエスト:

• queries (string[]): 検索クエリ
• context (string): 検索関連性のコンテキスト
• agent_name (string): レスポンスフレーミング用エージェント名

レスポンス: CEGroundedSearchResultのリスト (query, summary, sources with title/url/snippet)

マルチエージェント対話

アウティング、対話、マルチエージェントシーンのためのエージェント間会話。

AgentDialogue

マルチエージェント対話コンテキスト（例：エージェント間のアウティング）でエージェントのレスポンスを生成します。

リクエスト:

• agent_id (string): エージェントUUID（応答するエージェント）
• user_id (string): ユーザー識別子
• messages (CEChatMessage[]): 対話メッセージ
• request_type (string): "outing", "dialogue" など
• scene_guidance (string): シーン固有のプロンプトガイダンス
• tool_config_json (bytes): ツール設定JSON（任意）
• session_id (string): 自動コンテキストビルド用セッションID（任意）
• interaction_role (string): "owner" または "non_owner"（デフォルト: "owner"）

レスポンス: response (string), side_effects_json (bytes)

アプリケーションイベント

重要なアプリケーションイベントについてプラットフォームに通知します。プラットフォームは日記エントリの生成、目標の更新、その他のAIアクションを実行する場合があります。日記が作成されるとOnDiaryGenerated webhookが発火します。

TriggerEvent

アプリケーションイベント（達成、マイルストーン、ブレイクスルー、完了）を受け入れ、AIコンテンツ生成をトリガーします。

リクエスト:

• agent_id (string): エージェントUUID
• user_id (string): ユーザー識別子
• event_type (string): "achievement", "milestone", "breakthrough", "level_up"
• event_description (string): AI用の人間可読なコンテキスト
• metadata (map<string, string>): 追加コンテキスト (achievement_id, level など)
• language (string): 生成コンテンツの言語（デフォルト: "en"）

レスポンス: accepted (bool), event_id (string)

ナレッジベース

プロジェクトスコープのナレッジグラフ。ドキュメントをアップロードするか、API経由で構造化データをプッシュします -- プラットフォームがエンティティを抽出し、グラフを構築し、エージェントに会話中にクエリするための knowledge_search ツールを提供します。

ドキュメント

ドキュメントのアップロード

POST /projects/{projectId}/knowledge/documents

ドキュメントをアップロード（'file'フィールドのmultipart/form-data、最大50 MB）。202を返し、document_idとともに非同期抽出をトリガーします。

パラメーター:

• file (multipart): ドキュメントファイル

レスポンス: document_id, file_name, file_size, checksum, status, gcs_path

ドキュメント一覧

GET /projects/{projectId}/knowledge/documents

ドキュメント一覧。クエリ: limit（デフォルト50、最大200）。

レスポンス: documents[], total

ドキュメント取得

GET /projects/{projectId}/knowledge/documents/{docId}

単一のドキュメントを取得。

レスポンス: KBDocumentオブジェクト

ドキュメント削除

DELETE /projects/{projectId}/knowledge/documents/{docId}

ドキュメントを削除。

レスポンス: 204 No Content

ファクト＆グラフ

ファクト挿入

POST /projects/{projectId}/knowledge/facts

ナレッジグラフにエンティティとリレーションシップを挿入。既存ノードに対して解決し、バージョン履歴付きで作成/更新します。

パラメーター:

• source (string): ソース識別子（デフォルト: 'api'）
• facts[] (array): エンティティ: entity_type, label, properties
• relationships[] (array): エッジ: from_label, to_label, edge_type

レスポンス: processed, created, updated, details[]

ノード一覧

GET /projects/{projectId}/knowledge/nodes

ナレッジグラフノード一覧。クエリ: type（フィルター）、limit（デフォルト100、最大500）。

レスポンス: nodes[], total

ノード取得

GET /projects/{projectId}/knowledge/nodes/{nodeId}

接続されたエッジ付きのノードを取得。クエリ: history=trueでバージョン履歴。

レスポンス: node, outgoing[], incoming[], history[]

ノード削除

DELETE /projects/{projectId}/knowledge/nodes/{nodeId}

ノードを論理削除（is_active=falseに設定）。

レスポンス: 204 No Content

ノード履歴

GET /projects/{projectId}/knowledge/nodes/{nodeId}/history

ノードのバージョン履歴を取得。クエリ: limit（デフォルト50、最大200）。

レスポンス: history[], total

検索

ナレッジベース検索

GET /projects/{projectId}/knowledge/search

グラフトラバーサル付き全文検索。クエリ: q（必須）、limit、history、type、filters（JSON）。

パラメーター:

• q (string): 検索クエリ（必須）
• limit (int): 最大結果数（デフォルト20、最大100）
• type (string): フィルターするエンティティタイプ（カンマ区切り）
• filters (JSON string): プロパティフィルターオブジェクト
• history (bool): バージョン履歴を含める

レスポンス: query, results[]（関連ノード付き）, total

スキーマ

スキーマ作成

POST /projects/{projectId}/knowledge/schemas

フィールドと任意の類似性設定を持つエンティティタイプスキーマを作成。

パラメーター:

• entity_type (string): エンティティタイプ名（必須）
• fields[] (array): フィールド定義: name, type, required
• description (string): スキーマの説明
• similarity_config (object): match_fields[], threshold

レスポンス: KBEntitySchemaオブジェクト

スキーマ一覧

GET /projects/{projectId}/knowledge/schemas

プロジェクトのエンティティスキーマ一覧。

レスポンス: schemas[], total

スキーマ更新

PUT /projects/{projectId}/knowledge/schemas/{schemaId}

エンティティスキーマを更新。

パラメーター:

• entity_type (string): 更新されたエンティティタイプ名
• fields[] (array): 更新されたフィールド定義

レスポンス: KBEntitySchemaオブジェクト

スキーマ削除

DELETE /projects/{projectId}/knowledge/schemas/{schemaId}

エンティティスキーマを削除。

レスポンス: 204 No Content

統計

KB統計取得

GET /projects/{projectId}/knowledge/stats

ナレッジベース統計を取得（ドキュメント数、ノード数、エッジ数、抽出トークン数）。

レスポンス: documents {total, indexed, pending, failed}, nodes {total, active}, edges, extraction_tokens

アナリティクス

アナリティクスルール作成

POST /projects/{projectId}/knowledge/analytics/rules

アナリティクスルール（レコメンデーションまたはトレンド）を作成。

パラメーター:

• rule_type (string): 'recommendation' または 'trend'
• name (string): ルール名
• config (object): ルール設定
• enabled (bool): ルールが有効かどうか

レスポンス: KBAnalyticsRuleオブジェクト

レコメンデーション取得

GET /projects/{projectId}/knowledge/analytics/recommendations

レコメンデーションを取得。クエリ: rule_id, source_id（両方必須）, limit。

レスポンス: recommendations[], total

トレンド取得

GET /projects/{projectId}/knowledge/analytics/trends

トレンド集計を取得。クエリ: node_id（必須）。

レスポンス: trends[], total

フィードバック記録

POST /projects/{projectId}/knowledge/analytics/feedback

レコメンデーションフィードバック（表示/コンバージョン）を記録。

パラメーター:

• source_node_id (string): ソースノードID
• target_node_id (string): ターゲットノードID
• rule_id (string): アナリティクスルールID
• converted (bool): ユーザーがコンバージョンしたかどうか
• score_at_time (float): レコメンデーション表示時のスコア

レスポンス: status: 'recorded'

ユーザープライミング

ユーザーメタデータとコンテンツを事前ロードして、AIエージェントが最初の会話からユーザーを「知っている」状態にします。メタデータ（名前、会社、役職）は即座にファクトになります。コンテンツブロック（テキスト、チャットトランスクリプト）はLLM抽出を介して非同期で処理されます。

ユーザーのプライミング

ユーザーをプライミング

POST /agents/{agentId}/users/{userId}/prime

メタデータとコンテンツでユーザーをプライミング。202をジョブIDとともに返します。コンテンツのLLM抽出は非同期で実行されます。

パラメーター:

• display_name (string): ユーザーの表示名
• metadata (object): company, title, email, phone, custom (map)
• content[] (array): コンテンツブロック: type ('text', 'chat_transcript'), body
• source (string): ソース識別子（例: 'crm', 'linkedin'）

レスポンス: job_id, status ('queued'), facts_created

プライミングステータス取得

GET /agents/{agentId}/users/{userId}/prime/{jobId}

プライミングジョブのステータスを取得。

レスポンス: ImportJobオブジェクト (job_id, status, facts_created, error_message など)

コンテンツ

コンテンツ追加

POST /agents/{agentId}/users/{userId}/content

非同期LLM抽出用のコンテンツブロックを追加（例：プライミング後にチャットトランスクリプトを追加）。

パラメーター:

• content[] (array): コンテンツブロック: type, body
• source (string): ソース識別子

レスポンス: job_id, status ('queued')

メタデータ

ユーザーメタデータ取得

GET /agents/{agentId}/users/{userId}/metadata

ユーザーのプライミングメタデータを取得。

レスポンス: UserPrimingMetadataオブジェクト

ユーザーメタデータ更新

PATCH /agents/{agentId}/users/{userId}/metadata

プライミングメタデータを部分更新。更新されたフィールドから新しいファクトが自動生成されます。

パラメーター:

• display_name (string): 更新された名前
• company (string): 更新された会社
• title (string): 更新された役職
• email (string): 更新されたメール
• phone (string): 更新された電話番号
• custom (map): カスタムキーバリューペア（マージ）

レスポンス: metadata（更新済み）, facts_created

バッチインポート

バッチユーザーインポート

POST /agents/{agentId}/users/import

単一のリクエストでメタデータとコンテンツを含む複数のユーザーをインポート。メタデータファクトは同期的に作成。コンテンツ抽出は非同期で実行。

パラメーター:

• users[] (array): {user_id, display_name, metadata, content[]}の配列
• source (string): ソース識別子

レスポンス: job_id, status ('queued'), total_users, facts_created

インポートステータス取得

GET /agents/{agentId}/users/import/{jobId}

バッチインポートジョブのステータスを取得。

レスポンス: ImportJobオブジェクト

インポートジョブ一覧

GET /agents/{agentId}/users/imports

エージェントの最近のインポートジョブ一覧。クエリ: limit（デフォルト20）。

レスポンス: jobs[], count

共通型

BackendContext

• custom_fields (map<string, string>): プロンプトにパススルーされるアプリケーション固有の任意キーバリューペア
• state_json (bytes): 任意の構造化状態（JSON）（プロンプトにパススルー）

CEBig5Scores

• openness (double): 経験への開放性 (0.0-1.0)
• conscientiousness (double): 組織性と規律 (0.0-1.0)
• extraversion (double): 社交的エネルギーと熱意 (0.0-1.0)
• agreeableness (double): 温かさと協調性 (0.0-1.0)
• neuroticism (double): 感情的敏感さ (0.0-1.0)
• confidence (double): 評価の信頼度 (0.0-1.0)

BFASFacets

Big5スコアから導出されます。パーソナリティプロファイルレスポンスで読み取り専用です。

• intellect (double): Openness ファセット — 知的好奇心 (0.0-1.0)
• aesthetic (double): Openness ファセット — 美的感受性 (0.0-1.0)
• industriousness (double): Conscientiousness ファセット — 自己規律 (0.0-1.0)
• orderliness (double): Conscientiousness ファセット — 秩序への選好 (0.0-1.0)
• enthusiasm (double): Extraversion ファセット — ポジティブ感情 (0.0-1.0)
• assertiveness (double): Extraversion ファセット — 社会的主導性 (0.0-1.0)
• compassion (double): Agreeableness ファセット — 共感 (0.0-1.0)
• politeness (double): Agreeableness ファセット — 他者への敬意 (0.0-1.0)
• withdrawal (double): Neuroticism ファセット — 引きこもり傾向 (0.0-1.0)
• volatility (double): Neuroticism ファセット — 感情的不安定性 (0.0-1.0)

BehavioralTraits

パーソナリティから導出されます。パーソナリティプロファイルレスポンスで読み取り専用です。

• response_length (string): エージェントの発話の冗長さまたは簡潔さ
• question_frequency (string): エージェントがフォローアップ質問をする頻度
• empathy_style (string): 感情的サポートへのアプローチ（受容的、解決志向など）
• conflict_approach (string): 意見の相違への対処方法（順応的、直接的、仲介的など）

MoodState

• valence (double): 快-不快スペクトラム (0-100)
• arousal (double): 活性化/エネルギーレベル (0-100)
• tension (double): ストレス/穏やかさ状態 (0-100)
• affiliation (double): 社会的温かさ/親密さ (0-100)

CEChatMessage

• role (string): "user" または "assistant"
• content (string): メッセージテキスト
• timestamp (Timestamp): メッセージ送信時刻

MemoryCandidate

• content (string): 記憶コンテンツテキスト
• fact_type (string): preference, commitment, fact, experience, correction
• importance (double): 重要度スコア (0.0-1.0)
• entities (string[]): 関連エンティティ

Habit

• name (string): 習慣名
• category (string): 習慣カテゴリ
• strength (double): 現在の強度 (0.0-1.0)
• last_observed (Timestamp): 最終観測時刻
• is_formed (bool): 習慣が完全に形成されているかどうか

CEGoal

• id (string): 目標識別子
• description (string): 目標の説明
• status (string): "active", "completed", "abandoned"
• priority (string): 優先度レベル
• related_traits (string[]): 関連パーソナリティ特性
• created_at (Timestamp): 目標作成時刻

Interest

• topic (string): 興味のトピック
• category (string): 興味のカテゴリ
• confidence (double): 検出信頼度 (0.0-1.0)
• discovered_at (Timestamp): 興味が発見された時刻
• research_status (string): "pending" または "researched"

CEModelConfig

• provider (string): LLMプロバイダー名
• model (string): モデル識別子
• temperature (double): サンプリングTemperature
• max_tokens (int32): 生成する最大トークン数

ProactiveMessage

• message_id (string): 一意のメッセージ識別子
• agent_id (string): メッセージを生成したエージェント
• user_id (string): ターゲットユーザー
• wakeup_id (string): 関連するウェイクアップイベント
• check_type (string): チェックタイプ (check_in, follow_up, mood_driven)
• intent (string): エージェントが連絡を取りたい理由
• generated_message (string): 実際のメッセージテキスト
• status (string): pending, consumed, expired, failed_generation
• created_at (Timestamp): 生成時刻