NeboAI
NeboAI
Começar

Sidecar de apps

Um sidecar é um binário que roda ao lado de um app. Ele serve a API da página, guarda os dados do app e dá ferramentas ao funcionário do app. O Nebo o inicia, encaminha as requisições para ele por um socket local e o reinicia quando ele falha.

O contrato

Um sidecar é um servidor gRPC em um socket Unix. Escute no caminho indicado em NEBO_APP_SOCK e implemente apps.v0.UIService. O Nebo chama HandleRequest para cada requisição; HealthCheck e Configure fazem parte do serviço, mas hoje não são chamados. O socket precisa aparecer dentro do startup_timeout do manifesto, que por padrão é de 10 segundos e pode ser no máximo 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;
}

Os sidecars rodam no macOS e no Linux.

Onde o Nebo encontra o binário

Na pasta do app, o Nebo usa o primeiro destes que existir:

  1. Um arquivo chamado binary
  2. Um arquivo chamado app
  3. O primeiro arquivo em tmp/
  4. O primeiro arquivo em bin/
  5. O primeiro executável em sidecar/target/release/, para desenvolvimento local

O binário precisa ser um arquivo comum e executável, não um link simbólico, com no máximo 500 MB. Os apps publicados o levam em bin/<name>. Quando o arquivo muda no disco, o Nebo reinicia o sidecar.

Ambiente

O sidecar inicia com um ambiente vazio e estas variáveis:

VariávelValor
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSIONA identidade do app.
NEBO_APP_DIRA pasta do app.
NEBO_APP_SOCKO socket em que escutar, <app folder>/<id>.sock. O Nebo define o modo dele como 0600.
NEBO_DATA_DIRA pasta de dados do app, <data>/appdata/agents/<id>/. Também é o diretório de trabalho.
NEBO_API_URLA API local do bot, http://127.0.0.1:<port>.
NEBO_APP_TOKENUm token para chamar a API de apps do bot.
PATH, HOME, TMPDIR, LANG, LC_ALL, TZRepassada.

A saída padrão e a saída de erro vão para sidecar.log na pasta de dados. A entrada padrão é um pipe; fim de arquivo significa que o Nebo foi encerrado e o sidecar deve sair. O sidecar roda no próprio grupo de processos.

Requisições da página

Uma requisição para /apps/<id>/api/<path>, que a página faz com neboFetch e um caminho relativo, chega ao HandleRequest com path definido como <path>. Caminhos que começam com _ são recusados. O corpo das requisições é limitado a 10 MB e o das respostas a 32 MB.

Ferramentas para o funcionário

Declare as ferramentas no agent.json do app. Cada uma vira uma ferramenta chamada app__<app>__<name>, carregada quando o funcionário precisa dela. Uma chamada vira uma requisição ao sidecar em method e 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" } } }
  }
]

Chamar o Nebo

O sidecar pode usar os mesmos serviços que a página chamando $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... com o cabeçalho Authorization: Bearer $NEBO_APP_TOKEN.

RotaFaz
GET /storage, GET|PUT|DELETE /storage/<key>O armazenamento de chave-valor do app.
POST /agents/invoke, POST /agents/streamPergunta a um funcionário: {message, agent, data}. As respostas em stream são server-sent events.
POST /janus/complete, POST /janus/streamUma chamada direta ao modelo: {messages, model, temperature, max_tokens, system}.
POST /http/proxyUma requisição externa, {url, method, headers, body}, permitida pelas permissões network: do app.
GET /identityO funcionário do app.

Ciclo de vida

  • O Nebo verifica o socket a cada três segundos.
  • Um sidecar que falhou reinicia depois de um segundo, com o intervalo dobrando até no máximo 60 segundos. Depois de cinco falhas seguidas, ele é marcado como falho. Um sidecar que se mantém ativo por 60 segundos volta a ser considerado saudável.
  • Uma requisição a um sidecar parado o inicia e espera até 15 segundos. Requisições GET e HEAD são repetidas.
  • Para parar um sidecar, o Nebo envia SIGTERM ao grupo de processos dele e o encerra à força depois de dois segundos.