สัญญา
sidecar คือเซิร์ฟเวอร์ gRPC บน Unix socket รอรับการเชื่อมต่อบนพาธใน NEBO_APP_SOCK และ implement 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/สำหรับการพัฒนาในเครื่อง
ไบนารีต้องเป็นไฟล์ปฏิบัติการปกติ ไม่ใช่ symbolic link และมีขนาดไม่เกิน 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 ในเครื่องของบอท http://127.0.0.1:<port> |
NEBO_APP_TOKEN | โทเค็นสำหรับเรียก API ของแอปบนบอท |
PATH, HOME, TMPDIR, LANG, LC_ALL, TZ | ส่งผ่าน |
เอาต์พุตมาตรฐานและข้อผิดพลาดมาตรฐานจะไปที่ sidecar.log ในโฟลเดอร์ข้อมูล อินพุตมาตรฐานเป็นไปป์ เมื่อถึงจุดสิ้นสุดไฟล์หมายความว่า 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 ที่หยุดอยู่จะเริ่ม sidecar และรอสูงสุด 15 วินาที คำขอ GET และ HEAD จะถูกลองใหม่
- เมื่อต้องการหยุด sidecar Nebo จะส่ง SIGTERM ไปยังกลุ่มโปรเซส แล้วบังคับปิดหลังสองวินาที