ADK ile Yapay Zeka Ajanları Geliştirme: Veri Analisti Ajanı

1. Başlamadan önce

"ADK ile Yapay Zeka Ajanları Oluşturma" serisinin dördüncü bölümüne hoş geldiniz. Bu uygulamalı codelab'de, önceki oturumlarda öğrendiklerinizi birleştirerek bir Veri Analisti Aracısı oluşturacaksınız. Bu temsilci, verileri analiz etmek, değerli analizler oluşturmak ve veri analizi iş akışının temel yönlerini otomatikleştirmek için tasarlanacak.

ADK'da yer alan güçlü araçları kullanarak, yüklenen dosyaları keşfetmesi ve Google Cloud BigQuery gibi kurumsal düzeydeki veritabanlarına bağlanması için aracınızı güçlendirebilirsiniz.

Bu codelab'e şu kısaltılmış URL üzerinden de erişebilirsiniz: goo.gle/adk-data-analyst

Ön koşullar

Üretken yapay zeka kavramları hakkında temel bilgi
Python programlamada temel düzeyde yeterlilik ve komut satırını rahatça kullanabilme
Bu serideki önceki codelab'lerde yer alan "The Foundation" (Temel) ve "Empowering with Tools" (Araçlarla Güçlendirme) başlıklı codelab'lerdeki kavramlara aşina olmanız gerekir.

Neler öğreneceksiniz?

ADK çerçevesini kullanarak işlevsel bir veri analisti temsilcisi oluşturma
Bir aracının, yüklenen belgelerdeki verileri analiz etmesini sağlama yöntemleri.
Aracınızı kurumsal düzeyde veri analizi için BigQuery veritabanına bağlama
Amacı ve talimatları da dahil olmak üzere temsilcinizin temel mantığını tanımlama teknikleri.

Gerekenler

Çalışır durumda bir bilgisayar ve güvenilir bir internet bağlantısı.
Google Cloud Console'a erişmek için Chrome gibi bir tarayıcı
Meraklı ve öğrenmeye istekli olmalısınız.

2. Giriş

Günümüzün veri odaklı dünyasında, büyük miktarda bilgiyi hızlı ve doğru bir şekilde analiz edebilme becerisi hiç olmadığı kadar önemli. Ancak anlamlı analizler elde etme süreci genellikle SQL gibi alanlarda derin teknik uzmanlık gerektirir. Bu da karar alma sürecini yavaşlatabilecek bir darboğaz oluşturur. Bu boşluğu doldurup karmaşık veri kümeleriyle sohbet eder gibi kolayca etkileşim kurabilseydiniz ne olurdu?

Yapay zeka temsilcileri bu noktada oyunun kurallarını değiştiriyor. Sizinle verileriniz arasında akıllı bir arayüz görevi gören yapay zeka temsilcileri, doğal dil sorularını anlayabilir, bunları teknik sorgulara çevirebilir ve saniyeler içinde uygulanabilir analizler sunabilir.

Bu codelab'de, Agent Development Kit'i (ADK) kullanarak pratik bir veri analisti ajanı oluşturarak veri analizinin geleceğine adım atacaksınız. Öncelikle temel bir temsilci oluşturacak, ardından özelliklerini kademeli olarak geliştireceğiz. Öncelikle aracınıza, yüklenen belgelerdeki yapılandırılmamış verileri analiz etmeyi öğreteceksiniz. Ardından, büyük ölçekli ve gerçek dünyadaki bir sağlık hizmetleri veri kümesini sorgulamak ve analiz etmek için Google Cloud BigQuery adlı güçlü bir kurumsal veri ambarına bağlayacaksınız.

Bu eğitimin sonunda, yalnızca işlevsel bir yapay zeka asistanına sahip olmakla kalmayacak, aynı zamanda rutin veri görevlerini otomatikleştirebilen, analizi hızlandırabilen ve sizinle ekibiniz için önemli analizlere erişimi demokratikleştirebilen aracıları nasıl oluşturacağınız konusunda da sağlam bir anlayışa sahip olacaksınız.

