Keynote Developer Next ‘26: Debugging Agen dalam Skala Besar

1. Pengantar

Dalam codelab ini, Anda akan mempelajari cara men-debug agen AI yang berjalan di Google Cloud. Anda akan men-deploy agen simulator ke Agent Runtime, menggunakan Cloud Observability untuk mendeteksi masalah, serta menggunakan Gemini Cloud Assist dan Antigravity IDE untuk menemukan penyebab utama dan memperbaiki error secara real time.

Premis demo ini adalah kita baru saja menambahkan ADK EventCompaction ke Simulator Agent. Hal ini memungkinkan Simulator meringkas alur kerjanya secara berkala menggunakan Gemini, sehingga mengurangi total konteks yang dikirim ke model pada setiap giliran - sehingga meningkatkan kualitas respons, dan mengurangi total biaya. Namun, kita akan mengetahui bahwa ada bug di EventCompactionConfig, yang menyebabkan error di agen. Codelab ini menjelaskan cara menemukan masalah semacam itu, dan memperbaikinya dengan cepat.

Yang akan Anda lakukan

• Deploy Agen Simulator Marathon ke Agent Runtime.
• Siapkan Pemberitahuan Cloud Monitoring untuk mendeteksi error agen.
• Selidiki error menggunakan Cloud Trace dan Gemini Cloud Assist.
• Temukan penyebab utama dan perbaiki agen menggunakan Antigravity dan MCP.

Catatan: Gemini Cloud Assist saat ini dalam Pratinjau Pribadi. Anda tidak perlu tercantum dalam daftar yang diberi akses agar Cloud Assist dapat menjalankan codelab ini. Semua langkah Cloud Assist diisolasi ke #8 (Opsional): Menggunakan Investigasi Cloud Assist - lewati halaman ini jika Anda belum dapat mengakses Cloud Assist.

Yang Anda butuhkan

• Browser web seperti Chrome.
• Akun Google
• Antigravity (Mendukung Mac, Linux, dan Windows)
• Python 3.13+.
• uv (pengelola paket Python)

Perkiraan Durasi: 45 menit

Perkiraan Biaya: Kurang dari $5 USD

2. Sebelum memulai

Buat Project Google Cloud

1. Di Konsol Google Cloud, pilih atau buat project Google Cloud.
2. Pastikan penagihan diaktifkan untuk project Cloud Anda.

Menyiapkan lingkungan Anda

Buka Antigravity, lalu login. Kemudian, buka Terminal dengan menekan cmd-shift-P (atau ctrl-shift-P), lalu ketik "Create New Terminal".

1. Dari Terminal, lakukan autentikasi dengan Google Cloud:

gcloud auth login
gcloud auth application-default login

2. Tetapkan Project ID Anda:

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

Mengaktifkan API

Jalankan perintah berikut untuk mengaktifkan Google Cloud API yang diperlukan:

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

Jika Anda masuk dalam daftar yang diizinkan untuk Gemini Cloud Assist (Pratinjau Pribadi), aktifkan API tambahan berikut:

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

3. Menyiapkan Agen Simulator

Pada langkah ini, Anda akan meng-clone repositori demo dan mengonfigurasi variabel lingkungan untuk Agen Simulator.

Membuat Clone Repositori

Buat clone repositori next-26-keynotes dan buka direktori demo:

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

Mengonfigurasi Variabel Lingkungan

Agen Simulator menggunakan file .env untuk konfigurasi.

Temukan file sample.env di sisi kiri jendela Antigravity (Explorer):

Buka sample.env dan perbarui kolom GCP_PROJECT_ID dengan ID Project Google Cloud Anda yang sebenarnya. File-nya akan terlihat seperti ini:

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

Kami mengaktifkan integrasi OpenTelemetry untuk merekam trace terperinci dari panggilan alat dan alur penalaran agen.

4. Men-deploy Agen Simulator ke Agent Runtime

Sekarang, Anda akan men-deploy agen ke Agent Runtime menggunakan Agent Development Kit (ADK).

Menginstal dependensi

uv sync

Men-deploy ke Agent Runtime

1. Jalankan perintah adk deploy. Langkah ini mengemas agen Anda dan men-deploy-nya ke Google Cloud (Agent Runtime).

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

Proses ini mungkin memerlukan waktu hingga 5 menit untuk dijalankan. Anda akan melihat output seperti ini:

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

Catat ID Runtime Agen yang dihasilkan. Anda akan membutuhkannya nanti.

2. Dari browser web, buka konsol Agent Runtime. Anda akan melihat simulator_agent berjalan di Agent Runtime, dengan pengumpulan telemetri diaktifkan.

5. Menyiapkan Kebijakan Pemberitahuan

Untuk mendeteksi error Runtime Agen secara otomatis, Anda akan membuat pemberitahuan berbasis log di Konsol Google Cloud.

