ADK ile Yapay Zeka Ajanları Oluşturma: Araçlarla Güçlendirme

1. Başlamadan önce

"ADK ile Yapay Zeka Ajanları Oluşturma" serisinin ikinci bölümüne hoş geldiniz. Bu uygulamalı codelab'de, temel bir yapay zeka aracını çeşitli araçlarla güçlendireceksiniz.

Bu rehber, başlamanıza yardımcı olmak için iki yol sunar: Biri " ADK ile Yapay Zeka Ajanları Oluşturma: Temel Bilgiler" adlı codelab'den devam edenler, diğeri ise sıfırdan başlayanlar için. Her iki yöntem de başlamak için gerekli temel aracı koduna sahip olmanızı sağlar.

Bu codelab'i tamamladığınızda kişisel asistan aracınızı çeşitli amaçlara yönelik araçlarla güçlendirmiş olacaksınız. Bu sayede, onu gelişmiş bir çoklu aracı sistemine (MAS) dönüştürürken bu serinin sonraki bölümlerinde daha da genişletmeye bir adım daha yaklaşacaksınız.

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

Ön koşullar

Üretken yapay zeka kavramları hakkında bilgi sahibi olmak
Python programlama konusunda temel düzeyde yeterlilik
ADK ile Yapay Zeka Ajanları Oluşturma: Temel Bilgiler adlı codelab'i veya benzer bir codelab'i tamamlamış olmak

Neler öğreneceksiniz?

Araç olarak özel Python işlevleri oluşturarak aracınıza yeni beceriler kazandırın.
Google Arama gibi yerleşik araçları kullanarak aracınızı gerçek zamanlı bilgilere bağlayın.
Karmaşık görevler için özel alt aracılar oluşturarak çok araçlı bir aracı yapılandırın.
LangChain gibi popüler yapay zeka çerçevelerindeki araçları entegre ederek özellikleri hızla genişletin.

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ş

ADK ile oluşturulan temel bir aracı, güçlü bir LLM beynine sahiptir ancak sınırlamaları da vardır: Eğitim tarihinden sonra oluşturulan bilgilere erişemez ve harici hizmetlerle etkileşime giremez. Telefonu veya interneti olmayan bir kütüphaneye kilitlenmiş, zeki ve bilgili bir asistana benzer. Bir ajanın gerçekten faydalı olması için ona araçlar sağlamamız gerekir.

Araçları, yapay zeka asistanına dış dünyaya erişim izni veren bir hesap makinesi, web tarayıcısı veya belirli bir şirket veritabanına erişim gibi düşünebilirsiniz. ADK'da araç, aracının gerçek zamanlı verileri arama veya harici bir API'yi çağırma gibi belirli işlemleri gerçekleştirmesine olanak tanıyan modüler bir kod parçasıdır. Araçlar kullanıldığında bu özellik, basit bir sohbetin çok ötesine geçer.

ADK üç kategoride araç sunar:

İşlev Araçları: Uygulamanızın benzersiz gereksinimlerini karşılamak için geliştirdiğiniz özel araçlar (ör. önceden tanımlanmış işlevler ve aracılar).
Yerleşik Araçlar: Google Arama ve Kod Yürütme gibi yaygın işlemler için çerçeve tarafından sağlanan, kullanıma hazır araçlar.
Üçüncü taraf araçlar: Serper gibi popüler harici kitaplıklar ve LangChain ile CrewAI'ın araçları.

ADK Ajanları ile Araçları kullanma hakkında daha fazla bilgi edinmek için resmi belgelere göz atın. Bu codelab'de, basit aracımızı yetenekli bir kişisel seyahat asistanına dönüştürmek için araçlar ekleyeceğiz. Başlayalım!

3. Başlangıç: Temel Temsilciniz

Bir temsilciyi araçlarla destekleyebilmeniz için öncelikle üzerinde çalışacağınız temel bir temsilciye ihtiyacınız vardır. İlerlemenize en uygun yolu seçin.

A yolu: Foundation Codelab'den devam etme

"ADK ile Yapay Zeka Ajanları Oluşturma: Temel Bilgiler" adlı codelab'i yeni tamamladıysanız hazırsınız demektir. Mevcut ai-agents-adk proje dizininizde çalışmaya devam edebilirsiniz.

B yolu: Yeni bir başlangıç yapma

Bu codelab'e doğrudan başlıyorsanız ortamınızı ayarlamak ve gerekli başlangıç aracısını oluşturmak için bu 4 adımı tamamlayın.

