Managed Agents trong Gemini API: Hướng dẫn thực hành

Managed Agents trong Gemini API có giá bao nhiêu?

Có nhiều thành phần ảnh hưởng đến giá của Gemini Managed Agents, khiến việc ước tính chi phí chính xác trở nên khó khăn. Chi phí chủ yếu phụ thuộc vào bốn yếu tố:

1. Sử dụng mô hình (Tokens): Chúng ta bị tính phí dựa trên số lượng token đầu vào và đầu ra được mô hình Gemini bên dưới xử lý. Lưu ý rằng các token tạo ra ở kết quả trung gian cũng được tính. Ví dụ, nếu agent tạo một script Python để xây dựng báo cáo, các token cần cho script đó cũng bị tính phí.
2. Hạ tầng và phí nền tảng: Managed agents chạy trong môi trường tích hợp của Google, bao gồm phí dịch vụ cho việc dùng các công cụ nền tảng (như Vertex AI Agent Builder) để quản lý và triển khai agent.
3. Context Caching: Nếu agents thường xuyên tái sử dụng cùng dữ liệu, managed agents có thể dùng context caching. Cách này thường giúp giảm chi phí đáng kể so với mức giá token tiêu chuẩn.
4. Grounding: Nếu agent dùng các dịch vụ ground của Google như Google Search hoặc Google Maps, các khoản này được tính riêng, thường dựa trên hạn ngạch yêu cầu miễn phí ban đầu rồi sau đó là chi phí trên mỗi 1.000 truy vấn (thường khoảng $14/1.000 truy vấn). 

Trong hướng dẫn này, chúng ta sẽ xây dựng một agent dựa trên agent antigravity-preview-05-2026 được vậnhành bởi Gemini 3.5 Flash. Chi phí token của Gemini 3.5 Flash như sau:

Cách xây dựng Managed Agents trong Gemini API

Trong hướng dẫn này, chúng ta sẽ xây dựng một managed agent bằng Gemini API và Python. Vì managed agents là bản phát hành gần đây, hiện đang ở giai đoạn beta, hãy lưu ý rằng một số chi tiết triển khai có thể thay đổi.

Toàn bộ mã trong hướng dẫn này được lưu trong kho GitHub này, cũng là nơi chúng ta dùng để chia sẻ dữ liệu với agent phân tích dữ liệu.

Thiết lập API

Để tạo khóa AI, hãy truy cập Google AI Studio và nhấp “Create API Key” ở góc trên bên phải.

API key cần được gắn với một dự án Google Cloud. Chúng ta có thể chọn dự án hiện có hoặc tạo dự án mới. Ở đây, tôi tạo một dự án tên là gemini-managed-agents.

Sau khi tạo khóa, hãy sao chép khóa. Tiếp theo, tạo tệp tên .env trong thư mục nơi chúng ta sẽ tạo các agent và dán khóa vào với định dạng sau:

GEMINI_API_KEY=<paste_your_api_key_here>

Trước khi đóng Google AI Studio, chúng ta cần thiết lập thanh toán cho API key vừa tạo. Nếu không, yêu cầu của chúng ta sẽ bị từ chối vì Google không thể tính phí. Để thiết lập thanh toán, nhấp nút “Set up billing”.

Thiết lập môi trường Python

Chúng ta sẽ dùng Anaconda để thiết lập môi trường Python cho dự án này. Để tạo môi trường bằng Anaconda, dùng lệnh:

conda create --name gemini_agents python=3.12 -y

Lệnh này tạo môi trường tên gemini_agents sử dụng Python phiên bản 3.10. Tham số -y đơn giản là cách trả lời “yes” cho mọi câu hỏi trong quá trình tạo môi trường.

Tiếp theo, chúng ta kích hoạt môi trường:

conda activate gemini_agents

Cuối cùng, cài đặt các phụ thuộc cần thiết như sau:

pip install google-genai requests python-dotenv

