Bắt đầu

Hoàn thành các điều kiện cần này trước khi sử dụng bất kỳ dịch vụ AgentBase nào. Sau khi hoàn tất, hãy theo lộ trình đọc tài liệu để bắt đầu xây dựng.

Điều kiện cần (Prerequisites)

Tạo tài khoản GreenNode

Truy cập https://dashboard.console.greennode.ai/ và đăng ký hoặc đăng nhập.
Hoàn thành xác minh tài khoản.
Tạo hoặc tham gia một Organization. Tất cả tài nguyên AgentBase đều thuộc phạm vi một organization.

Lưu ý: Nếu công ty của bạn đã có một GreenNode organization, hãy yêu cầu quản trị viên mời bạn trước khi tạo tài khoản riêng.

Cài đặt các công cụ cần thiết

Python SDK

pip install greennode-agentbase

Đối với tích hợp LangGraph và LangChain:

pip install "greennode-agent-bridge[langgraph]"

curl và jq (cho các ví dụ RESTful API)

# macOS
brew install jq

# Ubuntu / Debian
apt-get install -y curl jq

# Windows — use WSL or Git Bash with jq from https://jqlang.github.io/jq/

Thiết lập IAM Service Account

Tất cả các cuộc gọi AgentBase API (Portal, RESTful API và SDK) đều yêu cầu một GreenNode IAM bearer token được lấy từ Service Account. Thực hiện các bước sau một lần để tạo service account của bạn.

Portal (GUI)

Bước 1: Di chuyển đến IAM Service Accounts

Mở: https://iam.console.greennode.ai/service-accounts
Nếu được yêu cầu, đăng nhập bằng tài khoản GreenNode của bạn.

Bước 2: Tạo Service Account mới

Nhấn "Create a Service Account".
Điền vào:
- Name: ví dụ, agentbase-dev
- Description: ví dụ, Service account for AgentBase test
Nhấn "Next Step".

Bước 3: Gắn Policies

Trong tab Permissions, nhấn "Attach Policies".
Tìm và gắn từng policy sau:
- AgentBaseFullAccess — truy cập các dịch vụ Identity, Runtime và Memory
- vcrFullAccess — truy cập Container Registry (để push/pull image)
- AiPlatformFullAccess — truy cập các LLM model và API key
Nhấn "Create Service Account".

Bước 4: Sao chép Client Secret (chỉ một lần duy nhất)

Lưu ý: Client Secret chỉ được hiển thị một lần duy nhất tại thời điểm tạo. Sao chép và lưu lại ngay lập tức — không thể truy xuất lại sau đó. Nếu bị mất, bạn phải reset nó (điều này sẽ vô hiệu hóa secret cũ).

Một cửa sổ popup xuất hiện với thông tin credential của bạn. Sao chép Client Secret và lưu trữ an toàn.
Nhấn "Back to list".
Tìm service account mới của bạn, nhấn vào nó, di chuyển đến tab "Security credentials".
Sao chép Client ID.

Cấu hình xác thực

Bây giờ bạn đã có Client ID và Client Secret, hãy cấu hình chúng để tất cả các cuộc gọi API và thao tác SDK có thể tự động xác thực.

Phương án A — Biến môi trường

export GREENNODE_CLIENT_ID="your-client-id"
export GREENNODE_CLIENT_SECRET="your-client-secret"

Phương án B — Tệp cấu hình

Tạo tệp .greennode.json trong thư mục gốc của dự án:

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}

Lưu ý: Không commit .greennode.json vào hệ thống quản lý phiên bản. Thêm nó vào .gitignore.

Lấy IAM Token (`$TOKEN`)

Tất cả các ví dụ RESTful API trong hướng dẫn này sử dụng $TOKEN. Lấy token bằng lệnh:

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')

Sau đó sử dụng trong các cuộc gọi API:

curl -s -X GET "https://agentbase.api.vngcloud.vn/..." \
  -H "Authorization: Bearer $TOKEN"

Thời hạn token: Token có thời hạn ngắn. Nếu bạn nhận được phản hồi 401 Unauthorized, chạy lại lệnh trên để lấy token mới.

Lưu ý (người dùng SDK): Python SDK tự động quản lý token — chỉ cần đảm bảo credential của bạn được cấu hình qua biến môi trường hoặc .greennode.json. Không cần lấy token thủ công.