Adımları tamamladıktan sonra öğrenme yolculuğunuza başlayabilirsiniz.

4. Döviz kuru için özel bir araç oluşturma

Bu aşamada, ADK kullanarak basit bir yapay zeka ajanı oluşturmayı ve bunu geliştirme kullanıcı arayüzünde çalıştırmayı zaten biliyor olmanız gerekir.

Önümüzdeki ay Japonya'ya gitmek için hazırlık yaptığınızı ve mevcut döviz kurunu kontrol etmeniz gerektiğini düşünün. Temsilciye "Singapur doları ile Japon yeninin döviz kuru nedir?" diye sorun.

Ajanın gerçek zamanlı döviz kurlarını alamadığını görürsünüz. Bunun nedeni, temsilcinin şu anda internet erişiminin ve harici sistem bağlantısının olmamasıdır. Aracı bir değerle yanıt verse bile, halüsinasyon olma ihtimali yüksek olduğundan bu değere güvenmek zordur.

Bu sorunu çözmek için bir REST API aracılığıyla döviz kurlarını alacak bir Python işlevi uygulayacak ve bunu aracı için İşlev Aracı olarak entegre edeceğiz.

Terminal penceresinde Ctrl + C klavye kısayolunu kullanarak çalışan aracı işlemini sonlandırın.

`custom_functions.py` dosyası oluşturma

personal_assistant klasöründe custom_functions.py adlı bir Python dosyası oluşturmak ve bu dosyayı Kod Düzenleyici'de açmak için terminalde bu komutu yürütün.

cloudshell edit personal_assistant/custom_functions.py

Klasör yapınız artık şu şekilde görünmelidir:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    └── custom_functions.py

Bu custom_functions.py dosyası, döviz kuru verilerini harici bir API'den almaktan sorumlu Python işlevini içerir. Aşağıdaki kodu kopyalayıp dosyaya yapıştırın:

import requests

# define a function to get exchange rate
def get_fx_rate(base: str, target: str):
        """
        Fetches the current exchange rate between two currencies.

        Args:
                base: The base currency (e.g., "SGD").
                target: The target currency (e.g., "JPY").

        Returns:
                The exchange rate information as a json response,
                or None if the rate could not be fetched.
        """
        base_url = "https://hexarate.paikama.co/api/rates/latest"
        api_url = f"{base_url}/{base}?target={target}"

        response = requests.get(api_url)
        if response.status_code == 200:
                return response.json()

Şimdi agent.py dosyasını düzenleyin: get_fx_rate işlevini içe aktarın ve FunctionTool olarak atayın.

`agent.py` dosyasını güncelleme

Bu kod bloğunu kopyalayın ve agent.py dosyasının mevcut içeriğini değiştirin:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool

from .custom_functions import get_fx_rate

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',
    tools=[FunctionTool(get_fx_rate)]
)

Değişikliklerden sonra şu komutu yazarak temsilciyi tekrar başlatın:

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

Müşteri temsilcisi hazır olduğunda aynı soruyu tekrar sorun: "Singapur doları ile Japon yeni arasındaki döviz kuru nedir?"

Bu kez, get_fx_rate aracının verdiği gerçek döviz kurunu görürsünüz.

Dilediğiniz kadar döviz kuruyla ilgili soru sorabilirsiniz.

5. Yerleşik Google Arama Aracı ile Entegrasyon

Artık döviz kurlarını sağlayabilen ajanla bir sonraki görev, gelecek ayın hava durumu tahminini almak. Ajana şu soruyu sorun: "Japonya'nın Tokyo şehrinde gelecek ay hava nasıl olacak?"

Hava durumu tahmini için gerçek zamanlı bilgi gerekir. Bu bilgi, aracımızda bulunmamaktadır. Gerçek zamanlı verilerin gerektiği her kullanım alanı için yeni Python işlevleri kodlayabilsek de giderek daha fazla özel araç eklemek, aracıyı çok karmaşık ve yönetilmesi zor hale getiriyor.

Neyse ki Agent Development Kit (ADK), Google Arama da dahil olmak üzere kullanıma hazır bir dizi yerleşik araç sunarak aracımızın dış dünyayla etkileşimini kolaylaştırıyor.

