契约
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 会使用以下各项中第一个存在的:
- 名为
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 | 要监听的套接字,<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,两秒后再强制结束它。