Runtime Reference
Runtime quản lý toàn bộ vòng đời của môi trường tính toán cho agent của bạn — triển khai container, autoscaling, quản lý phiên bản, và endpoint.
Khái niệm cơ bản (Core Concepts)
Runtime
Một Runtime là môi trường tính toán được quản lý, chạy agent đã được đóng gói trong container của bạn. Nó trừu tượng hóa việc lập lịch container, kiểm tra sức khỏe, autoscaling, và định tuyến HTTP.
Các trạng thái Runtime:
CREATING
Runtime đang được tạo; các container đang khởi động
ACTIVE
Tất cả các bản sao tối thiểu đều hoạt động tốt; endpoint đang phục vụ lưu lượng
UPDATING
Đang triển khai phiên bản mới
ERROR
Một hoặc nhiều bản sao bắt buộc không thể khởi động (kiểm tra log)
DELETING
Runtime đang được xóa
Phiên bản (Versions)
Mỗi khi bạn triển khai một container image mới cho runtime, AgentBase tạo một Version mới. Các phiên bản là bất biến — image và cấu hình của phiên bản không bao giờ thay đổi sau khi tạo.
Endpoint
Một Endpoint là URL mà client gọi để tương tác với agent của bạn. Một runtime có thể có nhiều endpoint và nhiều phiên bản — đây là các khái niệm độc lập. Endpoint default tự động theo dõi phiên bản mới nhất mỗi khi một phiên bản mới được deploy. Bạn có thể chỉ định bất kỳ endpoint nào là default, và tạo các endpoint bổ sung được ghim vào các phiên bản cụ thể (ví dụ, cho lưu lượng canary hoặc staging).
Compute Flavor
Một Compute Flavor xác định CPU và RAM được cấp phát cho mỗi bản sao của agent.
Autoscaling
Runtime Service hỗ trợ autoscaling dựa trên mức sử dụng CPU hoặc RAM. Bạn xác định:
minReplicas: Mức sàn — luôn chạy (phạm vi: 1–10)maxReplicas: Mức trần — giới hạn sử dụng tài nguyên (phạm vi: 1–10)cpuUtilizationvàmemoryUtilization: Ngưỡng (25–75%) kích hoạt việc scale-out
Khi tải giảm, AgentBase thu hẹp số bản sao về minReplicas.
Security Settings
IP Access Control — giới hạn dải IP CIDR nguồn được phép truy cập endpoint của Runtime; để trống nếu muốn cho phép mọi nguồn.
Inbound Identity — cấu hình cách xác thực request đến, thông qua Inbound Auth type: IAM Permissions (IAM token của GreenNode AI Platform — mặc định cho Runtime mới, secure by default), JSON Web Tokens (JWT) (validate qua Discovery URL hoặc JWKS inline), hoặc No authorization (accessible công khai, không có access control).
Hợp đồng dịch vụ (Service Contract)
Container agent của bạn phải đáp ứng các yêu cầu sau để hoạt động đúng với Runtime Service:
Lắng nghe trên cổng 8080 — cổng bắt buộc;
app.run(host="0.0.0.0", port=8080)Endpoint kiểm tra sức khỏe:
GET /healthphải trả về HTTP 200 để vượt qua kiểm tra sẵn sàngKhông trạng thái (Stateless): Không lưu trữ trạng thái phiên trong bộ nhớ tiến trình — sử dụng Memory Service thay thế
Biến môi trường được tự động tiêm (có sẵn trong tất cả các container agent đã triển khai):
GREENNODE_CLIENT_ID
IAM service account client ID
GREENNODE_CLIENT_SECRET
IAM service account client secret
GREENNODE_AGENT_IDENTITY
Tên agent identity
Tổng quan (Overview)
Cấu trúc Runtime:
Những điều quan trọng:
Mỗi
PATCH /agent-runtimes/{id}tạo một version mới — phiên bản và endpoint là các khái niệm độc lập trong một runtimeEndpoint default tự động theo dõi phiên bản mới nhất mỗi khi một phiên bản mới được deploy
Một runtime có thể có nhiều endpoint — bạn chọn endpoint nào là default
Bạn có toàn quyền kiểm soát tất cả các endpoint — tạo, cập nhật, hoặc xóa
Quản lý Runtime (Manage Runtimes)
Portal
Tạo một Runtime
Mở https://aiplatform.console.greennode.ai/my-agents?tab=runtime
Nhấn "Create Runtime"
Điền thông tin
Name
my-order-agent
Duy nhất, chữ thường, cho phép dấu gạch ngang
Description
Production order agent
Tùy chọn
Image URL
vcr.vngcloud.vn/<repo>/my-agent:v1
Đường dẫn image đầy đủ bao gồm tag
Flavor
1x1-general
1 CPU, 1 GB RAM
Min Replicas
1
Phạm vi: 1–10
Max Replicas
1
Đặt >1 để bật autoscaling
CPU Threshold
50
Scale out khi CPU vượt quá % này (25–75)
Memory Threshold
50
Scale out khi RAM vượt quá % này (25–75)
Registry Auth
Bật nếu là private
Username = robot account backendName (xem Supporting Services — Robot Accounts)
Environment Variables
KEY=value
Chỉ cấu hình không nhạy cảm
IP Access Control
10.0.0.0/16
Tùy chọn — dải IP CIDR nguồn được phép truy cập; để trống nếu muốn cho phép mọi nguồn
Inbound Auth type
IAM Permissions
Mặc định (secure by default) — IAM Permissions; các lựa chọn khác: JWT (Discovery URL hoặc JWKS inline) hoặc No authorization