3. Google Cloud hizmetlerini yapılandırma

Google Cloud projesi oluşturun

Bu codelab'deki tüm çalışmalarınızı düzenli tutmak ve diğer projelerden ayırmak için yeni bir Google Cloud projesi oluşturarak başlayacaksınız.

console.cloud.google.com/projectcreate adresine gidin.
Gerekli bilgileri girin:

Proje adı: İstediğiniz adı girebilirsiniz (ör.genai-workshop).
Konum: Kuruluş Yok olarak bırakın.
Faturalandırma hesabı: Bu seçenek görünürse "Google Cloud Platform Deneme Sürümü Faturalandırma Hesabı"nı veya isterseniz kendi faturalandırma hesabınızı seçin. Bu seçeneği görmüyorsanız bir sonraki adıma geçebilirsiniz.

Oluşturulan proje kimliğini kopyalayın. Daha sonra bu kimliğe ihtiyacınız olacak.

Her şey yolundaysa Oluştur düğmesini tıklayın.

Cloud Shell'i yapılandırma

Projeniz başarıyla oluşturulduktan sonra Cloud Shell'i ayarlamak için aşağıdaki adımları uygulayın.

1. Cloud Shell'i başlatma

shell.cloud.google.com adresine gidin. Yetkilendirme isteyen bir pop-up gösterilirse Yetkilendir'i tıklayın.

2. Proje kimliğini ayarlama

replace-with-your-project-id yerine yukarıdaki proje oluşturma adımındaki gerçek proje kimliğinizi yazın. Doğru Proje Kimliği'ni ayarlamak için Cloud Shell terminalinde aşağıdaki komutu çalıştırın.

gcloud config set project replace-with-your-project-id

Artık Cloud Shell terminalinde doğru projenin seçildiğini görebilirsiniz. Seçilen proje kimliği sarı renkle vurgulanır.

3. Gerekli API'leri etkinleştirme

Google Cloud hizmetlerini kullanmak için önce projenizde ilgili API'leri etkinleştirmeniz gerekir. Bu Codelab'deki hizmetleri etkinleştirmek için Cloud Shell terminalinde aşağıdaki komutları çalıştırın:

gcloud services enable \
 aiplatform.googleapis.com \
 bigquery.googleapis.com

İşlem başarılı olursa terminalinizde Operation/... finished successfully mesajı yazdırılır.

4. Python sanal ortamı oluşturun

Ardından, projenizin bağımlılıklarını yönetmek için izole bir Python ortamı oluşturun.

1. Proje dizini oluşturun ve bu dizine gidin:

mkdir -p ai-agents-adk && cd ai-agents-adk

2. Sanal ortam oluşturup etkinleştirin:

uv venv --python 3.12
source .venv/bin/activate

Terminal isteminizin önüne (ai-agents-adk) önekinin eklendiğini görürsünüz. Bu, sanal ortamın etkin olduğunu gösterir.

3. Install adk page

uv pip install google-adk --no-cache

5. Başlangıç aracısı oluşturma

Ortamınız hazır olduğunda basit bir ADK komutu kullanarak yapay zeka ajanınızı oluşturabilirsiniz.

1. Temsilci oluşturma

Terminalinizde aşağıdaki komutu çalıştırın:

adk create data_analyst_agent

2. Temsilcinizi yapılandırma

Ajanınızı yapılandırmanız istenir. Aşağıdaki seçimleri yapın:

Model seçin: 1'i seçin. gemini-2.5-flash.
Bir arka uç seçin: 2. seçeneği belirleyin. Vertex AI.
Google Cloud proje kimliğini girin: Doğru proje kimliğini onaylamak için Enter tuşuna basın.
Google Cloud bölgesini girin: Varsayılan us-central1 değerini kullanmak için Enter tuşuna basın.

3. Geliştirme web sunucusunu başlatma

Temsilci oluşturulduktan sonra aşağıdaki komutu çalıştırarak geliştirme web sunucusunu başlatın:

