Next 2026 Geliştirici Açılış Konuşması: Büyük Ölçekte Aracıların Hatalarını Ayıklama

1. Giriş

Bu codelab'de, Google Cloud'da çalışan yapay zeka aracılarına nasıl hata ayıklayacağınızı öğreneceksiniz. Agent Runtime'a bir simülatör aracısı dağıtacak, sorunları tespit etmek için Cloud Observability'yi kullanacak ve hataların temel nedenini belirleyip gerçek zamanlı olarak düzeltmek için Gemini Cloud Assist ile Antigravity IDE'yi kullanacaksınız.

Bu demoda, Simülatör Aracısı'na ADK EventCompaction'ın yeni eklendiği varsayılmaktadır. Bu sayede Simülatör, iş akışını Gemini ile düzenli olarak özetleyebilir. Böylece her dönüşte modele gönderilen toplam bağlam azaltılır, yanıt kalitesi artar ve toplam maliyetler düşer. Ancak EventCompactionConfig'imizde bir hata olduğunu ve bunun da aracıda hatalara neden olduğunu öğreneceğiz. Bu codelab'de, bu tür sorunları nasıl bulup hızlıca düzelteceğimiz açıklanmaktadır.

Yapacaklarınız

• Marathon Simulator Agent'ı Agent Runtime'a dağıtın.
• Aracı hatalarını tespit etmek için Cloud Monitoring uyarısı oluşturun.
• Cloud Trace ve Gemini Cloud Assist'i kullanarak hataları inceleyin.
• Antigravity ve MCP'yi kullanarak aracıdaki temel nedeni belirleyin ve düzeltin.

Not: Gemini Cloud Assist şu anda gizli önizleme sürümündedir. Bu codelab'i çalıştırmak için Cloud Assist'in izin verilenler listesinde olmanız gerekmez. Tüm Cloud Assist adımları #8 (İsteğe bağlı): Cloud Assist İncelemelerini Kullanın - Cloud Assist'e henüz erişemiyorsanız bu sayfayı atlayın!

İhtiyacınız olanlar

