Tworzenie agentów AI za pomocą ADK: zwiększanie możliwości dzięki narzędziom

1. Zanim zaczniesz

Witamy w drugiej części serii „Tworzenie agentów AI z użyciem pakietu ADK”. W tym praktycznym ćwiczeniu wyposażysz podstawowego agenta AI w różne narzędzia.

Na początek ten przewodnik zawiera 2 ścieżki: jedną dla osób, które kontynuują ćwiczenie „Tworzenie agentów AI za pomocą pakietu ADK: podstawy”, a drugą dla osób, które zaczynają od zera. Obie ścieżki zapewnią Ci niezbędny podstawowy kod agenta, aby rozpocząć.

Po ukończeniu tego ćwiczenia Twój osobisty asystent będzie miał do dyspozycji narzędzia do różnych celów. Będzie to kolejny krok w rozwoju tego agenta, który w dalszych częściach tej serii przekształcimy w zaawansowany system wieloagentowy (MAS).

To ćwiczenie z programowania jest też dostępne pod tym skróconym adresem URL: goo.gle/adk-using-tools.

Wymagania wstępne

Znajomość pojęć związanych z generatywną AI.
podstawowa znajomość programowania w Pythonie,
ukończenie kursu Tworzenie agentów AI z użyciem pakietu ADK: podstawy lub podobnego;

Czego się nauczysz

Nadaj agentowi nowe umiejętności, tworząc niestandardowe funkcje Pythona jako narzędzia.
Połącz agenta z informacjami w czasie rzeczywistym, korzystając z wbudowanych narzędzi, takich jak wyszukiwarka Google.
Skonstruuj agenta z wieloma narzędziami, tworząc wyspecjalizowanych subagentów do złożonych zadań.
Integruj narzędzia z popularnych platform AI, takich jak LangChain, aby szybko rozszerzać możliwości.

Czego potrzebujesz

działający komputer i niezawodne połączenie Wi-Fi;
przeglądarka, np. Chrome, do otwierania konsoli Google Cloud;
ciekawość i chęć do nauki,

2. Wprowadzenie

Podstawowy agent utworzony za pomocą ADK ma potężny model LLM, ale ma też ograniczenia: nie może uzyskiwać dostępu do informacji utworzonych po dacie jego trenowania ani wchodzić w interakcje z usługami zewnętrznymi. To jak genialny asystent, który zna wszystkie książki, ale jest zamknięty w bibliotece bez telefonu i dostępu do internetu. Aby agent był naprawdę przydatny, musimy dać mu narzędzia.

Narzędzia dają asystentowi AI dostęp do świata zewnętrznego: kalkulatora, przeglądarki internetowej lub określonej bazy danych firmy. W ADK narzędzie to modułowy fragment kodu, który umożliwia agentowi wykonywanie określonych działań, takich jak wyszukiwanie danych w czasie rzeczywistym lub wywoływanie zewnętrznego interfejsu API. Korzystanie z narzędzi znacznie rozszerza jego możliwości poza zwykłą rozmowę.

ADK oferuje 3 kategorie narzędzi:

Narzędzia funkcji: niestandardowe narzędzia opracowane przez Ciebie w celu spełnienia unikalnych wymagań aplikacji, takie jak predefiniowane funkcje i agenci.
Wbudowane narzędzia: gotowe do użycia narzędzia udostępniane przez platformę do wykonywania typowych operacji, takich jak wyszukiwanie w Google i wykonywanie kodu.
Narzędzia innych firm: popularne biblioteki zewnętrzne, takie jak Serper, oraz narzędzia z LangChain i CrewAI.

Więcej informacji o korzystaniu z narzędzi w przypadku agentów ADK znajdziesz w oficjalnej dokumentacji. W tym ćwiczeniu dodamy narzędzia, które przekształcą naszego prostego agenta w skutecznego osobistego asystenta podróży. Zaczynajmy!

3. Pierwsze kroki: agent podstawowy

Zanim wyposażysz agenta w narzędzia, musisz mieć podstawowego agenta, z którym będziesz pracować. Wybierz ścieżkę, która najlepiej pasuje do Twoich postępów.

Ścieżka A. Kontynuacja z Codelabu dotyczącego podstaw

