Gemini API’de Yönetilen Aracılar: Uygulamalı Bir Eğitim

Gemini API’de Yönetilen Aracıların Maliyeti Ne Kadar?

Gemini Yönetilen Aracılar’ın fiyatlandırmasında birçok bileşen yer alır; bu da kesin maliyet tahminleri vermeyi zorlaştırır. Maliyet dört ana faktörden etkilenir:

1. Model Kullanımı (Token’lar): Altta yatan Gemini modelinin işlediği girdi ve çıktı token sayısına göre ücretlendiriliriz. Bunların, ara sonuçlarda üretilen token’ları da içerdiğini unutmayın. Örneğin, aracı bir rapor oluşturmak için bir Python betiği üretirse, o betik için gereken token’lar da faturalandırılır.
2. Altyapı ve Platform Ücretleri: Yönetilen aracılar, aracıları yönetmek ve dağıtmak için Vertex AI Agent Builder gibi platform araçlarını kullanmayı içeren Google’ın entegre ortamında çalışır; bu da hizmet ücretlerini kapsar.
3. Bağlam Ön Bellekleme: Aracılar aynı verileri sık sık yeniden kullanıyorsa, yönetilen aracılar bağlam önbelleklemeden yararlanabilir. Bu genellikle standart token fiyatlandırmasına kıyasla önemli bir maliyet düşüşü sağlar.
4. Temellendirme: Aracı, Google Search veya Google Maps gibi Google temellendirme hizmetlerini kullanıyorsa, bunlar ayrı faturalandırılır; genellikle belirli bir ücretsiz istek kotasının ardından 1.000 sorgu başına bir maliyetle (tipik olarak 1.000 sorgu için yaklaşık 14 $) ücretlendirilir. 

Bu eğitimde, antigravity-preview-05-2026 aracısı üzerine inşa edilecek ve Gemini 3.5 Flash tarafından desteklenecek bir aracı oluşturacağız. Gemini 3.5 Flash’ın token maliyetleri şunlardır:

Gemini API’de Yönetilen Aracılar Nasıl Oluşturulur

Bu kılavuzda, Gemini API ve Python kullanarak bir yönetilen aracı oluşturacağız. Yönetilen aracılar hâlihazırda beta aşamasında yeni bir sürüm olduğundan, bazı uygulama ayrıntılarının değişebileceğini unutmayın.

Bu eğitimde yazacağımız tüm kodlar bu GitHub deposunda saklanır; veri analisti aracısıyla veri paylaşmak için de bunu kullanacağız.

API kurulumu

Bir AI anahtarı oluşturmak için Google AI Studio’ya gidin ve sağ üstteki “Create API Key” seçeneğine tıklayın.

API anahtarlarının bir Google Cloud projesiyle ilişkilendirilmesi gerekir. Mevcut bir projeyi seçebilir veya yeni bir tane oluşturabiliriz. Burada, gemini-managed-agents adlı bir proje oluşturdum.

Anahtarı oluşturduktan sonra kopyalıyoruz. Ardından, aracılarımızı oluşturacağımız klasörde .env adlı bir dosya oluşturup aşağıdaki biçimde yapıştırıyoruz:

GEMINI_API_KEY=<paste_your_api_key_here>

Google AI Studio’yu kapatmadan önce, az önce oluşturduğumuz API anahtarında faturalandırmayı ayarlamamız gerekir. Bunu yapmadan, isteklerimiz reddedilecektir; çünkü Google bizden ücret tahsil edemez. Faturalandırmayı ayarlamak için “Set up billing” düğmesine tıklayın.

Python ortamı kurulumu

Bu proje için bir Python ortamı oluşturmak üzere Anaconda kullanacağız. Anaconda ile bir ortam oluşturmak için şu komutu kullanın:

conda create --name gemini_agents python=3.12 -y

Bu, Python 3.10 sürümünü kullanan gemini_agents adlı bir ortam oluşturur. -y parametresi, ortam oluşturma sırasında tüm sorulara “evet” yanıtını otomatik vermek için bir kısayoldur.

