NeboAI
NeboAI
はじめる

アプリのサイドカー

サイドカーとは、アプリの横で動くバイナリです。ページのAPIを提供し、アプリのデータを保持し、アプリの社員にツールを与えます。Neboがサイドカーを起動し、ローカルソケット経由でリクエストを振り分け、失敗すると再起動します。

約束事

サイドカーは、Unixソケット上のgRPCサーバーです。NEBO_APP_SOCKのパスで待ち受け、apps.v0.UIServiceを実装してください。NeboはすべてのリクエストについてHandleRequestを呼び出します。HealthCheckとConfigureはサービスの一部ですが、現時点では呼び出されません。ソケットは、マニフェストのstartup_timeout(デフォルトは10秒、最大120秒)以内に現れる必要があります。

syntax = "proto3";
package apps.v0;

service UIService {
  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
  rpc Configure(SettingsMap) returns (Empty);
  rpc HandleRequest(HttpRequest) returns (HttpResponse);
}

message HttpRequest {
  string method = 1;               // GET, POST, PUT, DELETE, ...
  string path = 2;                 // relative to /apps/{id}/api/
  string query = 3;                // raw query string
  map<string, string> headers = 4;
  bytes body = 5;
}

message HttpResponse {
  int32 status_code = 1;
  map<string, string> headers = 2;
  bytes body = 3;
}

サイドカーはmacOSとLinuxで動きます。

Neboがバイナリを見つける場所

Neboは、アプリのフォルダ内で次のうち最初に見つかったものを使います:

  1. binaryという名前のファイル
  2. appという名前のファイル
  3. tmp/内の最初のファイル
  4. bin/内の最初のファイル
  5. sidecar/target/release/内の最初の実行ファイル(ローカル開発用)

バイナリは、シンボリックリンクではない通常の実行可能ファイルで、500 MB以下である必要があります。公開されたアプリではbin/<name>に置かれます。ディスク上のファイルが変わると、Neboはサイドカーを再起動します。

環境

サイドカーは、空の環境と次の変数で起動します:

変数値
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSIONアプリの身元情報。
NEBO_APP_DIRアプリのフォルダ。
NEBO_APP_SOCK待ち受けるソケット、<app folder>/<id>.sock。Neboがモードを0600に設定します。
NEBO_DATA_DIRアプリのデータフォルダ、<data>/appdata/agents/<id>/。作業ディレクトリでもあります。
NEBO_API_URLボットのローカルAPI、http://127.0.0.1:<port>。
NEBO_APP_TOKENボットのアプリAPIを呼び出すためのトークン。
PATH, HOME, TMPDIR, LANG, LC_ALL, TZそのまま引き継ぎ。

標準出力と標準エラー出力は、データフォルダ内のsidecar.logに書き込まれます。標準入力はパイプで、ファイルの終端はNeboがいなくなったことを意味するので、サイドカーは終了してください。サイドカーは独自のプロセスグループで動きます。

ページからのリクエスト

ページがneboFetchと相対パスで行う/apps/<id>/api/<path>へのリクエストは、pathが<path>に設定された状態でHandleRequestに届きます。_で始まるパスは拒否されます。リクエスト本文は10 MBまで、レスポンスは32 MBまでです。

社員向けのツール

アプリのagent.jsonでツールを宣言します。それぞれがapp__<app>__<name>という名前のツールになり、社員が必要とするときに読み込まれます。呼び出しは、methodとpathでのサイドカーへのリクエストになります。

"tools": [
  {
    "name": "list_deals",
    "description": "List open deals, optionally filtered by stage.",
    "method": "GET",
    "path": "/deals",
    "input_schema": { "type": "object", "properties": { "stage": { "type": "string" } } }
  }
]

Neboを呼び出す

サイドカーは、ヘッダーAuthorization: Bearer $NEBO_APP_TOKENを付けて$NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/...を呼び出すことで、ページと同じサービスを使えます。

ルート内容
GET /storage, GET|PUT|DELETE /storage/<key>アプリのキー・バリューストア。
POST /agents/invoke, POST /agents/stream社員への問い合わせ: {message, agent, data}。ストリームのレスポンスはServer-Sent Eventsです。
POST /janus/complete, POST /janus/streamモデルの直接呼び出し: {messages, model, temperature, max_tokens, system}。
POST /http/proxyアプリのnetwork:権限で許可された外部へのリクエスト、{url, method, headers, body}。
GET /identityアプリの社員。

ライフサイクル

  • Neboは3秒ごとにソケットを確認します。
  • 失敗したサイドカーは1秒後に再起動し、その間隔は倍々に延びて最大60秒になります。5回続けて失敗すると、失敗としてマークされます。60秒間動き続けたサイドカーは、再び正常と見なされます。
  • 停止中のサイドカーにリクエストが来ると、サイドカーが起動され、最大15秒待ちます。GETとHEADのリクエストは再試行されます。
  • サイドカーを停止するとき、NeboはそのプロセスグループにSIGTERMを送り、2秒後に強制終了します。