NeboAI
NeboAI
Começar

Sidecar de apps

Um sidecar é um binário que corre ao lado de uma app. Serve a API da página, guarda os dados da app e dá ferramentas ao funcionário da app. O Nebo inicia-o, encaminha-lhe os pedidos através de um socket local e reinicia-o quando falha.

O contrato

Um sidecar é um servidor gRPC num socket Unix. Escute no caminho indicado em NEBO_APP_SOCK e implemente apps.v0.UIService. O Nebo chama HandleRequest para cada pedido; HealthCheck e Configure fazem parte do serviço, mas hoje não são chamados. O socket tem de aparecer dentro do startup_timeout do manifesto, que por predefinição é de 10 segundos e pode ir até 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 correm em macOS e Linux.

Onde o Nebo encontra o binário

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

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

O binário tem de ser um ficheiro normal e executável, não uma ligação simbólica, e ter no máximo 500 MB. As apps publicadas incluem-no em bin/<name>. Quando o ficheiro muda no disco, o Nebo reinicia o sidecar.

Ambiente

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

VariávelValor
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSIONA identidade da app.
NEBO_APP_DIRA pasta da app.
NEBO_APP_SOCKO socket onde escutar, <app folder>/<id>.sock. O Nebo define o seu modo como 0600.
NEBO_DATA_DIRA pasta de dados da 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, TZTransmitida tal como está.

A saída padrão e o erro padrão vão para sidecar.log na pasta de dados. A entrada padrão é um pipe; o fim do ficheiro significa que o Nebo terminou e o sidecar deve sair. O sidecar corre no seu próprio grupo de processos.

Pedidos da página

Um pedido para /apps/<id>/api/<path>, que a página faz com neboFetch e um caminho relativo, chega a HandleRequest com path definido como <path>. Os caminhos que começam por _ são recusados. O corpo dos pedidos está limitado a 10 MB e o das respostas a 32 MB.

Ferramentas para o funcionário

Declare as ferramentas no agent.json da app. Cada uma torna-se uma ferramenta chamada app__<app>__<name>, carregada quando o funcionário precisa dela. Uma chamada torna-se um pedido 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 chave-valor da 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 a um modelo: {messages, model, temperature, max_tokens, system}.
POST /http/proxyUm pedido externo, {url, method, headers, body}, permitido pelas permissões network: da app.
GET /identityO funcionário da app.

Ciclo de vida

  • O Nebo sonda o socket a cada três segundos.
  • Um sidecar que falhou reinicia ao fim de um segundo, tempo que vai duplicando até um máximo de 60 segundos. Após cinco falhas seguidas, é marcado como falhado. Um sidecar que se mantenha ativo durante 60 segundos volta a estar saudável.
  • Um pedido a um sidecar parado inicia-o e espera até 15 segundos. Os pedidos GET e HEAD são repetidos.
  • Para parar um sidecar, o Nebo envia SIGTERM ao seu grupo de processos e termina-o à força ao fim de dois segundos.