Managed Agents di Gemini API: Tutorial Praktis

Berapa Biaya Managed Agents di Gemini API?

Ada banyak komponen yang terlibat dalam penetapan harga Gemini Managed Agents, sehingga sulit memberikan estimasi biaya yang presisi. Biaya ditentukan oleh empat faktor utama:

1. Penggunaan Model (Token): Kita dikenakan biaya berdasarkan jumlah token input dan output yang diproses oleh model Gemini yang mendasari. Perlu dicatat bahwa ini termasuk token yang dihasilkan dalam hasil perantara. Misalnya, jika agen membuat skrip Python untuk membangun laporan, token yang diperlukan untuk skrip tersebut juga ditagihkan.
2. Biaya Infrastruktur & Platform: Managed agents berjalan di lingkungan terintegrasi Google, yang melibatkan biaya layanan untuk menggunakan alat platform (seperti Vertex AI Agent Builder) guna mengelola dan menerapkan agen.
3. Context Caching: Jika agen sering menggunakan ulang data yang sama, managed agents dapat memanfaatkan context caching. Ini biasanya memberikan pengurangan biaya yang signifikan dibandingkan penetapan harga token standar.
4. Grounding: Jika agen menggunakan layanan ground Google seperti Google Search atau Google Maps, layanan ini ditagihkan terpisah, sering kali berdasarkan kuota permintaan gratis yang diikuti biaya per 1.000 kueri (biasanya sekitar $14/1.000 kueri). 

Dalam tutorial ini, kita akan membangun agen di atas agen antigravity-preview-05-2026 yang didukung oleh Gemini 3.5 Flash. Biaya token untuk Gemini 3.5 Flash adalah sebagai berikut:

Cara Membangun Managed Agents di Gemini API

Dalam panduan ini, kita akan membangun managed agent menggunakan Gemini API dan Python. Karena managed agents merupakan rilis terbaru yang saat ini masih beta, harap diingat bahwa beberapa detail implementasi dapat berubah.

Semua kode yang akan kita tulis dalam tutorial ini disimpan di repositori GitHub ini, yang juga akan kita gunakan untuk membagikan data kepada agen analis data.

Penyiapan API

Untuk membuat kunci AI, buka Google AI Studio dan klik “Create API Key” di kanan atas.

API key harus dikaitkan dengan proyek Google Cloud. Kita bisa memilih yang sudah ada atau membuat yang baru. Di sini, saya membuat satu bernama gemini-managed-agents.

Setelah membuat kunci, kita menyalinnya. Lalu kita membuat file bernama .env di folder tempat kita akan membuat agen dan menempelkannya dengan format berikut:

GEMINI_API_KEY=<paste_your_api_key_here>

Sebelum menutup Google AI Studio, kita perlu menyiapkan penagihan pada API key yang baru saja dibuat. Tanpa ini, permintaan kita akan ditolak karena Google tidak dapat menagih kita. Untuk menyiapkan penagihan, klik tombol “Set up billing”.

Penyiapan lingkungan Python

Kita akan menggunakan Anaconda untuk menyiapkan lingkungan Python untuk proyek ini. Untuk membuat environment menggunakan Anaconda, gunakan perintah:

conda create --name gemini_agents python=3.12 -y

Ini membuat environment bernama gemini_agents yang menggunakan Python versi 3.10. Parameter -y hanyalah pintasan untuk menjawab “ya” pada semua pertanyaan selama pembuatan environment.

Selanjutnya, kita perlu mengaktifkannya:

conda activate gemini_agents

Terakhir, kita perlu memasang dependensi yang diperlukan. Berikut caranya:

pip install google-genai requests python-dotenv

Membuat interaksi dasar dengan managed agent

Sekarang semuanya sudah siap untuk menjalankan agen pertama kita. Agen pertama ini tidak akan banyak melakukan hal. Ia hanya akan memasang matplotlib dan melaporkan versi yang terpasang.

Berikut penjelasan langkah demi langkah tentang cara kita dapat berinteraksi dengan managed agent (kode lengkap dapat ditemukan pada skrip simple_interaction.py di repositori):

Pertama, kita mengimpor paket yang diperlukan dan memuat API key dari file .env yang kita buat sebelumnya:

from dotenv import load_dotenv
from google import genai

# Load secure environment variables
load_dotenv()

Berikutnya, kita menginisialisasi klien Gemini dan membuat interaksi dengan agen dasar, yang saat ini bernama antigravity-preview-05-2026, dengan memintanya memasang 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"
)

Terakhir, kita mendapatkan keluaran dari agen dengan memeriksa properti status, environment_id, dan 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}")

Berikut hasilnya:

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

Status siklus hidup sandbox

Pada contoh di atas, kita menampilkan pengenal environment dari interaksi managed agent:

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

