合約
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 會使用以下項目中第一個存在的:
- 名為
binary的檔案 - 名為
app的檔案 tmp/中的第一個檔案bin/中的第一個檔案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,兩秒後再強制終止。