Tạo một tương tác cơ bản với managed agent

Giờ đây, chúng ta đã sẵn sàng chạy agent đầu tiên. Agent này chưa làm được nhiều: nó sẽ chỉ cài đặt matplotlib và báo lại phiên bản đã cài.

Dưới đây là giải thích từng bước về cách chúng ta có thể tương tác với một managed agent (toàn bộ mã có trong script simple_interaction.py trong kho mã):

Đầu tiên, chúng ta import các gói cần thiết và nạp API key từ tệp .env đã tạo trước đó:

from dotenv import load_dotenv
from google import genai

# Load secure environment variables
load_dotenv()

Tiếp theo, khởi tạo Gemini client và tạo một tương tác với agent gốc, hiện có tên antigravity-preview-05-2026, yêu cầu nó cài đặt matplotlib:

# Initialize the GenAI Client
client = genai.Client()

# Create a basic interaction with a managed agent
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install the matplotlib package, verify its version, and report back.",
    environment="remote"
)

Cuối cùng, chúng ta lấy đầu ra từ agent bằng cách kiểm tra các thuộc tính status, environment_id và output_text:

# Output the status of the agent
print(f"Status: {interaction.status}")
print(f"Environment ID: {interaction.environment_id}")
print(f"Output:\n{interaction.output_text}")

Kết quả như sau:

Status: completed
Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6
Output:
I have successfully installed the matplotlib package in the sandbox environment and verified its installation.

Here are the details:
- **Installation Command:** python3 -m pip install --break-system-packages matplotlib
- **Installed Version:** 3.10.9

Các trạng thái vòng đời của sandbox

Trong ví dụ trên, chúng ta đã hiển thị định danh môi trường của tương tác managed agent:

Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6

Giá trị này quan trọng vì nó đại diện cho định danh của môi trường nơi agent được thực thi. Các tương tác của agent được lưu trong môi trường tạm thời (ephemeral) và sẽ được giữ lại tối đa 7 ngày kể từ lần hoạt động cuối cùng trước khi bị xóa.

Sơ đồ dưới đây minh họa vòng đời của sandbox nơi agent được thực thi trong một tương tác.

Khi môi trường chưa bị xóa, chúng ta có thể truy cập và tiếp tục thực hiện các tương tác mới bằng cách dùng định danh môi trường.

Thực hiện nhiều tương tác

Trong ví dụ này, chúng ta minh họa cách thực hiện nhiều tương tác. Toàn bộ mã có trong tệp multiple_interactions.py từ kho mã.

# First interaction
inter1 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Write a Python script sum.py that adds all integers from 1 to 100.",
    environment="remote"
)

# Second interaction
inter2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    previous_interaction_id=inter1.id, # Passes the conversation history
    environment=inter1.environment_id, # Keeps the same filesystem state
    input="Execute 'sum.py' using Python and display the standard output."
)

# Output the status of the agent
print(f"Output:\n{inter2.output_text}")

Lưu ý rằng ở tương tác thứ hai, chúng ta đã thêm hai tham số:

• previous_interaction_id: Định danh của tương tác trước đó, để agent biết lịch sử hội thoại.

• environment: Định danh môi trường để agent biết cần thực thi trong sandbox nào.

Chia sẻ tệp với Agent

Chúng ta không thể xây dựng agent phân tích dữ liệu nếu không thể cấp quyền truy cập dữ liệu cho agent. Có một vài cách để chia sẻ dữ liệu với agent:

• Dữ liệu inline: Nạp nội dung tệp vào một chuỗi và gửi cùng với tương tác.
• Tệp được lưu trữ: Lưu trữ dữ liệu tại URL công khai và cung cấp URL để agent tải xuống.
• Kho GitHub: Cung cấp URL kho GitHub công khai cho agent.
• Google Cloud Bucket: Lưu trữ tệp trong Google Cloud Storage bucket và cấu hình dự án để agent có quyền truy cập bucket đó.

