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:
- Um arquivo chamado
binary - Um arquivo chamado
app - O primeiro arquivo em
tmp/ - O primeiro arquivo em
bin/ - 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ável | Valor |
|---|---|
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSION | A identidade do app. |
NEBO_APP_DIR | A pasta do app. |
NEBO_APP_SOCK | O socket em que escutar, <app folder>/<id>.sock. O Nebo define o modo dele como 0600. |
NEBO_DATA_DIR | A pasta de dados do app, <data>/appdata/agents/<id>/. Também é o diretório de trabalho. |
NEBO_API_URL | A API local do bot, http://127.0.0.1:<port>. |
NEBO_APP_TOKEN | Um token para chamar a API de apps do bot. |
PATH, HOME, TMPDIR, LANG, LC_ALL, TZ | Repassada. |
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.
| Rota | Faz |
|---|---|
GET /storage, GET|PUT|DELETE /storage/<key> | O armazenamento de chave-valor do app. |
POST /agents/invoke, POST /agents/stream | Pergunta a um funcionário: {message, agent, data}. As respostas em stream são server-sent events. |
POST /janus/complete, POST /janus/stream | Uma chamada direta ao modelo: {messages, model, temperature, max_tokens, system}. |
POST /http/proxy | Uma requisição externa, {url, method, headers, body}, permitida pelas permissões network: do app. |
GET /identity | O 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.