Managed Agents ใน Gemini API: คู่มือเวิร์กช็อปลงมือทำ

Managed Agents ใน Gemini API มีค่าใช้จ่ายเท่าไร?

โครงสร้างราคาของ Gemini Managed Agents มีหลายองค์ประกอบ ทำให้ประเมินค่าใช้จ่ายได้ยากอย่างแม่นยำ ต้นทุนหลักมาจาก 4 ปัจจัย:

1. การใช้โมเดล (โทเคน): มีการคิดค่าบริการตามจำนวนโทเคนขาเข้าและขาออกที่ประมวลผลโดยโมเดล Gemini ใต้ระบบ โปรดทราบว่ารวมโทเคนที่เกิดในการคำนวณระหว่างกลางด้วย เช่น หากเอเจนต์สร้างสคริปต์ Python เพื่อสร้างรายงาน โทเคนสำหรับสคริปต์นั้นก็ถูกคิดค่าบริการเช่นกัน
2. ค่าธรรมเนียมโครงสร้างพื้นฐานและแพลตฟอร์ม: Managed agents ทำงานภายในสภาพแวดล้อมแบบบูรณาการของ Google ซึ่งมีค่าบริการสำหรับเครื่องมือแพลตฟอร์ม (เช่น Vertex AI Agent Builder) ที่ใช้จัดการและปรับใช้อีเจนต์
3. Context Caching: หากเอเจนต์ใช้ข้อมูลเดิมซ้ำบ่อย Managed agents สามารถใช้ context caching ซึ่งมักช่วยลดค่าใช้จ่ายได้มากเมื่อเทียบกับราคาตามโทเคนแบบมาตรฐาน
4. Grounding: หากเอเจนต์ใช้บริการยึดโยงข้อมูลของ Google เช่น Google Search หรือ Google Maps จะมีการคิดค่าบริการแยก โดยมักมีโควตาฟรีจำนวนหนึ่งและคิดค่าบริการต่อ 1,000 คำค้น (โดยทั่วไปประมาณ $14/1,000 คำค้น) 

ในบทเรียนนี้ เราจะสร้างเอเจนต์บนเอเจนต์ antigravity-preview-05-2026 ซึ่งขับเคลื่อนd โดย Gemini 3.5 Flash โดยค่าโทเคนของ Gemini 3.5 Flash มีดังนี้:

วิธีสร้าง Managed Agents ใน Gemini API

ในคู่มือนี้ เราจะสร้าง managed agent โดยใช้ Gemini API และ Python เนื่องจาก managed agents เพิ่งเปิดตัวและยังอยู่ในช่วงเบตา โปรดทราบว่ารายละเอียดการใช้งานบางอย่างอาจเปลี่ยนแปลงได้

โค้ดทั้งหมดในบทเรียนนี้อยู่ที่ GitHub repository นี้ ซึ่งเราจะใช้แชร์ข้อมูลกับเอเจนต์นักวิเคราะห์ข้อมูลด้วย

การตั้งค่า API

เพื่อสร้างคีย์ AI ให้ไปที่ Google AI Studio แล้วคลิก “Create API Key” ที่มุมขวาบน

API key ต้องผูกกับโปรเจ็กต์ Google Cloud สามารถเลือกโปรเจ็กต์ที่มีอยู่หรือสร้างใหม่ ที่นี่ได้สร้างโปรเจ็กต์ชื่อ gemini-managed-agents

หลังจากสร้างคีย์แล้ว ให้คัดลอก จากนั้นสร้างไฟล์ชื่อ .env ในโฟลเดอร์ที่เราจะสร้างเอเจนต์ และวางลงไปในรูปแบบต่อไปนี้:

GEMINI_API_KEY=<paste_your_api_key_here>

ก่อนปิด Google AI Studio ต้องตั้งค่าการเรียกเก็บเงินให้กับ API key ที่เพิ่งสร้าง มิฉะนั้นคำขอจะถูกปฏิเสธเพราะ Google ไม่สามารถเรียกเก็บเงินได้ ตั้งค่าการเรียกเก็บเงินได้โดยคลิกปุ่ม “Set up billing”