Nilai ini penting karena merepresentasikan pengenal environment tempat agen dijalankan. Interaksi agen disimpan di environment sementara yang dipertahankan hingga 7 hari setelah aktivitas terakhir sebelum dihapus.

Diagram di bawah mengilustrasikan siklus hidup sandbox tempat agen dieksekusi selama interaksi.

Selama environment belum dihapus, kita dapat mengaksesnya dan melakukan interaksi lanjutan dengan menggunakan pengenal environment.

Melakukan beberapa interaksi

Pada contoh ini, kita menunjukkan cara melakukan beberapa interaksi. Kode lengkap tersedia di berkas multiple_interactions.py dari repositori.

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

Perhatikan bahwa pada interaksi kedua, kita menambahkan dua parameter:

• previous_interaction_id: Pengenal interaksi sebelumnya, sehingga agen mengetahui riwayat percakapan.

• environment: Pengenal environment agar agen tahu di sandbox mana ia harus mengeksekusi.

Berbagi File Dengan Agen

Kita tidak dapat membangun agen analis data jika kita tidak dapat memberikan akses data kepada agen. Ada beberapa cara untuk membagikan data dengan agen:

• Data inline: Memuat konten file ke dalam string dan mengirimkannya saat interaksi.
• File terhosting: Menghosting data di URL publik dan memberikan URL untuk diunduh oleh agen.
• Repositori GitHub: Kita dapat memberikan URL repositori GitHub publik kepada agen.
• Google Cloud Bucket: Menghosting file di bucket Google Cloud Storage dan mengonfigurasi proyek agar agen memiliki akses ke bucket tersebut.

Kita tidak akan membahas semua solusi ini dalam artikel ini. Kita akan menunjukkan cara mengirim data inline dengan memuat file lokal ke dalam string dan berbagi repositori GitHub. Yang pertama ideal untuk berbagi file lokal kecil (hingga 1 MB per file, dengan batas total 2 MB untuk semua file), sedangkan yang kedua lebih cocok untuk berbagi file yang lebih besar, seperti dataset.

Berbagi data inline

Berikut contoh cara menyediakan data inline (kode lengkap di 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")
            }
        ]
    }
)

Data disediakan menggunakan parameter sources pada konfigurasi environment. target mendefinisikan lokasi tempat data akan disimpan di environment agen. File harus ditempatkan di folder workspace. Dalam hal ini, akan menjadi file bernama number.txt. 

Parameter content menyediakan konten file. Untuk sumber inline, ini hanyalah string, yang dalam kasus ini kita baca menggunakan fungsi read_text_file() di berkas utils.py.

Berbagi repositori GitHub

Untuk berbagi file yang lebih besar, kita dapat memberikan URL repositori GitHub. Berikut caranya:

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

Pada contoh di atas, repositori dengan URL https://github.com/fran-aubry/gemini-agents-tutorial dikloning ke folder bernama repository, di dalam workspace agen.

Mengunduh Environment Agen

Kita sudah mempelajari cara berinteraksi dengan managed agents dan cara menyediakan file kepada agen-agen ini. Untuk membuat agen analis data, hal terakhir yang perlu kita pelajari adalah cara mengunduh environment agen. Ini diperlukan agar kita dapat mengakses bagan dan hasil yang dihasilkan oleh agen.

Setiap workspace dapat diunduh pada URL:

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

Di mana <env_id> harus diganti dengan pengenal environment yang ingin kita unduh.

Berikut fungsi Python yang menggunakan paket requests untuk mengunduh paket (fungsi ini merupakan bagian dari berkas utils.py yang kita buat):

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

Membangun Agen Analis Data

Di bagian ini, kita mempelajari cara membuat agen yang melakukan analisis data. Untuk menguji agen, kita akan menggunakan dataset Netflix ini dari Kaggle, yang juga disimpan di folder data pada repositori kami.

Di semua contoh sebelumnya, kita selalu berinteraksi dengan agen dasar: antigravity-preview-05-2026. Di sini kita akan terlebih dahulu membuat agen menggunakan fungsi client.agents.create().

Membuat agen

Berikut cara kita dapat membuat agen:

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

Mari kita uraikan setiap parameternya:

• id: Ini mendefinisikan nama agen, dalam hal ini data-analyst. Kita akan menggunakan pengenal ini pada metode client.interactions.create() alih-alih antigravity-preview-05-2026 yang sejauh ini kita gunakan. 

• base_agent: Agen yang digunakan sebagai dasar. Artinya, kita membangun agen di atas agen antigravity-preview-05-2026.

• base_environment: Seperti sebelumnya, ini memungkinkan kita menyediakan file kepada agen. Kita menyediakan dua berkas khusus: .agents/AGENTS.md dan .agents/skills/csv-aggregator/SKILL.md. Berkas-berkas ini adalah tempat kita mendefinisikan perilaku agen. Berkas AGENTS.md mendefinisikan perilaku umum agen, sementara SKILL.md mendefinisikan keterampilan tertentu untuk agen. Kita juga menyediakan repositori kepada agen agar ia memiliki akses ke berkas data yang ingin kita analisis.

