Bu sayfa, Cloud Translation API ile çevrilmiştir.

ADK ile Yapay Zeka Ajanları Geliştirme: Temel

1. Başlamadan önce

"ADK ile Yapay Zeka Temsilcileri Oluşturma" serisinin ilk bölümüne hoş geldiniz. Bu uygulamalı codelab serisinde, Google'ın Agent Development Kit'ini (ADK) kullanarak kendi akıllı yapay zeka aracınızı oluşturacağınız heyecan verici bir yolculuğa çıkacaksınız.

Geliştirme ortamınızı ayarlama ve temel bir sohbet aracısı oluşturma konusunda size yol göstererek en temel bilgilerle başlayacağız. Bu codelab'in sonunda, ilk etkileşimli yapay zekanızı oluşturmuş olacaksınız. Bu yapay zeka, bu serinin sonraki bölümlerinde çoklu aracı sistemine (MAS) dönüştürülürken geliştirilmeye hazır olacak.

Bu codelab'i yerel ortamınızda veya Google Cloud'da tamamlayabilirsiniz. En tutarlı deneyim için Google Cloud ortamındaki Cloud Shell'i kullanmanızı öneririz. Cloud Shell, $HOME dizininde 5 GB kalıcı depolama alanı da sağlar. Bu, komut dosyalarını, yapılandırma dosyalarını veya klonlanmış depoları depolamak için kullanışlıdır.

Bu codelab'e goo.gle/adk-foundation kısaltılmış URL'si üzerinden de erişebilirsiniz.

Ön koşullar

Üretken yapay zeka kavramları hakkında bilgi sahibi olmak
Python programlama konusunda temel düzeyde yeterlilik
Komut satırı / terminal hakkında bilgi sahibi olma

Neler öğreneceksiniz?

Python ortamı oluşturma
ADK'yı kullanarak basit bir kişisel asistan aracısı oluşturma
Aracıyı çalıştırma, test etme ve hata ayıklama

Gerekenler

Çalışan bir bilgisayar ve güvenilir kablosuz bağlantı
Google Cloud Console'a erişmek için Chrome gibi bir tarayıcı
Meraklı bir zihin ve öğrenme isteği

2. Giriş

Üretken yapay zeka dünyası hızla gelişiyor ve yapay zeka aracıları şu anda popüler bir konu. Yapay zeka aracısı, kişisel asistan gibi sizin adınıza hareket etmek üzere tasarlanmış akıllı bir bilgisayar programıdır. Dijital ortamını algılayabilir, kararlar verebilir ve doğrudan insan kontrolü olmadan belirli hedeflere ulaşmak için eylemlerde bulunabilir. Bunu, işleri halletmek için öğrenebilen ve uyum sağlayabilen proaktif, bağımsız bir varlık olarak düşünebilirsiniz.

Yapay zeka aracısı, temel olarak anlamak ve akıl yürütmek için "beyin" olarak büyük dil modelini (LLM) kullanır. Bu sayede metin, resim ve ses gibi çeşitli kaynaklardan gelen bilgileri işleyebilir. Ardından, bu anlayışı kullanarak bir plan oluşturur ve önceden tanımlanmış bir hedefe ulaşmak için bir dizi görevi yerine getirir.

Agent Development Kit (ADK) gibi kullanıma hazır çerçeveler sayesinde artık derin bir uzmanlığa sahip olmasanız bile kendi yapay zeka temsilcilerinizi kolayca oluşturabilirsiniz. Bu yolculuğa, görevlerinizde size yardımcı olacak kişisel asistan aracısı oluşturarak başlayacağız. Başlayalım!

3. Google Cloud Hizmetlerini Yapılandırma

Google Cloud projesi oluşturma

Bu codelab'deki etkinliklerin yalnızca bu yeni proje içinde izole edilmesi için yeni bir Google Cloud projesi oluşturarak başlayın.

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çeneği görüyorsanız Google Cloud Platform Deneme Sürümü Faturalandırma Hesabı'nı seçin. Bu seçeneği görmüyorsanız endişelenmeyin. Bir sonraki adıma geçmeniz yeterlidir.

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 ve yetkilendirmenizi isteyen bir pop-up görürseniz Yetkilendir'i tıklayın.