การตั้งค่าสภาพแวดล้อม Python

เราจะใช้ Anaconda เพื่อตั้งค่าสภาพแวดล้อม Python สำหรับโปรเจ็กต์นี้ ในการสร้างสภาพแวดล้อมด้วย Anaconda ใช้คำสั่ง:

conda create --name gemini_agents python=3.12 -y

คำสั่งนี้จะสร้างสภาพแวดล้อมชื่อ gemini_agents ที่ใช้ Python เวอร์ชัน 3.10 พารามิเตอร์ -y เป็นทางลัดในการตอบ “yes” ให้กับทุกคำถามระหว่างการสร้างสภาพแวดล้อม

จากนั้นต้องเปิดใช้งานสภาพแวดล้อม:

conda activate gemini_agents

สุดท้าย ติดตั้งแพ็กเกจที่จำเป็น ดังนี้:

pip install google-genai requests python-dotenv

สร้างปฏิสัมพันธ์พื้นฐานกับ managed agent

ตอนนี้ทุกอย่างพร้อมสำหรับการรันเอเจนต์ตัวแรก เอเจนต์ตัวนี้จะทำงานไม่มาก เพียงติดตั้ง matplotlib และรายงานเวอร์ชันที่ติดตั้ง

ต่อไปนี้คือคำอธิบายทีละขั้นตอนว่าจะโต้ตอบกับ managed agent ได้อย่างไร (ดูโค้ดเต็มในสคริปต์ simple_interaction.py ใน repository):

เริ่มจากนำเข้าแพ็กเกจที่จำเป็นและโหลด API key จากไฟล์ .env ที่สร้างไว้ก่อนหน้า:

from dotenv import load_dotenv
from google import genai

# Load secure environment variables
load_dotenv()

ถัดไป เริ่มต้นใช้งานไคลเอนต์ Gemini และสร้างปฏิสัมพันธ์กับเอเจนต์พื้นฐานซึ่งขณะนี้ชื่อ antigravity-preview-05-2026 โดยขอให้ติดตั้ง 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"
)

สุดท้าย อ่านผลลัพธ์จากเอเจนต์โดยตรวจดูพรอพเพอร์ตี status, environment_id และ 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}")

ผลลัพธ์จะเป็นดังนี้:

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

สถานะวงจรชีวิตของ Sandbox

ในตัวอย่างด้านบน เราแสดงตัวระบุสภาพแวดล้อมของปฏิสัมพันธ์กับ managed agent:

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

ค่านี้สำคัญเพราะเป็นตัวระบุสภาพแวดล้อมที่เอเจนต์ถูกรัน ปฏิสัมพันธ์ของเอเจนต์จะถูกเก็บไว้ในสภาพแวดล้อมชั่วคราว ซึ่งจะถูกเก็บไว้ได้นานสูงสุด 7 วันหลังการใช้งานครั้งสุดท้ายก่อนลบ

ไดอะแกรมด้านล่างแสดงวงจรชีวิตของ sandbox ที่ใช้รันเอเจนต์ระหว่างปฏิสัมพันธ์

ตราบใดที่สภาพแวดล้อมยังไม่ถูกลบ เราสามารถเข้าถึงและทำปฏิสัมพันธ์เพิ่มเติมได้โดยใช้ตัวระบุสภาพแวดล้อม

ทำปฏิสัมพันธ์หลายครั้ง

ตัวอย่างนี้แสดงวิธีทำปฏิสัมพันธ์หลายครั้ง โค้ดเต็มอยู่ในไฟล์ multiple_interactions.py จากโครงการ

# 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}")

สังเกตว่าในการโต้ตอบครั้งที่สอง เราเพิ่มพารามิเตอร์สองตัวคือ:

• previous_interaction_id: ตัวระบุของปฏิสัมพันธ์ก่อนหน้า เพื่อให้เอเจนต์รับรู้ประวัติการสนทนา

• environment: ตัวระบุสภาพแวดล้อมเพื่อบอกเอเจนต์ว่าจะต้องรันใน sandbox ใด

การแชร์ไฟล์กับเอเจนต์