Chúng ta sẽ không đi sâu vào mọi giải pháp trong bài viết này. Chúng ta sẽ minh họa cách gửi dữ liệu inline bằng cách nạp tệp cục bộ vào chuỗi và cách chia sẻ kho GitHub. Cách đầu tiên phù hợp để chia sẻ tệp nhỏ cục bộ (tối đa 1 MB mỗi tệp, với tổng giới hạn 2 MB cho tất cả tệp), trong khi cách sau phù hợp hơn để chia sẻ tệp lớn, như các bộ dữ liệu.

Chia sẻ dữ liệu inline

Ví dụ về cách cung cấp dữ liệu inline (toàn bộ mã trong inline_example.py):

inter = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Add all the numbers in the /workspace/numbers.txt file.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                # The file where to store the data in the agent environment
                "target": "/workspace/numbers.txt",
                # Assumes that the file data/numbers.txt exists
                "content": utils.read_text_file("data/numbers.txt")
            }
        ]
    }
)

Dữ liệu được cung cấp thông qua tham số sources trong cấu hình environment. target xác định vị trí lưu dữ liệu trong môi trường của agent. Tệp nên được đặt trong thư mục workspace. Ở đây sẽ là tệp tên number.txt. 

Tham số content cung cấp nội dung tệp. Với nguồn inline, đó đơn giản là một chuỗi, trong trường hợp này chúng ta đọc bằng hàm read_text_file() trong tệp utils.py.

Chia sẻ kho GitHub

Để chia sẻ tệp lớn hơn, chúng ta có thể cung cấp URL kho GitHub. Cách thực hiện như sau:

inter = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Add all the numbers in the /workspace/repository/numbers.txt file.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/fran-aubry/gemini-agents-tutorial",
                "target": "/workspace/repository"
            }
        ]
    }
)

Trong ví dụ trên, kho có URL https://github.com/fran-aubry/gemini-agents-tutorial được clone vào một thư mục tên repository, bên trong workspace của agent.

Tải xuống môi trường của Agent

Chúng ta đã biết cách tương tác với managed agents và cách cung cấp tệp cho các agent này. Để tạo agent phân tích dữ liệu, điều cuối cùng cần học là cách tải xuống môi trường của agent. Điều này cần thiết để chúng ta có thể truy cập biểu đồ và kết quả do agent tạo ra.

Mỗi workspace có thể được tải xuống tại URL:

https://generativelanguage.googleapis.com/v1beta/files/environment-<env_id>:download

Trong đó <env_id> cần được thay bằng định danh của môi trường chúng ta muốn tải về.

Dưới đây là hàm Python dùng gói requests để tải một gói (hàm này là một phần của tệp utils.py mà chúng ta đã tạo):

def download_env(env_id, path="environments"):
    download_url = f"https://generativelanguage.googleapis.com/v1beta/files/environment-{env_id}:download"
    try:
        request_params = {"alt": "media"}  # Retrieves raw media binary
        request_headers = {"x-goog-api-key": os.environ.get("GEMINI_API_KEY")}
        # Download the environment
        print(f"Downloading environment: {env_id}")
        response = requests.get(
            download_url,
            params=request_params,
            headers=request_headers,
            allow_redirects=True
        )
        response.raise_for_status()
        # Save the compressed workspace archive locally
        archive_name = f"{env_id}.tar"
        output_path = os.path.join(path, archive_name)
        with open(output_path, "wb") as archive_file:
            archive_file.write(response.content)
        print(f"Successfully downloaded workspace snapshot archive: {output_path}")     
    except requests.exceptions.RequestException as error:
        print(f"Failed to download sandbox workspace via HTTP request: {error}")
    except tarfile.TarError as archive_error:
        print(f"Failed to unpack download tarball: {archive_error}")

Xây dựng Agent phân tích dữ liệu

