Контракт
Супровідний процес — це 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 використовує перший наявний із цих варіантів:
- Файл із назвою
binary - Файл із назвою
app - Перший файл у
tmp/ - Перший файл у
bin/ - Перший виконуваний файл у
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 його групі процесів, а через дві секунди примусово завершує його.