เราไม่อาจสร้างเอเจนต์นักวิเคราะห์ข้อมูลได้ หากไม่สามารถให้เอเจนต์เข้าถึงข้อมูล วิธีการแชร์ข้อมูลกับเอเจนต์มีหลายแบบ:

• Inline data: โหลดเนื้อหาไฟล์เป็นสตริงและส่งระหว่างปฏิสัมพันธ์
• Hosted file:โฮสต์ข้อมูลไว้ที่ URL สาธารณะแล้วให้ URL แก่เอเจนต์เพื่อดาวน์โหลด
• GitHub repository: ให้ URL ของ GitHub repository แบบสาธารณะแก่เอเจนต์
• Google Cloud Bucket: โฮสต์ไฟล์ใน Google Cloud Storage bucket และกำหนดค่าโปรเจ็กต์เพื่อให้เอเจนต์เข้าถึง bucket นั้นได้

ในบทความนี้จะไม่เจาะทุกรูปแบบ เราจะแสดงวิธีส่ง inline data โดยโหลดไฟล์โลคอลเป็นสตริง และการแชร์ GitHub repository วิธีแรกเหมาะกับไฟล์ขนาดเล็ก (สูงสุด 1 MB ต่อไฟล์ และรวมทุกไฟล์ไม่เกิน 2 MB) ส่วนวิธีหลังเหมาะกับไฟล์ขนาดใหญ่ เช่น ชุดข้อมูล

การแชร์ inline data

ตัวอย่างการให้ inline data (โค้ดเต็มใน 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")
            }
        ]
    }
)

ให้ข้อมูลผ่านพารามิเตอร์ sources ในคอนฟิก environment โดย target คือที่อยู่ที่จะเก็บข้อมูลในสภาพแวดล้อมของเอเจนต์ ไฟล์ควรอยู่ในโฟลเดอร์ workspace ในที่นี้จะเป็นไฟล์ชื่อ number.txt 

พารามิเตอร์ content คือเนื้อหาไฟล์ สำหรับแหล่งข้อมูลแบบ inline จะเป็นเพียงสตริง ซึ่งในตัวอย่างนี้อ่านด้วยฟังก์ชัน read_text_file() ในไฟล์ utils.py

การแชร์ GitHub repository

สำหรับไฟล์ขนาดใหญ่ขึ้น สามารถให้ URL ของ GitHub repository ได้ ดังนี้:

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"
            }
        ]
    }
)

ในตัวอย่างข้างต้น repository ที่ URL https://github.com/fran-aubry/gemini-agents-tutorial จะถูกโคลนไปยังโฟลเดอร์ชื่อ repository ภายในพื้นที่ทำงานของเอเจนต์

การดาวน์โหลดสภาพแวดล้อมของเอเจนต์

เราได้เรียนรู้แล้วว่าจะโต้ตอบกับ managed agents อย่างไรและจะให้ไฟล์แก่เอเจนต์อย่างไร ในการสร้างเอเจนต์นักวิเคราะห์ข้อมูล สิ่งสุดท้ายที่ต้องรู้คือวิธีดาวน์โหลดสภาพแวดล้อมของเอเจนต์ เพื่อให้เข้าถึงกราฟและผลลัพธ์ที่เอเจนต์สร้างขึ้นได้

พื้นที่ทำงานแต่ละอันสามารถดาวน์โหลดได้ที่ URL:

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

โดยให้แทนที่ <env_id> ด้วยตัวระบุของสภาพแวดล้อมที่ต้องการดาวน์โหลด

นี่คือตัวอย่างฟังก์ชัน Python ที่ใช้แพ็กเกจ requests เพื่อดาวน์โหลดแพ็กเกจ (ฟังก์ชันนี้เป็นส่วนหนึ่งของไฟล์ utils.py ที่สร้างไว้):

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}")

สร้างเอเจนต์นักวิเคราะห์ข้อมูล

ในส่วนนี้ เราจะสร้างเอเจนต์ที่ทำการวิเคราะห์ข้อมูล เพื่อลองเอเจนต์ เราจะใช้ ชุดข้อมูล Netflix นี้ จาก Kaggle ซึ่งถูกเก็บในโฟลเดอร์ data ของ repository ด้วย