Sonra, ortamı etkinleştirmemiz gerekir:

conda activate gemini_agents

Son olarak, gerekli bağımlılıkları kurmamız gerekiyor. Şöyle:

pip install google-genai requests python-dotenv

Yönetilen bir aracıyla basit bir etkileşim oluşturma

Artık ilk aracımızı çalıştırmak için her şey hazır. Bu ilk aracı çok bir şey yapmayacak; yalnızca matplotlib’i kuracak ve kurulan sürümü bildirecek.

Yönetilen bir aracıyla nasıl etkileşim kurabileceğimizin adım adım açıklaması burada (tam kod, depodaki simple_interaction.py betiğinde bulunabilir):

Önce, gerekli paketleri içe aktarır ve daha önce oluşturduğumuz .env dosyasından API anahtarını yükleriz:

from dotenv import load_dotenv
from google import genai

# Load secure environment variables
load_dotenv()

Sonra, Gemini istemcisini başlatır ve temel aracıyla bir etkileşim oluştururuz; adı şu anda antigravity-preview-05-2026—ona matplotlib’i kurmasını isteriz:

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

Son olarak, status, environment_id ve output_text özelliklerini inceleyerek aracının çıktısını alırız:

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

İşte sonuç:

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

Korumalı alan yaşam döngüsü durumları

Yukarıdaki örnekte, yönetilen aracı etkileşiminin ortam tanımlayıcısını gösterdik:

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

Bu değer önemlidir; çünkü aracının yürütüldüğü ortamın tanımlayıcısını temsil eder. Aracı etkileşimleri, silinmeden önce son etkinlikten itibaren 7 güne kadar saklanan geçici bir ortamda tutulur.

Aşağıdaki diyagram, bir etkileşim sırasında aracının yürütüldüğü korumalı alanın yaşam döngüsünü göstermektedir.

Ortam silinmemişken, ortam tanımlayıcısını kullanarak erişebilir ve daha fazla etkileşim gerçekleştirebiliriz.

Birden fazla etkileşim gerçekleştirme

Bu örnekte, birden fazla etkileşimin nasıl yapılacağını gösteriyoruz. Tam kod, depodaki multiple_interactions.py dosyasında mevcuttur.

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

İkinci etkileşimde iki parametre eklediğimize dikkat edin:

• previous_interaction_id: Önceki etkileşimin tanımlayıcısı; böylece aracı, konuşma geçmişinden haberdar olur.

• environment: Aracının hangi korumalı alanda çalışması gerektiğini bilmesi için ortam tanımlayıcısı.

Bir Aracıyla Dosya Paylaşma

Veri analisti aracısı oluşturamayız, eğer aracıya veriye erişim veremezsek. Bir aracıyla veri paylaşmanın birkaç farklı yolu vardır:

• Satır içi veri: Dosya içeriğini bir string’e yükleyip etkileşim sırasında göndermek.
• Barındırılan dosya:Veriyi herkese açık bir URL’de barındırıp, aracıya indirmesi için bu URL’yi sağlamak.
• GitHub deposu: Aracıya herkese açık bir GitHub deposu URL’si sağlayabiliriz.
• Google Cloud Bucket:Bir dosyayı Google Cloud Storage kovasında barındırıp, projeyi aracı bu kovaya erişebilecek şekilde yapılandırmak.

Bu yazıda tüm bu çözümleri incelemeyeceğiz. Yerel bir dosyayı string’e yükleyip satır içi veri gönderme ve bir GitHub deposu paylaşmayı göstereceğiz. İlki, küçük yerel dosyaları paylaşmak (dosya başına 1 MB’a, tüm dosyalar toplamda 2 MB’a kadar) için idealdir; ikincisi ise veri kümeleri gibi daha büyük dosyaları paylaşmak için daha uygundur.

Satır içi veri paylaşma

Satır içi veri sağlamaya ilişkin bir örnek burada (tam kod inline_example.py içinde):

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