2. Proje kimliğini ayarlama

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

gcloud config set project <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

İşlem başarılı olursa terminalinizde Operation/... finished successfully ifadesi gösterilir.

4. Python sanal ortamı oluşturun

Herhangi bir Python projesine başlamadan önce sanal ortam oluşturmak iyi bir uygulamadır. Bu, projenin bağımlılıklarını yalıtarak diğer projelerle veya sistemin genel Python paketleriyle çakışmaları önler.

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

mkdir 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. adk sayfasını yükleme

uv pip install google-adk

5. Temsilci oluşturun

Ortamınız hazır olduğunda yapay zeka temsilcinizin temelini oluşturabilirsiniz. ADK, temsilcinizin mantığını ve yapılandırmasını tanımlamak için birkaç dosya gerektirir:

agent.py: Aracınızın adını, kullandığı LLM'yi ve temel talimatlarını tanımlayan birincil Python kodunu içerir.
__init__.py: Dizini Python paketi olarak işaretler. Bu sayede ADK, aracı tanımınızı keşfedip yükleyebilir.
.env: API anahtarı, proje kimliği ve konum gibi hassas bilgileri ve yapılandırma değişkenlerini depolar.

Bu komut, üç temel dosyayı içeren personal_assistant adlı yeni bir dizin oluşturur.

adk create personal_assistant

Komut yürütüldükten sonra, aracınızı yapılandırmak için birkaç seçenek belirlemeniz istenir.

İlk adımda, gemini-2.5-flash modelini kullanmak için 1. seçeneği belirleyin. Bu model, sohbet görevleri için ideal olan hızlı ve verimli bir modeldir.

Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1

İkinci adımda, arka uç hizmet sağlayıcı olarak Google Cloud'un güçlü ve yönetilen yapay zeka platformu Vertex AI'ı (2. seçenek) seçin.

1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

Ardından, köşeli parantezlerin [...] içinde gösterilen proje kimliğinin doğru ayarlandığını doğrulamanız gerekir. Doğruysa Enter tuşuna basın. Doğru değilse aşağıdaki istemde doğru proje kimliğini girin:

Enter Google Cloud project ID [your-project-id]:

Son olarak, bu codelab'de us-central1 bölgesini kullanmak için sonraki soruda Enter tuşuna basın.

Enter Google Cloud region [us-central1]:

Terminalinizde benzer bir çıkış görmeniz gerekir.

Agent created in /home/<your-username>/ai-agent-adk/personal_assistant:
- .env
- __init__.py
- agent.py

6. Temsilci kodlarını keşfetme

Oluşturulan dosyaları görüntülemek için Cloud Shell Düzenleyici'de ai-agents-adk klasörünü açın.

Üst menüde Dosya > Klasörü Aç... seçeneğini tıklayın.
ai-agents-adk klasörünü bulup seçin.
Tamam'ı tıklayın.

Üstteki menü çubuğu görünmüyorsa klasörler simgesini tıklayıp Klasörü Aç'ı da seçebilirsiniz.

Düzenleyici penceresi tamamen yüklendikten sonra personal-assistant klasörüne gidin. Yukarıda belirtilen gerekli dosyaları (agent.py, __init__.py ve .env) görürsünüz.

.env dosyası genellikle varsayılan olarak gizlenir. Cloud Shell Düzenleyici'de görünür hale getirmek için:

en üstteki menü çubuğuna gidin,
Görünüm'ü tıklayın ve
Gizli Dosyaları Aç/Kapat'ı seçin.

Her dosyanın içeriğini keşfedin.

agent.py

Bu dosya, google.adk.agents kitaplığındaki Agent sınıfını kullanarak aracınızı oluşturur.

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

