NeboAI
NeboAI
Zacznij

Sidecar aplikacji

Sidecar to plik binarny działający obok aplikacji. Obsługuje API strony, przechowuje dane aplikacji i daje pracownikowi aplikacji narzędzia. Nebo go uruchamia, kieruje do niego żądania przez lokalne gniazdo i uruchamia go ponownie, gdy ulegnie awarii.

Kontrakt

Sidecar to serwer gRPC na gnieździe Unix. Nasłuchuj na ścieżce z NEBO_APP_SOCK i zaimplementuj apps.v0.UIService. Nebo wywołuje HandleRequest dla każdego żądania; HealthCheck i Configure należą do usługi, ale obecnie nie są wywoływane. Gniazdo musi pojawić się w czasie startup_timeout z manifestu, który domyślnie wynosi 10 sekund i może wynosić najwyżej 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;
}

Sidecary działają na macOS i Linuksie.

Gdzie Nebo szuka pliku binarnego

W folderze aplikacji Nebo używa pierwszego istniejącego z poniższych:

  1. Pliku o nazwie binary
  2. Pliku o nazwie app
  3. Pierwszego pliku w tmp/
  4. Pierwszego pliku w bin/
  5. Pierwszego pliku wykonywalnego w sidecar/target/release/, do lokalnego programowania

Plik binarny musi być zwykłym plikiem wykonywalnym, a nie dowiązaniem symbolicznym, i mieć najwyżej 500 MB. Opublikowane aplikacje mają go w bin/<name>. Gdy plik zmieni się na dysku, Nebo uruchamia sidecar ponownie.

Środowisko

Sidecar startuje z pustym środowiskiem i tymi zmiennymi:

ZmiennaWartość
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSIONTożsamość aplikacji.
NEBO_APP_DIRFolder aplikacji.
NEBO_APP_SOCKGniazdo do nasłuchiwania, <app folder>/<id>.sock. Nebo ustawia jego tryb na 0600.
NEBO_DATA_DIRFolder danych aplikacji, <data>/appdata/agents/<id>/. Jest to też katalog roboczy.
NEBO_API_URLLokalne API bota, http://127.0.0.1:<port>.
NEBO_APP_TOKENToken do wywoływania API aplikacji bota.
PATH, HOME, TMPDIR, LANG, LC_ALL, TZPrzekazywana bez zmian.

Standardowe wyjście i standardowe wyjście błędów trafiają do sidecar.log w folderze danych. Standardowe wejście to potok; koniec pliku oznacza, że Nebo zniknęło i sidecar powinien się zakończyć. Sidecar działa we własnej grupie procesów.

Żądania ze strony

Żądanie do /apps/<id>/api/<path>, które strona wysyła przez neboFetch ze ścieżką względną, trafia do HandleRequest z path ustawionym na <path>. Ścieżki zaczynające się od _ są odrzucane. Treść żądania jest ograniczona do 10 MB, a odpowiedzi do 32 MB.

Narzędzia dla pracownika

Zadeklaruj narzędzia w pliku agent.json aplikacji. Każde staje się narzędziem o nazwie app__<app>__<name>, ładowanym, gdy pracownik go potrzebuje. Wywołanie staje się żądaniem do sidecara pod method i 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" } } }
  }
]

Wywoływanie Nebo

Sidecar może korzystać z tych samych usług co strona, wywołując $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... z nagłówkiem Authorization: Bearer $NEBO_APP_TOKEN.

TrasaDziałanie
GET /storage, GET|PUT|DELETE /storage/<key>Magazyn klucz–wartość aplikacji.
POST /agents/invoke, POST /agents/streamPyta pracownika: {message, agent, data}. Odpowiedzi strumieniowe to zdarzenia wysyłane przez serwer (SSE).
POST /janus/complete, POST /janus/streamBezpośrednie wywołanie modelu: {messages, model, temperature, max_tokens, system}.
POST /http/proxyŻądanie zewnętrzne, {url, method, headers, body}, dozwolone przez uprawnienia network: aplikacji.
GET /identityPracownik aplikacji.

Cykl życia

  • Nebo sprawdza gniazdo co trzy sekundy.
  • Sidecar, który uległ awarii, uruchamia się ponownie po jednej sekundzie, a odstęp podwaja się do najwyżej 60 sekund. Po pięciu awariach z rzędu zostaje oznaczony jako niedziałający. Sidecar, który działa przez 60 sekund, znów jest uznawany za sprawny.
  • Żądanie do zatrzymanego sidecara uruchamia go i czeka do 15 sekund. Żądania GET i HEAD są ponawiane.
  • Aby zatrzymać sidecar, Nebo wysyła SIGTERM do jego grupy procesów, a po dwóch sekundach go zabija.