NeboAI
NeboAI
Magsimula

App Sidecar

Ang sidecar ay isang binary na tumatakbo sa tabi ng isang app. Inihahain nito ang API ng pahina, iniingatan ang data ng app, at binibigyan ng mga tool ang empleyado ng app. Sinisimulan ito ng Nebo, niruruta ang mga request dito sa isang lokal na socket, at nire-restart ito kapag pumalya.

Ang contract

Ang sidecar ay isang gRPC server sa isang Unix socket. Makinig sa path sa NEBO_APP_SOCK at ipatupad ang apps.v0.UIService. Tinatawag ng Nebo ang HandleRequest para sa bawat request; bahagi ng service ang HealthCheck at Configure pero hindi pa tinatawag sa ngayon. Dapat lumabas ang socket sa loob ng startup_timeout ng manifest, na 10 segundo bilang default at hanggang 120 lang.

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;
}

Tumatakbo ang mga sidecar sa macOS at Linux.

Kung saan hinahanap ng Nebo ang binary

Sa folder ng app, ginagamit ng Nebo ang unang umiiral sa mga ito:

  1. Isang file na may pangalang binary
  2. Isang file na may pangalang app
  3. Ang unang file sa tmp/
  4. Ang unang file sa bin/
  5. Ang unang executable sa sidecar/target/release/, para sa lokal na development

Dapat regular at executable na file ang binary, hindi symbolic link, at hanggang 500 MB lang. Dala ito ng mga na-publish na app sa bin/<name>. Kapag nagbago ang file sa disk, nire-restart ng Nebo ang sidecar.

Environment

Nagsisimula ang sidecar na may walang lamang environment at ang mga variable na ito:

VariableHalaga
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSIONAng pagkakakilanlan ng app.
NEBO_APP_DIRAng folder ng app.
NEBO_APP_SOCKAng socket na pakikinggan, <app folder>/<id>.sock. Itinatakda ng Nebo ang mode nito sa 0600.
NEBO_DATA_DIRAng data folder ng app, <data>/appdata/agents/<id>/. Ito rin ang working directory.
NEBO_API_URLAng lokal na API ng bot, http://127.0.0.1:<port>.
NEBO_APP_TOKENToken para sa pagtawag sa app API ng bot.
PATH, HOME, TMPDIR, LANG, LC_ALL, TZIpinapasa.

Napupunta sa sidecar.log sa data folder ang standard output at standard error. Pipe ang standard input; ang end of file ay nangangahulugang umalis na ang Nebo at dapat nang lumabas ang sidecar. Tumatakbo ang sidecar sa sarili nitong process group.

Mga request mula sa pahina

Ang request sa /apps/<id>/api/<path>, na ginagawa ng pahina gamit ang neboFetch at isang relative path, ay nakakarating sa HandleRequest na naka-set ang path sa <path>. Tinatanggihan ang mga path na nagsisimula sa _. Limitado sa 10 MB ang mga request body at sa 32 MB ang mga response.

Mga tool para sa empleyado

Ideklara ang mga tool sa agent.json ng app. Nagiging tool na may pangalang app__<app>__<name> ang bawat isa, na nilo-load kapag kailangan ng empleyado. Nagiging request sa sidecar sa method at path ang isang tawag.

"tools": [
  {
    "name": "list_deals",
    "description": "List open deals, optionally filtered by stage.",
    "method": "GET",
    "path": "/deals",
    "input_schema": { "type": "object", "properties": { "stage": { "type": "string" } } }
  }
]

Pagtawag sa Nebo

Magagamit ng sidecar ang parehong mga serbisyo gaya ng pahina sa pamamagitan ng pagtawag sa $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... gamit ang header na Authorization: Bearer $NEBO_APP_TOKEN.

RutaGinagawa
GET /storage, GET|PUT|DELETE /storage/<key>Ang key-value store ng app.
POST /agents/invoke, POST /agents/streamNagtatanong sa isang empleyado: {message, agent, data}. Server-sent events ang mga stream response.
POST /janus/complete, POST /janus/streamIsang direktang model call: {messages, model, temperature, max_tokens, system}.
POST /http/proxyIsang panlabas na request, {url, method, headers, body}, na pinapayagan ng mga network: na pahintulot ng app.
GET /identityAng empleyado ng app.

Lifecycle

  • Sinusuri ng Nebo ang socket tuwing tatlong segundo.
  • Nire-restart ang pumalyang sidecar pagkalipas ng isang segundo, dumodoble hanggang 60 segundo. Pagkatapos ng limang magkakasunod na pagpalya, minamarkahan itong failed. Muling itinuturing na healthy ang sidecar na nananatiling tumatakbo nang 60 segundo.
  • Sinisimulan ng request sa nakahintong sidecar ang sidecar at naghihintay nang hanggang 15 segundo. Inuulit ang mga GET at HEAD request.
  • Para ihinto ang sidecar, nagpapadala ang Nebo ng SIGTERM sa process group nito, pagkatapos ay pinapatay ito pagkalipas ng dalawang segundo.