Runtime

The Runtime manages the full lifecycle of your agent's compute environment — container deployment, autoscaling, versioning, and endpoints.

Core Concepts

Runtime

A Runtime is the managed compute environment that runs your containerized agent. It abstracts container scheduling, health checks, autoscaling, and HTTP routing.

Runtime states:

State

Description

CREATING

Runtime is being created; containers are starting

ACTIVE

All minimum replicas are healthy; endpoint is serving traffic

UPDATING

A new version deployment is in progress

ERROR

One or more required replicas could not start (check logs)

DELETING

Runtime is being deleted

Versions

Every time you deploy a new container image to a runtime, AgentBase creates a new Version. Versions are immutable — a version's image and configuration never change after creation.

Endpoint

An Endpoint is the URL that clients call to interact with your agent. A runtime can have multiple endpoints and multiple versions — these are independent concepts. The default endpoint automatically tracks the latest version whenever a new version is deployed. You can designate any endpoint as the default, and create additional endpoints pinned to specific versions (for example, for canary or staging traffic).

Compute Flavors

A Compute Flavor defines the CPU and RAM allocated to each replica of your agent.

Autoscaling

The Runtime Service supports autoscaling based on CPU or RAM utilization. You define:

minReplicas: The floor — always running (range: 1–10)
maxReplicas: The ceiling — caps resource usage (range: 1–10)
cpuUtilization and memoryUtilization: Thresholds (25–75%) that trigger scale-out

When load drops, AgentBase scales replicas back down to minReplicas.

Service Contract

Your agent container must satisfy these requirements to work correctly with the Runtime Service:

Listen on port 8080 — the required port; app.run(host="0.0.0.0", port=8080)
Health check endpoint: GET /health must return HTTP 200 to pass readiness checks
Stateless: Do not store session state in process memory — use the Memory Service instead

Auto-injected environment variables (available in all deployed agent containers):

Variable

Description

GREENNODE_CLIENT_ID

IAM service account client ID

GREENNODE_CLIENT_SECRET

IAM service account client secret

GREENNODE_AGENT_IDENTITY

Agent identity name

Overview

Runtime topology:

Runtime: my-order-agent
│
├── Versions
│   ├── Version 1  (image: my-agent:v1.0.0)
│   └── Version 2  (image: my-agent:v2.0.0)  ← latest
│
├── Endpoints
│   ├── DEFAULT  → https://<default-url>   (auto-tracks latest version)
│   └── canary   → https://<canary-url>    (pinned to Version 1)
│
└── Autoscaling: min=1, max=3, CPU threshold=50%

Key facts:

Each PATCH /agent-runtimes/{id} creates a new version — versions and endpoints are independent concepts under a runtime
The default endpoint automatically tracks the latest version whenever a new version is deployed
A runtime can have multiple endpoints — you choose which one is the default
You have full control over all endpoints — create, update, or delete

Manage Runtimes

Portal

Create a Runtime

Open https://aiplatform.console.vngcloud.vn/runtime
Click "Create Runtime"
Fill information

Field

Example Value

Notes

Name

my-order-agent

Unique, lowercase, hyphens allowed

Description

Production order agent

Optional

Image URL

vcr.vngcloud.vn/<repo>/my-agent:v1

Full image path including tag

Flavor

1x1-general

1 CPU, 1 GB RAM

Min Replicas

1

Range: 1–10

Max Replicas

1

Set >1 to enable autoscaling

CPU Threshold

50

Scale out when CPU exceeds this % (25–75)

Memory Threshold

50

Scale out when RAM exceeds this % (25–75)

Registry Auth

Enable if private

Username = robot account backendName (see Supporting Services — Robot Accounts)

Environment Variables

KEY=value

Non-sensitive config only

Click Create
Runtime appears with status CREATING, then transitions to ACTIVE

List Runtimes

All runtimes are shown in a paginated table with: Name, Status, Description, Last version, Last updated

Get Runtime Details

Click a runtime name to view: status, image, flavor, autoscaling, environment variables, endpoints

Update a Runtime

Open the runtime detail page → "Edit"
Modify image URL, flavor, autoscaling, or env vars → Save

Delete a Runtime

Warning: Deletion is irreversible. This permanently removes the runtime and all its endpoints.

In Runtime detail page, find the runtime → Delete → confirm

RESTful API

Prerequisite: All API examples below use $TOKEN — an IAM bearer token. See Configure Authentication for how to obtain it.