Memahami AGENTS.md

Berkas ini dapat dianggap sebagai system prompt. Ia bertindak sebagai buku petunjuk utama untuk agen. Kita harus menggunakannya untuk mendefinisikan dengan jelas peran spesifik agen, tujuan utamanya, dan batasan yang perlu dipatuhi saat bekerja. 

Ini juga tempat terbaik bagi kita untuk mencantumkan alat atau sumber data spesifik yang boleh diakses agen serta memberikan contoh cara kita ingin ia berkomunikasi atau menangani tugas. 

Dengan menjaga instruksi tetap sederhana dan tertata rapi dalam berkas, kita membantu agen memahami dengan tepat bagaimana harus bertindak dan hasil seperti apa yang kita harapkan.

Lokasi berkas di environment agen harus .agents/AGENTS.md.

Memahami SKILL.md

Berkas skill digunakan untuk membekali agen dengan keterampilan spesifik. Satu agen dapat memiliki banyak keterampilan, dan masing-masing harus dijelaskan dalam berkas SKILL.md yang berlokasi di .agents/skills/<skill_name>/SKILL.md, mengganti <skill_name> dengan nama keterampilan.

Struktur berkas skill sebaiknya:

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

Untuk mencontohkannya, kita membekali agen data-analyst dengan keterampilan bernama csv-aggregator yang didefinisikan di sini. Keterampilan ini digunakan saat kita ingin mengelompokkan baris CSV berdasarkan suatu kolom sambil menjumlahkan kolom lain. 

Dalam kasus dataset Netflix, jika kita ingin mengetahui genre tayangan dengan jumlah penonton terbanyak, kita ingin mengelompokkan baris berdasarkan Genre dan menjumlahkan nilai di kolom Viewership. Berkas skill ini menjelaskan kepada agen cara melakukan tugas tersebut.

Memuat agen

Karena agen bersifat persisten, jika kita mencoba menjalankan pembuatan agen dua kali, kita akan mendapat error. Karena itu, kita membuat fungsi load_or_create_agent() di berkas utils.py. Fungsi ini akan mencoba membuat agen dan, jika sudah ada, memuatnya menggunakan fungsi client.agents.load().

Menggabungkan semuanya

Sekarang kita memiliki agen analis data, saatnya mengujinya dengan memintanya menganalisis genre Netflix. 

Kita mulai seperti sebelumnya dengan mengimpor pustaka, memuat API key, dan menginisialisasi klien:

from dotenv import load_dotenv
from google import genai
import utils

load_dotenv()
client = genai.Client()

Lalu kita membuat (atau memuat, jika ini bukan pertama kalinya kita menjalankan skrip) agen data-analyst menggunakan fungsi utils.load_or_create_agent():

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

Kemudian kita dapat berinteraksi dengan agen dengan cara yang sama seperti sebelumnya. Satu-satunya perbedaan adalah pada parameter agent, kini kita memberikan agen milik kita, bukan antigravity-preview-05-2026.

Kita mulai dengan meminta agen memasang paket matplotlib:

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

Perhatikan bahwa karena environment sudah dikonfigurasi pada level agen, kita tidak perlu lagi menyediakan berkas, jadi kita cukup memberikan string ”remote”.

Berikutnya, kita memintanya menggunakan alat csv-aggregator untuk menganalisis data Netflix menurut genre guna melihat genre yang paling banyak ditonton:

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
)

Perhatikan bahwa kita memberikan pengenal environment dari interaksi sebelumnya agar agen dapat melanjutkan pekerjaan di atasnya.

Terakhir, kita meminta agen untuk membuat plot data dengan mengeksekusi skrip genres.py yang dibuat pada langkah sebelumnya (berkas SKILL.md menginstruksikan agen untuk membuat skrip ini):

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

Setelah interaksi ini, plot seharusnya sudah dibuat. Kita bisa mendapatkannya secara lokal dengan mengunduh environment:

utils.download_env(inter3.environment_id)

Berikut hasilnya:

Kode lengkap interaksi agen dapat ditemukan di analyze_netflix_genres.py.

Kesimpulan

Kemampuan untuk membuat agen kompleks dengan satu panggilan API tanpa harus bergantung pada infrastruktur komputasi cloud yang rumit untuk membuat sandbox sangatlah kuat. Kemampuan ini membuat sangat mudah untuk membuat agen yang andal tanpa harus mengkhawatirkan environment tempat agen-agen ini dijalankan.

Dalam tutorial ini, kita membahas dasar-dasar Gemini Managed Agents namun belum membuat agen yang benar-benar kompleks. Saya mendorong Anda untuk mengeksplorasi lebih lanjut dan terus membangun di atas fondasi ini untuk mengasah keterampilan Anda.