Trong phần này, chúng ta học cách tạo một agent thực hiện phân tích dữ liệu. Để kiểm thử agent, chúng ta sẽ dùng bộ dữ liệu Netflix này từ Kaggle, cũng được lưu trong thư mục data của kho mã.

Trong mọi ví dụ trước, chúng ta luôn tương tác với agent gốc: antigravity-preview-05-2026. Ở đây, trước hết chúng ta sẽ tạo một agent bằng hàm client.agents.create().

Tạo một agent

Cách tạo agent như sau:

agent = client.agents.create(
            id=”data-analyst”,
            base_agent="antigravity-preview-05-2026",
            base_environment={
                "type": "remote",
                "sources": [
                    {
                        "type": "inline", 
                        "target": ".agents/AGENTS.md", 
                        "content": read_text_file(".agents/AGENTS.md")
                    },
                    # Explicitly load the skill
                    {
                        "type": "inline", 
                        "target": ".agents/skills/csv-aggregator/SKILL.md", 
                        "content": read_text_file(".agents/skills/csv-aggregator/SKILL.md")
                    },	
                    {
                        "type": "repository",
                        "source": "https://github.com/fran-aubry/gemini-agents-tutorial",
                        "target": "/workspace/repository"
                    }
                ]
            }

Giải thích các tham số:

• id: Định nghĩa tên của agent, ở đây là data-analyst. Chúng ta sẽ dùng định danh này trong phương thức client.interactions.create() thay cho antigravity-preview-05-2026 mà ta dùng trước đó. 

• base_agent: Agent được dùng làm nền tảng. Điều này nghĩa là chúng ta xây dựng một agent dựa trên agent antigravity-preview-05-2026.

• base_environment: Như trước đây, phần này cho phép chúng ta cung cấp tệp cho agent. Chúng ta đã cung cấp hai tệp đặc biệt: .agents/AGENTS.md và .agents/skills/csv-aggregator/SKILL.md. Đây là nơi chúng ta định nghĩa hành vi của agent. Tệp AGENTS.md định nghĩa hành vi chung của agent, trong khi SKILL.md định nghĩa một kỹ năng cụ thể cho agent. Chúng ta cũng cung cấp cho agent kho mã để nó có quyền truy cập các tệp dữ liệu cần phân tích.

Tìm hiểu AGENTS.md

Tệp này có thể được coi như một system prompt. Nó hoạt động như sổ tay hướng dẫn chính cho agent. Chúng ta nên dùng nó để xác định rõ vai trò cụ thể của agent, các mục tiêu chính và những giới hạn cần tuân thủ khi làm việc. 

Đây cũng là nơi tốt nhất để liệt kê mọi công cụ hoặc nguồn dữ liệu cụ thể mà agent được phép truy cập, và đưa ra ví dụ về cách chúng ta muốn nó giao tiếp hoặc xử lý nhiệm vụ. 

Bằng cách giữ hướng dẫn đơn giản và có tổ chức trong tệp này, chúng ta giúp agent hiểu chính xác cách hành xử và kết quả kỳ vọng.

Vị trí của tệp trong môi trường của agent nên là .agents/AGENTS.md.

Tìm hiểu SKILL.md

Các tệp kỹ năng được dùng để trang bị cho agent những kỹ năng cụ thể. Một agent có thể có nhiều kỹ năng, và mỗi kỹ năng nên được mô tả trong tệp SKILL.md đặt tại .agents/skills/<skill_name>/SKILL.md, thay <skill_name> bằng tên kỹ năng.

Cấu trúc của một tệp kỹ năng nên như sau:

---
name: <skill_name>
description: <description of when to use the skill>
---
<steps on how to perform the task>

Để minh họa, chúng ta trang bị cho agent data-analyst kỹ năng tên csv-aggregator được định nghĩa tại đây. Kỹ năng này dùng khi chúng ta muốn nhóm các hàng trong tệp CSV theo một cột và cộng dồn một cột khác. 

Trong trường hợp bộ dữ liệu Netflix, nếu muốn biết thể loại chương trình có lượt xem nhiều nhất, chúng ta muốn nhóm theo cột Genre và cộng các giá trị trong cột Viewership. Tệp kỹ năng này giải thích cho agent cách thực hiện nhiệm vụ đó.

Nạp agent

Vì agent là đối tượng tồn tại bền vững, nếu thử chạy việc tạo agent hai lần, chúng ta sẽ gặp lỗi. Do đó, chúng ta đã tạo hàm load_or_create_agent() trong tệp utils.py. Hàm này sẽ cố gắng tạo agent và, nếu đã tồn tại, sẽ nạp nó bằng hàm client.agents.load().

Ghép lại tất cả

Giờ đây chúng ta đã có agent phân tích dữ liệu, hãy kiểm thử bằng cách yêu cầu nó phân tích các thể loại trên Netflix. 

Chúng ta bắt đầu như trước bằng cách import thư viện, nạp API key và khởi tạo client:

from dotenv import load_dotenv
from google import genai
import utils

load_dotenv()
client = genai.Client()

Sau đó, chúng ta tạo (hoặc nạp nếu không phải lần đầu chạy script) agent data-analyst bằng hàm utils.load_or_create_agent():

data_analyst = utils.load_or_create_agent(client, "data-analyst")
print(f"Agent '{data_analyst.id}' initialized.")

Tiếp theo, chúng ta có thể tương tác với agent như trước. Khác biệt duy nhất là ở tham số agent, chúng ta cung cấp agent của mình thay vì antigravity-preview-05-2026.

Bắt đầu bằng cách yêu cầu agent cài gói matplotlib:

inter1 = client.interactions.create(
    agent=data_analyst.id,
    input="Install the matplotlib package.",
    environment="remote"
)

Lưu ý rằng vì môi trường đã được cấu hình ở cấp độ agent, chúng ta không cần cung cấp tệp nữa, nên chỉ cần truyền chuỗi ”remote”.

Tiếp theo, yêu cầu agent dùng công cụ csv-aggregator để phân tích dữ liệu Netflix theo thể loại nhằm xem những thể loại được xem nhiều nhất:

inter2 = client.interactions.create(
    agent=data_analyst.id,
    input="Use the csv-aggregator to plot the top 10 genres from /workspace/repository/data/netflix.csv in terms of viewership",
    environment=inter1.environment_id
)

Lưu ý rằng chúng ta cung cấp định danh môi trường của tương tác trước để agent có thể tiếp tục làm việc dựa trên đó.

Cuối cùng, yêu cầu agent vẽ biểu đồ bằng cách thực thi script genres.py được tạo ở bước trước (tệp SKILL.md hướng dẫn agent tạo script này):

inter3 = client.interactions.create(
    agent=data_analyst.id,
    input="Execute the genres.py script using python.",
    environment=inter2.environment_id
)

Sau tương tác này, biểu đồ sẽ được tạo. Chúng ta có thể lấy về máy bằng cách tải xuống môi trường:

utils.download_env(inter3.environment_id)

Kết quả như sau:

Toàn bộ mã cho tương tác với agent có trong analyze_netflix_genres.py.

Kết luận

Khả năng tạo các agent phức tạp chỉ với một lệnh gọi API mà không cần phụ thuộc vào hạ tầng điện toán đám mây phức tạp để tạo sandbox là một sức mạnh lớn. Tính năng này giúp việc xây dựng các agent mạnh mẽ trở nên rất dễ dàng mà không phải lo lắng về môi trường thực thi.

Trong hướng dẫn này, chúng ta đã tìm hiểu những điều cơ bản về Gemini Managed Agents nhưng chưa tạo các agent thực sự phức tạp. Tôi khuyến khích bạn đào sâu hơn và tiếp tục xây dựng trên nền tảng này để rèn luyện kỹ năng.