ในทุกตัวอย่างก่อนหน้านี้ เราโต้ตอบกับเอเจนต์พื้นฐาน antigravity-preview-05-2026 เสมอ ที่นี่เราจะสร้างเอเจนต์โดยใช้ฟังก์ชัน client.agents.create() ก่อน

การสร้างเอเจนต์

วิธีสร้างเอเจนต์มีดังนี้:

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"
                    }
                ]
            }

อธิบายพารามิเตอร์แต่ละตัว:

• id: ชื่อเอเจนต์ ซึ่งในที่นี้คือ data-analyst เราจะใช้ตัวระบุนี้ในเมธอด client.interactions.create() แทน antigravity-preview-05-2026 ที่ใช้มาก่อนหน้านี้ 

• base_agent: เอเจนต์ที่จะใช้เป็นฐาน หมายถึงเรากำลังกำหนดเอเจนต์ทับบนเอเจนต์ antigravity-preview-05-2026

• base_environment: เช่นเดียวกับก่อนหน้า ใช้เพื่อให้ไฟล์แก่เอเจนต์ เราให้ไฟล์พิเศษสองไฟล์คือ .agents/AGENTS.md และ .agents/skills/csv-aggregator/SKILL.md ซึ่งเป็นที่ที่เรากำหนดพฤติกรรมของเอเจนต์ ไฟล์ AGENTS.md กำหนดพฤติกรรมทั่วไปของเอเจนต์ ขณะที่ SKILL.md กำหนดสกิลเฉพาะอย่างหนึ่งให้เอเจนต์ นอกจากนี้ เรายังให้ repository แก่เอเจนต์เพื่อให้เข้าถึงไฟล์ข้อมูลที่จะวิเคราะห์ได้

ทำความเข้าใจ AGENTS.md

ไฟล์นี้มองได้ว่าเป็น system prompt ทำหน้าที่เป็นคู่มือหลักสำหรับเอเจนต์ ควรใช้เพื่อกำหนดบทบาทเฉพาะ เป้าหมายหลัก และกรอบขอบเขตที่เอเจนต์ต้องปฏิบัติตามอย่างชัดเจน 

ยังเป็นที่ที่เหมาะสำหรับระบุเครื่องมือหรือแหล่งข้อมูลที่เอเจนต์ได้รับอนุญาตให้ใช้ และยกตัวอย่างวิธีการสื่อสารหรือจัดการงานที่ต้องการ 

เมื่อเก็บคำแนะนำให้เรียบง่ายและจัดระเบียบดีในไฟล์นี้ จะช่วยให้เอเจนต์เข้าใจวิธีปฏิบัติตัวและผลลัพธ์ที่คาดหวังได้ชัดเจน

ตำแหน่งไฟล์ในสภาพแวดล้อมของเอเจนต์ควรเป็น .agents/AGENTS.md

ทำความเข้าใจ SKILL.md

ไฟล์ skill ใช้ติดตั้งความสามารถเฉพาะให้เอเจนต์ เอเจนต์หนึ่งตัวมีได้หลายสกิล แต่ละสกิลควรถูกอธิบายในไฟล์ SKILL.md ที่อยู่ใน .agents/skills/<skill_name>/SKILL.md โดยแทนที่ <skill_name> ด้วยชื่อสกิล

โครงสร้างของไฟล์สกิลควรเป็น:

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

เพื่อเป็นตัวอย่าง เราได้ติดตั้งสกิลชื่อ csv-aggregator ให้เอเจนต์ data-analyst ตามที่กำหนดไว้ ที่นี่ สกิลนี้ใช้เมื่อเราต้องการจัดกลุ่มแถวในไฟล์ CSV ตามคอลัมน์หนึ่งๆ พร้อมกับบวกค่าในอีกคอลัมน์หนึ่ง 

สำหรับชุดข้อมูล Netflix หากอยากรู้ว่าแนวรายการใดมีผู้ชมมากที่สุด เราจะจัดกลุ่มตามคอลัมน์ Genre และบวกค่าจากคอลัมน์ Viewership ไฟล์สกิลนี้อธิบายกับเอเจนต์ว่าจะทำงานนี้อย่างไร

