NeboAI
NeboAI
Commencer

Sidecar des apps

Un sidecar est un binaire qui s'exécute à côté d'une application. Il sert l'API de la page, conserve les données de l'application et fournit des outils à l'employé de l'application. Nebo le démarre, lui achemine les requêtes via un socket local et le redémarre en cas d'échec.

Le contrat

Un sidecar est un serveur gRPC sur un socket Unix. Écoutez sur le chemin indiqué par NEBO_APP_SOCK et implémentez apps.v0.UIService. Nebo appelle HandleRequest pour chaque requête ; HealthCheck et Configure font partie du service mais ne sont pas appelés aujourd'hui. Le socket doit apparaître dans le délai startup_timeout du manifeste, qui est de 10 secondes par défaut et peut aller jusqu'à 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;
}

Les sidecars fonctionnent sur macOS et Linux.

Où Nebo trouve le binaire

Dans le dossier de l'application, Nebo utilise le premier de ces éléments qui existe :

  1. Un fichier nommé binary
  2. Un fichier nommé app
  3. Le premier fichier de tmp/
  4. Le premier fichier de bin/
  5. Le premier exécutable de sidecar/target/release/, pour le développement local

Le binaire doit être un fichier ordinaire et exécutable, pas un lien symbolique, et peser au maximum 500 MB. Les applications publiées le placent dans bin/<name>. Quand le fichier change sur le disque, Nebo redémarre le sidecar.

Environnement

Le sidecar démarre avec un environnement vide et les variables suivantes :

VariableValeur
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSIONL'identité de l'application.
NEBO_APP_DIRLe dossier de l'application.
NEBO_APP_SOCKLe socket sur lequel écouter, <app folder>/<id>.sock. Nebo règle ses droits sur 0600.
NEBO_DATA_DIRLe dossier de données de l'application, <data>/appdata/agents/<id>/. C'est aussi le répertoire de travail.
NEBO_API_URLL'API locale du bot, http://127.0.0.1:<port>.
NEBO_APP_TOKENUn jeton pour appeler l'API d'application du bot.
PATH, HOME, TMPDIR, LANG, LC_ALL, TZTransmise telle quelle.

La sortie standard et la sortie d'erreur vont dans sidecar.log, dans le dossier de données. L'entrée standard est un pipe ; une fin de fichier signifie que Nebo est parti et que le sidecar doit s'arrêter. Le sidecar s'exécute dans son propre groupe de processus.

Requêtes de la page

Une requête vers /apps/<id>/api/<path>, que la page effectue avec neboFetch et un chemin relatif, arrive à HandleRequest avec path défini sur <path>. Les chemins qui commencent par _ sont refusés. Le corps des requêtes est limité à 10 MB et celui des réponses à 32 MB.

Outils pour l'employé

Déclarez les outils dans l’agent.json de l'application. Chacun devient un outil nommé app__<app>__<name>, chargé lorsque l'employé en a besoin. Un appel devient une requête vers le sidecar selon method et 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" } } }
  }
]

Appeler Nebo

Le sidecar peut utiliser les mêmes services que la page en appelant $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... avec l'en-tête Authorization: Bearer $NEBO_APP_TOKEN.

RouteRôle
GET /storage, GET|PUT|DELETE /storage/<key>Le magasin clé-valeur de l'application.
POST /agents/invoke, POST /agents/streamInterroge un employé : {message, agent, data}. Les réponses en streaming sont des server-sent events.
POST /janus/complete, POST /janus/streamUn appel direct au modèle : {messages, model, temperature, max_tokens, system}.
POST /http/proxyUne requête externe, {url, method, headers, body}, autorisée par les permissions network: de l'application.
GET /identityL'employé de l'application.

Cycle de vie

  • Nebo sonde le socket toutes les trois secondes.
  • Un sidecar en échec redémarre au bout d'une seconde, puis le délai double jusqu'à 60 secondes au maximum. Après cinq échecs consécutifs, il est marqué en échec. Un sidecar qui reste actif pendant 60 secondes est de nouveau considéré comme sain.
  • Une requête vers un sidecar arrêté le démarre et attend jusqu'à 15 secondes. Les requêtes GET et HEAD sont relancées.
  • Pour arrêter un sidecar, Nebo envoie SIGTERM à son groupe de processus, puis le tue au bout de deux secondes.