Veri, environment yapılandırmasındaki sources parametresi kullanılarak sağlanır. target, verinin aracı ortamında depolanacağı yeri tanımlar. Dosyalar workspace klasöründe bulunmalıdır. Bu durumda, number.txt adlı bir dosya olacaktır. 

content parametresi dosya içeriğini sağlar. inline kaynaklar için bu yalnızca bir string’dir; bu örnekte utils.py dosyasındaki read_text_file() işleviyle okuyoruz.

Bir GitHub deposu paylaşma

Daha büyük dosyaları paylaşmak için bir GitHub deposu URL’si sağlayabiliriz. Şöyle:

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

Yukarıdaki örnekte, https://github.com/fran-aubry/gemini-agents-tutorial URL’sine sahip depo, aracının çalışma alanı içinde repository adlı bir klasöre kopyalanır.

Bir Aracının Ortamını İndirme

Yönetilen aracılarla nasıl etkileşim kuracağımızı ve bu aracılara dosyaları nasıl sağlayacağımızı zaten öğrendik. Veri analisti aracımızı oluşturmak için öğrenmemiz gereken son şey, bir aracının ortamını nasıl indireceğimiz. Bu, aracı tarafından oluşturulan grafiklere ve sonuçlara erişebilmemiz için gereklidir.

Her çalışma alanı şu URL’den indirilebilir:

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

Burada <env_id>, indirmek istediğimiz ortamın tanımlayıcısıyla değiştirilmelidir.

İşte bir paketi indirmek için requests paketini kullanan bir Python işlevi (bu işlev, oluşturduğumuz utils.py dosyasının bir parçasıdır):

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

Bir Veri Analisti Aracısı Oluşturma

Bu bölümde, veri analizi yapan bir aracı oluşturmayı öğreneceğiz. Aracıyı test etmek için Kaggle’dan alınan bu Netflix veri kümesini kullanacağız; bu veri kümesi data klasöründe de saklanmaktadır.

Önceki tüm örneklerde, hep temel aracıyla etkileşim kurduk: antigravity-preview-05-2026. Burada önce client.agents.create() işlevini kullanarak bir aracı oluşturacağız.

Bir aracı oluşturma

Bir aracı şöyle oluşturabiliriz:

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

Parametreleri tek tek açıklayalım:

• id: Aracının adını tanımlar; bu örnekte data-analyst. client.interactions.create() yönteminde, şimdiye kadar kullandığımız antigravity-preview-05-2026 yerine bu tanımlayıcıyı kullanacağız. 

• base_agent: Temel olarak kullanılacak aracı. Bu, antigravity-preview-05-2026 aracısının üzerine bir aracı inşa ettiğimiz anlamına gelir.

• base_environment: Daha önce olduğu gibi, aracıya dosya sağlamamıza olanak tanır. İki özel dosya sağladık: .agents/AGENTS.md ve .agents/skills/csv-aggregator/SKILL.md. Bu dosyalarda aracının davranışını tanımladık. AGENTS.md dosyası aracının genel davranışını tanımlarken, SKILL.md belirli bir beceriyi tanımlar. Ayrıca, analiz etmek istediğimiz veri dosyalarına erişmesi için aracıya depoyu da sağladık.

AGENTS.md’yi anlama

Bu dosyayı bir sistem istemi olarak düşünebiliriz. Aracı için birincil talimat kılavuzumuzdur. Aracının özel rolünü, ana hedeflerini ve çalışırken uyması gereken sınırları açıkça tanımlamak için kullanmalıyız. 

Ayrıca, aracıya erişmesine izin verilen belirli araçları veya veri kaynaklarını listelemek ve ondan görevleri nasıl ele almasını veya nasıl iletişim kurmasını istediğimize dair örnekler vermek için de en doğru yerdir. 

Bu talimatları dosya içinde basit ve düzenli tutarak, aracının nasıl davranacağını ve hangi sonuçları üretmesini beklediğimizi netleştiririz.