Create a Runtime

Public registry image:

curl -s -X POST "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-order-agent",
    "description": "Production order agent",
    "imageUrl": "vcr.vngcloud.vn/<repo-backendName>/my-agent:v1.0.0",
    "command": [],
    "args": [],
    "environmentVariables": {
      "LOG_LEVEL": "info"
    },
    "flavorId": "1x1-general",
    "autoscaling": {
      "minReplicas": 1,
      "maxReplicas": 3,
      "cpuUtilization": 50,
      "memoryUtilization": 50
    }
  }' | jq .

Private registry image (imageAuth required):

curl -s -X POST "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-order-agent",
    "imageUrl": "vcr.vngcloud.vn/<repo-backendName>/my-agent:v1.0.0",
    "imageAuth": {
      "enabled": true,
      "username": "<robot-account-backendName>",
      "password": "<robot-account-secret>"
    },
    "command": [],
    "args": [],
    "environmentVariables": {},
    "flavorId": "1x1-general",
    "autoscaling": {
      "minReplicas": 1,
      "maxReplicas": 1,
      "cpuUtilization": 50,
      "memoryUtilization": 50
    }
  }' | jq .

Poll until ACTIVE:

RUNTIME_ID="<id-from-response>"
while true; do
  STATUS=$(curl -s "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID" \
    -H "Authorization: Bearer $TOKEN" | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "ACTIVE" ] && break
  sleep 10
done

Possible statuses: CREATING → ACTIVE (success) or ERROR (failed)

List Runtimes

curl -s "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes?page=1&size=20" \
  -H "Authorization: Bearer $TOKEN" | jq .

Response shape:

{
  "listData": [...],
  "page": 1,
  "pageSize": 20,
  "totalPage": 1,
  "totalItem": 3
}

Get Runtime Details

curl -s "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

Update a Runtime

Each update creates a new version. The DEFAULT endpoint automatically points to the latest version.

Note: All fields (except imageAuth) are required in the PATCH body.

curl -s -X PATCH "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Production order agent v2",
    "imageUrl": "vcr.vngcloud.vn/<repo-backendName>/my-agent:v2.0.0",
    "imageAuth": {
      "enabled": true,
      "username": "<robot-backendName>",
      "password": "<robot-secret>"
    },
    "command": [],
    "args": [],
    "environmentVariables": {"LOG_LEVEL": "info"},
    "flavorId": "1x1-general",
    "autoscaling": {
      "minReplicas": 1,
      "maxReplicas": 3,
      "cpuUtilization": 50,
      "memoryUtilization": 50
    }
  }' | jq .

Delete a Runtime

Warning: Deletion is irreversible.

curl -s -X DELETE "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID" \
  -H "Authorization: Bearer $TOKEN"

Reset Service Account

If IAM service account credentials are changed or revoked, reset them to recover the runtime:

curl -s -X PATCH "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID/reset-service-account" \
  -H "Authorization: Bearer $TOKEN" | jq .

Warning: This regenerates GREENNODE_CLIENT_ID and GREENNODE_CLIENT_SECRET. The runtime restarts with new credentials.

Manage Endpoints

Each runtime has a DEFAULT endpoint created automatically. You can create additional endpoints pointing to specific versions.

Portal

List Endpoints

Open the runtime detail page → "Endpoints" tab

Create Endpoint

On the runtime detail page → "Endpoints" tab → "Create Endpoint"
Fill in Name and Version → Create

Update Endpoint Version

On the "Endpoints" tab → click an endpoint → "Edit"
Change Version → Save

RESTful API

List Endpoints

curl -s "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID/endpoints?page=1&size=20" \
  -H "Authorization: Bearer $TOKEN" | jq .

Endpoint fields: id, agentRuntimeId, name, version, url, status, createdAt, updatedAt

Create Endpoint

curl -s -X POST "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID/endpoints" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "canary", "version": 2}' | jq .

Update Endpoint Version

curl -s -X PATCH "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID/endpoints/$ENDPOINT_ID?version=3" \
  -H "Authorization: Bearer $TOKEN" | jq .

Delete Endpoint

curl -s -X DELETE "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID/endpoints/$ENDPOINT_ID" \
  -H "Authorization: Bearer $TOKEN"

Runtime Versions

Each PATCH on a runtime creates a new immutable version. Use versions to roll back by pointing an endpoint to an older version number.

