Gemini API ile yönetilen bir teknoloji özeti ajanı oluşturma

1. Genel Bakış

Yapay zeka ve teknoloji dünyası, herkesin takip edebileceğinden daha hızlı ilerliyor. Her gün yeni modeller, makaleler ve ürünler yayınlanıyor. Bugünün başlıklarını getiren, kısa özetler yazan ve her sabah PDF oluşturan bir özet aracısı bu sorunu çözebilir. Ancak böyle bir aracı oluşturmak için bir çerçeve seçmek, Python'da araçlar tanımlamak, bir düzenleme döngüsü yazmak, bir kapsayıcı paketlemek ve Cloud Run'a dağıtmak gerekiyordu. Tüm bunlar, aracı tek bir web isteğinde bulunmadan önce gerçekleşir.

Gemini API'deki yönetilen ajanlar bu denklemi değiştiriyor. İki Markdown yapılandırma dosyası ve önceden oluşturulmuş bir oluşturucu komut dosyası yazıp bir API çağrısı yaptığınızda gerçek bir Ubuntu sanal alanı başlatılır, web'de gezinir, özetlerinizi yazar ve PDF oluşturur. Kapsayıcı yok. Dağıtım yok. Düzenleme kodu yok.

Bu codelab'de, boş bir işlevden günlük özet işlevine kadar her şeyi adım adım yaparak tam olarak bu tür bir aracı oluşturacaksınız.

Ne oluşturacaksınız?

  • Gerçek bir Linux sanal ortamında ilk yönetilen aracınızı oluşturma ve çalıştırma
  • Ayrıntılı talimatlarla temsilciyi özelleştirme
  • Aracının PDF çıktısını indirme
  • Web'i yeniden getirmeden özeti iyileştirmek için sohbete devam etme
  • Aracı yapılandırmasını kaydedin ve gelecekteki çalıştırmalarda kimliğe göre çağırın.

İhtiyacınız olanlar

  • Python 3.10 veya sonraki sürümler
  • Faturalandırmanın etkin olduğu bir Gemini API anahtarı: aistudio.google.com/api-keys
  • ~1 ABD doları tutarında API kredisi (her tam çalıştırma 0,30-1,30 ABD doları tutarındadır)

2. Gemini API'de yönetilen ajanlar nedir?

Üç yapay zeka sistemi düzeyi

Koda geçmeden önce, yönetilen aracıların iki alternatife kıyasla nerede yer aldığını inceleyelim:

Seviye

Nedir?

Altyapıyı Kim Yönetir?

Standart LLM

Siz istem girersiniz, o da metinle yanıt verir. Eller yok, hafıza yok, internet yok.

Geçersiz: Kendi başına hiçbir şey yapamaz.

Self-Hosted Agent

ADK/LangChain/AutoGen + Docker + araçlar + bellek bağlantısını yaparsınız.

Siz: tümü (veya Agent Engine gibi yönetilen bir platform)

Yönetilen Ajan

Hedef belirleyin. Google, güvenli bir korumalı alan sağlar. Ajan, kodu yazar, çalıştırır, hataları okur, web'de arama yapar ve hataları bağımsız olarak düzeltir.

Google: tümü

Bu codelab, üçüncü satırla ilgilidir. Bir görev ve yapılandırma dosyaları sağlarsınız. Diğer her şeyi Google halleder.

ADK + Cloud Run ile neler oluşturabilirsiniz?

Web'e göz atan, Python çalıştıran ve PDF oluşturan bir haber özeti aracısı oluşturmak için ADK + Cloud Run ile tüm bunlara ihtiyacınız olur:

# agent.py: define tools and wire up the agent
from google.adk.agents import LlmAgent
from google.adk.tools import google_search, built_in_code_execution

agent = LlmAgent(
    name="digest-agent",
    model=MODEL,
    instruction=AGENTS_MD,          # your editorial voice and rules
    tools=[google_search, built_in_code_execution],
)

