Skip to content

v1.0

Jump to bottom
Cizzuk edited this page May 10, 2026 · 4 revisions

Side Bridge Protocol v1.0の仕様です。

接続の概要

  • 通信方式: HTTP/HTTPS
  • メソッド: POST
  • Content-Type: application/json
  • 認証ヘッダー(任意): x-sidebridge-key

クライアントはJSONのリクエストを送信し、BridgeもJSONのレスポンスを返します。

通信の大まかな流れ

  • セッション開始時、messagesがないUser Requestを送信します。
    • 履歴から復元された場合などには、historyが含まれることがあります。
    • このリクエストへのレスポンスにもoptionsを含めることができます。
  • ユーザーがメッセージを確定すると、messages付きのUser Requestを送信します。
    • ユーザーはメッセージが空のままでも送信できます。空のメッセージは履歴には残りません。
  • Bridgeは全てのリクエストに対して、Bridge Responseを返します。

認証とセキュリティ

クライアントはx-sidebridge-keyヘッダーを使用して、任意文字列の認証キーをBridgeに送信できます。Side Searchではキーをキーチェーンに保存します。

本プロトコル自体は追加の暗号化や認証方式を規定しません。インターネットで使用する場合はHTTPSを使用したりVPNを使用するなど、ご自身で適切に通信内容を保護するようにしてください。

JSONスキーマ

必須キーが欠けている、または型が不正なJSONは、Side Searchがデコードする時にエラーになります。不要なキーは通常無視されます。

Message

{
  "id": "00000000-0000-0000-0000-000000000000",
  "from": "assistant",
  "content": "Hello World!",
  "sources": [
    {
      "title": "Example",
      "url": "https://example.com"
    }
  ]
}
  • id (必須): メッセージのUUID
  • from (必須): user, assistant, systemのいずれか
  • content (必須): メッセージの本文
  • sources: アシスタントが参照したWebページのURLなど
    • title (必須)
    • url (必須)

補足

  • contentの内容は、設定によってはマークダウンとしてレンダリングされます。

User Request (client -> bridge)

{
  "sidebridge": "1.0",
  "chatId": "00000000-0000-0000-0000-000000000000",
  "messages": [],
  "history": []
}
  • sidebridge (必須): プロトコルのバージョン
  • chatId (必須): チャットのUUID
  • messages: 今回送信するメッセージ
  • history: 会話履歴(古い順)

補足

  • options.disableSendHistoryがオンの場合、historyが省略されます。

Bridge Response (bridge -> client)

{
  "messages": [],
  "options": {
    "disableSendHistory": false,
    "endSession": false
  }
}
  • messages: 返信やエラーメッセージ
  • options: セッションオプション

補足

  • エラー時も可能ならmessagesに説明を入れて返すと、Side Search上でメッセージが表示されるため、おすすめです。

Session Options

{
  "disableSendHistory": false,
  "endSession": false
}
  • disableSendHistory: 次回以降のUser Requestからhistoryを省略
  • endSession: セッション終了フラグ

補足

  • endSessionをtrueにすると、以降アシスタントにメッセージを送信できなくなり、バックグラウンドで実行中の音声認識も停止します。

通信の流れのサンプル

実際の通信の際のJSONの例です。

ユーザーがアシスタントを開始した時

User Request

{
  "sidebridge": "1.0",
  "chatId": "401790B9-38C5-429D-AE6A-FC4CF35A88AD",
  "history": []
}

Bridge Response

{}

ユーザーが1つ目のメッセージを送信した時

User Request

{
  "sidebridge": "1.0",
  "chatId": "401790B9-38C5-429D-AE6A-FC4CF35A88AD",
  "messages": [
    {
      "id": "00C5D592-9490-4DB8-A25E-E81BA9CFA0B9",
      "from": "user",
      "content": "Hello Side Bridge!"
    }
  ],
  "history": [
    {
      "id": "00C5D592-9490-4DB8-A25E-E81BA9CFA0B9",
      "from": "user",
      "content": "Hello Side Bridge!"
    }
  ]
}

Bridge Response

{
  "messages": [
    {
      "id": "D2DF7849-6219-4BB3-AA06-19A9381ACDC1",
      "from": "assistant",
      "content": "Hello User!"
    }
  ]
}

ユーザーが2つ目のメッセージを送信して、会話が終了した時

User Request

{
  "sidebridge": "1.0",
  "chatId": "401790B9-38C5-429D-AE6A-FC4CF35A88AD",
  "messages": [
    {
      "id": "7B499EED-F880-4B00-BD63-4EE4490A2F47",
      "from": "user",
      "content": "Goodbye Assistant!"
    }
  ],
  "history": [
    {
      "id": "00C5D592-9490-4DB8-A25E-E81BA9CFA0B9",
      "from": "user",
      "content": "Hello Side Bridge!"
    },
    {
      "id": "D2DF7849-6219-4BB3-AA06-19A9381ACDC1",
      "from": "assistant",
      "content": "Hello User!"
    },
    {
      "id": "7B499EED-F880-4B00-BD63-4EE4490A2F47",
      "from": "user",
      "content": "Goodbye Assistant!"
    }
  ]
}

Bridge Response

{
  "messages": [
    {
      "id": "CD4625ED-C0FE-47D7-A489-F4C4DB1C903B",
      "from": "assistant",
      "content": "Thank you!"
    }
  ],
  "options": {
    "endSession": true
  }
}

Clone this wiki locally