NeboAI
NeboAI
Bắt đầu

App Sidecar

Sidecar là một tệp nhị phân chạy bên cạnh ứng dụng. Nó phục vụ API của trang, lưu giữ dữ liệu của ứng dụng và cung cấp công cụ cho nhân viên của ứng dụng. Nebo khởi động nó, định tuyến yêu cầu tới nó qua một socket cục bộ và khởi động lại khi nó gặp lỗi.

Giao kèo

Sidecar là một máy chủ gRPC trên Unix socket. Lắng nghe trên đường dẫn trong NEBO_APP_SOCK và triển khai apps.v0.UIService. Nebo gọi HandleRequest cho mọi yêu cầu; HealthCheck và Configure là một phần của dịch vụ nhưng hiện chưa được gọi. Socket phải xuất hiện trong khoảng startup_timeout của manifest, mặc định là 10 giây và tối đa là 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 chạy trên macOS và Linux.

Nơi Nebo tìm tệp nhị phân

Trong thư mục của ứng dụng, Nebo dùng mục đầu tiên tồn tại trong danh sách sau:

  1. Một tệp tên binary
  2. Một tệp tên app
  3. Tệp đầu tiên trong tmp/
  4. Tệp đầu tiên trong bin/
  5. Tệp thực thi đầu tiên trong sidecar/target/release/, dành cho phát triển cục bộ

Tệp nhị phân phải là một tệp thông thường có quyền thực thi, không phải liên kết tượng trưng, và tối đa 500 MB. Ứng dụng đã xuất bản mang nó tại bin/<name>. Khi tệp thay đổi trên ổ đĩa, Nebo khởi động lại sidecar.

Môi trường

Sidecar khởi động với một môi trường trống và các biến sau:

BiếnGiá trị
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSIONDanh tính của ứng dụng.
NEBO_APP_DIRThư mục của ứng dụng.
NEBO_APP_SOCKSocket để lắng nghe, <app folder>/<id>.sock. Nebo đặt chế độ của nó là 0600.
NEBO_DATA_DIRThư mục dữ liệu của ứng dụng, <data>/appdata/agents/<id>/. Đồng thời là thư mục làm việc.
NEBO_API_URLAPI cục bộ của bot, http://127.0.0.1:<port>.
NEBO_APP_TOKENToken để gọi API ứng dụng của bot.
PATH, HOME, TMPDIR, LANG, LC_ALL, TZTruyền nguyên.

Đầu ra chuẩn và lỗi chuẩn được ghi vào sidecar.log trong thư mục dữ liệu. Đầu vào chuẩn là một pipe; kết thúc tệp nghĩa là Nebo đã dừng và sidecar nên thoát. Sidecar chạy trong nhóm tiến trình riêng.

Yêu cầu từ trang

Một yêu cầu tới /apps/<id>/api/<path>, mà trang gửi bằng neboFetch với một đường dẫn tương đối, sẽ đến HandleRequest với path được đặt là <path>. Các đường dẫn bắt đầu bằng _ bị từ chối. Nội dung yêu cầu giới hạn ở 10 MB và phản hồi ở 32 MB.

Công cụ cho nhân viên

Khai báo công cụ trong agent.json của ứng dụng. Mỗi mục trở thành một công cụ tên app__<app>__<name>, được nạp khi nhân viên cần. Một lệnh gọi trở thành một yêu cầu tới sidecar tại method và 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" } } }
  }
]

Gọi Nebo

Sidecar có thể dùng các dịch vụ giống như trang bằng cách gọi $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... với header Authorization: Bearer $NEBO_APP_TOKEN.

TuyếnChức năng
GET /storage, GET|PUT|DELETE /storage/<key>Kho khóa-giá trị của ứng dụng.
POST /agents/invoke, POST /agents/streamHỏi một nhân viên: {message, agent, data}. Phản hồi dạng luồng là server-sent events.
POST /janus/complete, POST /janus/streamMột lệnh gọi mô hình trực tiếp: {messages, model, temperature, max_tokens, system}.
POST /http/proxyMột yêu cầu ra bên ngoài, {url, method, headers, body}, được cho phép bởi các quyền network: của ứng dụng.
GET /identityNhân viên của ứng dụng.

Vòng đời

  • Nebo thăm dò socket mỗi ba giây.
  • Sidecar gặp lỗi sẽ khởi động lại sau một giây, thời gian chờ tăng gấp đôi đến tối đa 60 giây. Sau năm lần lỗi liên tiếp, nó bị đánh dấu là thất bại. Sidecar chạy ổn định trong 60 giây sẽ được coi là khỏe mạnh trở lại.
  • Một yêu cầu tới sidecar đã dừng sẽ khởi động nó và chờ tối đa 15 giây. Các yêu cầu GET và HEAD được thử lại.
  • Để dừng sidecar, Nebo gửi SIGTERM tới nhóm tiến trình của nó, rồi buộc dừng sau hai giây.