# app.py: serve the agent over HTTP
from google.adk.runners import FastApiRunner
runner = FastApiRunner(agent=agent)
app = runner.app

# pdf_tool.py: custom tool, install reportlab, render PDF
# scraper.py: custom tool, fetch each news source
# streaming.py: wire agent events to your SSE endpoint

# Dockerfile: package everything
FROM python:3.12
COPY . /app
RUN pip install google-adk reportlab requests
CMD ["uvicorn", "app:app", "--host", "0.0.0.0"]

# Deploy to Cloud Run
gcloud run deploy digest-agent \
  --image gcr.io/your-project/digest-agent \
  --set-secrets GEMINI_API_KEY=gemini-key:latest \
  --memory 2Gi

Bu, aracı bir kez çalıştırmadan önceki durumdur. Sandbox izolasyonu (bu nedenle aracı sunucunuza zarar veremez), paket yükleme, araç çağrıları arasındaki durum yönetimi ve etkinlikleri bir istemciye getirmek için kullanılan akış altyapısı size aittir.

Yönetilen aracıların yerine ne koyduğu

from google import genai
client = genai.Client()

stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="",
    stream=True,
    environment={
        "type": "remote",
        "sources": [          # your config files, mounted at startup
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": AGENTS_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/SKILL.md",
                "content": SKILL_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/scripts/generate_pdf.py",
                "content": GENERATE_PDF_PY,
            },
        ],
    },
)

ADK + Cloud Run için gerekenler

Yönetilen Ajanlar sizin için hangi işlemleri yapar?

Container görüntüsü + Dockerfile + CI/CD

Tamamen yönetilen Ubuntu sanal alanı (Python 3.12, Node 22, 4 CPU / 16 GB RAM)

Cloud Run dağıtımı ve ölçeklendirme

Her etkileşim için sağlanır, 7 gün boyunca işlem yapılmadığında otomatik olarak sona erer.

Korumalı alan izolasyonu

Etkileşim başına yalıtılmış

Özel PDF aracı + pip install

Aracı, paketleri korumalı alanın içine yükler.

SSE yayın altyapısı

stream=True, bir etkinlik yineleyicisi döndürür.

Python'da araç tanımları

Yerleşik araçlar: web'de gezinme, kod yürütme, dosya sistemi

Araç aramaları arasında durum yönetimi

Ajanın muhakeme döngüsüne yerleştirilmiştir.

Yapılandırma dosyaları (AGENTS.md, SKILL.md, önceden oluşturulmuş bir komut dosyası) yazıp bir API çağrısı yaparsınız. Diğer her şeyi Google halleder.

Koruma alanının işleyiş şekli

interactions.create() call
        │
        ▼
Google provisions Ubuntu sandbox (Python 3.12, Node 22, 4 CPU / 16 GB RAM)
        │
        ▼
Agent reasoning loop:
  plan → fetch URLs → run Python → write files → reason → repeat
        │
        ▼
Events stream back in real time: tool calls, text chunks, completion
        │
        ▼
interaction.completed → environment_id + interaction_id

Koruma alanı, 7 gün boyunca işlem yapılmadığında kalıcı olur. Çıktıyı iyileştirmek, takip görevleri çalıştırmak veya kaydedilmiş adlandırılmış bir aracıya çatallamak için environment_id ile devam edebilirsiniz.

3. Kur

Bu codelab'i Google Cloud Shell'de açmak için aşağıdaki düğmeyi tıklayın. Tüm bağımlılıklar önceden yüklenir.

Cloud Shell'de Aç

B seçeneği: Yerel kurulum

git clone https://github.com/Saoussen-CH/tech-digest-managed-agent.git
cd tech-digest-managed-agent

Gerekirse uv uygulamasını yükleyin:

curl -LsSf https://astral.sh/uv/install.sh | sh