adk web

Bağlantıyı Ctrl + tıklayabilir veya Cmd + tıklayabilirsiniz (ör. http://localhost:8000) komutunu terminalde çalıştırabilir veya

Web Önizlemesi düğmesini tıklayın.
Bağlantı Noktasını Değiştir'i seçin.
Bağlantı noktası numarasını girin (ör.8000).
Değiştir ve Önizle'yi tıklayın.

Ardından, tarayıcınızda sohbet uygulamasına benzer bir kullanıcı arayüzü görünür.

4. Temsilcinizle sohbet etme

Bu arayüzü kullanarak temsilcinizle sohbet edebilirsiniz. "Merhaba, neler yapabilirsin?" gibi bir şey söyleyin.

6. Bir Dokümandaki Verileri Analiz Etme

Bu bölümde, temsilciye bir doküman yükleyip içeriği hakkında sorular soracaksınız.

1. Belgeyi özetleme

Dokümanın özetini almak için aşağıdaki adımları uygulayın:

Google'ın Sağlık Hizmetleri Stratejisi ile ilgili dosyayı indirin.
Aracınızın kullanıcı arayüzünde dosya yükle düğmesini tıklayın ve yeni indirdiğiniz dosyayı seçin.
Sohbet arayüzünde, dosyayı özetlemesini isteyin: "Bu dosyanın özetini ver"
Enter tuşuna basın.

Dokümanın içeriğinin kısa bir özetini alırsınız.

2. Daha ayrıntılı sorular sorun

Şimdi, belgeyi daha ayrıntılı incelemek için daha ayrıntılı sorular sormayı deneyin:

Google, yapay zeka ve veri girişimleriyle şu anda hangi temel hastalıkları hedefliyor?
Google, sağlık hizmetleri verilerinin birlikte çalışabilirliğini iyileştirmek ve veri ayrılıklarını ortadan kaldırmak için ne gibi planlar yapıyor?
Google Cloud, sağlık hizmetleri işletmelerini ve araştırmacıları desteklemek için nasıl kullanılıyor?
Google'ın bir sonraki aşamada keşfetmeyi düşündüğü yeni hastalık alanları nelerdir (ör. KOAH, kanser, ruh sağlığı)?

3. Ek soru sorma

Daha ayrıntılı inceleme için sayfa referans numarasını öğrenmek gibi ek sorular da sorabilirsiniz:

Diyabetle ilgili bilgileri nerede gördünüz?
Beni hastalıklarla ilgili sayfalara yönlendir.
İncelemem gereken ilginç grafikler nerede?

Görev: Ajanın analiz etmesini istediğiniz kendi belgenizi bulup yükleyin. Temsilciye içeriğiyle ilgili sorular sorun.

7. Doküman analizlerini canlı web aramasıyla birleştirme

Artık belge konusunda uzman olan temsilcinin, güncel ve harici bilgilere de erişmesi gerekiyor. Ajanımıza web'de arama yapma olanağı verelim.

Web sunucusunu durdurmak için Cloud Shell terminalinde Ctrl+C tuşlarına basın.
Şu komutu çalıştırarak Cloud Shell Düzenleyici'de data_analyst_agent/agent.py dosyasını açın:

cloudshell edit data_analyst_agent/agent.py

google_search aracını içe aktarmak ve eklemek için dosyayı değiştirin:

from google.adk.agents.llm_agent import Agent
from google.adk.tools import google_search

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction="""
        First, check the uploaded files for an answer. 
        If the information is not in the files, use your tools to search the web. 
        Answer user questions to the best of your ability.
    """,
    tools=[
        google_search
    ]
)

Terminalinize adk web yazarak dosyayı kaydedin ve web sunucusunu yeniden başlatın.
Temsilci kullanıcı arayüzünde GoogleHealthStrategy.pdf dosyasını yeniden yükleyin.
Şimdi hem belgenin bağlamını hem de harici bilgileri gerektiren bir soru sorun:

