Kontrakt
Sidecar je server gRPC na sokete Unix. Počúvajte na ceste v NEBO_APP_SOCK a implementujte apps.v0.UIService. Nebo volá HandleRequest pre každú požiadavku; HealthCheck a Configure sú súčasťou služby, ale dnes sa nevolajú. Soket sa musí objaviť v rámci startup_timeout z manifestu, ktorý je predvolene 10 sekúnd a môže byť najviac 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 bežia na macOS a Linuxe.
Kde Nebo nájde binárny súbor
V priečinku aplikácie Nebo použije prvý existujúci z týchto:
- Súbor s názvom
binary - Súbor s názvom
app - Prvý súbor v
tmp/ - Prvý súbor v
bin/ - Prvý spustiteľný súbor v
sidecar/target/release/, na lokálny vývoj
Binárny súbor musí byť bežný spustiteľný súbor, nie symbolický odkaz, a najviac 500 MB. Publikované aplikácie ho majú v bin/<name>. Keď sa súbor na disku zmení, Nebo sidecar reštartuje.
Prostredie
Sidecar sa spúšťa s prázdnym prostredím a týmito premennými:
| Premenná | Hodnota |
|---|---|
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSION | Identita aplikácie. |
NEBO_APP_DIR | Priečinok aplikácie. |
NEBO_APP_SOCK | Soket, na ktorom treba počúvať, <app folder>/<id>.sock. Nebo mu nastaví režim 0600. |
NEBO_DATA_DIR | Dátový priečinok aplikácie, <data>/appdata/agents/<id>/. Zároveň pracovný adresár. |
NEBO_API_URL | Lokálne API bota, http://127.0.0.1:<port>. |
NEBO_APP_TOKEN | Token na volanie API aplikácií bota. |
PATH, HOME, TMPDIR, LANG, LC_ALL, TZ | Prenesené. |
Štandardný výstup a štandardný chybový výstup idú do sidecar.log v dátovom priečinku. Štandardný vstup je rúra; koniec súboru znamená, že Nebo skončilo a sidecar by sa mal ukončiť. Sidecar beží vo vlastnej skupine procesov.
Požiadavky zo stránky
Požiadavka na /apps/<id>/api/<path>, ktorú stránka urobí pomocou neboFetch a relatívnej cesty, dorazí do HandleRequest s path nastaveným na <path>. Cesty, ktoré začínajú na _, sa odmietnu. Telá požiadaviek sú obmedzené na 10 MB a odpovede na 32 MB.
Nástroje pre zamestnanca
Nástroje deklarujte v agent.json aplikácie. Z každého sa stane nástroj s názvom app__<app>__<name>, ktorý sa načíta, keď ho zamestnanec potrebuje. Volanie sa zmení na požiadavku do sidecaru 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" } } }
}
] Volanie Nebo
Sidecar môže používať tie isté služby ako stránka volaním $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... s hlavičkou Authorization: Bearer $NEBO_APP_TOKEN.
| Cesta | Robí |
|---|---|
GET /storage, GET|PUT|DELETE /storage/<key> | Úložisko kľúč-hodnota aplikácie. |
POST /agents/invoke, POST /agents/stream | Opýta sa zamestnanca: {message, agent, data}. Streamované odpovede sú udalosti odosielané serverom. |
POST /janus/complete, POST /janus/stream | Priame volanie modelu: {messages, model, temperature, max_tokens, system}. |
POST /http/proxy | Vonkajšia požiadavka, {url, method, headers, body}, povolená oprávneniami network: aplikácie. |
GET /identity | Zamestnanec aplikácie. |
Životný cyklus
- Nebo kontroluje soket každé tri sekundy.
- Zlyhaný sidecar sa reštartuje po jednej sekunde, s každým ďalším pokusom sa čas zdvojnásobí až na najviac 60 sekúnd. Po piatich zlyhaniach za sebou sa označí ako zlyhaný. Sidecar, ktorý vydrží bežať 60 sekúnd, je znova v poriadku.
- Požiadavka na zastavený sidecar ho spustí a čaká až 15 sekúnd. Požiadavky GET a HEAD sa opakujú.
- Na zastavenie sidecaru pošle Nebo jeho skupine procesov SIGTERM a po dvoch sekundách ho násilne ukončí.