API anahtarınızı yapılandırma

cp .env.example .env
cloudshell edit .env

Anahtarınızı ayarlayın:

GEMINI_API_KEY=your-key-here

Bağımlıları yükleme

uv sync

4. İlk temsilci görüşmenizi yapma

Başlangıç dosyasını açın.

cloudshell edit run_digest.py

run_digest() için şu anda doldurulması gereken bir YAPILACAKLAR öğesi ve sonraki adımda doldurulması gereken üç YAPILACAKLAR öğesi var. Yukarıda iki yardımcı zaten önceden doldurulmuştur:

  • load_source(path): Dosyayı, komut dosyasına göre .agents/ konumundan okur. Bunu, sonraki alıştırmada editoryal tarz, PDF başucu kitabı ve oluşturucuyu korumalı alana eklemek için kullanacaksınız.
  • run_stream(stream): Etkinlik akışını işler ve (environment_id, interaction_id) değerini döndürür. Etkinlik döngüsünü kendiniz yazmanız gerekmez.

Eklenmesi gerekenler

YAPILACAKLAR 1: pass yerine aşağıdakileri girin (Şimdilik 3. ve 4. YAPILACAKLAR'ı yoksayın. Bunlar sonraki adım içindir):

    from google import genai
    client = genai.Client()

    stream = client.interactions.create(
        agent=BASE_AGENT,
        input="Fetch the Hacker News front page and list the top 5 stories.",
        stream=True,
        environment="remote",
    )

    environment_id, interaction_id = run_stream(stream)
    print(f"\nDone. environment_id={environment_id}")

Her bölümün işlevi

genai.Client(), ortamdan GEMINI_API_KEY okur. Diğer her şey bu istemci üzerinden geçer.

interactions.create(), ana görüşmedir. Bu işlevin çalışması için dört parametre gerekir:

  • agent=BASE_AGENT: Gemini 3.5 Flash tarafından desteklenen, genel amaçlı bir yönetilen ajan olan Antigravity ajanını (antigravity-preview-05-2026) seçer. Varsayılan olarak etkinleştirilmiş üç yerleşik araçla birlikte gelir: code_execution (Bash, Python, Node.js'yi çalıştırma), google_search ve url_context (web sayfalarını getirme ve okuma). environment parametresini ilettiğinizde dosya sistemi araçları (read_file, write_file, list_files) otomatik olarak etkinleştirilir. Tek bir çağrı ile Python 3.12, Node.js 22, git, pip ve curl önceden yüklenmiş olarak tam olarak yönetilen bir Ubuntu ortamı sağlanır. Derlenecek kapsayıcı veya çalıştırılacak dağıtım yoktur.
  • input: Bu çalıştırma için görev. Temsilci, Hacker News'a göz atar ve sonuçları değerlendirir.
  • environment="remote": Bu etkileşim için yeni bir bulut korumalı alanı sağlar.
  • stream=True: Engellemek yerine etkinliklerin yinelenebilir bir öğesini döndürür. Bu parametre olmadan arama 30-90 saniye bekler ve tüm çıkışı interaction.output_text olarak döndürür. Yayınla birlikte, temsilci nedenini görür ve anında işlem yaparsınız. Burada akış, gelişmiş bir özellik değildir. 90 saniyelik siyah bir kutu, temsilcinin çalışıp çalışmadığı veya takılıp kalmadığı hakkında size bilgi vermediğinden doğru varsayılan seçenektir.

Yeni sağladığınız: Her interactions.create() çağrısı, özel bir korumalı alanı başlatır:

Bileşen

Spesifikasyon

İşletim Sistemi

İzole Ubuntu Linux ortamı

Önceden yüklenmiş çalışma zamanları

Python 3.12, Node.js 22, Bash

İşlem

4 CPU çekirdeği, 16 GB RAM

Bağlam Yönetimi

Otomatik sıkıştırma, yaklaşık 135.000 jetonda tetiklenir.

Ağ İletişimi

Çıkış proxy'si üzerinden giden web erişimi

Aracı, pip veya npm ile herhangi bir paketi yükleyebilir, dosyaları okuyup yazabilir ve giden web istekleri gönderebilir. Makinenize ve kimlik bilgilerinize asla dokunulmaz.

environment_id, az önce çalıştırılan korumalı alanın tanıtıcısıdır. interaction.completed işleminden sonra sanal alan kapatılmaz ve 7 güne kadar etkin kalır. environment_id simgesini kullanarak geri dönebilirsiniz. İkinci bir interactions.create() görüşmesine aktarıldığında, aracı aynı dosya sistemi, dosyalar ve yüklü paketlerle hiç ayrılmamış gibi devam eder. Bir sonraki adım, PDF'yi aracıyı yeniden çalıştırmadan indirmek için bu bilgiyi kullanır. Ondan sonraki adım ise bu bilgiyi kullanarak sohbete devam eder.

interaction_id, yeni tamamlanan görüşme turunun tanıtıcısıdır. Sonraki görüşmede previous_interaction_id olarak iletin. Temsilci, bu turda söylediklerini ve yaptıklarını tamamen hatırlar.

Doğrula

uv run python run_digest.py

Ajan çalışırken canlı çıkış görmeniz gerekir:

[agent started]
  [tool] run_code
Here are the top 5 stories currently on the Hacker News front page, retrieved via the official Hacker News API:

1. **Qwen 3.6 27B is the sweet spot for local development** — 471 points
2. **.self: A new top-level domain designed to support self-hosting** — 116 points
...
Done. environment_id=e3de58774073f75a6ef42924c6ce2e88

API, environment="remote" ile bile gerçek bir environment_id döndürür. Korumalı alan çalıştırıldı. Eksik olan yapılandırma: ses yok, beceri yok, PDF oluşturucu yok. Ajan, hikayeleri yalnızca metin olarak yazdırıp durdu. Sonraki adımda bunları ekleyeceksiniz.

Çıktının her satırı run_stream()'daki bir etkinlikle eşlenir:

step.type

Nedir?

run_stream() adlı kullanıcının yazdığı içerikler

"url_context_call"

bir URL'yi getiren aracı

[tool] url_context (https://...)

"code_execution_call"

Korumalı alanda kod çalıştıran ajan

[tool] run_code

"google_search_call"

Temsilci web'de arama yapıyor

[tool] google_search

"function_call"

dosya araçları ve diğerleri

[tool] read_file (/workspace/...)

step.delta / delta.type == "text"

Müşteri temsilcisinin metin yazması

doğrudan stdout'a aktarılır.

5. Ajanı özelleştirme

Temsilcinin talimatı yoktu: ses, beceri veya PDF oluşturucu yoktu. Bu adımda, yapılandırma dosyalarını .agents/ konumundan yükleyip korumalı alana monte edersiniz.

Neyi değiştirmeliyim?

run_digest.py ile ilgili dört değişiklik yapın:

YAPILACAKLAR 2: load_source() öğesinin altına üç modül düzeyinde sabit ekleyin (bunlar run_digest() dışında, dosyanın en üstünde yer alır):

AGENTS_MD       = load_source(".agents/AGENTS.md")
SKILL_MD        = load_source(".agents/skills/digest-pdf/SKILL.md")
GENERATE_PDF_PY = load_source(".agents/skills/digest-pdf/scripts/generate_pdf.py")

Ne yüklediğinizi görmek için her dosyayı açın: AGENTS.md, editoryal tarz ve iş akışı kurallarını belirler; SKILL.md, adım adım PDF başucu kitabıdır; generate_pdf.py, aracının çalıştıracağı önceden oluşturulmuş oluşturucudur.

Şimdi run_digest() içinde iki değişiklik daha yapın:

YAPILACAKLAR 3: environment değerini "remote" yerine kaynaklar sözlüğü olarak değiştirin ve input değerini "" olarak ayarlayın:

        environment={
            "type": "remote",
            "sources": [
                {
                    "type": "inline",
                    "target": ".agents/AGENTS.md",
                    "content": AGENTS_MD,
                },
                {
                    "type": "inline",
                    "target": ".agents/skills/digest-pdf/SKILL.md",
                    "content": SKILL_MD,
                },
                {
                    "type": "inline",
                    "target": ".agents/skills/digest-pdf/scripts/generate_pdf.py",
                    "content": GENERATE_PDF_PY,
                },
            ],
        },

YAPILACAKLAR 4: Bu satırları print(f"\nDone. environment_id={environment_id}") kodundan hemen sonra ekleyin:

    set_key(".env", "ENVIRONMENT_ID", environment_id)
    set_key(".env", "INTERACTION_ID", interaction_id)

(set_key, run_digest.py'nin en üstüne zaten içe aktarılmıştır.)

Bu işlem, her iki kimliği de bu çalıştırma sırasında .env konumuna yazar. Böylece sonraki adım, PDF'yi aracıyı yeniden çalıştırmadan indirebilir.

Her kaynağın işlevi

Her kaynak, aracı çalışmadan önce başlangıçta korumalı alan dosya sistemine yerleştirilmiş bir dosyadır. target yolları, Antigravity koşumunun bunları bulmayı beklediği yerlerle eşleşir:

.agents/
├── AGENTS.md                              ← auto-loaded as global instructions
└── skills/
    └── digest-pdf/
        ├── SKILL.md                       ← auto-discovered and registered as a skill
        └── scripts/
            └── generate_pdf.py            ← pre-built renderer the agent can run

target yol

Değişken

Koşumun bu verilerle yaptığı işlemler

.agents/AGENTS.md

AGENTS_MD

Kalıcı talimatlar olarak otomatik yüklenir: editoryal tarz, iş akışı, uygulama kuralları

.agents/skills/digest-pdf/SKILL.md

SKILL_MD

Otomatik olarak keşfedilir ve adlandırılmış beceri olarak kaydedilir. Aracı, beceriyi adıyla çağırır.

.agents/skills/digest-pdf/scripts/generate_pdf.py

GENERATE_PDF_PY

Önceden oluşturulmuş PDF oluşturucu; temsilci summaries.json yazıp bu komut dosyasını çalıştırır.

Doğrula

uv run python run_digest.py

Çalıştırma işlemi 1-3 dakika sürer. Aracının yapılandırma dosyalarını okuduğunu, özet yazdığını ve PDF'yi kaydettiğini görmelisiniz:

[agent started]
  [tool] read_file (/.agents/skills/digest-pdf/SKILL.md)
  [tool] list_files (/.agents/skills/digest-pdf/scripts)
  [tool] read_file (/.agents/skills/digest-pdf/scripts/generate_pdf.py)
  [tool] run_code
  [tool] write_file (/workspace/summaries.json)
  [tool] run_code
  [tool] delete_file (/tmp/test_scrape.py)
I have successfully generated today's tech news digest and saved the formatted document to /workspace/digest.pdf.
Done. environment_id=4129ffd75574e308748e9425d7ec828f

environment_id artık gerçek bir değerdir: Sandbox, yapılandırma dosyalarınızla çalıştı ve aracı digest.pdf oluşturdu. Sonraki adımda bu dosya indirilir.

6. PDF'yi indirin

Temsilci, sanal ortamda digest.pdf ile /workspace/digest.pdf arasında yazdı. Ortam anlık görüntüsü, Gemini Files API aracılığıyla tar arşivi olarak kullanılabilir.

Gerekirse requests uygulamasını yükleyin:

uv pip install requests

Doldurulması gerekenler

download_pdf.py adlı kişiyi aç. İki yapılacak iş var.

YAPILACAKLAR 1: requests.get() görüşmesini doldurun:

    r = requests.get(
        f"https://generativelanguage.googleapis.com/v1beta/files/environment-{environment_id}:download",
        params={"alt": "media"},
        headers={"x-goog-api-key": api_key},
        allow_redirects=True,
    )
    r.raise_for_status()

URL, korumalı alan anlık görüntüsüne yönlendirir. params={"alt": "media"} meta veriler yerine ham baytlar döndürür. Mevcut GEMINI_API_KEY, Files API'nin de kimliğini doğrular.

YAPILACAKLAR 2: Tar arşivindeki PDF'yi bulup ayıklayın:

            member = next(m for m in tar.getmembers() if m.name.endswith("workspace/digest.pdf"))
            tar.extract(member, path=tmp, filter="data")

Tar yolu öneki çalıştırmalar arasında değişiklik gösterir. Bu nedenle, tam yolu sabit kodlamak yerine soneke göre arama yapın. filter="data", güvenli olmayan tar çıkarma işlemiyle ilgili Python 3.13 kullanımdan kaldırma uyarısını bastırır.

Doğrula

uv run python download_pdf.py

Saved digest.pdf (48,231 bytes)

digest.pdf dosyasını aynı dizinde açın. Müşteri temsilcisinin canlı web sayfalarından oluşturduğu biçimlendirilmiş özeti içerir.

7. Görüşmeye Devam Etme

digest.pdf adlı ürüne zaten sahipsiniz. Yalnızca dosyayı istiyorsanız işlem tamamlanmıştır. Bu adımda farklı bir konu ele alınır: Ajanın, web'i yeniden getirmeden özeti değiştirmesi istenir.

Korumalı alan hâlâ kullanılabilir. Ajan, /workspace/digest.pdf ve özetlediği her hikayeyi hatırlıyor. İkinci bir interactions.create() çağrısı, aynı sandbox'a bir takip mesajı gönderir. Burada, her hikayenin altına "Önemi" notu eklemesini istiyorsunuz. PDF, yeniden getirme ve yeniden özetleme yapılmadan yerinde güncelleniyor.

Doldurulması gerekenler

refine_digest.py adlı kişiyi aç. Üç yapılacaklar öğesi var.

Yapılacaklar 1 ve 2: interactions.create() içindeki iki çok aşamalı etkileşim parametresini doldurun:

    environment=environment_id,
    previous_interaction_id=interaction_id,

environment=environment_id dosyaları ve paketleriyle aynı sanal ortamı devam ettirir. previous_interaction_id=interaction_id, temsilciye görüşme geçmişini verir. İlk görüşmeye kıyasla başka bir değişiklik olmaz.

YAPILACAKLAR 3: Etkinlik döngüsünden sonra yeni interaction_id değerini .env'e geri kalıcı olarak yazın:

set_key(".env", "INTERACTION_ID", interaction_id)

Her interactions.create() çağrısı yeni bir interaction_id oluşturur. Yeniden yazma işlemi, sonraki çalıştırmanın bu iyileştirmeyi previous_interaction_id olarak geçeceği ve zincirlemenin doğru şekilde yapılacağı anlamına gelir. Sandbox kimliği hiçbir zaman değişmediğinden ENVIRONMENT_ID değerinin güncellenmesi gerekmez.

Çok aşamalı etkileşimi mümkün kılan iki parametre

Kimlik

Koruduğu bilgiler

Analoji

environment=environment_id

Dosyalar, yüklenen paketler, sistem durumu: Linux dosya sistemindeki her şey

Toplantılar arasında aynı ofis masasını kullanma

previous_interaction_id=interaction_id

Sohbet geçmişi: Temsilcinin önceki dönüşlerde söyledikleri ve yaptıkları

Son toplantıda konuşulanları hatırlama

Aşağıdaki kimliklerden birini bağımsız olarak iletebilirsiniz:

  • environment_id yalnızca: Dosyaları ve paketleri yeniden kullanın ancak yeni bir sohbet başlatın. Aynı çalışma alanındaki yeni görevler için kullanışlıdır.
  • previous_interaction_id yalnızca: Sohbet bağlamına devam edin ancak yeni bir korumalı alanda (dosyalar silinir).
  • Her ikisi de: Bu adımda kullanılan tam süreklilik.

environment_id olmadan: boş korumalı alan, PDF yok. previous_interaction_id olmadan: Bağlam yok, temsilci belirli bir bölümü iyileştiremez.

Doğrula

uv run python refine_digest.py

Akış hızlı olmalıdır. Ajan hiçbir şeyi yeniden getirmez. İşlem tamamlandıktan sonra:

Refinement done.
Saved digest_v2.pdf (52,418 bytes)

digest_v2.pdf uygulamasını açın ve digest.pdf ile karşılaştırın. Artık her haberde "Öneminin nedeni" satırı eklenmiş olmalıdır.

8. Yönetilen aracı yapılandırmasını kalıcı hale getirme

Şu ana kadar yapılan tüm görüşmelerde AGENTS.md, SKILL.md ve generate_pdf.py satır içi olarak iletildi. Bu yöntem işe yarar ancak arama kodunuz her çalıştırmada dosyanın tüm içeriğini taşır. agents.create(), yapılandırmayı Google tarafında kaydedilmiş adlı bir aracıya yerleştirir. Bir sonraki çağırma işleminde yalnızca aracı kimliği iletilir:

Inline calls:   send sources on every call
Named agent:    bake once → invoke by ID, no sources

Doldurulması gerekenler

save_agent.py adlı kişiyi aç. Bir yapılacak işi (TODO 1) var.

Sabitlerin doğrudan run_digest.py kaynağından içe aktarıldığını (kopyalama yok) unutmayın:

from run_digest import BASE_AGENT, AGENTS_MD, SKILL_MD, GENERATE_PDF_PY

YAPILACAKLAR 1: agents.create() görüşmesini doldurun:

agent = client.agents.create(
    id="my-digest",
    base_agent=BASE_AGENT,
    description="Daily tech digest with editorial voice and PDF generation.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": AGENTS_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/SKILL.md",
                "content": SKILL_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/scripts/generate_pdf.py",
                "content": GENERATE_PDF_PY,
            },
        ],
    },
)

base_environment (environment değil), önceki adımdaki satır içi çağrıdan temel farktır: Kaynaklar Google'ın tarafında saklanır ve gelecekteki her çağrıda otomatik olarak monte edilir. Her özet çalıştırmasında değil, yalnızca bir kez çalıştırın.

Doğrulama: Aracıyı kaydetme

uv run python save_agent.py

Saved: my-digest
my-digest: Daily tech digest with editorial voice and PDF generation.

Kayıtlı aracıyı çağırma

invoke_agent.py adlı kişiyi aç. Kaynak olmadan, kayıtlı aracıyı kimliğe göre çağırır:

stream = client.interactions.create(
    agent="my-digest",
    input="",
    stream=True,
    environment="remote",
)

Bunu satır içi çağrıyla karşılaştırdığımızda agent=BASE_AGENT yerine "my-digest", üç satır içi kaynağın bulunduğu environment bloğunun tamamı yerine ise environment="remote" kullanıldığını görüyoruz. Yapılandırma, Google tarafında zaten yerleşiktir.

Doğrulama: Kayıtlı aracı çağırma

uv run python invoke_agent.py

Satır içi çalıştırmayla aynı canlı yayını görürsünüz ancak çağrı kaynak dosyası içermez. Çalıştırma işleminden sonra .env içindeki ENVIRONMENT_ID ve INTERACTION_ID güncellenir. Böylece refine_digest.py'ü eskisi gibi kullanmaya devam edebilirsiniz.

[agent started]
  [tool] read_file
  [tool] write_file
  [tool] run_code
I have successfully created today's tech news digest.
Done. environment_id=9a1c3e02-...

9. Temizleme

Sandbox, 7 gün boyunca işlem yapılmadığında otomatik olarak sona erer. Durdurulacak sunucu yok. Silinecek kapsayıcı yok.

Kaydettiğiniz bir aracı yapılandırmasını silmek için:

uv run python delete_agent.py

10. Özet

Sıfırdan, her seferinde bir kavram olacak şekilde yönetilen bir aracı oluşturdunuz. Her bir alıştırmada öğretilenler:

Egzersiz

Kavram

Key API

İlk görüşmenizi yapın

Gerçek bir Linux korumalı alanı sağlama ve etkinliklerini canlı olarak yayınlama

interactions.create(agent, input, environment, stream=True), event.event_type

Aracıyı özelleştirme

Yapılandırma dosyalarını bağlayın; aynı çalıştırmada kimlikleri .env olarak kalıcı hale getirin

environment.sources, set_key

PDF'yi indirin

Temsilciyi yeniden çalıştırmadan PDF'yi indirme

Gemini Files API :download download_pdf.py içinde

Görüşmeyi sürdürün

Web'i yeniden getirmeden sohbete devam etme

environment=environment_id, previous_interaction_id=interaction_id

Aracı yapılandırmasını kalıcı hale getirme

Aracı yapılandırmasını kalıcı hale getirme; kimliğe göre çağırma, kaynak gerekmez

agents.create(), agents.list()

Temel kalıplar

  1. Tek çağrı, tek korumalı alan: interactions.create() tüm altyapıyı yönetir (dağıtılacak container'lar veya yerel olarak yüklenecek paketler yoktur).
  2. Aşamalı akış: stream=True, 90 saniyelik bir kara kutuyu araç çağrıları ve metin parçaları içeren canlı bir yayına dönüştürür.
  3. Satır içi kaynaklar: mount AGENTS.md, SKILL.md ve önceden oluşturulmuş komut dosyalarını yükleme veya dağıtım adımı olmadan korumalı alana yerleştirme
  4. Otomatik koşum keşfi: .agents/ içine yerleştirilen dosyalar otomatik olarak alınır (SDK yapılandırması gerekmez).
  5. İki boyutlu durum: environment_id dosyaları ve paketleri izler; previous_interaction_id sohbet bağlamını izler; her ikisi de bağımsız olarak iletilebilir.
  6. Anlık görüntü indirme: Ortam, Gemini Files API aracılığıyla erişilebilen tam bir dosya sistemi tar'ıdır.
  7. Adlandırılmış aracı: agents.create(), yapılandırmayı kalıcı olarak yerleştirir. Gelecekteki çağrılarda kaynak olmadan yalnızca aracı kimliği ve environment="remote" iletilir.

ADK + Cloud Run ve yönetilen aracılar: Bir bakışta farklar

Kapasite

ADK + Cloud Run

Gemini API'de yönetilen ajanlar

Korumalı alan sağlama

docker build + gcloud run deploy

interactions.create()

Araçları tanımlama

Temsilciye kaydedilen Python işlevleri

Dahili: web'de gezinme, kod yürütme, dosya sistemi

Paketleri yükleme

Dockerfile'da pip install

Ajan, korumalı alan pip install içinde çalışır.

Etkinlikleri yayınlama

Özel SSE altyapısı

stream=True

Oturuma devam etme

Oturum veritabanı + bağlam yerleştirme

environment_id + previous_interaction_id

Yapılandırma dosyaları

Temsilciye gömülü kod olarak eklenmiş veya başlangıçta yerleştirilmiş

environment.sources üzerinden bağlandı

Yönetilecek altyapı

Container, Cloud Run, IAM, sır

Yok

Sonraki adımlar