NeboAI
NeboAI
Начать

Sidecar для приложений

Sidecar — это бинарный файл, который работает рядом с приложением. Он обслуживает API страницы, хранит данные приложения и даёт сотруднику приложения инструменты. Nebo запускает его, направляет к нему запросы через локальный сокет и перезапускает при сбое.

Контракт

Sidecar — это gRPC-сервер на Unix-сокете. Слушайте путь из 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 работает в собственной группе процессов.

Запросы со страницы

Запрос к /apps/<id>/api/<path>, который страница делает через neboFetch с относительным путём, попадает в HandleRequest с path, равным <path>. Пути, начинающиеся с _, отклоняются. Тело запроса ограничено 10 MB, ответа — 32 MB.

Инструменты для сотрудника

Объявите инструменты в agent.json приложения. Каждый становится инструментом с именем app__<app>__<name>, который загружается, когда он нужен сотруднику. Вызов превращается в запрос к sidecar по method и 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" } } }
  }
]

Обращение к Nebo

Sidecar может пользоваться теми же сервисами, что и страница, вызывая $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... с заголовком Authorization: Bearer $NEBO_APP_TOKEN.

МаршрутЧто делает
GET /storage, GET|PUT|DELETE /storage/<key>Хранилище «ключ — значение» приложения.
POST /agents/invoke, POST /agents/streamЗапрос к сотруднику: {message, agent, data}. Потоковые ответы приходят как server-sent events.
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 секунд. После пяти сбоев подряд он помечается как неисправный. Sidecar, который проработал 60 секунд, снова считается исправным.
  • Запрос к остановленному sidecar запускает его и ждёт до 15 секунд. Запросы GET и HEAD повторяются.
  • Чтобы остановить sidecar, Nebo отправляет SIGTERM его группе процессов, а через две секунды принудительно завершает её.