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

1. Başlamadan önce

"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.

Ö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ı
• Faturalandırmanın etkin olduğu bir Google Cloud projesi
• 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üşünülebilir. 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 Kurma
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ırlık yaptığınızı ve mevcut döviz kurunu kontrol etmeniz gerektiğini düşünün. Aracıya "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 (Windows/Linux için) veya Cmd + C (macOS için) 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. Geçerli konumunuzu onaylamak için terminalinizde pwd (print working directory) komutunu çalıştırın.

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üncelleyin**:**

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:

uv run adk web

Aracı çalışır duruma geldiğinde aynı soruyu tekrar sorun: "Singapur dolarından Japon yenine 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. Gerekli her anlık veri için yeni Python işlevleri kodlayabilsek de özel araçların sayısı arttıkça aracı yönetmek zorlaşır ve karmaşık hale gelir.

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. Temsilcimize bir Google Arama aracı ekleyelim.

Bunun için agent.py dosyasını aşağıdaki şekilde düzenlemeniz gerekir:

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

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

Dosyayı düzenledikten sonra adk web örneğini yeniden başlatın. Unutursanız

1. Terminali tıklayın, örneği durdurmak için Ctrl + C veya Cmd + C tuşlarına basın.
2. uv run adk web simgesini tıklayarak örneği başlatın.
3. Aynı soruyu sormayı deneyin: "Japonya'nın Tokyo şehrinde gelecek ay hava nasıl olacak?"

Uyarı: Bu durum, kasıtlı olarak hataya neden olur. ADK, yerleşik bir aracı kullanan hiçbir temsilcinin aynı anda başka bir araç kullanamayacağı şekilde tasarlanmıştır.

Önerilen yaklaşım, çoklu aracı modelini benimsemektir: Tek görevi Google aramaları yapmak olan özel bir aracı oluşturun. Ardından, bu yeni Google Arama Aracısı'nı ana personal_assistant'mıza araç olarak atarız.

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 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 import agent_tool

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), 
        agent_tool.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 aracının (google_search_agent) 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 agent_tool.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 yeniden başlatın.

adk web

instance değerini girin ve bu soruyu tekrar aracıya sorun: "What is the weather forecast in Tokyo, Japan for next month?" (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. Aracı 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

Ajanımız, 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. 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.

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

uv add langchain-community
uv add 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 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 import agent_tool
from google.adk.tools import langchain_tool

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), 
        agent_tool.AgentTool(agent=google_search_agent),
        langchain_tool.LangchainTool(langchain_wikipedia_tool),
    ]
)

Şimdi adk web örneğini yeniden başlatın ve temsilciye şu soruyu sorun: "Kyoto'nun tarihi hakkında bilgi ver."

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 aracınızı seyahat planlama amacıyla kullanmak için çok 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ı)

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ı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.