from google.adk.agents import Agent: Bu satır, ADK kitaplığından gerekli Agent sınıfını içe aktarır.
root_agent = Agent(...): Burada, yapay zeka temsilcinizin bir örneğini oluşturuyorsunuz.
name="root_agent": Aracınızın benzersiz tanımlayıcısı. ADK, temsilcinizi bu şekilde tanır ve ona bu şekilde atıfta bulunur.
model="gemini-2.5-flash": Bu önemli parametre, aracınızın anlama, akıl yürütme ve yanıt oluşturma için temel "beyin" olarak hangi büyük dil modelini (LLM) kullanacağını belirtir. gemini-2.5-flash, sohbet görevleri için uygun olan hızlı ve verimli bir modeldir.
description="...": Bu, aracının amacının veya özelliklerinin kısa bir özetini sağlar. Açıklama, daha çok insanların anlaması veya çoklu temsilci sistemindeki diğer temsilcilerin bu temsilcinin ne yaptığını anlaması için kullanılır. Genellikle günlük kaydı, hata ayıklama veya aracıyla ilgili bilgileri gösterme için kullanılır.
instruction="...": Bu, aracınızın davranışını yönlendiren ve kişiliğini tanımlayan sistem istemidir. Bu talimat, LLM'ye nasıl davranması gerektiğini ve asıl amacının ne olduğunu söyler. Bu örnekte, aracı "faydalı bir asistan" olarak tanımlar. Bu talimat, aracının sohbet tarzını ve yeteneklerini şekillendirmek için çok önemlidir.

init.py

Bu dosya, Python'ın personal-assistant dosyasını paket olarak tanıması için gereklidir. Böylece ADK, agent.py dosyanızı doğru şekilde içe aktarabilir.

from . import agent

from . import agent: Bu satır, göreli bir içe aktarma işlemi gerçekleştirerek Python'a geçerli paket (personal-assistant) içinde agent adlı bir modül (agent.py'ye karşılık gelir) aramasını söyler. Bu basit satır, ADK'nın personal-assistant aracınızı yüklemeye çalıştığında agent.py içinde tanımlanan root_agent'yi bulup başlatabilmesini sağlar. Boş olsa bile, dizinin Python paketi olmasını sağlayan __init__.py dosyasıdır.

.env

Bu dosya, ortama özel yapılandırmaları ve hassas kimlik bilgilerini içerir.

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION

GOOGLE_GENAI_USE_VERTEXAI: Bu, ADK'ya üretken yapay zeka işlemleriniz için Google'ın Vertex AI hizmetini kullanmayı planladığınızı bildirir. Bu, Google Cloud'un yönetilen hizmetlerinden ve gelişmiş modellerinden yararlanmak için önemlidir.
GOOGLE_CLOUD_PROJECT: Bu değişken, Google Cloud projenizin benzersiz tanımlayıcısını tutar. ADK, aracınızı bulut kaynaklarınızla doğru şekilde ilişkilendirmek ve faturalandırmayı etkinleştirmek için bu bilgiye ihtiyaç duyar.
GOOGLE_CLOUD_LOCATION: Bu, Vertex AI kaynaklarınızın bulunduğu Google Cloud bölgesini belirtir (ör. us-central1). Doğru konumu kullanmak, aracınızın o bölgedeki Vertex AI hizmetleriyle etkili bir şekilde iletişim kurmasını sağlar.

7. Terminalde aracıyı çalıştırma

Üç dosya da yerinde olduğunda aracıyı doğrudan terminalden çalıştırmaya hazırsınız demektir. Bunu yapmak için terminalde aşağıdaki adk run komutunu çalıştırın:

adk run personal_assistant

Her şey doğru şekilde ayarlanmışsa terminalinizde benzer bir çıktı görürsünüz. [user]: simgesini gördüğünüz sürece uyarılar konusunda endişelenmenize gerek yoktur.

...
Running agent personal_assistant, type exit to exit.
[user]: 
...

Devam edin ve temsilciyle sohbet edin. "Merhaba. Benim için ne yapabilirsin?" sorusuna yanıt alırsınız.

