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:
- Um ficheiro chamado
binary - Um ficheiro chamado
app - O primeiro ficheiro em
tmp/ - O primeiro ficheiro em
bin/ - 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ável | Valor |
|---|---|
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSION | A identidade da app. |
NEBO_APP_DIR | A pasta da app. |
NEBO_APP_SOCK | O socket onde escutar, <app folder>/<id>.sock. O Nebo define o seu modo como 0600. |
NEBO_DATA_DIR | A pasta de dados da 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 | Transmitida 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.
| Rota | Faz |
|---|---|
GET /storage, GET|PUT|DELETE /storage/<key> | O armazenamento chave-valor da 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 a um modelo: {messages, model, temperature, max_tokens, system}. |
POST /http/proxy | Um pedido externo, {url, method, headers, body}, permitido pelas permissões network: da app. |
GET /identity | O 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.