Nhấn Create
Runtime xuất hiện với trạng thái
CREATING, sau đó chuyển sangACTIVE
Xem danh sách Runtime
Tất cả các runtime được hiển thị trong bảng phân trang với: Tên, Trạng thái, Mô tả, Phiên bản cuối, Cập nhật cuối
Xem chi tiết Runtime
Nhấn vào tên runtime để xem: trạng thái, image, flavor, autoscaling, biến môi trường, endpoint

Cập nhật một Runtime
Mở trang chi tiết runtime → "Edit"
Thay đổi image URL, flavor, autoscaling, hoặc biến môi trường → Save
Xóa một Runtime
Lưu ý: Xóa là không thể khôi phục. Thao tác này xóa vĩnh viễn runtime và tất cả các endpoint của nó.
Trong trang chi tiết Runtime, tìm runtime → Delete → xác nhận
RESTful API
�Điều kiện cần: Tất cả các ví dụ API dưới đây sử dụng
$TOKEN— một IAM bearer token. Xem Configure Authentication để biết cách lấy token.
Tạo một Runtime
Image từ registry công khai:
Image từ registry riêng tư (cần imageAuth):
Kiểm tra cho đến khi ACTIVE:
Các trạng thái có thể: CREATING → ACTIVE (thành công) hoặc ERROR (thất bại)
Xem danh sách Runtime
Cấu trúc phản hồi:
Xem chi tiết Runtime
Cập nhật một Runtime
Mỗi lần cập nhật tạo một version mới. Endpoint DEFAULT tự động trỏ đến phiên bản mới nhất.
Lưu ý: Tất cả các trường (trừ
imageAuth) là bắt buộc trong body PATCH.
Xóa một Runtime
Lưu ý: Xóa là không thể khôi phục.
Đặt lại Service Account
Nếu thông tin đăng nhập IAM service account bị thay đổi hoặc bị thu hồi, đặt lại chúng để khôi phục runtime:
Lưu ý: Thao tác này tạo lại
GREENNODE_CLIENT_IDvàGREENNODE_CLIENT_SECRET. Runtime sẽ khởi động lại với credential mới.
Quản lý Endpoint (Manage Endpoints)
Mỗi runtime có một endpoint DEFAULT được tạo tự động. Bạn có thể tạo các endpoint bổ sung trỏ đến các phiên bản cụ thể.
Portal
Xem danh sách Endpoint
Mở trang chi tiết runtime → tab "Endpoints"
Tạo Endpoint
Trên trang chi tiết runtime → tab "Endpoints" → "Create Endpoint"
Điền Name và Version → Create
Cập nhật phiên bản Endpoint
Trên tab "Endpoints" → nhấn vào một endpoint → "Edit"
Thay đổi Version → Save
RESTful API
Xem danh sách Endpoint
Các trường Endpoint: id, agentRuntimeId, name, version, url, status, createdAt, updatedAt
Tạo Endpoint
Cập nhật phiên bản Endpoint
Xóa Endpoint
Phiên bản Runtime (Runtime Versions)
Mỗi PATCH trên một runtime tạo một phiên bản bất biến mới. Sử dụng phiên bản để quay lại bằng cách trỏ một endpoint đến số phiên bản cũ hơn.
Portal
Mở trang chi tiết runtime → tab "Versions"