...
Running agent personal_assistant, type exit to exit.
[user]: hello. What can you do for me?
[personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as:
...

Çıktının bazen Markdown ile biçimlendirildiğini fark edebilirsiniz. Bu biçimlendirme, terminalde okunmayı zorlaştırabilir. Bir sonraki adımda, çok daha zengin ve sohbet uygulamasına benzer bir deneyim için Geliştirme kullanıcı arayüzünü kullanacağız.

Sorun giderme

Bu API yöntemi, faturalandırmanın etkinleştirilmiş olmasını gerektirir

{‘message': ‘This API method requires billing to be enabled'} mesajını alırsanız aşağıdakileri yapın:

.env dosyasında doğru proje kimliğini kullanıp kullanmadığınızı kontrol edin.
Bağlı faturalandırma hesabı sayfasına gidip faturalandırma hesabının zaten bağlı olup olmadığını kontrol edin.
Aksi takdirde, seçenekler arasından Google Cloud Platform Deneme Sürümü Faturalandırma Hesabı'nı seçin.

Vertex AI API, projede kullanılmamış

{'message': 'Vertex AI API has not been used in project...'} içeren bir hata mesajı alırsanız terminale şunu yazarak Vertex AI API'yi etkinleştirin:

gcloud services enable aiplatform.googleapis.com

İşlem başarılı olursa terminalinizde Operation/... finished successfully ifadesi gösterilir.

Diğer Hatalar

Yukarıda belirtilmeyen başka hatalar alırsanız tarayıcıda Cloud Shell sekmesini yeniden yüklemeyi deneyin (istenirse yeniden yetkilendirin).

8. Temsilciyi geliştirme web kullanıcı arayüzünde çalıştırma

Agent Development Kit, geliştirme kullanıcı arayüzünü kullanarak aracınızı bir sohbet uygulaması olarak başlatmanın kolay bir yolunu da sunar. adk run. yerine adk web komutunu kullanmanız yeterlidir.

Terminalinizde hâlâ adk run çalışıyorsa bu komutu yazmadan önce exit yazarak kapatın:

adk web

Terminalde benzer bir çıkış görmeniz gerekir:

...
INFO:     Started server process [4978]
INFO:     Waiting for application startup.

+------------------------------------------------------+
| ADK Web Server started                               |
|                                                      |
| For local testing, access at http://localhost:8000.  |
+------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Geliştirme kullanıcı arayüzüne erişmek için iki seçeneğiniz vardır:

Terminal üzerinden açma

Bağlantıyı Ctrl + tıklayın veya Cmd + tıklayın (ör. http://localhost:8000) terminalde gösterildiği gibi.

Web Önizlemesi ile açma

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. Bu arayüzü kullanarak kişisel asistanınızla sohbet edebilirsiniz.

Markdown biçimlendirmesinin artık doğru şekilde görüntülendiğini fark edeceksiniz. Bu kullanıcı arayüzü, her mesajlaşma etkinliğinde, temsilcinin durumunda, kullanıcı isteklerinde ve daha pek çok durumda hata ayıklama ve inceleme yapmanıza da olanak tanır. Keyifli sohbetler!

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

Bu codelab'de uzun süreli ürünler kullanılmadığından, terminalde Ctrl + C veya Cmd + C tuşlarına basarak etkin aracı oturumlarınızı (ör. terminalinizdeki adk web örneği) durdurmanız yeterlidir.

Aracı Proje Klasörlerini ve Dosyalarını Silme

Yalnızca kodu Cloud Shell ortamınızdan kaldırmak istiyorsanız aşağıdaki komutları kullanın:

cd ~
rm -rf ai-agents-adk

Vertex AI API'yi devre dışı bırakma

Daha önce etkinleştirilen Vertex AI API'yi devre dışı bırakmak için şu komutu çalıştırın:

gcloud services disable aiplatform.googleapis.com

Google Cloud projesinin tamamını kapatma

Google Cloud projenizi tamamen kapatmak istiyorsanız ayrıntılı talimatlar için resmi kılavuza bakın.

10. Sonuç

Tebrikler! Aracı Geliştirme Kitini (ADK) kullanarak basit bir kişisel asistan aracısı oluşturmayı başardınız. Artık bir ADK aracısının temel bileşenleri hakkında sağlam bir temel ve anlayışa sahipsiniz.

Bir sonraki adım olarak, aracınıza gerçek zamanlı bilgilere erişme ve harici hizmetlerle etkileşim kurma araçları vererek yeteneklerini önemli ölçüde genişletebilirsiniz. Yolculuğunuza devam etmek istiyorsanız bu serideki bir sonraki codelab olan ADK ile Yapay Zeka Aracı Geliştirme: Araçlarla Güçlendirme, bu süreçte size rehberlik edecektir.