• Chrome gibi bir web tarayıcısı
• Google Hesabı
• Antigravity (Mac, Linux ve Windows'u destekler)
• Python 3.13 veya sonraki sürümler.
• uv (Python paket yöneticisi)

Tahmini Süre: 45 dakika

Tahmini Maliyet: 5 ABD dolarından az

2. Başlamadan önce

Google Cloud projesi oluşturma

1. Google Cloud Console'da bir Google Cloud projesi seçin veya oluşturun.
2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun.

Ortamınızı ayarlama

Antigravity'i açın ve oturum açın. Ardından, cmd-shift-P (veya ctrl-shift-P) tuşuna basıp "Create New Terminal" (Yeni Terminal Oluştur) yazarak bir Terminal açın.

1. Terminalden Google Cloud ile kimlik doğrulaması yapın:

gcloud auth login
gcloud auth application-default login

2. Proje kimliğinizi ayarlayın:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
gcloud auth application-default set-quota-project $PROJECT_ID

API'leri etkinleştir

Gerekli Google Cloud API'lerini etkinleştirmek için aşağıdaki komutu çalıştırın:

gcloud services enable \
 aiplatform.googleapis.com \
 logging.googleapis.com \
 apphub.googleapis.com \
 cloudtrace.googleapis.com \
 telemetry.googleapis.com

Gemini Cloud Assist (özel önizleme) için izin verilenler listesindeyseniz şu ek API'leri etkinleştirin:

gcloud services enable \
 geminicloudassist.googleapis.com \
 cloudaicompanion.googleapis.com

3. Simülasyon Ajanı'nı ayarlama

Bu adımda, demo deposunu klonlayacak ve simülasyon aracısı için ortam değişkenlerini yapılandıracaksınız.

Depoyu Klonlama

next-26-keynotes deposunu klonlayın ve demo dizinine gidin:

git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/debugging-agents

Ortam değişkenlerini yapılandırma

Simülasyon Aracı, yapılandırma için .env dosyasını kullanır.

Antigravity penceresinin (Explorer) sol tarafında sample.env dosyasını bulun:

sample.env dosyasını açın ve GCP_PROJECT_ID alanını gerçek Google Cloud projesi kimliğinizle güncelleyin. Dosya aşağıdaki gibi görünmelidir:

GCP_PROJECT_ID="YOUR_PROJECT_ID"
GCP_LOCATION="us-central1"
GOOGLE_GENAI_USE_VERTEXAI=TRUE
USE_VERTEXAI_SESSION_SERVICE=true
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false

Aracının araç çağrıları ve muhakeme akışıyla ilgili ayrıntılı izleri yakalamak için OpenTelemetry entegrasyonlarını etkinleştiriyoruz.

4. Simülasyon aracısı Agent Runtime'a dağıtma

Şimdi, Agent Development Kit (ADK) kullanarak ajanı Agent Runtime'a dağıtacaksınız.

Bağımlıları yükleme

uv sync

Agent Runtime'a dağıtma

1. adk deploy komutunu çalıştırın. Bu adımda, aracınız paketlenir ve Google Cloud'a (Agent Runtime) dağıtılır.

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

Bu işlem 5 dakika kadar sürebilir. Sonunda aşağıdaki gibi bir çıkış görürsünüz:

✅ Created Agent Runtime:
projects/1234567890/locations/us-central1/reasoningEngines/9876543210...

Oluşturulan Agent Runtime kimliğini not edin. Bu bilgiye daha sonra ihtiyacınız olacak.

2. Web tarayıcısından Agent Runtime Console'u açın. Telemetri toplama etkin durumdayken simulator_agent'nın Agent Runtime'da çalıştığını görmeniz gerekir.

5. Uyarı politikası oluşturma

Aracı çalışma zamanı hatalarını otomatik olarak algılamak için Google Cloud Console'da günlük tabanlı bir uyarı oluşturursunuz.

1. Cloud Monitoring - Alerting konsoluna gidin.

2. Bildirim Kanallarını Düzenle'yi tıklayın. E-posta türüne gidin ve kişisel e-posta adresinize göndermek için bir e-posta bildirimi kanalı oluşturun. Kaydet'i tıklayın.

3. Uyarılar kontrol paneline dönün ve Politika Oluştur'u tıklayın.
4. Ekranın sağ tarafında Günlüğe dayalı uyarı oluştur'u tıklayın.

5. Log Explorer'a yönlendirilirsiniz. Aşağıdaki günlük sorgusunu yapıştırın ve kısmını proje kimliğinizle değiştirin.

resource.type="aiplatform.googleapis.com/ReasoningEngine"
logName="projects/<YOUR_PROJECT_ID>/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr"
"ERROR"

Bu günlük sorgusu, Agent Runtime'ın temel API adı ReasoningEngine olan Agent Runtime aracınızdaki Error günlüklerini arar.

6. Run Query'yi (Sorguyu Çalıştır) tıklayın. Henüz herhangi bir günlük görmezsiniz. Bu normaldir.
7. Sonuçlar araç çubuğunda İşlemler'i, ardından Günlük uyarısı oluştur'u tıklayın.

8. Günlük tabanlı uyarıyı yapılandırın. Uyarıya bir ad verin (herhangi bir ad olabilir) ve önem düzeyini Hata olarak ayarlayın.

9. "Bildirim sıklığını ayarla" bölümünde Sonraki'yi tıklayın (varsayılan ayarları koruyun).

10. Kimler bilgilendirilmeli? bölümünde, uyarıyı az önce ayarladığınız e-posta bildirim kanalını (ör. My Email).
11. Kaydet'i tıklayın.

6. Olayı Tetikleme

Aracı dağıtıp izledikten sonra, şimdi hata verecek şekilde maraton simülasyonunu çağırmayı deneyelim.

1. Google Cloud Console'da Agent Runtime konsoluna gidin.
2. simulator_agent simgesini tıklayın.
3. Üstteki araç çubuğundan Playground'u tıklayın. Bu işlem, ADK aracısıyla yeni bir oturum başlatır.

4. Oturum sohbeti penceresinde Test Simulation yazıp Enter tuşuna basarak istemi gönderin.

Bu işlem, planlanan rota boyunca binlerce simüle edilmiş koşucuyu takip ederek maraton simülasyonunu başlatır. Simülasyon, yarışın birden fazla "bölgesini" değerlendirdiğinden get_runner_telemetry ve analyze_medical_risk için birden fazla araç çağrısı görmeniz gerekir.

Birkaç dakika sonra aracının çalışmayı durdurmasını ve yanıt vermemesini bekleyebilirsiniz.

5. Bir dakika içinde gelen kutunuza, aracıda yeni bir olay olduğunu bildiren bir e-posta gelir.

Cloud Monitoring Console'u açmak için Olayı Görüntüle'yi tıklayın. Konsol'da sorunu incelemek için bir sonraki sayfaya gidin.

7. Olayı Konsol'da İnceleme

1. Olayı Cloud Monitoring Console'da görüntüleyin. Simülatör aracısından gelen hata günlüklerini görmelisiniz.

Bu görünümde, temsilcinin tam olarak hangi noktada başarısız olduğunu görmek zordur. Temsilcinin temel araç çağrılarını ve muhakeme akışını görmek için temsilcinin İzleri incelenir.

2. Temsilci Çalışma Zamanı Konsolu'nu tekrar açın. simulator_agent'ı tıklayın, ardından Traces (İzler) sekmesini açın.

3. Listedeki en son izlemeyi tıklayın. Ardından sağ üstte Zaman Çizelgesi'ni tıklayın. Her biri ayrı bir "aralık" olan izleme görünümü gösterilir. Bir kapsam, aracının iş akışındaki bir model veya araç çağrısını temsil eder.

4. İzleme görünümünde son aralığı tıklayın. Kırmızı olmalıdır.
5. Stacktrace'i (Yığın İzleme) tıklayın. Gemini API model çağrısıyla ilgili hata günlüklerini görmelisiniz. Özellikle 400: Invalid Argument hatası. Bu, Simülatör Temsilcisi'nin Gemini API'ye gönderdiği bir yükle ilgili istek düzeyinde bir sorunu gösterir.

8. [İsteğe bağlı] Hata ayıklamak için Cloud Assist Investigations'ı kullanma

Bu adımları yalnızca Gemini Cloud Assist (özel önizleme) için izin verilenler listesindeyseniz uygulayın. Aksi takdirde bir sonraki sayfaya geçin.

1. Başarısız olan aralıkta Günlükler ve Etkinlikler'i tıklayın. Yanında ışıltı düğmesi bulunan "İstisna" günlüğünü bulun. Ardından Günlüğü İncele'yi tıklayın.

2. Bu işlem, ekranın sağ tarafındaki bir kenar çubuğundan Cloud Assist incelemesi başlatır. Yükleme işlemi yaklaşık 3-5 dakika sürer.

3. İşlem tamamlandığında araştırmayı açın.

4. İnceleme Özetini görüntüleyin.

5. Aşağı kaydırıp Hipotezler'i görüntüleyin. Gemini Cloud Assist, Gemini API 400 hatasına neden olan Simulator Agent'ın agent.py dosyasındaki belirli satırı tanımlamalıdır.

Temsilcimizin kaynak kodunu açarak daha ayrıntılı bir inceleme yapalım ve sorunun temel nedenini bulmak için Antigravity'yi kullanalım. Sonraki sayfaya geçin.

9. Sorunun kök nedenini belirlemek ve sorunu düzeltmek için Antigravity'yi kullanma

1. Antigravity'yi yeniden açın.
2. Ekranın sağ üst kısmında Agent Manager'ı (Aracı Yöneticisi) açın.

3. Modelin Gemini 3 Flash ve Planlama modunda ayarlandığından emin olun.

4. Aşağıdaki istemi girip Enter tuşuna basın.

Why is the Simulator Agent failing to run in Agent Engine? 
We just added Events Compaction to the agent - could that be the cause? Search the ADK Python GitHub repository for relevant GitHub issues. https://github.com/google/adk-python/issues  - including issues that have been closed. 

For instance, you could query: is:issue eventscompactionconfig does not trigger summarization

Also look closely at the EventsCompactionConfig in agent.py.    

Antigravity'nin agent.py içindeki kodu incelediğini ve GitHub'da ilgili sorunları aradığını görmelisiniz:

Gemini API 400 hatasının temel nedeni, Gemini 3 Flash'in yaklaşık 1 milyon olan giriş bağlamı jetonu sınırını aşmamızdır. Bunun nedeni, Simulator Agents araç çağrılarından gelen büyük yanıtları etkili bir şekilde özetlemek için EventCompaction'ı yeterince sık tetiklemememizdir.

Bu sorunu düzeltmek için Antigravity, belirli bir jeton sayısına ulaştığımızda token_threshold parametresinin EventsCompactionConfig'ye eklenmesini önererek her çağırmada bağlamın düzenli olarak sıkıştırılmasını sağlamalıdır.

Bu, GitHub'daki bu sorunda önerilen düzeltmeyle uyumludur.

Düzeltmeyi agent.py. için uygula

Aşağıdakine benzer bir ifade gördüğünüzü doğrulayın:

app = App(
    name="simulator_agent",
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compaction_interval=3,
        overlap_size=1,
        summarizer=summarizer,
        token_threshold=200000,
        event_retention_size=2,
    ),
)