1. Buka konsol Cloud Monitoring - Alerting.

2. Klik Edit Notification Channels. Scroll ke bawah ke jenis Email, lalu buat saluran notifikasi email untuk dikirim ke email pribadi Anda. Klik Save.

3. Kembali ke dasbor Pemberitahuan, lalu klik Buat Kebijakan.
4. Di sisi kanan layar, klik Buat pemberitahuan berbasis log.

5. Anda akan dialihkan ke Log Explorer. Tempelkan kueri log berikut, dengan mengganti dengan Project ID Anda.

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

Kueri log ini mencari log Error dalam agen Agent Runtime Anda, dengan ReasoningEngine sebagai nama API yang mendasari Agent Runtime.

6. Klik Run Query. Anda belum akan melihat log apa pun - itu sudah diperkirakan.
7. Klik Tindakan di toolbar hasil, lalu klik Buat pemberitahuan log.

8. Konfigurasi pemberitahuan berbasis log. Beri nama pemberitahuan (apa saja), lalu tetapkan tingkat keparahan ke Error.

9. Klik Berikutnya untuk bagian "Tetapkan frekuensi notifikasi" (pertahankan setelan default).

10. Untuk Siapa yang harus diberi tahu?, tetapkan pemberitahuan untuk memicu Saluran Notifikasi Email yang baru saja Anda siapkan (yaitu. My Email).
11. Klik Simpan.

6. Memicu Insiden

Setelah agen di-deploy dan dipantau, mari kita coba memanggil simulasi maraton dengan cara yang menimbulkan error.

1. Di Konsol Google Cloud, buka konsol Agent Runtime.
2. Klik simulator_agent.
3. Dari toolbar atas, klik Playground. Tindakan ini akan memulai sesi baru dengan agen ADK.

4. Dari jendela chat sesi, ketik Test Simulation, lalu tekan enter untuk mengirim perintah.

Tindakan ini akan memulai simulasi maraton, melacak ribuan pelari simulasi melalui rute yang direncanakan. Anda akan melihat beberapa panggilan alat ke get_runner_telemetry dan analyze_medical_risk, karena simulasi mengevaluasi beberapa "zona" balapan.

Setelah beberapa menit, Anda akan melihat agen berhenti berjalan dan tidak memberikan respons.

5. Dalam waktu sekitar satu menit, Anda akan melihat email masuk ke kotak masuk Anda, yang memberi tahu Anda tentang Insiden baru dalam agen.

Klik Lihat Insiden untuk membuka konsol Cloud Monitoring. Lanjutkan ke halaman berikutnya untuk menyelidiki masalah dalam Konsol.

7. Menyelidiki Insiden di Konsol

1. Lihat Insiden di konsol Cloud Monitoring. Anda akan melihat log error yang berasal dari Agen Simulator.

Dari tampilan ini, sulit untuk melihat secara persis pada titik mana Agen gagal. Untuk melihat panggilan alat dan alur penalaran yang mendasari agen, kita akan memeriksa Rekaman Aktivitas agen.

2. Buka kembali konsol Agent Runtime. Klik simulator_agent, lalu buka tab Traces.

3. Klik rekaman aktivitas terbaru dalam daftar. Kemudian di kanan atas, klik Linimasa. Anda akan melihat tampilan rekaman aktivitas dengan "rentang" individual. Satu rentang mewakili panggilan model atau alat dalam alur kerja agen.

4. Klik rentang terakhir di tampilan rekaman aktivitas. Warnanya harus merah.
5. Klik Stacktrace. Anda akan melihat log error terkait panggilan model Gemini API. Khususnya, error 400: Invalid Argument. Hal ini menandakan masalah tingkat permintaan dengan payload yang dikirim Agen Simulator ke Gemini API.

8. [Opsional] Menggunakan Investigasi Cloud Assist untuk Men-debug

Ikuti langkah-langkah ini hanya jika Anda tercantum dalam daftar yang diizinkan untuk Gemini Cloud Assist (Pratinjau Pribadi). Jika tidak, lanjutkan ke halaman berikutnya.

1. Dalam rentang yang gagal, klik Log dan Peristiwa. Temukan log "Pengecualian" dengan tombol kilau di sampingnya. Kemudian, klik Selidiki Log.

2. Tindakan ini akan memulai Investigasi Cloud Assist dari sidebar di sisi kanan layar. Proses ini akan memakan waktu sekitar 3-5 menit untuk dimuat.

3. Setelah selesai, buka penyelidikan.

4. Lihat Ringkasan Investigasi.

5. Scroll ke bawah dan lihat Hipotesis. Gemini Cloud Assist seharusnya mengidentifikasi baris tertentu dalam file agent.py Simulator Agent yang memunculkan error 400 Gemini API.

Mari kita gali lebih dalam dengan membuka kode sumber agen, dan menggunakan Antigravity untuk menemukan penyebab utama masalah ini. Lanjutkan ke halaman berikutnya.

