Kontrakt
Sidecar je server gRPC na Unixovém socketu. Naslouchejte na cestě v NEBO_APP_SOCK a implementujte apps.v0.UIService. Nebo volá HandleRequest pro každý požadavek; HealthCheck a Configure jsou součástí služby, ale dnes se nevolají. Socket se musí objevit do startup_timeout z manifestu, který je ve výchozím stavu 10 sekund a může být nejvýše 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;
} Sidecary běží na macOS a Linuxu.
Kde Nebo najde binární soubor
Ve složce aplikace Nebo použije první z těchto souborů, který existuje:
- Soubor s názvem
binary - Soubor s názvem
app - První soubor v
tmp/ - První soubor v
bin/ - První spustitelný soubor v
sidecar/target/release/, pro místní vývoj
Binární soubor musí být běžný spustitelný soubor, ne symbolický odkaz, a mít nejvýše 500 MB. Publikované aplikace ho mají v bin/<name>. Když se soubor na disku změní, Nebo sidecar restartuje.
Prostředí
Sidecar se spouští s prázdným prostředím a s těmito proměnnými:
| Proměnná | Hodnota |
|---|---|
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSION | Identita aplikace. |
NEBO_APP_DIR | Složka aplikace. |
NEBO_APP_SOCK | Socket, na kterém se má naslouchat, <app folder>/<id>.sock. Nebo nastaví jeho režim na 0600. |
NEBO_DATA_DIR | Datová složka aplikace, <data>/appdata/agents/<id>/. Zároveň pracovní adresář. |
NEBO_API_URL | Místní API bota, http://127.0.0.1:<port>. |
NEBO_APP_TOKEN | Token pro volání API aplikací bota. |
PATH, HOME, TMPDIR, LANG, LC_ALL, TZ | Předává se. |
Standardní výstup a standardní chybový výstup jdou do sidecar.log v datové složce. Standardní vstup je roura; konec souboru znamená, že Nebo skončil a sidecar by se měl ukončit. Sidecar běží ve vlastní skupině procesů.
Požadavky ze stránky
Požadavek na /apps/<id>/api/<path>, který stránka provede pomocí neboFetch a relativní cesty, dorazí do HandleRequest s path nastaveným na <path>. Cesty začínající _ se odmítají. Těla požadavků jsou omezena na 10 MB a odpovědi na 32 MB.
Nástroje pro zaměstnance
Nástroje deklarujte v agent.json aplikace. Z každého se stane nástroj s názvem app__<app>__<name>, který se načte, když ho zaměstnanec potřebuje. Volání se změní na požadavek na sidecar na method a 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" } } }
}
] Volání Nebo
Sidecar může používat stejné služby jako stránka voláním $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... s hlavičkou Authorization: Bearer $NEBO_APP_TOKEN.
| Cesta | Co dělá |
|---|---|
GET /storage, GET|PUT|DELETE /storage/<key> | Úložiště klíč-hodnota aplikace. |
POST /agents/invoke, POST /agents/stream | Dotaz na zaměstnance: {message, agent, data}. Streamované odpovědi jsou server-sent events. |
POST /janus/complete, POST /janus/stream | Přímé volání modelu: {messages, model, temperature, max_tokens, system}. |
POST /http/proxy | Externí požadavek, {url, method, headers, body}, povolený oprávněními network: aplikace. |
GET /identity | Zaměstnanec aplikace. |
Životní cyklus
- Nebo socket kontroluje každé tři sekundy.
- Selhaný sidecar se restartuje po jedné sekundě, s prodlevou zdvojnásobovanou až na nejvýše 60 sekund. Po pěti selháních za sebou se označí jako selhaný. Sidecar, který vydrží běžet 60 sekund, je opět v pořádku.
- Požadavek na zastavený sidecar ho spustí a čeká až 15 sekund. Požadavky GET a HEAD se opakují.
- Při zastavování sidecaru pošle Nebo jeho skupině procesů SIGTERM a po dvou sekundách ho násilně ukončí.