Aracıya Google Arama aracını eklemek için çoklu aracı kalıbını uygulamanız gerekir. Öncelikle tek görevi Google aramaları yapmak olan özel bir temsilci oluşturursunuz. Ardından, bu yeni Google Arama Aracısı'nı ana personal_assistant'mıza araç olarak atarsınız. İlgili adımlar aşağıdadır:

`custom_agents.py` dosyası oluşturma

Terminalde bu komutu çalıştırarak personal_assistant klasöründe custom_agents.py adlı bir Python dosyası oluşturun ve bu dosyayı Kod Düzenleyici'de açın:

cloudshell edit personal_assistant/custom_agents.py

Klasör yapınız artık şu şekilde görünmelidir:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    └── custom_agents.py

Bu custom_agents.py dosyası, özel google_search_agent için kodu içerir. Aşağıdaki kodu custom_agents.py dosyasına kopyalayın:

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


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

Dosya oluşturulduktan sonra agent.py dosyasını aşağıda gösterildiği gibi güncelleyin.

`agent.py` dosyasını güncelleme

Bu kod bloğunu kopyalayın ve agent.py dosyasının mevcut içeriğini değiştirin:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools.agent_tool import AgentTool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent


root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        AgentTool(agent=google_search_agent),
    ]
)

Koddaki güçlü yeni kalıbı inceleyelim:

Yeni bir uzman temsilci: Tamamen yeni bir temsilci tanımladık: google_search_agent. Bu aracın özel açıklamasını ve tek aracının google_search olduğunu unutmayın. Arama uzmanı
agent_tool.AgentTool: Bu, ADK'dan alınan özel bir sarmalayıcıdır. Bu işlev, bir ajanın tamamını (google_search_agent) alıp standart bir araç gibi görünecek ve davranacak şekilde paketler.
Daha Akıllı **root_agent**: root_agent aracımıza AgentTool(agent=google_search_agent) adlı yeni bir araç eklendi. Web'de nasıl arama yapacağını bilmez ancak arama görevlerini devredebileceği bir aracı olduğunu bilir.

Talimat alanının root_agent'dan kaldırıldığını fark edin. Talimatları artık sahip olduğu araçlarla örtülü olarak tanımlanıyor.

root_agent, kullanıcının isteğini anlayıp get_fx_rate işlevine veya google_search_agent'ye iletmekle görevli bir düzenleyici ya da yönlendirici haline geldi. Bu merkeziyetsiz tasarım, karmaşık ve bakımı kolay aracı sistemleri oluşturmak için çok önemlidir.

Şimdi örneği başlatmak için terminale şu komutu girin:

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

Ajan çalıştıktan sonra ajana tekrar şu soruyu sorun: "Japonya'nın Tokyo şehrinde gelecek ay hava nasıl olacak?"

Temsilci artık en son bilgileri almak için google_search_agent kullanıyor

Güncel bir döviz kuru sorusu da sorabilirsiniz. Temsilci artık ilgili soru için doğru aracı kullanabilir.

Temsilciye anlık bilgi gerektiren başka sorular da sorabilir ve elindeki araçları kullanarak sorguları nasıl işlediğini gözlemleyebilirsiniz.

6. LangChain'in Wikipedia aracından yararlanma

Temsilcimiz, harika bir seyahat asistanı olmaya hazırlanıyor. get_fx_rate aracıyla döviz işlemlerini, google_search_agent aracıyla da lojistik işlemlerini yönetebilir. Ancak harika bir gezi sadece lojistikle ilgili değildir. Gittiğiniz yerin kültürünü ve tarihini anlamak da önemlidir.

google_search_agent, kültürel ve tarihi gerçekleri bulabilir ancak Wikipedia gibi özel bir kaynaktan alınan bilgiler genellikle daha yapılandırılmış ve güvenilirdir.

Neyse ki ADK, yüksek oranda genişletilebilir şekilde tasarlanmıştır. Bu sayede CrewAI ve LangChain gibi diğer yapay zeka aracı çerçevelerindeki araçları sorunsuz bir şekilde entegre edebilirsiniz. Bu birlikte çalışabilirlik, daha hızlı geliştirme süresi sağlaması ve mevcut araçları yeniden kullanmanıza olanak tanıması nedeniyle çok önemlidir. Bu kullanım alanında LangChain'deki Wikipedia araçlarından yararlanacağız.

Öncelikle çalışan aracı işlemini durdurun (Ctrl + C) ve Terminal'e aşağıdaki komutları yazarak mevcut Python sanal ortamına ek kitaplıklar yükleyin.

uv pip install langchain-community wikipedia