Dosyanın aracının ortamındaki konumu .agents/AGENTS.md olmalıdır.

SKILL.md’yi anlama

Beceri dosyaları, aracıya belirli beceriler kazandırmak için kullanılır. Bir aracının birden fazla becerisi olabilir ve her biri .agents/skills/<skill_name>/SKILL.md konumunda, <skill_name> beceri adıyla değiştirilerek, bir SKILL.md dosyasında tanımlanmalıdır.

Bir beceri dosyasının yapısı şöyle olmalıdır:

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

Bunu örneklemek için, data-analyst aracısını burada tanımlanan csv-aggregator adlı bir beceriyle donattık. Bu beceri, bir CSV’deki satırları bir sütuna göre gruplayıp başka bir sütunu toplamak istediğimizde kullanılır. 

Netflix veri kümesi özelinde, en çok izlenen türleri bilmek istiyorsak, satırları Genre sütununa göre gruplamak ve Viewership sütunundaki değerleri toplamak isteriz. Bu beceri dosyası, aracıya bu görevi nasıl gerçekleştireceğini açıklar.

Aracıyı yükleme

Aracılar kalıcı olduğundan, aracı oluşturmayı iki kez çalıştırmaya çalışırsak hata alırız. Bu nedenle utils.py dosyasında load_or_create_agent() işlevini oluşturduk. Bu işlev, aracıyı oluşturmaya çalışacak; eğer mevcutsa client.agents.load() işlevini kullanarak yükleyecektir.

Hepsini bir araya getirme

Artık bir veri analisti aracımız olduğuna göre, Netflix türlerini analiz etmesini isteyerek test etme zamanı. 

Daha önce olduğu gibi kütüphaneleri içe aktararak, API anahtarını yükleyerek ve istemciyi başlatarak başlıyoruz:

from dotenv import load_dotenv
from google import genai
import utils

load_dotenv()
client = genai.Client()

Ardından, utils.load_or_create_agent() işlevini kullanarak data-analyst aracısını oluştururuz (veya betiği ilk kez çalıştırmıyorsak yükleriz):

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

Sonrasında, daha önce yaptığımız gibi aracıyla etkileşime geçebiliriz. Tek fark, agent parametresinde artık antigravity-preview-05-2026 yerine kendi aracımızı sağlamamız.

Önce aracıdan matplotlib paketini kurmasını isteriz:

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

Ortam zaten aracının düzeyinde yapılandırıldığı için, artık dosya sağlamamız gerekmiyor; bu yüzden yalnızca ”remote” string’ini veriyoruz.

Sonra ondan, Netflix verilerini türlere göre analiz etmek için csv-aggregator aracını kullanmasını ve en çok izlenen türlerin neler olduğunu görmesini isteriz:

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
)

Aracının, bunun üzerine çalışmaya devam edebilmesi için önceki etkileşimin ortam tanımlayıcısını sağladığımıza dikkat edin.

Son olarak, önceki adımda oluşturulan genres.py betiğini çalıştırarak veriyi görselleştirmesini isteriz (SKILL.md dosyası, aracının bu betiği oluşturmasını söyler):

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

Bu etkileşimden sonra grafik oluşturulmuş olmalıdır. Ortamı indirerek yerelde alabiliriz:

utils.download_env(inter3.environment_id)

İşte sonuç:

Aracı etkileşiminin tam kodu analyze_netflix_genres.py içinde bulunabilir.

Sonuç

Karmaşık bulut bilişim altyapılarına güvenmeden, tek bir API çağrısıyla karmaşık aracılar oluşturabilmek son derece güçlüdür. Bu yetenek, bu aracılarının yürütüldüğü ortam hakkında endişelenmeden güçlü aracılar oluşturmayı çok kolaylaştırır.

Bu eğitimde, Gemini Yönetilen Aracılar’ın temellerini ele aldık; ancak gerçekten karmaşık aracılar oluşturmadık. Daha derine inmenizi ve bu temel üzerine inşa etmeye devam ederek becerilerinizi geliştirmenizi öneririm.