HTTP APIとWebSocket

このドキュメントでは、LLM Chatパッケージサービスが提供するHTTP APIエンドポイントとWebSocketプロトコルをまとめます。

パッケージはゲートウェイ/ワーカー構成を採用しています。ブラウザーがゲートウェイへWebSocketを開くと、ゲートウェイがセッションごとにワーカープロセスを起動し、エージェンティックループを実行します。チャットはすべてWebSocketで処理され、HTTPは使いません — HTTPエンドポイントは設定、ユーザー環境設定、ヘルス/診断の用途にのみ使われます。

HTTP APIエンドポイント

設定のレスポンスはすべて{ success, reason, data }形式のJSONを使います。CORSのプリフライトを避けるため、PUT / DELETEはクエリパラメーター_method=PUTまたは_method=DELETEとtext/plainの本文を持つPOSTとしても送信できます。

ヘルスと診断

サービスポートはconfigs/sys.jsonのserver.portで指定します（デフォルト8884）。ランチャーが起動時にこの値を読み込みます。

ユーザー設定

設定はユーザーごとに保存されます（configs/{user}.json）。設定名はMachbaseのユーザー名です。

以下のトークン検証・設定・環境設定APIでは、すべてのリクエストにAuthorization: Bearer {APIトークン}ヘッダーが必要です（Neo Webコンソールで発行したnt_で始まるトークン）。サーバーはMachbase NeoのPOST /db/token/validateでトークンを検証してアカウントを確定し、本人のものではない名前を要求すると拒否します。アカウント名は小文字で扱います（例：SYS → sys）。

トークン検証

Settings画面の검증（検証）ボタンがこのAPIを呼び出します。コンソールのログインアカウントと一致するかどうかは、ブラウザー側で別途確認します。

ユーザー別UI環境設定

対象ユーザーはトークンから決まります — 名前をパラメーターとして受け取りません。

WebSocketパス

リレールート

接続先のMachbase Neoサーバーへ直接プロキシするルートです（UIがTQLを実行し、チャート/ダッシュボードを描画するときに使用）。

リレーは呼び出し元トークンのアカウントで実行されるため、権限外のテーブルはMachbaseが拒否します。

例：ヘルスチェック

curl http://localhost:8884/health

{"ok": true}

例：トークン検証

TOKEN=nt_a_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
curl -H "Authorization: Bearer $TOKEN" http://localhost:8884/api/token/validate

{"success": true, "reason": "success", "data": {"user": "sys"}}

例：保存済み設定の一覧

curl -H "Authorization: Bearer $TOKEN" http://localhost:8884/api/configs

{"success": true, "reason": "success", "data": {"configs": ["sys"]}}

トークンなしで呼び出すと401が返ります。

WebSocketプロトコル

チャットUIはWebSocketでサービスと通信します。接続URLはws://{host}:{port}/wsです。ゲートウェイは各セッションをワーカープロセスへルーティングし、ワーカーのストリーミングメッセージをブラウザーへ中継します。

すべてのクライアントメッセージにauth_token（Machbase Neo APIトークン）を含める必要があります。ゲートウェイはメッセージごとにトークンを検証してユーザーを確定するため、トークンを変更したりNeoでトークンを削除したりすると、次のメッセージからすぐに反映されます。user_idフィールドは本人の判定には使いません。

検証したトークンは、ゲートウェイがワーカーへ送るchatメッセージにのみ載せて渡し、ワーカー設定ファイル（workers/*.json）やユーザー設定ファイルには記録しません。

検証に失敗すると、次のレスポンスが返ります。

{"type": "error", "code": "auth_required", "msg": "API 토큰이 확인되지 않았습니다. 설정에서 토큰을 확인한 뒤 다시 시도하세요."}

別のアカウントが作成したセッションIDでメッセージを送ると、code: "auth_required"、msg: "다른 계정의 세션입니다."（別アカウントのセッションです）で拒否します。

クライアント → サーバーメッセージ

get_models — 利用可能なLLMプロバイダーとモデルを要求します。

{"type": "get_models", "auth_token": "nt_a_xxxx..."}

chat — チャットメッセージを送信します（providerとmodelは必須）。

{
  "type": "chat",
  "auth_token": "nt_a_xxxx...",
  "session_id": "sess-1234567890",
  "provider": "claude",
  "model": "claude-sonnet-4-6",
  "query": "Analyze the GOLD table",
  "tz": "Asia/Seoul"
}

tzは任意で、ブラウザのタイムゾーン（IANA名）です。照会結果・チャート・レポートの時刻と、モデルに伝える現在時刻の基準になり、省略するとサーバーのタイムゾーンを使います。

stop — 現在の生成を停止します。

{"type": "stop", "session_id": "sess-1234567890"}

clear — セッションを初期化します（ワーカーを終了）。

{"type": "clear", "session_id": "sess-1234567890"}

サーバー → クライアントメッセージ

models — get_modelsに対するレスポンスです。

{"type": "models", "providers": [ { "provider": "claude", "models": ["..."] } ]}

このアカウントの設定がまだ保存されていない場合は、providersの代わりに次が返ります。

{"type": "models", "msg": "No providers configured. Please set API keys in Settings."}

msg — ストリーミングのエンベロープです。進行状況の説明も最終回答も、すべてmsgイベントとして届きます。内部のmessage.typeが段階を表し、テキストはbody.ofStreamBlockDeltaで届きます。

{
  "type": "msg",
  "message": {
    "ver": "1.0",
    "id": 1699999999999,
    "type": "stream_block_delta",
    "body": {
      "ofStreamBlockDelta": {
        "contentType": "text/markdown",
        "text": "Querying the GOLD table..."
      }
    }
  }
}

内部のmessage.typeの段階（発生順）は次のとおりです。

• answer_start — 応答の開始
• stream_block_start / stream_block_delta / stream_block_stop — 進行状況の説明（ツールの各ステップがここでマークダウンテキストとして説明される）
• stream_msg_start / stream_msg_delta / stream_msg_stop — 最終回答のテキスト
• answer_stop — 応答の完了

followups — 回答の後に続けて尋ねるとよい質問の候補（生成できない場合は送られません）：

{"type": "followups", "session_id": "sess-1234567890", "items": ["..."]}

error — エラーが発生したことを通知します（例：config_requiredのようなcodeを含む場合があります）。

{"type": "error", "session_id": "sess-1234567890", "msg": "Agent error: ..."}

注：tool_call / tool_resultという個別のメッセージはありません。ツールの動作は、stream_block_deltaの進行イベントの中でマークダウンテキストとしてストリーミングされます。

ページ移動

• 前へ：技術リファレンス
• 目次に戻る
• 次へ：トラブルシューティング