> For the complete documentation index, see [llms.txt](https://docs.vngcloud.vn/vng-cloud-document/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vngcloud.vn/vng-cloud-document/ai-stack/agent-base/reference.md).

# Reference

> Complete reference for all AgentBase API endpoints, pagination conventions, environment variables, SDK imports, and platform limits.

***

## Service URLs

### Portal Consoles

| Service                   | URL                                                |
| ------------------------- | -------------------------------------------------- |
| IAM Service Accounts      | <https://iam.console.vngcloud.vn/service-accounts> |
| IAM Policies              | <https://iam.console.vngcloud.vn/policies>         |
| Access Control (Identity) | <https://aiplatform.console.vngcloud.vn/identity>  |
| Runtime                   | <https://aiplatform.console.vngcloud.vn/runtime>   |
| Memory                    | <https://aiplatform.console.vngcloud.vn/memory>    |
| Container Registry (vCR)  | <https://vcr.console.vngcloud.vn>                  |
| AI Platform (AIP) Models  | <https://aiplatform.console.vngcloud.vn/models>    |

### API Base URLs

| Service                           | Base URL                                             |
| --------------------------------- | ---------------------------------------------------- |
| Access Control                    | `https://agentbase.api.vngcloud.vn/identity/api/v1`  |
| Runtime                           | `https://agentbase.api.vngcloud.vn/runtime`          |
| Memory                            | `https://agentbase.api.vngcloud.vn/memory`           |
| Container Registry (vCR)          | `https://vcr.api.vngcloud.vn`                        |
| AIP Management                    | `https://aiplatform-hcm.api.vngcloud.vn`             |
| LLM Inference (OpenAI-compatible) | `https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1` |
| Registry Host (Docker)            | `vcr.vngcloud.vn`                                    |

***

## API Endpoints by Service

### Access Control (`https://agentbase.api.vngcloud.vn/identity/api/v1`)

**Agent Identities:**

| Method   | Path                               | Description                 |
| -------- | ---------------------------------- | --------------------------- |
| `POST`   | `/agent-identities`                | Create identity             |
| `GET`    | `/agent-identities?page=0&size=20` | List identities (0-indexed) |
| `GET`    | `/agent-identities/{name}`         | Get identity                |
| `PUT`    | `/agent-identities/{name}`         | Update identity             |
| `DELETE` | `/agent-identities/{name}`         | Delete identity             |

**Static API Key Providers:**

| Method   | Path                                                                           | Description         |
| -------- | ------------------------------------------------------------------------------ | ------------------- |
| `POST`   | `/outbound-auth/api-key-providers`                                             | Create provider     |
| `GET`    | `/outbound-auth/api-key-providers?page=0&size=20`                              | List providers      |
| `GET`    | `/outbound-auth/api-key-providers/{name}`                                      | Get provider        |
| `PUT`    | `/outbound-auth/api-key-providers/{name}`                                      | Update (rotate key) |
| `DELETE` | `/outbound-auth/api-key-providers/{name}`                                      | Delete provider     |
| `GET`    | `/outbound-auth/api-key-providers/{name}/agent-identities/{agentName}/api-key` | Retrieve key        |

**Delegated API Key Providers:**

| Method   | Path                                                                                     | Description           |
| -------- | ---------------------------------------------------------------------------------------- | --------------------- |
| `POST`   | `/outbound-auth/delegated-api-key-providers`                                             | Create provider       |
| `GET`    | `/outbound-auth/delegated-api-key-providers?page=0&size=20`                              | List providers        |
| `GET`    | `/outbound-auth/delegated-api-key-providers/{name}`                                      | Get provider          |
| `DELETE` | `/outbound-auth/delegated-api-key-providers/{name}`                                      | Delete provider       |
| `POST`   | `/outbound-auth/delegated-api-key-providers/{name}/agent-identities/{agentName}/api-key` | Request delegated key |

**OAuth2 Providers:**

| Method   | Path                                                                             | Description     |
| -------- | -------------------------------------------------------------------------------- | --------------- |
| `POST`   | `/outbound-auth/oauth2-providers`                                                | Create provider |
| `GET`    | `/outbound-auth/oauth2-providers?page=0&size=20`                                 | List providers  |
| `GET`    | `/outbound-auth/oauth2-providers/{name}`                                         | Get provider    |
| `PUT`    | `/outbound-auth/oauth2-providers/{name}`                                         | Update provider |
| `DELETE` | `/outbound-auth/oauth2-providers/{name}`                                         | Delete provider |
| `POST`   | `/outbound-auth/oauth2-providers/{name}/agent-identities/{agentName}/tokens/m2m` | Get M2M token   |
| `POST`   | `/outbound-auth/oauth2-providers/{name}/agent-identities/{agentName}/tokens/3lo` | Get 3LO token   |

***

### Runtime (`https://agentbase.api.vngcloud.vn/runtime`)

**Agent Runtimes:**

| Method   | Path                                         | Description                          |
| -------- | -------------------------------------------- | ------------------------------------ |
| `POST`   | `/agent-runtimes`                            | Create runtime                       |
| `GET`    | `/agent-runtimes?page=1&size=20`             | List runtimes (1-indexed)            |
| `GET`    | `/agent-runtimes/{id}`                       | Get runtime                          |
| `PATCH`  | `/agent-runtimes/{id}`                       | Update runtime (creates new version) |
| `DELETE` | `/agent-runtimes/{id}`                       | Delete runtime                       |
| `PATCH`  | `/agent-runtimes/{id}/reset-service-account` | Reset IAM credentials                |

**Endpoints:**

| Method   | Path                                                    | Description             |
| -------- | ------------------------------------------------------- | ----------------------- |
| `GET`    | `/agent-runtimes/{id}/endpoints?page=1&size=20`         | List endpoints          |
| `POST`   | `/agent-runtimes/{id}/endpoints`                        | Create endpoint         |
| `PATCH`  | `/agent-runtimes/{id}/endpoints/{endpointId}?version=N` | Update endpoint version |
| `DELETE` | `/agent-runtimes/{id}/endpoints/{endpointId}`           | Delete endpoint         |

**Versions:**

| Method | Path                                           | Description   |
| ------ | ---------------------------------------------- | ------------- |
| `GET`  | `/agent-runtimes/{id}/versions?page=1&size=20` | List versions |

**Flavors:**

| Method | Path       | Description          |
| ------ | ---------- | -------------------- |
| `GET`  | `/flavors` | List compute flavors |

**Insight (Logs & Metrics):**

| Method | Path                                                  | Description         |
| ------ | ----------------------------------------------------- | ------------------- |
| `POST` | `/agent-runtimes/{id}/logs`                           | Get runtime logs    |
| `POST` | `/agent-runtimes/{id}/endpoints/{endpointId}/logs`    | Get endpoint logs   |
| `GET`  | `/agent-runtimes/{id}/endpoints/{endpointId}/metrics` | Get CPU/RAM metrics |

***

### Memory (`https://agentbase.api.vngcloud.vn/memory`)

**Memories:**

| Method   | Path                                         | Description               |
| -------- | -------------------------------------------- | ------------------------- |
| `POST`   | `/memories`                                  | Create memory             |
| `GET`    | `/memories?page=1&size=10`                   | List memories (1-indexed) |
| `GET`    | `/memories/{id}`                             | Get memory                |
| `DELETE` | `/memories/{id}`                             | Delete memory             |
| `GET`    | `/memories/{id}/long-term-memory-strategies` | List strategies           |

**Events:**

| Method | Path                                                                         | Description  |
| ------ | ---------------------------------------------------------------------------- | ------------ |
| `POST` | `/memories/{id}/actors/{actorId}/sessions/{sessionId}/events`                | Create event |
| `GET`  | `/memories/{id}/actors/{actorId}/sessions/{sessionId}/events?page=1&size=20` | List events  |
| `GET`  | `/memories/{id}/actors?page=1&size=10`                                       | List actors  |

**Memory Records:**

| Method | Path                                                                                                | Description           |
| ------ | --------------------------------------------------------------------------------------------------- | --------------------- |
| `GET`  | `/memories/{id}/memory-records?namespace=<encoded>&limit=100`                                       | Browse records        |
| `POST` | `/memories/{id}/memory-records:search?namespace=<encoded>`                                          | Semantic search       |
| `POST` | `/memories/{id}/memory-records:generate-from-session?actorId=&sessionId=&longTermMemoryStrategyId=` | Generate from session |

***

### Container Registry (`https://vcr.api.vngcloud.vn`)

| Method   | Path                                                     | Description                       |
| -------- | -------------------------------------------------------- | --------------------------------- |
| `GET`    | `/v1/repository?page=1&size=50`                          | List repositories                 |
| `POST`   | `/v1/repository`                                         | Create repository                 |
| `GET`    | `/v1/repository/{repoId}`                                | Get repository                    |
| `DELETE` | `/v1/repository/{repoId}`                                | Delete repository (must be empty) |
| `GET`    | `/v1/user?page=1&size=50`                                | List robot accounts               |
| `POST`   | `/v1/user`                                               | Create robot account              |
| `GET`    | `/v1/user/permissions`                                   | List available permissions        |
| `DELETE` | `/v1/user/{repoUserId}`                                  | Delete robot account              |
| `GET`    | `/v1/repository/{repoId}/images?name=&page=1&size=10`    | List images                       |
| `DELETE` | `/v1/repository/{repoId}/images/delete?imageName={name}` | Delete image                      |

***

### AI Platform (`https://aiplatform-hcm.api.vngcloud.vn`)

| Method   | Path                          | Description                          |
| -------- | ----------------------------- | ------------------------------------ |
| `GET`    | `/v1/api-keys?page=1&size=20` | List API keys                        |
| `POST`   | `/v1/api-keys`                | Create API key (async)               |
| `GET`    | `/v1/api-keys/{name}`         | Get API key (poll for ACTIVE)        |
| `PUT`    | `/v1/api-keys/{name}`         | Update API key                       |
| `DELETE` | `/v1/api-keys/{name}`         | Delete API key (async, poll for 404) |
| `GET`    | `/v1/models?page=1&size=20`   | List models                          |
| `GET`    | `/v1/models/detail/{uuid}`    | Get model detail                     |

**LLM Inference (OpenAI-compatible):**

| Method | Path                   | Description     |
| ------ | ---------------------- | --------------- |
| `POST` | `/v1/chat/completions` | Chat completion |
| `POST` | `/v1/completions`      | Text completion |
| `POST` | `/v1/embeddings`       | Embeddings      |

Base URL for inference: `https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1`

***

## Pagination Reference

> **Critical:** Pagination conventions differ across services. Using the wrong page index causes unexpected empty results or 400 errors.

| Service        | First Page | Items Key   | Count Key        | Pages Key     |
| -------------- | ---------- | ----------- | ---------------- | ------------- |
| Access Control | `page=0`   | `.content`  | `.totalElements` | `.totalPages` |
| Runtime        | `page=1`   | `.listData` | `.totalItem`     | `.totalPage`  |
| Memory         | `page=1`   | `.listData` | `.totalItem`     | `.totalPage`  |
| vCR            | `page=1`   | `.listData` | `.totalItem`     | `.totalPage`  |
| AIP            | `page=1`   | `.listData` | `.totalItem`     | `.totalPage`  |

***

## Response Shape Reference

**Access Control (Spring-style):**

```json
{
  "content": [...],
  "totalElements": 5,
  "totalPages": 1,
  "size": 20,
  "number": 0
}
```

**Runtime / Memory / vCR / AIP (GreenNode-style):**

```json
{
  "listData": [...],
  "page": 1,
  "pageSize": 20,
  "totalPage": 1,
  "totalItem": 5
}
```

***

## Authentication

All API calls require a GreenNode IAM bearer token:

```bash
Authorization: Bearer <token>
```

**Get token:** See [Configure Authentication](/vng-cloud-document/ai-stack/agent-base/getting-started.md#configure-authentication) for full setup. Quick reference:

```bash
TOKEN=$(curl -s -X POST "https://iam.api.vngcloud.vn/accounts-api/v2/auth/token" \
  -u "$GREENNODE_CLIENT_ID:$GREENNODE_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -H "Content-Type: application/x-www-form-urlencoded" | jq -r '.access_token')
```

**Token expiry:** Tokens are short-lived. On 401, re-obtain a fresh token.

***

## SDK Imports

```python
# Main AgentBase SDK
from greennode_agentbase import (
    GreenNodeAgentBaseApp,      # Web server for agent
    RequestContext,             # HTTP request metadata (user_id, session_id)
    PingStatus,                 # Health status enum (HEALTHY, HEALTHY_BUSY)
    IdentityClient,             # Access Control client
    MemoryClient,               # Memory service client
    IAMCredentials,             # IAM auth credentials
    requires_api_key,           # Decorator: inject static API key
    requires_access_token,      # Decorator: inject OAuth2 access token
)

# Access Control requests
from greennode_agentbase.identity import (
    CreateAgentIdentityRequest,
    UpdateAgentIdentityRequest,
    CreateApikeyProviderRequest,
    UpdateApikeyProviderRequest,
    CreateDelegatedApiKeyProviderRequest,
    CreateOauth2ProviderRequest,
    UpdateOauth2ProviderRequest,
    GetDelegatedApiKeyRequest,
    GetM2mTokenRequest,
    ThreeLoTokenRequest,
)

# Memory models
from greennode_agentbase.memory.models import (
    MemoryCreateRequest,
    LongTermMemoryStrategy,
    EventCreateRequest,
    ChatMessage,
    MemoryRecordSearchRequest,
)

# LangGraph bridge (short-term memory checkpointer)
from greennode_agent_bridge import AgentBaseMemoryEvents
```

***

## Auto-Injected Environment Variables

When an agent is deployed on AgentBase Runtime, these environment variables are automatically injected:

| Variable                   | Description                       | Used by                         |
| -------------------------- | --------------------------------- | ------------------------------- |
| `GREENNODE_CLIENT_ID`      | IAM service account client ID     | SDK auto-auth                   |
| `GREENNODE_CLIENT_SECRET`  | IAM service account client secret | SDK auto-auth                   |
| `GREENNODE_AGENT_IDENTITY` | Agent identity name               | SDK auth + credential retrieval |

***

## Runtime Service Contract

Your agent container must meet these requirements:

| Requirement        | Value                                |
| ------------------ | ------------------------------------ |
| Listen port        | `8080` (required)                    |
| Health check       | `GET /health` must return HTTP 200   |
| SDK server startup | `app.run(host="0.0.0.0", port=8080)` |

**Incoming request headers (when using Memory):**

| Header                             | Description                           |
| ---------------------------------- | ------------------------------------- |
| `X-GreenNode-AgentBase-User-Id`    | End-user ID →`actor_id` for memory    |
| `X-GreenNode-AgentBase-Session-Id` | Session ID →`thread_id` for LangGraph |

***

## Platform Limits

### Access Control

| Limit                         | Value              |
| ----------------------------- | ------------------ |
| Identity name max length      | 50 chars           |
| Identity name pattern         | `^[a-zA-Z0-9_-]+$` |
| Auth provider name max length | 50 chars           |
| Auth provider name pattern    | `^[a-zA-Z0-9_-]+$` |

### Runtime

| Limit                              | Value  |
| ---------------------------------- | ------ |
| Min replicas                       | 1      |
| Max replicas                       | 10     |
| CPU utilization threshold range    | 25–75% |
| Memory utilization threshold range | 25–75% |
| Log offset max (`from`)            | 5000   |
| Log limit max (`limit`)            | 1000   |

### Memory

| Limit                                  | Value               |
| -------------------------------------- | ------------------- |
| Memory name max length                 | 50 chars            |
| Memory name pattern                    | `^[a-zA-Z0-9._-]*$` |
| Event expiry duration range            | 1–365 days          |
| Semantic search `limit` range          | 5–200               |
| Semantic search `scoreThreshold` range | 0.0–1.0             |

### Container Registry (vCR)

| Limit                                 | Value                        |
| ------------------------------------- | ---------------------------- |
| Pagination first page                 | `page=1` (0 returns 400)     |
| `name=` param required for image list | Yes, even if empty           |
| Repo deletion                         | Must delete all images first |

### AI Platform (AIP)

| Limit                | Value                     |
| -------------------- | ------------------------- |
| API key name pattern | `^[a-z0-9\-]{5,50}$`      |
| API key creation     | Async — poll until ACTIVE |
| API key deletion     | Async — poll until 404    |

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.vngcloud.vn/vng-cloud-document/ai-stack/agent-base/reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.