9. Menggunakan Antigravity untuk Menemukan Penyebab Masalah dan Menerapkan Patch

1. Buka kembali Antigravity.
2. Buka Agent Manager di kanan atas layar.

3. Pastikan model disetel ke Gemini 3 Flash dan mode Perencanaan.

4. Masukkan perintah berikut, lalu tekan enter.

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.    

Anda akan melihat Antigravity memeriksa kode di agent.py, dan menelusuri masalah yang relevan di GitHub:

Penyebab utama error 400 Gemini API adalah karena kita melebihi batas token konteks input Gemini 3 Flash, yaitu sekitar 1 juta. Hal ini terjadi karena kita tidak cukup sering memicu EventCompaction untuk meringkas secara efektif respons besar dari panggilan alat Agen Simulator.

Untuk memperbaikinya, Antigravity harus menyarankan penambahan parameter token_threshold ke EventsCompactionConfig, untuk memadatkan konteks secara berkala dalam setiap pemanggilan setelah kita mencapai jumlah token tertentu.

Hal ini sesuai dengan perbaikan yang disarankan dalam masalah GitHub ini.

Terapkan perbaikan pada agent.py.

Pastikan Anda melihat sesuatu yang mirip dengan ini:

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,
    ),
)

Yang penting, token_threshold dan event_retention_size harus ditetapkan.

10. Men-deploy Ulang dan Memvalidasi Perbaikan

Setelah menerapkan perbaikan token_threshold ke EventCompactionConfig agen ADK, kita dapat men-deploy ulang Agen Simulator ke Agent Runtime.

1. Buka Antigravity –> New Terminal.
2. Menetapkan variabel lingkungan. AGENT_RUNTIME_ID harus berupa Nama Resource lengkap dari simulator_agent Anda. Ini dapat ditemukan di konsol Agent Runtime - daftar agen.

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

3. Deploy ulang agen:

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

Proses ini akan memerlukan waktu beberapa menit. Setelah berhasil, Anda akan melihat:

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

4. Buka konsol Agent Runtime. Buka kembali simulator_agent. Klik Playground
5. Masukkan perintah yang sama: Test Simulation - lalu, tekan enter.
6. Simulasi Marathon backend penuh akan memerlukan waktu beberapa menit untuk dijalankan. Anda akan melihat beberapa panggilan alat. Pada akhirnya, Anda akan melihat respons seperti ini:

Hal ini menunjukkan bahwa simulator berhasil dijalankan. ✅

7. Buka tampilan Trace untuk sesi ADK tersebut.
8. Anda akan melihat semua rentang "biru", tanpa error merah. Perhatikan bagaimana jumlah total token sesi melebihi batas token konteks 1 juta Gemini API. Tidak masalah, karena sekarang EventCompaction berjalan cukup sering dalam setiap pemanggilan, untuk menghindari penggunaan batas konteks keseluruhan untuk setiap panggilan model.

🎊 Hore! Kami telah memperbaiki error di agen Simulator.

11. Pembersihan

Agar tidak menimbulkan biaya pada akun Google Cloud Anda, hapus resource yang dibuat selama codelab ini.

Menghapus Aplikasi Runtime Agen

Anda dapat menghapus instance Reasoning Engine melalui konsol atau menggunakan perintah gcloud (jika Anda memiliki nama resource). Untuk mempermudah, gunakan konsol:

1. Buka halaman Agent Runtime.
2. Pilih simulator_agent –> klik tombol tiga titik di sisi kanan.
3. Klik Hapus.

Menghapus Kebijakan Cloud Monitoring

1. Buka konsol Cloud Monitoring -> Alerting.
2. Scroll ke bawah ke Kebijakan, lalu klik tombol tiga titik untuk Hapus kebijakan.

12. 🎊 Selamat!

Selamat! Anda baru saja berhasil men-debug agen AI di Google Cloud.

Yang telah Anda pelajari

• Cara men-deploy agen ke Agent Runtime.
• Cara mendeteksi error menggunakan Pemberitahuan Cloud Monitoring.
• Cara menjelajahi Insiden aktif menggunakan Cloud Logging dan tampilan rekaman aktivitas Agent Runtime.
• Cara menyelidiki kegagalan menggunakan Gemini Cloud Assist.
• Cara menggunakan Antigravity untuk menemukan penyebab utama dan menambal bug agen.
• Cara menyesuaikan Pemadatan Peristiwa ADK untuk menangani giliran agen yang berjalan lama dan berat alat.

Langkah berikutnya

• Pelajari lebih lanjut Agent Runtime.
• Pelajari lebih lanjut Agent Development Kit.
• Pelajari lebih lanjut Pemberitahuan di Cloud Monitoring.
• Pelajari lebih lanjut Gemini Cloud Assist.