NeboAI
NeboAI
Kom i gang

App-sidecar

En sidecar er en binær, der kører ved siden af en app. Den serverer sidens API, gemmer appens data og giver appens medarbejder værktøjer. Nebo starter den, sender anmodninger til den over en lokal socket og genstarter den, når den fejler.

Kontrakten

En sidecar er en gRPC-server på en Unix-socket. Lyt på stien i NEBO_APP_SOCK, og implementér apps.v0.UIService. Nebo kalder HandleRequest for hver anmodning; HealthCheck og Configure er en del af tjenesten, men kaldes ikke i dag. Socketten skal dukke op inden for manifestets startup_timeout, som er 10 sekunder som standard og højst må være 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;
}

Sidecars kører på macOS og Linux.

Hvor Nebo finder binæren

I appens mappe bruger Nebo den første af disse, der findes:

  1. En fil med navnet binary
  2. En fil med navnet app
  3. Den første fil i tmp/
  4. Den første fil i bin/
  5. Det første program i sidecar/target/release/, til lokal udvikling

Binæren skal være en almindelig, eksekverbar fil, ikke et symbolsk link, og højst 500 MB. Udgivne apps har den i bin/<name>. Når filen ændres på disken, genstarter Nebo sidecaren.

Miljø

Sidecaren starter med et tomt miljø og disse variabler:

VariabelVærdi
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSIONAppens identitet.
NEBO_APP_DIRAppens mappe.
NEBO_APP_SOCKSocketten, der skal lyttes på, <app folder>/<id>.sock. Nebo sætter dens tilstand til 0600.
NEBO_DATA_DIRAppens datamappe, <data>/appdata/agents/<id>/. Også arbejdsmappen.
NEBO_API_URLBottens lokale API, http://127.0.0.1:<port>.
NEBO_APP_TOKENEt token til at kalde bottens app-API.
PATH, HOME, TMPDIR, LANG, LC_ALL, TZVideregives.

Standardoutput og standardfejl går til sidecar.log i datamappen. Standardinput er en pipe; slut på filen betyder, at Nebo er væk, og at sidecaren skal afslutte. Sidecaren kører i sin egen procesgruppe.

Anmodninger fra siden

En anmodning til /apps/<id>/api/<path>, som siden laver med neboFetch og en relativ sti, når HandleRequest med path sat til <path>. Stier, der starter med _, afvises. Anmodningers brødtekst er begrænset til 10 MB og svar til 32 MB.

Værktøjer til medarbejderen

Erklær værktøjer i appens agent.json. Hvert bliver et værktøj med navnet app__<app>__<name>, der indlæses, når medarbejderen har brug for det. Et kald bliver til en anmodning til sidecaren på method og 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" } } }
  }
]

Kald Nebo

Sidecaren kan bruge de samme tjenester som siden ved at kalde $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... med headeren Authorization: Bearer $NEBO_APP_TOKEN.

RuteGør
GET /storage, GET|PUT|DELETE /storage/<key>Appens nøgle-værdi-lager.
POST /agents/invoke, POST /agents/streamSpørger en medarbejder: {message, agent, data}. Streamede svar er server-sent events.
POST /janus/complete, POST /janus/streamEt direkte modelkald: {messages, model, temperature, max_tokens, system}.
POST /http/proxyEn udgående anmodning, {url, method, headers, body}, tilladt af appens network:-tilladelser.
GET /identityAppens medarbejder.

Livscyklus

  • Nebo tjekker socketten hvert tredje sekund.
  • En fejlet sidecar genstarter efter et sekund, fordoblet op til højst 60 sekunder. Efter fem fejl i træk markeres den som fejlet. En sidecar, der holder sig kørende i 60 sekunder, er sund igen.
  • En anmodning til en stoppet sidecar starter den og venter op til 15 sekunder. GET- og HEAD-anmodninger prøves igen.
  • For at stoppe en sidecar sender Nebo SIGTERM til dens procesgruppe og dræber den derefter efter to sekunder.