Portal

Open the runtime detail page → "Versions" tab

RESTful API

List Versions

curl -s "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID/versions?page=1&size=20" \
  -H "Authorization: Bearer $TOKEN" | jq .

Version fields: agentRuntimeId, version (integer), imageUrl, flavorId, autoscaling, createdAt

Rollback

Point the DEFAULT endpoint to an older version:

ENDPOINT_ID=$(curl -s "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID/endpoints?page=1&size=10" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.listData[] | select(.name=="DEFAULT") | .id')

curl -s -X PATCH "https://agentbase.api.vngcloud.vn/runtime/agent-runtimes/$RUNTIME_ID/endpoints/$ENDPOINT_ID?version=1" \
  -H "Authorization: Bearer $TOKEN" | jq .

Runtime Service Contract

Your agent container must fulfill these requirements:

Port and Health Check

Requirement

Value

Notes

Listen port

8080

Required — not configurable

Health check path

GET /health

Must return HTTP 200

Using the greennode-agentbase SDK (recommended):

from greennode_agentbase import GreenNodeAgentBaseApp, RequestContext, PingStatus

app = GreenNodeAgentBaseApp()

@app.entrypoint
def handler(payload: dict, context: RequestContext) -> dict:
    return {"output": "Hello!"}

if __name__ == "__main__":
    import os
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", "8080")))

Without the SDK (FastAPI example):

from fastapi import FastAPI

app = FastAPI()

@app.get("/health")
def health():
    return {"status": "ok"}

@app.post("/invoke")
def invoke(body: dict):
    return {"output": f"Echo: {body.get('input', '')}"}

Auto-Injected Environment Variables

The Runtime automatically injects these into every container:

Variable

Description

GREENNODE_CLIENT_ID

IAM service account client ID for the runtime

GREENNODE_CLIENT_SECRET

IAM service account client secret

GREENNODE_AGENT_IDENTITY

The agent identity name

Request Headers

Incoming requests to your agent include:

Header

Description

X-GreenNode-AgentBase-User-Id

End-user ID (use as actorId for memory operations)

X-GreenNode-AgentBase-Session-Id

Session ID (use as thread_id for LangGraph checkpointing)

Important: If your agent uses memory, validate that these headers are present and return an error if missing. Do not fall back to default values — silent defaults cause data mixing between users.

PreviousAccess Control NextMemory

Last updated 1 month ago

hashtagCore Concepts

hashtagRuntime

hashtagVersions

hashtagEndpoint

hashtagCompute Flavors

hashtagAutoscaling

hashtagService Contract

hashtagOverview

hashtagManage Runtimes

hashtagPortal

hashtagCreate a Runtime

hashtagList Runtimes

hashtagGet Runtime Details

hashtagUpdate a Runtime

hashtagDelete a Runtime

hashtagRESTful API

hashtagCreate a Runtime

hashtagList Runtimes

hashtagGet Runtime Details

hashtagUpdate a Runtime

hashtagDelete a Runtime

hashtagReset Service Account

hashtagManage Endpoints

hashtagPortal

hashtagList Endpoints

hashtagCreate Endpoint

hashtagUpdate Endpoint Version

hashtagRESTful API

hashtagList Endpoints

hashtagCreate Endpoint

hashtagUpdate Endpoint Version

hashtagDelete Endpoint

hashtagRuntime Versions

hashtagPortal

hashtagRESTful API

hashtagList Versions

hashtagRollback

hashtagRuntime Service Contract

hashtagPort and Health Check

hashtagAuto-Injected Environment Variables

hashtagRequest Headers

Core Concepts

Runtime

Versions

Endpoint

Compute Flavors

Autoscaling

Service Contract

Overview

Manage Runtimes

Portal

Create a Runtime

List Runtimes

Get Runtime Details

Update a Runtime

Delete a Runtime

RESTful API

Create a Runtime

List Runtimes

Get Runtime Details

Update a Runtime

Delete a Runtime

Reset Service Account

Manage Endpoints

Portal

List Endpoints

Create Endpoint

Update Endpoint Version

RESTful API

List Endpoints

Create Endpoint

Update Endpoint Version

Delete Endpoint

Runtime Versions

Portal

RESTful API

List Versions

Rollback

Runtime Service Contract

Port and Health Check

Auto-Injected Environment Variables

Request Headers