En önemlisi, token_threshold ve event_retention_size ayarlanmalıdır.

10. Düzeltmeyi yeniden dağıtma ve doğrulama

token_threshold ADK aracısının EventCompactionConfig düzeltmesini uyguladığımıza göre, simülasyon aracısını aracı çalışma zamanına yeniden dağıtabiliriz.

1. Antigravity –> New Terminal'i (Yeni Terminal) açın.
2. Ortam değişkenlerini ayarlayın. AGENT_RUNTIME_ID, simulator_agent öğenizin tam kaynak adı olmalıdır. Bu bilgi, Agent Runtime konsolundaki aracı listesinde bulunabilir.

export AGENT_RUNTIME_ID="projects/x/locations/us-central1/reasoningEngines/x"
export PROJECT_ID="your-project-id"

3. Aracıyı yeniden dağıtın:

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --agent_engine_id="$AGENT_RUNTIME_ID" \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

Bunun çalışması birkaç dakika sürer. İşlem başarılı olduğunda şunları görürsünüz:

✅ Updated agent engine: projects/xxx/locations/us-central1/reasoningEngines/...
Cleaning up the temp folder: simulator_agent_tmp...

4. Agent Runtime konsolunu açın. simulator_agent uygulamasını yeniden açın. Playground'u tıklayın.
5. Aynı istemi girin: Test Simulation - ardından Enter tuşuna basın.
6. Tam arka uç Marathon simülasyonunun çalıştırılması birkaç dakika sürer. Birden fazla araç çağrısı görmelisiniz. Sonunda şuna benzer bir yanıt görürsünüz:

Bu, simülatörün başarıyla çalıştığını gösterir. ✅

7. İlgili ADK oturumunun İzleme görünümünü açın.
8. Kırmızı hata olmadan tüm "mavi" aralıkları görmelisiniz. Oturumların toplam jeton sayısının, Gemini API'nin 1 milyon bağlam jetonu sınırını aştığını unutmayın. Bu durum, artık EventCompaction her çağırmada yeterince sık çalıştırıldığından ve tek tek model çağrıları için genel bağlam sınırının aşılmasını önlediğinden sorun teşkil etmez.

🎊 Tebrikler! Simülasyon aracı temsilcisindeki hata düzeltildi.

11. Temizleme

Google Cloud hesabınızın ücretlendirilmesini önlemek için bu codelab sırasında oluşturulan kaynakları silin.

Aracı Çalışma Zamanı Uygulamasını Silme

Reasoning Engine örneğini konsol üzerinden veya gcloud komutunu kullanarak (kaynak adınız varsa) silebilirsiniz. Basitlik için konsolu kullanın:

1. Agent Runtime sayfasına gidin.
2. simulator_agent simgesini seçin ve sağ taraftaki üç nokta düğmesini tıklayın.
3. Sil'i tıklayın.

Cloud Monitoring politikasını silme

1. Cloud Monitoring konsolu -> Uyarılar'a gidin.
2. Aşağı kaydırarak Politikalar'a gidin, ardından üç nokta düğmesini tıklayarak politikayı silin.

12. 🎊 Tebrikler!

Tebrikler! Google Cloud'da bir yapay zeka aracısının hata ayıklama işlemini başarıyla tamamladınız.

Öğrendikleriniz

• Temsilcileri Agent Runtime'a dağıtma
• Cloud Monitoring uyarılarını kullanarak hataları tespit etme
• Cloud Logging ve Agent Runtime'ın izleme görünümünü kullanarak etkin olayları keşfetme
• Gemini Cloud Assist'i kullanarak hataları nasıl inceleyeceğinizi öğrenin.
• Aracı hatalarının temel nedenini bulmak ve bu hataları düzeltmek için Antigravity'yi kullanma
• Uzun süren ve çok sayıda araç kullanılan aracı dönüşlerini işlemek için ADK Event Compaction'ı nasıl hassas şekilde ayarlayacağınızı öğrenin.

Sonraki adımlar

• Agent Runtime hakkında daha fazla bilgi edinin.
• Agent Development Kit hakkında daha fazla bilgi edinin.
• Cloud Monitoring'de uyarılar hakkında daha fazla bilgi edinin.
• Gemini Cloud Assist hakkında daha fazla bilgi edinin.