RESTful API
Xem danh sách phiên bản
Các trường Version: agentRuntimeId, version (số nguyên), imageUrl, flavorId, autoscaling, createdAt
Quay lại phiên bản cũ (Rollback)
Trỏ endpoint DEFAULT đến một phiên bản cũ hơn:
Hợp đồng dịch vụ Runtime (Runtime Service Contract)
Container agent của bạn phải đáp ứng các yêu cầu sau:
Port và Health Check
Cổng lắng nghe
8080
Bắt buộc — không thể cấu hình
Đường dẫn kiểm tra sức khỏe
GET /health
Phải trả về HTTP 200
Sử dụng greennode-agentbase SDK (khuyến nghị):
Không sử dụng SDK (ví dụ FastAPI):
Biến môi trường tự động (Auto-Injected Environment Variables)
Runtime tự động tiêm các biến sau vào mỗi container:
GREENNODE_CLIENT_ID
IAM service account client ID cho runtime
GREENNODE_CLIENT_SECRET
IAM service account client secret
GREENNODE_AGENT_IDENTITY
Tên agent identity
Request Header
Các request đến agent của bạn có thể bao gồm các header sau — do client gửi lên và được chuyển nguyên vẹn:
X-GreenNode-AgentBase-User-Id
ID người dùng cuối (sử dụng làm actorId cho các thao tác memory)
X-GreenNode-AgentBase-Session-Id
ID phiên (sử dụng làm thread_id cho LangGraph checkpointing)
Quan trọng: AgentBase không truyền danh tính caller (đã xác thực ở Inbound Auth) vào container — các header này không được AgentBase xác thực và có thể bị client giả mạo. Nếu agent của bạn sử dụng memory, hãy xác thực rằng các header này có mặt và trả về lỗi nếu thiếu. Không sử dụng giá trị mặc định và không dùng các header này cho logic phân quyền.
Header khi request đến container
Cách AgentBase xử lý header phụ thuộc vào chế độ Inbound Auth của endpoint:
Inbound Auth
Xử lý header Authorization và x-agentbase-endpoint-inbound-header-authorization
No authorization
Chuyển nguyên vẹn đến container — bạn có thể tự xác thực trong agent bằng các header này
IAM Permissions, JWT
AgentBase dùng token trong các header này để xác thực caller, sau đó strip cả hai header trước khi request đến container — container không đọc được token, kể cả khi gửi token xác thực qua x-agentbase-endpoint-inbound-header-authorization và đặt token khác vào Authorization
Các header khác (ví dụ X-Api-Key, Cookie, traceparent, header tùy chỉnh) được chuyển nguyên vẹn ở mọi chế độ. X-Forwarded-For được nối thêm địa chỉ của proxy.
Quan trọng: AgentBase hiện không truyền danh tính caller (user ID, claim của JWT) vào container. Không xây dựng logic phân quyền dựa trên các header như
x-agentbase-endpoint-inbound-user-id,portal-user-id,iam-user-id— các header này do client gửi lên và được chuyển nguyên vẹn, nên có thể bị giả mạo. Nếu agent cần một token riêng ở chế độ IAM Permissions/JWT (API key của ứng dụng, JWT của end-user), hãy gửi qua header tùy chỉnh, ví dụX-Api-Key— không dùngAuthorization.
Last updated