The document discusses Google's strategy in healthcare. What are three other major tech companies that are also investing heavily in healthcare AI, and what are their primary focus areas?

Artık aracı, hem belgedeki hem de canlı Google Arama'daki bilgileri sentezleyerek size kapsamlı bir yanıt verecek. Şu soruları sormayı deneyebilirsiniz:

Dokümanda, diyabetik retinopati için yapay zeka kullanımından bahsediliyor. Bu alanda son bir yıl içinde duyurulan ve FDA tarafından onaylanan en yeni teknolojilerden bazıları nelerdir?
Dosyada iş ortaklıklarından bahsediliyor. Google'ın sağlık sektöründeki son işbirlikleri hakkında yakın tarihli haber makaleleri veya basın bültenleri bulabilir misin?

Challenge: Kendi belgenizle ilgili benzer sorular sormayı deneyin. Yerel bir belgeden ve internetteki sonuçlardan yararlanan bir şey.

8. BigQuery ile sağlık hizmeti verilerini analiz etme

Tek tek doküman yüklemek ölçeklenebilir değildir. Gerçek dünyadaki bir senaryoda veriler, Google Cloud BigQuery gibi kurumsal sistemlerde bulunur.

Şu anda, ajan tabanlı uygulamalar geliştiren geliştiricilerin genellikle kendi özel araçlarını oluşturup bakımını yapması gerekiyor. Bu manuel süreç yavaş, riskli ve önemli bir ek yük oluşturur. Bu durum, geliştiricileri yeniliğe odaklanmak yerine kimlik doğrulama ve hata işleme gibi her şeyi yönetmeye zorlar.

Agent Development Kit (ADK), BigQuery etkileşimi için birinci taraf araçları içerir. Bu analiz için Centers for Medicare & Medicaid Services (CMS) tarafından sağlanan ve herkese açık olan Medicare Kullanım veri kümesini kullanacağız.

Öncelikle aracımızı büyük bir kamu sağlığı veri kümesine bağlayalım.

Cloud Shell terminalinde Ctrl+C tuşlarına basarak web sunucusunu durdurun.
Terminalde şu komutu çalıştırarak Cloud Shell Düzenleyici'de data_analyst_agent/agent.py dosyasını açın:

cloudshell edit data_analyst_agent/agent.py

Güçlü BigQueryToolset özelliğini yapılandırmak için dosyanın tüm içeriğini aşağıdaki kodla değiştirin:

import google.auth
from google.adk.agents.llm_agent import Agent
from google.adk.tools import google_search
from google.adk.tools.agent_tool import AgentTool
from google.adk.tools.bigquery import (
    BigQueryToolset,
    BigQueryCredentialsConfig
)
from google.adk.tools.bigquery.config import (
    BigQueryToolConfig,
    WriteMode
)

# Automatically get credentials from the gcloud environment
application_default_credentials, _ = google.auth.default()
credentials_config = BigQueryCredentialsConfig(
    credentials=application_default_credentials
)

# Configure the BigQuery tool
tool_config = BigQueryToolConfig(
    write_mode=WriteMode.ALLOWED,
    application_name='data_analyst_agent'
)

# Create the toolset with the specified configurations
bigquery_toolset = BigQueryToolset(
    credentials_config=credentials_config, bigquery_tool_config=tool_config
)

# Create an agent with google search tool as a search specialist
google_search_agent = Agent(
    model='gemini-2.5-flash',
    name='google_search_agent',
    description='A search agent that uses google search to get latest information about current events, weather, or business hours.',
    instruction='Use google search to answer user questions about real-time, logistical information.',
    tools=[google_search],
)

# Define the final agent with its instructions and tools
root_agent = Agent(
    model="gemini-2.5-flash",
    name="bigquery_agent",
    description=(
        "Agent to answer questions about BigQuery data and execute SQL queries."
    ),
    instruction="""
        You are an expert data analyst agent with access to BigQuery tools.
        When a user asks about a dataset, first use your tools to understand its schema.
        Then, use this knowledge to construct and execute SQL queries to answer the user's questions.
        Always confirm with the user if their question is ambiguous (e.g., for which year?).
    """,
    tools=[
        AgentTool(google_search_agent),
        bigquery_toolset
    ],
)

