NeboAI
NeboAI
Aan de slag

App-sidecar

Een sidecar is een binary die naast een app draait. Hij levert de API van de pagina, bewaart de data van de app en geeft de medewerker van de app tools. Nebo start hem, routeert verzoeken via een lokale socket naar hem en start hem opnieuw als hij vastloopt.

Het contract

Een sidecar is een gRPC-server op een Unix-socket. Luister op het pad in NEBO_APP_SOCK en implementeer apps.v0.UIService. Nebo roept HandleRequest aan voor elk verzoek; HealthCheck en Configure horen bij de service, maar worden nu nog niet aangeroepen. De socket moet verschijnen binnen de startup_timeout van het manifest, die standaard 10 seconden is en maximaal 120 mag zijn.

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 draaien op macOS en Linux.

Waar Nebo de binary vindt

In de map van de app gebruikt Nebo de eerste die bestaat van:

  1. Een bestand met de naam binary
  2. Een bestand met de naam app
  3. Het eerste bestand in tmp/
  4. Het eerste bestand in bin/
  5. Het eerste uitvoerbare bestand in sidecar/target/release/, voor lokale ontwikkeling

De binary moet een gewoon, uitvoerbaar bestand zijn, geen symbolische link, en maximaal 500 MB groot. Gepubliceerde apps hebben hem in bin/<name>. Als het bestand op schijf verandert, start Nebo de sidecar opnieuw.

Omgeving

De sidecar start met een lege omgeving en deze variabelen:

VariabeleWaarde
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSIONDe identiteit van de app.
NEBO_APP_DIRDe map van de app.
NEBO_APP_SOCKDe socket om op te luisteren, <app folder>/<id>.sock. Nebo zet de modus op 0600.
NEBO_DATA_DIRDe datamap van de app, <data>/appdata/agents/<id>/. Ook de werkmap.
NEBO_API_URLDe lokale API van de bot, http://127.0.0.1:<port>.
NEBO_APP_TOKENEen token om de app-API van de bot aan te roepen.
PATH, HOME, TMPDIR, LANG, LC_ALL, TZDoorgegeven.

Standaarduitvoer en standaardfout gaan naar sidecar.log in de datamap. Standaardinvoer is een pipe; einde van het bestand betekent dat Nebo weg is en dat de sidecar moet afsluiten. De sidecar draait in zijn eigen procesgroep.

Verzoeken vanaf de pagina

Een verzoek naar /apps/<id>/api/<path>, dat de pagina doet met neboFetch en een relatief pad, komt bij HandleRequest aan met path ingesteld op <path>. Paden die met _ beginnen, worden geweigerd. De body van een verzoek is beperkt tot 10 MB en antwoorden tot 32 MB.

Tools voor de medewerker

Declareer tools in de agent.json van de app. Elke tool krijgt de naam app__<app>__<name> en wordt geladen wanneer de medewerker hem nodig heeft. Een aanroep wordt een verzoek aan de sidecar op method en 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 aanroepen

De sidecar kan dezelfde services gebruiken als de pagina door $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... aan te roepen met de header Authorization: Bearer $NEBO_APP_TOKEN.

RouteDoet
GET /storage, GET|PUT|DELETE /storage/<key>De key-value-opslag van de app.
POST /agents/invoke, POST /agents/streamVraagt iets aan een medewerker: {message, agent, data}. Streamantwoorden zijn server-sent events.
POST /janus/complete, POST /janus/streamEen directe modelaanroep: {messages, model, temperature, max_tokens, system}.
POST /http/proxyEen extern verzoek, {url, method, headers, body}, toegestaan door de network:-machtigingen van de app.
GET /identityDe medewerker van de app.

Levenscyclus

  • Nebo controleert de socket elke drie seconden.
  • Een mislukte sidecar start na één seconde opnieuw, en die wachttijd verdubbelt tot maximaal 60 seconden. Na vijf mislukkingen op rij wordt hij als mislukt gemarkeerd. Een sidecar die 60 seconden blijft draaien, is weer gezond.
  • Een verzoek aan een gestopte sidecar start hem en wacht maximaal 15 seconden. GET- en HEAD-verzoeken worden opnieuw geprobeerd.
  • Om een sidecar te stoppen stuurt Nebo SIGTERM naar zijn procesgroep en beëindigt hem na twee seconden geforceerd.