Το συμβόλαιο
Ένα 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 χρησιμοποιεί το πρώτο από τα παρακάτω που υπάρχει:
- Ένα αρχείο με όνομα
binary - Ένα αρχείο με όνομα
app - Το πρώτο αρχείο στο
tmp/ - Το πρώτο αρχείο στο
bin/ - Το πρώτο εκτελέσιμο στο
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 στην ομάδα διεργασιών του και το τερματίζει βίαια μετά από δύο δευτερόλεπτα.