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

1. Başlamadan önce

LÜTFEN OKUYUN:

Bu eğitim için etkin bir faturalandırma hesabına sahip bir Google Cloud projesi gerekir.

Yüz yüze atölye katılımcıları için

• Eğitmeninizin verdiği özel kurulum ve faturalandırma talimatlarını uygulayın.

Kendi Kendine Çalışan Kullanıcılar İçin

• Deneme sürümünü kullanmak için aşağıdaki adımları uygulayın:

1. Tarayıcınızda gizli pencere açın.
2. Bu ödül alma portalına gidin.
3. Kişisel Gmail hesabınızı kullanarak giriş yapın.
4. Portaldaki adım adım talimatları uygulayın.

"ADK ile Yapay Zeka Aracı 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.

Başlamak için bu kılavuzda iki yol sunulmaktadır: Biri " ADK ile Yapay Zeka Temsilcileri 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'in sonunda, kişisel asistan aracınızı çeşitli amaçlara yönelik araçlarla güçlendirmiş olacaksınız. Bu araçlar, bu serinin sonraki bölümlerinde, kişisel asistan aracınızı gelişmiş bir çoklu aracı sistemine (MAS) dönüştürürken daha da geliştirilecek.

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ı Geliştirme: Temeller 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 yapay zekanın gerçekten faydalı olabilmesi için ona araçlar sunmamı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ç, temsilcinin 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 basit sohbetin çok ötesine geçer.

ADK üç kategoride araç sunar:

1. İş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).
2. 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.
3. Üçüncü taraf araçlar: Serper gibi popüler harici kitaplıklar ve LangChain ile CrewAI'ın araçları.

Araçları ADK aracılarıyla 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şlarken: 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 Aracı 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.

1. Google Cloud Hizmetlerini Yapılandırma
2. Python sanal ortamı oluşturma
3. Temsilci oluşturma
4. Aracı geliştirme kullanıcı arayüzünde çalıştırma

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'yı kullanarak basit bir yapay zeka aracısı oluşturmayı ve bu aracıyı geliştirme kullanıcı arayüzünde çalıştırmayı öğrenmiş olmanız gerekir.

Önümüzdeki ay Japonya'ya gitmek için hazırlanıyorsunuz ve mevcut döviz kurunu kontrol etmeniz gerekiyor. Temsilciye "Singapur doları ile Japon yeninin döviz kuru nedir?" diye sorun.

Aracını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

Not: Devam etmeden önce doğru dizinde (ai-agents-adk) olduğunuzdan emin olun. Mevcut konumunuzu kontrol etmek için terminalinizde pwd (print working directory) komutunu çalıştırabilirsiniz.

Terminalde bu komutu yazarak personal_assistant klasöründe custom_functions.py adlı bir Python dosyası oluşturun.

touch personal_assistant/custom_functions.py

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

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

Kod Düzenleyici'de custom_functions.py simgesini açın. Bu dosya, döviz kuru verilerini harici bir API'den almaktan sorumlu Python işlevini içerir.

Aşağıdaki kodu kopyalayıp 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()

Not: Üçlü tırnak işaretleri ("""...""") arasındaki açıklayıcı metne dikkat edin. Bu metne docstring adı verilir. Bu, insan geliştiriciler için iyi bir uygulama olsa da yapay zeka aracı için gereklidir.

Aracının temelindeki LLM, aracın ne yaptığını, bağımsız değişkenlerinin (bu örnekte base ve target) ne anlama geldiğini ve ne zaman kullanılması gerektiğini anlamak için işlev adını ve bu docstring'i okur.

Temsilcinin aracınızı doğru şekilde kullanması için en önemli faktör, net ve açıklayıcı bir docstring'dir.

Ş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)]
)

Not: ADK, aracı klasörünü bir Python modülü olarak çalıştırdığından diğer Python dosyalarındaki işlevleri içe aktarmak için göreli içe aktarma işlemi gerekir. Bu yaklaşım, küçük bir araç seti için uygundur ancak araç büyüdükçe bir araç paketi oluşturmamız gerekir.

Değişikliklerden sonra aşağıdaki komutu yazarak aracıyı tekrar başlatın:

adk web

Müşteri temsilcisi bağlandığında 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 gibi döviz kuruyla ilgili sorular 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. Aracıya şu soruyu sorun: "Japonya'nın Tokyo şehrinde gelecek ay hava nasıl olacak?"

Tahmin edebileceğiniz gibi, hava durumu tahmini için gerçek zamanlı bilgi gerekir ancak temsilcimiz bu bilgiye sahip değildir. 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 Built-in Tools (Yerleşik Araçlar) 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 aracı oluşturursunuz. Ardından, bu yeni Google Arama Aracısı'nı ana personal_assistant'mıza araç olarak atarsınız. Şu adımları uygulayabilirsiniz:

custom_agents.py dosyası oluşturma

Not: Devam etmeden önce doğru dizinde (ai-agents-adk) olduğunuzdan emin olun. Terminalinizde pwd (print working directory) komutunu çalıştırarak mevcut konumunuzu onaylayın.

Şimdi terminalde şu komutu çalıştırarak personal_assistant klasöründe custom_agents.py adlı bir Python dosyası oluşturun:

touch 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 dosya, özel google_search_agent için kodu içerir. Kod Düzenleyici'yi kullanarak 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, google_search_agent adlı aracımızın tamamını 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 bölümünden kaldırıldığını fark edeceksiniz. 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 tür

adk web

Terminalde örneği başlatın ve bu soruyu tekrar aracıya 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 kurunu işleyebilir ve google_search_agent aracıyla lojistiği yönetebilir. Ancak harika bir gezi sadece lojistikle ilgili değildir. Gideceğiniz yerin kültürünü ve tarihini anlamak da önemlidir.

google_search_agent, kültürel ve tarihi bilgiler 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ısı ç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.

İlk olarak, ç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

Not: Devam etmeden önce doğru dizinde (ai-agents-adk) olduğunuzdan emin olun. Terminalinizde pwd (print working directory) komutunu çalıştırarak mevcut konumunuzu onaylayın.

Şimdi terminalde aşağıdaki komutu çalıştırarak personal_assistant klasöründe third_party_tools.py adlı bir Python dosyası oluşturun:

touch 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. Cloud Editor'ı kullanarak aşağıdaki kodu third_party_tools.py içine 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 tür

adk web

Terminalde örneği başlatın ve temsilciye "Tell me about the history of Kyoto" (Kyoto'nun tarihi hakkında bilgi ver) sorusunu sorun.

Aracı, bunu doğru şekilde geçmiş 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.

Aracının 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ı)

Not: Seriye devam etmeyi planlıyorsanız bu adımı uygulamanız gerekmez. Bu codelab'e bir eğitmenle birlikte yüz yüze katılıyorsanız eğitmeniniz yapmanız gerekenler hakkında daha fazla talimat verecektir.

Bu codelab'de uzun süreli çalışan ürünler kullanılmadığı için 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 aracı oluşturmaktan basit ama güçlü bir çoklu aracı sistemi düzenlemeye geçiş yaptınız.

Artık serinin sonraki codelab'ine 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.