NeboAI
NeboAI
Začať

Sidecar aplikácie

Sidecar je binárny súbor, ktorý beží vedľa aplikácie. Obsluhuje API stránky, uchováva dáta aplikácie a dáva zamestnancovi aplikácie nástroje. Nebo ho spustí, smeruje mu požiadavky cez lokálny soket a pri zlyhaní ho reštartuje.

Kontrakt

Sidecar je server gRPC na sokete Unix. Počúvajte na ceste v NEBO_APP_SOCK a implementujte apps.v0.UIService. Nebo volá HandleRequest pre každú požiadavku; HealthCheck a Configure sú súčasťou služby, ale dnes sa nevolajú. Soket sa musí objaviť v rámci startup_timeout z manifestu, ktorý je predvolene 10 sekúnd a môže byť najviac 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 bežia na macOS a Linuxe.

Kde Nebo nájde binárny súbor

V priečinku aplikácie Nebo použije prvý existujúci z týchto:

  1. Súbor s názvom binary
  2. Súbor s názvom app
  3. Prvý súbor v tmp/
  4. Prvý súbor v bin/
  5. Prvý spustiteľný súbor v sidecar/target/release/, na lokálny vývoj

Binárny súbor musí byť bežný spustiteľný súbor, nie symbolický odkaz, a najviac 500 MB. Publikované aplikácie ho majú v bin/<name>. Keď sa súbor na disku zmení, Nebo sidecar reštartuje.

Prostredie

Sidecar sa spúšťa s prázdnym prostredím a týmito premennými:

PremennáHodnota
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSIONIdentita aplikácie.
NEBO_APP_DIRPriečinok aplikácie.
NEBO_APP_SOCKSoket, na ktorom treba počúvať, <app folder>/<id>.sock. Nebo mu nastaví režim 0600.
NEBO_DATA_DIRDátový priečinok aplikácie, <data>/appdata/agents/<id>/. Zároveň pracovný adresár.
NEBO_API_URLLokálne API bota, http://127.0.0.1:<port>.
NEBO_APP_TOKENToken na volanie API aplikácií bota.
PATH, HOME, TMPDIR, LANG, LC_ALL, TZPrenesené.

Štandardný výstup a štandardný chybový výstup idú do sidecar.log v dátovom priečinku. Štandardný vstup je rúra; koniec súboru znamená, že Nebo skončilo a sidecar by sa mal ukončiť. Sidecar beží vo vlastnej skupine procesov.

Požiadavky zo stránky

Požiadavka na /apps/<id>/api/<path>, ktorú stránka urobí pomocou neboFetch a relatívnej cesty, dorazí do HandleRequest s path nastaveným na <path>. Cesty, ktoré začínajú na _, sa odmietnu. Telá požiadaviek sú obmedzené na 10 MB a odpovede na 32 MB.

Nástroje pre zamestnanca

Nástroje deklarujte v agent.json aplikácie. Z každého sa stane nástroj s názvom app__<app>__<name>, ktorý sa načíta, keď ho zamestnanec potrebuje. Volanie sa zmení na požiadavku do sidecaru na method a 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" } } }
  }
]

Volanie Nebo

Sidecar môže používať tie isté služby ako stránka volaním $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... s hlavičkou Authorization: Bearer $NEBO_APP_TOKEN.

CestaRobí
GET /storage, GET|PUT|DELETE /storage/<key>Úložisko kľúč-hodnota aplikácie.
POST /agents/invoke, POST /agents/streamOpýta sa zamestnanca: {message, agent, data}. Streamované odpovede sú udalosti odosielané serverom.
POST /janus/complete, POST /janus/streamPriame volanie modelu: {messages, model, temperature, max_tokens, system}.
POST /http/proxyVonkajšia požiadavka, {url, method, headers, body}, povolená oprávneniami network: aplikácie.
GET /identityZamestnanec aplikácie.

Životný cyklus

  • Nebo kontroluje soket každé tri sekundy.
  • Zlyhaný sidecar sa reštartuje po jednej sekunde, s každým ďalším pokusom sa čas zdvojnásobí až na najviac 60 sekúnd. Po piatich zlyhaniach za sebou sa označí ako zlyhaný. Sidecar, ktorý vydrží bežať 60 sekúnd, je znova v poriadku.
  • Požiadavka na zastavený sidecar ho spustí a čaká až 15 sekúnd. Požiadavky GET a HEAD sa opakujú.
  • Na zastavenie sidecaru pošle Nebo jeho skupine procesov SIGTERM a po dvoch sekundách ho násilne ukončí.