NeboAI
NeboAI
Ξεκινήστε

Sidecar εφαρμογών

Ένα sidecar είναι ένα εκτελέσιμο που λειτουργεί δίπλα σε μια εφαρμογή. Σερβίρει το API της σελίδας, κρατά τα δεδομένα της εφαρμογής και δίνει εργαλεία στον υπάλληλο της εφαρμογής. Το Nebo το ξεκινά, δρομολογεί αιτήματα προς αυτό μέσω ενός τοπικού socket και το επανεκκινεί όταν αποτυγχάνει.

Το συμβόλαιο

Ένα sidecar είναι ένας διακομιστής gRPC σε ένα Unix socket. Ακούστε στη διαδρομή του NEBO_APP_SOCK και υλοποιήστε το apps.v0.UIService. Το Nebo καλεί το HandleRequest για κάθε αίτημα· τα HealthCheck και Configure είναι μέρος της υπηρεσίας αλλά δεν καλούνται σήμερα. Το socket πρέπει να εμφανιστεί μέσα στο startup_timeout του manifest, που είναι από προεπιλογή 10 δευτερόλεπτα και το πολύ 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;
}

Τα sidecar λειτουργούν σε macOS και Linux.

Πού βρίσκει το Nebo το εκτελέσιμο

Στον φάκελο της εφαρμογής, το Nebo χρησιμοποιεί το πρώτο από τα παρακάτω που υπάρχει:

  1. Ένα αρχείο με όνομα binary
  2. Ένα αρχείο με όνομα app
  3. Το πρώτο αρχείο στο tmp/
  4. Το πρώτο αρχείο στο bin/
  5. Το πρώτο εκτελέσιμο στο sidecar/target/release/, για τοπική ανάπτυξη

Το εκτελέσιμο πρέπει να είναι κανονικό, εκτελέσιμο αρχείο, όχι συμβολικός σύνδεσμος, και το πολύ 500 MB. Οι δημοσιευμένες εφαρμογές το έχουν στο bin/<name>. Όταν το αρχείο αλλάζει στον δίσκο, το Nebo επανεκκινεί το sidecar.

Περιβάλλον

Το sidecar ξεκινά με κενό περιβάλλον και τις εξής μεταβλητές:

ΜεταβλητήΤιμή
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSIONΗ ταυτότητα της εφαρμογής.
NEBO_APP_DIRΟ φάκελος της εφαρμογής.
NEBO_APP_SOCKΤο socket όπου γίνεται η ακρόαση, <app folder>/<id>.sock. Το Nebo ορίζει τα δικαιώματά του σε 0600.
NEBO_DATA_DIRΟ φάκελος δεδομένων της εφαρμογής, <data>/appdata/agents/<id>/. Είναι επίσης ο κατάλογος εργασίας.
NEBO_API_URLΤο τοπικό API του bot, http://127.0.0.1:<port>.
NEBO_APP_TOKENΈνα token για κλήσεις στο API εφαρμογών του bot.
PATH, HOME, TMPDIR, LANG, LC_ALL, TZΜεταβιβάζεται.

Η τυπική έξοδος και η τυπική έξοδος σφαλμάτων πηγαίνουν στο sidecar.log στον φάκελο δεδομένων. Η τυπική είσοδος είναι ένα pipe· το τέλος αρχείου σημαίνει ότι το Nebo έφυγε και το sidecar πρέπει να τερματιστεί. Το sidecar εκτελείται στη δική του ομάδα διεργασιών.

Αιτήματα από τη σελίδα

Ένα αίτημα στο /apps/<id>/api/<path>, που κάνει η σελίδα με το neboFetch και μια σχετική διαδρομή, φτάνει στο HandleRequest με το path ορισμένο σε <path>. Οι διαδρομές που ξεκινούν με _ απορρίπτονται. Τα σώματα αιτημάτων περιορίζονται στα 10 MB και οι αποκρίσεις στα 32 MB.

Εργαλεία για τον υπάλληλο

Δηλώστε εργαλεία στο agent.json της εφαρμογής. Το καθένα γίνεται εργαλείο με όνομα app__<app>__<name>, που φορτώνεται όταν το χρειάζεται ο υπάλληλος. Μια κλήση γίνεται αίτημα προς το sidecar στα method και 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" } } }
  }
]

Κλήσεις προς το Nebo

Το sidecar μπορεί να χρησιμοποιεί τις ίδιες υπηρεσίες με τη σελίδα καλώντας το $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... με την κεφαλίδα Authorization: Bearer $NEBO_APP_TOKEN.

ΔιαδρομήΤι κάνει
GET /storage, GET|PUT|DELETE /storage/<key>Ο χώρος αποθήκευσης κλειδιού-τιμής της εφαρμογής.
POST /agents/invoke, POST /agents/streamΡωτά έναν υπάλληλο: {message, agent, data}. Οι αποκρίσεις ροής είναι server-sent events.
POST /janus/complete, POST /janus/streamΜια απευθείας κλήση μοντέλου: {messages, model, temperature, max_tokens, system}.
POST /http/proxyΈνα εξωτερικό αίτημα, {url, method, headers, body}, που επιτρέπεται από τα δικαιώματα network: της εφαρμογής.
GET /identityΟ υπάλληλος της εφαρμογής.

Κύκλος ζωής

  • Το Nebo ελέγχει το socket κάθε τρία δευτερόλεπτα.
  • Ένα sidecar που απέτυχε επανεκκινείται μετά από ένα δευτερόλεπτο, με διπλασιασμό έως το πολύ 60 δευτερόλεπτα. Μετά από πέντε συνεχόμενες αποτυχίες επισημαίνεται ως αποτυχημένο. Ένα sidecar που μένει σε λειτουργία για 60 δευτερόλεπτα θεωρείται ξανά υγιές.
  • Ένα αίτημα προς ένα σταματημένο sidecar το ξεκινά και περιμένει έως 15 δευτερόλεπτα. Τα αιτήματα GET και HEAD επαναλαμβάνονται.
  • Για να σταματήσει ένα sidecar, το Nebo στέλνει SIGTERM στην ομάδα διεργασιών του και το τερματίζει βίαια μετά από δύο δευτερόλεπτα.