`third_party_tools.py` dosyası oluşturma

Aşağıdaki komut, personal_assistant klasöründe third_party_tools.py adlı bir Python dosyası oluşturur ve Cloud Düzenleyici'de açar:

cloudshell edit personal_assistant/third_party_tools.py

Klasör yapınız artık şu şekilde görünmelidir:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    ├── custom_agents.py
    └── third_party_tools.py

Bu dosya, LangChain Wikipedia aracının uygulamasını içerir. Aşağıdaki kodu third_party_tools.py dosyasına kopyalayın**:**

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

# Configure the Wikipedia LangChain tool to act as our cultural guide
langchain_wikipedia_tool = WikipediaQueryRun(
    api_wrapper=WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=3000)
)

# Give the tool a more specific description for our agent
langchain_wikipedia_tool.description = (
    "Provides deep historical and cultural information on landmarks, concepts, and places."
    "Use this for 'tell me about' or 'what is the history of' type questions."
)

`agent.py` dosyasını güncelleme

Şimdi agent.py dosyasını aşağıdaki içerikle güncelleyin:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools.agent_tool import AgentTool
from google.adk.tools.langchain_tool import LangchainTool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent
from .third_party_tools import langchain_wikipedia_tool


root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        AgentTool(agent=google_search_agent),
        LangchainTool(langchain_wikipedia_tool),
    ]
)

Şimdi örneği başlatmak için terminale şu komutu girin:

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

Temsilci hazır olduğunda ona "Kyoto'nun tarihi hakkında bilgi ver" sorusunu sorun.

Aracı, bunu doğru şekilde geçmişe yönelik bir sorgu olarak tanımlar ve yeni Wikipedia aracını kullanır. Üçüncü taraf bir aracı entegre edip belirli bir rol vererek seyahat planlama amacıyla kullanacağınız aracınızı önemli ölçüde daha akıllı ve faydalı hale getirdiniz.

Temsilcinin bu seçimi tam olarak nasıl yaptığını görmek için adk web kullanıcı arayüzündeki etkinlik inceleyiciyi kullanabilirsiniz. Etkinlikler sekmesini ve ardından en son functionCall etkinliğini tıklayın.

İnceleyici, mevcut tüm araçların listesini gösterir ve temsilci tarafından yürütülen aracın tool_code'unu vurgular.

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

Bu codelab'de uzun süreli çalışan ürünler yer almadığından, terminalde Ctrl + 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.

8. Sonuç

Tebrikler! Kişisel asistan aracısını özel işlevler ve gerçek zamanlı Google Arama erişimiyle başarıyla desteklediniz. Google ADK ile araçları kullanma hakkında bu resmi dokümanı okuyun.

Daha da önemlisi, yetenekli aracıları oluşturmak için temel mimari kalıbı (araç olarak özel aracıları kullanma) öğrendiniz. Özel bir google_search_agent oluşturup root_agent'nize vererek tek bir temsilci oluşturmaktan basit ama güçlü bir çoklu temsilci sistemi düzenlemeye geçiş yaptınız.

Artık serinin bir sonraki codelab'ine (yakında yayınlanacak) hazırsınız. Bu codelab'de birden fazla aracı ve iş akışını düzenleme konusunu daha ayrıntılı olarak ele alacağız. Orada görüşmek üzere.

ADK ile Yapay Zeka Ajanları Oluşturma: Araçlarla Güçlendirme Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

1. Başlamadan önce

Ön koşullar

Neler öğreneceksiniz?

Gerekenler

2. Giriş

3. Başlangıç: Temel Temsilciniz

4. Döviz kuru için özel bir araç oluşturma

custom_functions.py dosyası oluşturma

agent.py dosyasını güncelleme

5. Yerleşik Google Arama Aracı ile Entegrasyon

custom_agents.py dosyası oluşturma

agent.py dosyasını güncelleme

6. LangChain'in Wikipedia aracından yararlanma

third_party_tools.py dosyası oluşturma

agent.py dosyasını güncelleme

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

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

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

Google Cloud projesinin tamamını kapatma

8. Sonuç

ADK ile Yapay Zeka Ajanları Oluşturma: Araçlarla Güçlendirme

`custom_functions.py` dosyası oluşturma

`agent.py` dosyasını güncelleme

`custom_agents.py` dosyası oluşturma

`agent.py` dosyasını güncelleme

`third_party_tools.py` dosyası oluşturma

`agent.py` dosyasını güncelleme