Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

Trạng thái
Mô tả

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)

  • cpuUtilization và 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:

  1. Lắng nghe trên cổng 8080 — cổng bắt buộc; app.run(host="0.0.0.0", port=8080)

  2. Endpoint kiểm tra sức khỏe: GET /health phải trả về HTTP 200 để vượt qua kiểm tra sẵn sàng

  3. Khô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):

Biến
Mô tả

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 runtime

  • 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

  • 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

  1. Mở https://aiplatform.console.greennode.ai/my-agents?tab=runtime

  2. Nhấn "Create Runtime"

  3. Điền thông tin

Trường
Giá trị ví dụ
Ghi chú

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

Security Settings — IP Access Control và Inbound Identity
  1. Nhấn Create

  2. Runtime xuất hiện với trạng thái CREATING, sau đó chuyển sang ACTIVE

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

1774594267224

Cập nhật một Runtime

  1. Mở trang chi tiết runtime → "Edit"

  2. 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_ID và 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

  1. Mở trang chi tiết runtime → tab "Endpoints"

Tạo Endpoint

  1. Trên trang chi tiết runtime → tab "Endpoints" → "Create Endpoint"

  2. Điền Name và Version → Create

Cập nhật phiên bản Endpoint

  1. Trên tab "Endpoints" → nhấn vào một endpoint → "Edit"

  2. 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

  1. Mở trang chi tiết runtime → tab "Versions"

1774594455831

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

Yêu cầu
Giá trị
Ghi chú

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:

Biến
Mô tả

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:

Header
Mô tả

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ùng Authorization.


Last updated