Terminalinize adk web yazarak dosyayı kaydedin ve web sunucusunu yeniden başlatın.
Artık aracınızdan herkese açık Medicare veri kümesini analiz etmesini isteyebilirsiniz. Verileri keşfederek başlayın:

Look into the cms_medicare dataset in the bigquery-public-data project. What can you tell me about it?

Ajan, veri kümesini incelemek ve kullanılabilir tabloların listesini sağlamak için araçlarını kullanır. Buradan, belirli analiz sorularıyla ayrıntılı inceleme yapabilirsiniz. Temsilci, sorgularının doğru olduğundan emin olmak için netleştirici sorular sorabilir.

Bazı sorular için, sorgu oluşturmak üzere kullanabilmesi amacıyla proje kimliğini temsilciye sağlamanız gerekir. Örneğin:

Deneyebileceğiniz bazı analitik istem örnekleri:

inpatient_charges_2015 tablosunu kullanarak toplam taburcu sayısına göre en iyi 5 prosedür (DRG tanımları) nedir?
Kaliforniya'da (CA) "BÜYÜK EKLEM DEĞİŞİMİ" için ortalama toplam ödeme tutarı nedir?
Aynı işlem için hangi eyaletteki ortalama karşılanan ücretler en yüksektir?

Bu codelab'in sonuna geldik. Kurumsal veri sistemleri tarafından desteklenen veri aracılarıyla yapabileceklerinizin yalnızca küçük bir kısmını keşfettiniz. cms_medicare veri kümesiyle ilgili sorularınızı temsilcinize sorabilirsiniz.

Zorluk: BigQuery'de başka bir herkese açık veri kümesi bulun ve keşfetmek için aracınızı kullanın. Ayrıca, kendi verilerinizle kendi veri kümenizi oluşturup bunu gizli olarak analiz edebilirsiniz.

9. Temizleme (isteğe bağlı)

Gelecekteki ücretlendirmeleri önlemek için bu codelab'de kullanılan kaynakları silebilirsiniz.

1. Temsilciyi durdurma

Cloud Shell terminalinde adk web işlemini durdurmak için Ctrl+C tuşlarına basın.

2. Proje dosyalarını silme

Aracı kodunu Cloud Shell kabuk ortamınızdan kaldırmak için terminalde aşağıdaki komutu çalıştırın:

cd ~ && rm -rf ai-agents-adk

3. API'leri devre dışı bırakma

Daha önce etkinleştirdiğiniz API'leri devre dışı bırakmak için terminalde aşağıdaki komutu çalıştırın:

gcloud services disable \
 aiplatform.googleapis.com \
 bigquery.googleapis.com

4. Projeyi kapatma

Google Cloud projesinin tamamını silmek istiyorsanız projeleri kapatma kılavuzunu inceleyin.

10. Sonuç

Tebrikler! Agent Development Kit (ADK) çerçevesini kullanarak bir veri analisti temsilcisi oluşturmayı başardınız. Bu temsilci, çeşitli kaynaklardaki verileri analiz edebilir, analizler oluşturabilir ve veri analizi iş akışının bazı bölümlerini otomatikleştirmenize yardımcı olabilir.

Öğrenme yolculuğunuza devam etmek için aşağıdaki kaynakları inceleyin:

Resmi blog yayınını okuyun: Announcing the BigQuery Toolset for AI Agents (Yapay Zeka Aracıları için BigQuery Araç Seti Duyurusu)
Belgeleri inceleyin: Yeni özellikler ve gelişmiş kılavuzlar için resmi Aracı Geliştirme Kiti (ADK) belgelerini ziyaret edin.
Koda göz atma: ADK GitHub deposuna göz atın.
Daha fazla veri keşfedin: Google Cloud herkese açık veri kümeleri kataloğunu keşfedin.