Jeśli właśnie ukończono ćwiczenie „ Tworzenie agentów AI z użyciem pakietu ADK: podstawy”, wszystko jest gotowe. Możesz nadal pracować w dotychczasowym katalogu projektu ai-agents-adk.

Ścieżka B. Zacznij od nowa

Jeśli zaczynasz to ćwiczenie bezpośrednio, wykonaj te 4 kroki, aby skonfigurować środowisko i utworzyć niezbędnego agenta początkowego.

Po wykonaniu tych czynności możesz rozpocząć naukę.

4. Tworzenie niestandardowego narzędzia do wymiany walut

Na tym etapie powinna już być Ci znana metoda tworzenia prostego agenta AI za pomocą pakietu ADK i uruchamiania go w interfejsie programistycznym.

Załóżmy, że przygotowujesz się do wyjazdu do Japonii w przyszłym miesiącu i musisz sprawdzić aktualny kurs wymiany walut. Zadaj agentowi pytanie „Jaki jest kurs wymiany dolara singapurskiego na jena japońskiego?”

Zobaczysz, że agent nie może pobrać kursów wymiany w czasie rzeczywistym. Dzieje się tak, ponieważ agent nie ma obecnie dostępu do internetu ani połączenia z systemami zewnętrznymi. Nawet jeśli agent odpowie jakąś wartością, trudno jej zaufać, ponieważ prawdopodobnie będzie to halucynacja.

Aby rozwiązać ten problem, zaimplementujemy funkcję Pythona, która pobiera kursy wymiany za pomocą interfejsu API (typu) REST, i zintegrujemy ją jako narzędzie funkcji dla agenta.

Zakończ działanie procesu agenta, naciskając skrót klawiszowy Ctrl+C w oknie terminala.

Tworzenie pliku `custom_functions.py`

Uruchom to polecenie w terminalu, aby utworzyć plik Pythona o nazwie custom_functions.py w folderze personal_assistant, a także otworzyć go w edytorze kodu.

cloudshell edit personal_assistant/custom_functions.py

Struktura folderów powinna teraz wyglądać tak:

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

Ten plik custom_functions.py będzie zawierać funkcję w języku Python, która pobiera dane o kursach wymiany z zewnętrznego interfejsu API. Skopiuj ten kod i wklej go do pliku:

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()

Teraz zmień plik agent.py: zaimportuj funkcję get_fx_rate i przypisz ją jako FunctionTool.

Zaktualizuj plik `agent.py`

Skopiuj ten blok kodu i zastąp nim dotychczasową zawartość pliku agent.py:

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

Po wprowadzeniu zmian uruchom ponownie agenta, wpisując:

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

Gdy agent będzie dostępny, zadaj to samo pytanie: „Jaki jest kurs wymiany dolara singapurskiego na jena japońskiego?”

Tym razem powinien wyświetlić się rzeczywisty kurs wymiany podany przez narzędzie get_fx_rate.

Możesz zadawać dowolne pytania dotyczące wymiany walut.

5. Integracja z wbudowanym narzędziem wyszukiwarki Google

Skoro agent potrafi już podawać kursy wymiany walut, następnym zadaniem jest uzyskanie prognozy pogody na przyszły miesiąc. Zadaj agentowi pytanie: „Jaka jest prognoza pogody w Tokio w Japonii na przyszły miesiąc?”

Prognoza pogody wymaga informacji w czasie rzeczywistym, których nasz agent nie ma. Moglibyśmy kodować nowe funkcje Pythona dla każdego przypadku użycia, który wymaga danych w czasie rzeczywistym, ale dodawanie coraz większej liczby narzędzi niestandardowych szybko sprawia, że agent staje się zbyt skomplikowany i trudny w zarządzaniu.

Na szczęście pakiet Agent Development Kit (ADK) udostępnia zestaw wbudowanych narzędzi, w tym wyszukiwarkę Google, które są gotowe do użycia i upraszczają interakcję agenta ze światem zewnętrznym.

Aby wyposażyć agenta w narzędzie wyszukiwarki Google, musisz wdrożyć wzorzec wielu agentów. Najpierw tworzysz specjalistycznego agenta, którego jedynym zadaniem jest przeprowadzanie wyszukiwań w Google. Następnie przypisujesz tego nowego agenta wyszukiwarki Google do naszego głównego personal_assistant jako narzędzie. Aby to zrobić:

Tworzenie pliku `custom_agents.py`

Uruchom to polecenie w terminalu, aby utworzyć plik Pythona o nazwie custom_agents.py w folderze personal_assistant i otworzyć go w edytorze kodu:

cloudshell edit personal_assistant/custom_agents.py

Struktura folderów powinna teraz wyglądać tak:

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

Plik custom_agents.py będzie zawierać kod specjalistycznego google_search_agent. Skopiuj ten kod do pliku custom_agents.py:

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

Po utworzeniu pliku zaktualizuj plik agent.py w sposób pokazany poniżej.

Zaktualizuj plik `agent.py`

Skopiuj ten blok kodu i zastąp nim dotychczasową zawartość pliku agent.py:

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

Przyjrzyjmy się nowemu wzorcowi w kodzie:

Nowy agent specjalista: zdefiniowaliśmy zupełnie nowego agenta, google_search_agent. Zwróć uwagę na jego szczegółowy opis i fakt, że jedynym narzędziem jest google_search. Jest specjalistą ds. wyszukiwania.
agent_tool.AgentTool: Jest to specjalny kontener z ADK. Pobiera całego agenta (naszego agenta google_search_agent) i pakuje go tak, aby wyglądał i działał jak standardowe narzędzie.
Bardziej inteligentny**root_agent**: nasz root_agent ma teraz nowe narzędzie: AgentTool(agent=google_search_agent). Nie wie, jak przeszukiwać internet, ale wie, że ma narzędzie, któremu może zlecić zadania wyszukiwania.

Zwróć uwagę, że pole instrukcji zniknęło z root_agent. Jego instrukcje są teraz definiowane w sposób dorozumiany przez dostępne narzędzia.

root_agent stał się koordynatorem lub routerem, którego głównym zadaniem jest zrozumienie prośby użytkownika i przekazanie jej do odpowiedniego narzędzia, czyli funkcji get_fx_rate lub google_search_agent. Ta zdecentralizowana architektura jest kluczem do tworzenia złożonych systemów agentów, które można utrzymywać.

Teraz wpisz w terminalu to polecenie, aby uruchomić instancję:

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

Gdy agent będzie działać, zadaj mu ponownie to pytanie: „Jaka jest prognoza pogody w Tokio w Japonii na przyszły miesiąc?”

Agent korzysta teraz z google_search_agent, aby uzyskiwać najnowsze informacje

Możesz też zadać pytanie dotyczące bieżącego kursu wymiany. Agent powinien teraz być w stanie użyć odpowiedniego narzędzia do danego pytania.

Możesz zadawać agentowi inne pytania, które wymagają informacji w czasie rzeczywistym, i obserwować, jak radzi sobie z zapytaniami, korzystając z dostępnych narzędzi.

6. Korzystanie z narzędzia Wikipedia w LangChain

Nasz agent staje się świetnym asystentem podróży. Może obsługiwać wymianę walut za pomocą narzędzia get_fx_rate i zarządzać logistyką za pomocą narzędzia google_search_agent. Jednak udana podróż to nie tylko logistyka, ale też poznanie kultury i historii miejsca docelowego.

google_search_agent może wyszukiwać fakty kulturowe i historyczne, ale informacje z dedykowanego źródła, takiego jak Wikipedia, są często bardziej uporządkowane i wiarygodne.

Na szczęście ADK jest bardzo rozszerzalny, co pozwala na bezproblemową integrację narzędzi z innych platform agentów AI, takich jak CrewAI i LangChain. Ta interoperacyjność jest kluczowa, ponieważ pozwala skrócić czas programowania i ponownie wykorzystać istniejące narzędzia. W tym przypadku użycia skorzystamy z narzędzi Wikipedii z biblioteki LangChain.

Najpierw zatrzymaj działający proces agenta (Ctrl + C) i zainstaluj dodatkowe biblioteki w bieżącym środowisku wirtualnym Pythona, wpisując te polecenia w terminalu.

uv pip install langchain-community wikipedia

Tworzenie pliku `third_party_tools.py`

To polecenie tworzy plik Pythona o nazwie third_party_tools.py w folderze personal_assistant i otwiera go w edytorze Cloud Editor:

cloudshell edit personal_assistant/third_party_tools.py

Struktura folderów powinna teraz wyglądać tak:

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

Ten plik będzie zawierać implementację narzędzia LangChain Wikipedia. Skopiuj ten kod do pliku third_party_tools.py:

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

Zaktualizuj plik `agent.py`

Teraz zaktualizuj plik agent.py za pomocą poniższej treści:

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

Teraz wpisz w terminalu to polecenie, aby uruchomić instancję:

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

Gdy agent będzie gotowy, zadaj mu to pytanie: „Opowiedz mi o historii Kioto”.

Agent prawidłowo identyfikuje to zapytanie jako historyczne i używa nowego narzędzia Wikipedia. Dzięki integracji narzędzia innej firmy i przypisaniu mu konkretnej roli Twój agent stał się znacznie bardziej inteligentny i przydatny w planowaniu podróży.

Aby dokładnie sprawdzić, jak agent podjął tę decyzję, możesz użyć inspektora zdarzeń w adk web interfejsie. Kliknij kartę Zdarzenia, a potem najnowsze zdarzenie functionCall.

Inspektor wyświetla listę wszystkich dostępnych narzędzi i wyróżnia kod narzędzia, które zostało wykonane przez agenta.

7. Czyszczenie (opcjonalnie)

Ten przewodnik nie dotyczy żadnych długotrwałych usług, więc wystarczy, że zatrzymasz aktywne sesje agenta (np. instancję adk web w terminalu), naciskając Ctrl + C w terminalu.

Usuwanie folderów i plików projektu agenta

Jeśli chcesz usunąć kod tylko ze środowiska Cloud Shell, użyj tych poleceń:

cd ~
rm -rf ai-agents-adk

Wyłączanie Vertex AI API

Aby wyłączyć interfejs Vertex AI API, który został wcześniej włączony, uruchom to polecenie:

gcloud services disable aiplatform.googleapis.com

Zamykanie całego projektu Google Cloud

Jeśli chcesz całkowicie wyłączyć projekt Google Cloud, zapoznaj się ze szczegółowymi instrukcjami w oficjalnym przewodniku.

8. Podsumowanie

Gratulacje! Udało Ci się wyposażyć osobistego asystenta w funkcje niestandardowe i dostęp do wyszukiwarki Google w czasie rzeczywistym. Zapoznaj się z oficjalną dokumentacją na temat korzystania z narzędzi w pakiecie Google ADK.

Co ważniejsze, poznałeś podstawowy wzorzec architektury do tworzenia wydajnych agentów: używanie wyspecjalizowanych agentów jako narzędzi. Tworząc dedykowany google_search_agent i przekazując go root_agent, wykonujesz pierwszy krok od tworzenia pojedynczego agenta do koordynowania prostego, ale wydajnego systemu wieloagentowego.

Jesteś teraz doskonale przygotowany(-a) do kolejnego modułu (już wkrótce) z tej serii, w którym zagłębimy się w orkiestrację wielu agentów i przepływów pracy. Do zobaczenia!

Tworzenie agentów AI za pomocą ADK: zwiększanie możliwości dzięki narzędziom

1. Zanim zaczniesz

Wymagania wstępne

Czego się nauczysz

Czego potrzebujesz

2. Wprowadzenie

3. Pierwsze kroki: agent podstawowy

4. Tworzenie niestandardowego narzędzia do wymiany walut

Tworzenie pliku custom_functions.py

Zaktualizuj plik agent.py

5. Integracja z wbudowanym narzędziem wyszukiwarki Google

Tworzenie pliku custom_agents.py

Zaktualizuj plik agent.py

6. Korzystanie z narzędzia Wikipedia w LangChain

Tworzenie pliku third_party_tools.py

Zaktualizuj plik agent.py

7. Czyszczenie (opcjonalnie)

Usuwanie folderów i plików projektu agenta

Wyłączanie Vertex AI API

Zamykanie całego projektu Google Cloud

8. Podsumowanie

Tworzenie pliku `custom_functions.py`

Zaktualizuj plik `agent.py`

Tworzenie pliku `custom_agents.py`

Zaktualizuj plik `agent.py`

Tworzenie pliku `third_party_tools.py`

Zaktualizuj plik `agent.py`