NeboAI
NeboAI
開始使用

App Sidecar

sidecar 是在應用程式旁執行的二進位檔。它提供頁面的 API、保存應用程式的資料,並為應用程式的員工提供工具。Nebo 會啟動它、透過本機 socket 將請求路由給它,並在它失敗時重新啟動它。

合約

sidecar 是在 Unix socket 上執行的 gRPC 伺服器。監聽 NEBO_APP_SOCK 中的路徑,並實作 apps.v0.UIService。Nebo 會為每個請求呼叫 HandleRequest;HealthCheck 與 Configure 雖然是服務的一部分,但目前不會被呼叫。socket 必須在 manifest 的 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;
}

sidecar 可在 macOS 與 Linux 上執行。

Nebo 在哪裡找二進位檔

在應用程式的資料夾中,Nebo 會使用以下項目中第一個存在的:

  1. 名為 binary 的檔案
  2. 名為 app 的檔案
  3. tmp/ 中的第一個檔案
  4. bin/ 中的第一個檔案
  5. sidecar/target/release/ 中的第一個可執行檔,供本機開發使用

二進位檔必須是一般的可執行檔,不能是符號連結,且大小不超過 500 MB。已發布的應用程式會將它放在 bin/<name>。當磁碟上的檔案變更時,Nebo 會重新啟動 sidecar。

環境

sidecar 會以空白的環境啟動,並帶有以下變數:

變數值
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSION應用程式的身分。
NEBO_APP_DIR應用程式的資料夾。
NEBO_APP_SOCK要監聽的 socket,<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 已經離開,sidecar 應該結束。sidecar 在自己的程序群組中執行。

來自頁面的請求

對 /apps/<id>/api/<path> 的請求(頁面以 neboFetch 搭配相對路徑發出)會送達 HandleRequest,並將 path 設為 <path>。以 _ 開頭的路徑會被拒絕。請求內文上限為 10 MB,回應上限為 32 MB。

給員工的工具

在應用程式的 agent.json 中宣告工具。每個工具都會成為名為 app__<app>__<name> 的工具,在員工需要時載入。一次呼叫會變成以 method 和 path 對 sidecar 發出的請求。

"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

sidecar 可以使用與頁面相同的服務,方法是以標頭 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}。串流回應採用伺服器推送事件。
POST /janus/complete, POST /janus/stream直接模型呼叫:{messages, model, temperature, max_tokens, system}。
POST /http/proxy對外部的請求,{url, method, headers, body},依應用程式的 network: 權限允許。
GET /identity應用程式的員工。

生命週期

  • Nebo 每三秒探測一次 socket。
  • 失敗的 sidecar 會在一秒後重新啟動,間隔每次加倍,最長 60 秒。連續失敗五次後會被標記為失敗。持續運作 60 秒的 sidecar 會再度被視為正常。
  • 對已停止的 sidecar 發出請求時會啟動它,並最多等待 15 秒。GET 與 HEAD 請求會自動重試。
  • 要停止 sidecar 時,Nebo 會對其程序群組傳送 SIGTERM,兩秒後再強制終止。