NeboAI
NeboAI
Почати

Супровідний процес застосунку

Супровідний процес — це виконуваний файл, що працює поряд із застосунком. Він обслуговує API сторінки, зберігає дані застосунку й дає співробітникові застосунку інструменти. Nebo запускає його, спрямовує до нього запити через локальний сокет і перезапускає, коли він збоїть.

Контракт

Супровідний процес — це 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;
}

Супровідні процеси працюють на macOS і Linux.

Де Nebo шукає виконуваний файл

У папці застосунку Nebo використовує перший наявний із цих варіантів:

  1. Файл із назвою binary
  2. Файл із назвою app
  3. Перший файл у tmp/
  4. Перший файл у bin/
  5. Перший виконуваний файл у sidecar/target/release/, для локальної розробки

Виконуваний файл має бути звичайним виконуваним файлом, а не символьним посиланням, і не більшим за 500 MB. Опубліковані застосунки містять його в bin/<name>. Коли файл на диску змінюється, Nebo перезапускає супровідний процес.

Середовище

Супровідний процес запускається з порожнім середовищем і такими змінними:

ЗміннаЗначення
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 завершив роботу і супровідний процес має вийти. Супровідний процес працює у власній групі процесів.

Запити зі сторінки

Запит до /apps/<id>/api/<path>, який сторінка робить через neboFetch з відносним шляхом, потрапляє в HandleRequest з path, рівним <path>. Шляхи, що починаються з _, відхиляються. Тіла запитів обмежено 10 MB, а відповіді — 32 MB.

Інструменти для співробітника

Оголошуйте інструменти в agent.json застосунку. Кожен стає інструментом із назвою app__<app>__<name>, що завантажується, коли він потрібен співробітникові. Виклик стає запитом до супровідного процесу за 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

Супровідний процес може користуватися тими самими сервісами, що й сторінка, викликаючи $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 перевіряє сокет кожні три секунди.
  • Збійний супровідний процес перезапускається через одну секунду, і затримка подвоюється до максимум 60 секунд. Після п’яти невдач поспіль він позначається як збійний. Супровідний процес, що пропрацював 60 секунд, знову вважається справним.
  • Запит до зупиненого супровідного процесу запускає його й чекає до 15 секунд. Запити GET і HEAD повторюються.
  • Щоб зупинити супровідний процес, Nebo надсилає SIGTERM його групі процесів, а через дві секунди примусово завершує його.