NeboAI
NeboAI
Începe

Sidecar pentru aplicații

Un sidecar este un binar care rulează lângă o aplicație. Servește API-ul paginii, păstrează datele aplicației și îi dă angajatului aplicației instrumente. Nebo îl pornește, îi direcționează cererile printr-un socket local și îl repornește când cade.

Contractul

Un sidecar este un server gRPC pe un socket Unix. Ascultă pe calea din NEBO_APP_SOCK și implementează apps.v0.UIService. Nebo apelează HandleRequest pentru fiecare cerere; HealthCheck și Configure fac parte din serviciu, dar nu sunt apelate deocamdată. Socketul trebuie să apară în intervalul startup_timeout din manifest, care este implicit de 10 secunde și poate fi de cel mult 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;
}

Sidecarurile rulează pe macOS și Linux.

Unde găsește Nebo binarul

În folderul aplicației, Nebo îl folosește pe primul dintre acestea care există:

  1. Un fișier numit binary
  2. Un fișier numit app
  3. Primul fișier din tmp/
  4. Primul fișier din bin/
  5. Primul executabil din sidecar/target/release/, pentru dezvoltarea locală

Binarul trebuie să fie un fișier obișnuit, executabil, nu un link simbolic, și să aibă cel mult 500 MB. Aplicațiile publicate îl conțin la bin/<name>. Când fișierul se schimbă pe disc, Nebo repornește sidecarul.

Mediu

Sidecarul pornește cu un mediu gol și cu aceste variabile:

VariabilăValoare
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSIONIdentitatea aplicației.
NEBO_APP_DIRFolderul aplicației.
NEBO_APP_SOCKSocketul pe care se ascultă, <app folder>/<id>.sock. Nebo îi setează modul la 0600.
NEBO_DATA_DIRFolderul de date al aplicației, <data>/appdata/agents/<id>/. Este și directorul de lucru.
NEBO_API_URLAPI-ul local al botului, http://127.0.0.1:<port>.
NEBO_APP_TOKENUn token pentru apelarea API-ului de aplicații al botului.
PATH, HOME, TMPDIR, LANG, LC_ALL, TZTransmis mai departe.

Ieșirea standard și eroarea standard ajung în sidecar.log, în folderul de date. Intrarea standard este un pipe; sfârșitul fișierului înseamnă că Nebo a dispărut și sidecarul ar trebui să se închidă. Sidecarul rulează în propriul grup de procese.

Cereri de la pagină

O cerere către /apps/<id>/api/<path>, pe care pagina o face cu neboFetch și o cale relativă, ajunge la HandleRequest cu path setat la <path>. Căile care încep cu _ sunt refuzate. Corpul cererilor e limitat la 10 MB, iar răspunsurile la 32 MB.

Instrumente pentru angajat

Declară instrumentele în agent.json al aplicației. Fiecare devine un instrument numit app__<app>__<name>, încărcat când angajatul are nevoie de el. Un apel devine o cerere către sidecar la 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" } } }
  }
]

Apelarea lui Nebo

Sidecarul poate folosi aceleași servicii ca pagina, apelând $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... cu antetul Authorization: Bearer $NEBO_APP_TOKEN.

RutăCe face
GET /storage, GET|PUT|DELETE /storage/<key>Depozitul cheie-valoare al aplicației.
POST /agents/invoke, POST /agents/streamÎntreabă un angajat: {message, agent, data}. Răspunsurile în flux sunt evenimente trimise de server.
POST /janus/complete, POST /janus/streamUn apel direct către model: {messages, model, temperature, max_tokens, system}.
POST /http/proxyO cerere externă, {url, method, headers, body}, permisă de permisiunile network: ale aplicației.
GET /identityAngajatul aplicației.

Ciclul de viață

  • Nebo verifică socketul la fiecare trei secunde.
  • Un sidecar căzut repornește după o secundă, intervalul dublându-se până la cel mult 60 de secunde. După cinci eșecuri la rând, e marcat ca eșuat. Un sidecar care rămâne pornit 60 de secunde e considerat din nou sănătos.
  • O cerere către un sidecar oprit îl pornește și așteaptă până la 15 secunde. Cererile GET și HEAD sunt reîncercate.
  • Ca să oprească un sidecar, Nebo trimite SIGTERM grupului lui de procese, apoi îl oprește forțat după două secunde.