การโหลดเอเจนต์

เนื่องจากเอเจนต์มีความคงอยู่ หากพยายามสร้างเอเจนต์ซ้ำจะเกิดข้อผิดพลาด ด้วยเหตุนี้ เราจึงสร้างฟังก์ชัน load_or_create_agent() ในไฟล์ utils.py ฟังก์ชันนี้จะพยายามสร้างเอเจนต์ และหากมีอยู่แล้วจะโหลดแทนด้วยฟังก์ชัน client.agents.load()

รวมทุกอย่างเข้าด้วยกัน

ตอนนี้เรามีเอเจนต์นักวิเคราะห์ข้อมูลแล้ว ถึงเวลาทดสอบด้วยการให้วิเคราะห์แนวรายการของ Netflix 

เริ่มต้นเช่นเดิมด้วยการนำเข้าไลบรารี โหลด API key และเริ่มต้นไคลเอนต์:

from dotenv import load_dotenv
from google import genai
import utils

load_dotenv()
client = genai.Client()

จากนั้นสร้าง (หรือโหลด หากไม่ใช่ครั้งแรกที่รันสคริปต์) เอเจนต์ data-analyst ด้วยฟังก์ชัน utils.load_or_create_agent():

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

จากนั้นโต้ตอบกับเอเจนต์เช่นเดิม ความแตกต่างเพียงอย่างเดียวคือในพารามิเตอร์ agent ตอนนี้เราส่งเอเจนต์ของเราแทน antigravity-preview-05-2026

เริ่มด้วยการให้เอเจนต์ติดตั้งแพ็กเกจ matplotlib:

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

สังเกตว่าเนื่องจากสภาพแวดล้อมถูกกำหนดไว้ที่ระดับเอเจนต์แล้ว เราไม่ต้องส่งไฟล์อีก จึงระบุเพียงสตริง ”remote”

ถัดไป ขอให้ใช้เครื่องมือ csv-aggregator เพื่อวิเคราะห์ข้อมูล Netflix ตามแนวรายการ เพื่อดูว่าแนวใดมีผู้ชมมากที่สุด:

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
)

โปรดสังเกตว่าเราให้ตัวระบุสภาพแวดล้อมของปฏิสัมพันธ์ก่อนหน้า เพื่อให้เอเจนต์ทำงานต่อบนสภาพแวดล้อมเดิม

สุดท้าย ให้เอเจนต์วาดกราฟด้วยการรันสคริปต์ genres.py ที่สร้างขึ้นในขั้นตอนก่อนหน้า (ไฟล์ SKILL.md ระบุให้เอเจนต์สร้างสคริปต์นี้):

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

หลังจากปฏิสัมพันธ์นี้ กราฟควรถูกสร้างขึ้นแล้ว สามารถดาวน์โหลดสภาพแวดล้อมมาไว้ในเครื่องได้ดังนี้:

utils.download_env(inter3.environment_id)

ผลลัพธ์เป็นดังนี้:

ดูโค้ดเต็มของปฏิสัมพันธ์กับเอเจนต์ได้ที่ analyze_netflix_genres.py

สรุป

ความสามารถในการสร้างเอเจนต์ที่ซับซ้อนได้ด้วยการเรียก API เพียงครั้งเดียว โดยไม่ต้องพึ่งโครงสร้างพื้นฐานคลาวด์ที่ซับซ้อนในการสร้าง sandbox นั้นทรงพลังมาก สิ่งนี้ทำให้สร้างเอเจนต์ที่มีขีดความสามารถสูงได้อย่างง่ายดาย โดยไม่ต้องกังวลเกี่ยวกับสภาพแวดล้อมที่เอเจนต์ถูกรัน

ในบทเรียนนี้ เราครอบคลุมพื้นฐานของ Gemini Managed Agents แต่ยังไม่ได้สร้างเอเจนต์ที่ซับซ้อนจริงๆ ขอแนะนำให้ลองต่อยอด สำรวจเพิ่มเติม และพัฒนาบนรากฐานนี้เพื่อเพิ่มพูนทักษะ