NeboAI
NeboAI
开始使用

应用边车

sidecar 是一个与应用并行运行的二进制程序。它为页面提供 API、保存应用的数据,并为应用的员工提供工具。Nebo 负责启动它,通过本地套接字把请求路由给它,并在它出故障时重启它。

契约

sidecar 是运行在 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;
}

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要监听的套接字,<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 在自己的进程组中运行。

来自页面的请求

页面用 neboFetch 加相对路径发出的、发往 /apps/<id>/api/<path> 的请求,会到达 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}。流式响应为服务器发送事件(SSE)。
POST /janus/complete, POST /janus/stream直接调用模型:{messages, model, temperature, max_tokens, system}。
POST /http/proxy外部请求,{url, method, headers, body},需应用的 network: 权限允许。
GET /identity应用的员工。

生命周期

  • Nebo 每三秒探测一次套接字。
  • 出故障的 sidecar 会在一秒后重启,之后间隔逐次翻倍,最长 60 秒。连续失败五次后,它会被标记为失败。持续运行 60 秒的 sidecar 会重新被视为健康。
  • 发往已停止的 sidecar 的请求会启动它,并最多等待 15 秒。GET 和 HEAD 请求会自动重试。
  • 要停止 sidecar 时,Nebo 会向其进程组发送 SIGTERM,两秒后再强制结束它。