NeboAI
NeboAI
Empezar

Sidecar de apps

Un sidecar es un binario que se ejecuta junto a una app. Sirve la API de la página, guarda los datos de la app y da herramientas al empleado de la app. Nebo lo inicia, le enruta las solicitudes a través de un socket local y lo reinicia cuando falla.

El contrato

Un sidecar es un servidor gRPC sobre un socket Unix. Escucha en la ruta de NEBO_APP_SOCK e implementa apps.v0.UIService. Nebo llama a HandleRequest en cada solicitud; HealthCheck y Configure forman parte del servicio, pero hoy no se llaman. El socket debe aparecer dentro del startup_timeout del manifiesto, que por defecto es de 10 segundos y como máximo puede ser de 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;
}

Los sidecars funcionan en macOS y Linux.

Dónde busca Nebo el binario

En la carpeta de la app, Nebo usa el primero de estos que exista:

  1. Un archivo llamado binary
  2. Un archivo llamado app
  3. El primer archivo de tmp/
  4. El primer archivo de bin/
  5. El primer ejecutable de sidecar/target/release/, para el desarrollo local

El binario debe ser un archivo normal y ejecutable, no un enlace simbólico, y ocupar como máximo 500 MB. Las apps publicadas lo llevan en bin/<name>. Cuando el archivo cambia en el disco, Nebo reinicia el sidecar.

Entorno

El sidecar se inicia con un entorno vacío y estas variables:

VariableValor
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSIONLa identidad de la app.
NEBO_APP_DIRLa carpeta de la app.
NEBO_APP_SOCKEl socket en el que escuchar, <app folder>/<id>.sock. Nebo establece su modo en 0600.
NEBO_DATA_DIRLa carpeta de datos de la app, <data>/appdata/agents/<id>/. También es el directorio de trabajo.
NEBO_API_URLLa API local del bot, http://127.0.0.1:<port>.
NEBO_APP_TOKENUn token para llamar a la API de apps del bot.
PATH, HOME, TMPDIR, LANG, LC_ALL, TZSe transmite tal cual.

La salida estándar y la salida de error van a sidecar.log, en la carpeta de datos. La entrada estándar es una tubería; el fin de archivo significa que Nebo se ha ido y que el sidecar debe salir. El sidecar se ejecuta en su propio grupo de procesos.

Solicitudes de la página

Una solicitud a /apps/<id>/api/<path>, que la página hace con neboFetch y una ruta relativa, llega a HandleRequest con path establecido en <path>. Las rutas que empiezan por _ se rechazan. El cuerpo de las solicitudes tiene un límite de 10 MB y el de las respuestas, de 32 MB.

Herramientas para el empleado

Declara las herramientas en el agent.json de la app. Cada una se convierte en una herramienta llamada app__<app>__<name>, que se carga cuando el empleado la necesita. Cada llamada se convierte en una solicitud al sidecar en method y 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" } } }
  }
]

Llamar a Nebo

El sidecar puede usar los mismos servicios que la página llamando a $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... con la cabecera Authorization: Bearer $NEBO_APP_TOKEN.

RutaQué hace
GET /storage, GET|PUT|DELETE /storage/<key>El almacén de clave-valor de la app.
POST /agents/invoke, POST /agents/streamPregunta a un empleado: {message, agent, data}. Las respuestas en streaming son eventos enviados por el servidor.
POST /janus/complete, POST /janus/streamUna llamada directa al modelo: {messages, model, temperature, max_tokens, system}.
POST /http/proxyUna solicitud externa, {url, method, headers, body}, permitida por los permisos network: de la app.
GET /identityEl empleado de la app.

Ciclo de vida

  • Nebo sondea el socket cada tres segundos.
  • Un sidecar que falla se reinicia al cabo de un segundo, y el tiempo se duplica hasta un máximo de 60 segundos. Tras cinco fallos seguidos, se marca como fallido. Un sidecar que se mantiene en marcha durante 60 segundos vuelve a considerarse sano.
  • Una solicitud a un sidecar detenido lo inicia y espera hasta 15 segundos. Las solicitudes GET y HEAD se reintentan.
  • Para detener un sidecar, Nebo envía SIGTERM a su grupo de procesos y lo mata al cabo de dos segundos.