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

1. Zanim zaczniesz

PRZECZYTAJ:

Aby wykonać zadania z tego samouczka, musisz mieć projekt Google Cloud z aktywnym kontem rozliczeniowym.

Dla uczestników warsztatów stacjonarnych

• Postępuj zgodnie z instrukcjami konfiguracji i rozliczeń przekazanymi przez nauczyciela.

Dla osób uczących się samodzielnie

• Aby skorzystać z okresu próbnego, wykonaj te czynności:

1. Otwórz okno incognito w przeglądarce.
2. Otwórz ten portal odbioru nagród.
3. Zaloguj się, korzystając z osobistego konta Gmail.
4. Postępuj zgodnie z instrukcjami krok po kroku podanymi w portalu.

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.

Ten przewodnik zawiera 2 ścieżki: jedną dla osób, które kontynuują ćwiczenie Tworzenie agentów AI z użyciem ADK: podstawy, i drugą dla osób, które zaczynają od zera. Obie ścieżki zapewnią Ci niezbędny podstawowy kod agenta, aby rozpocząć pracę.

Po ukończeniu tego ćwiczenia Twój osobisty asystent będzie wyposażony w 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).

Do tych ćwiczeń z programowania możesz też przejść, klikając ten skrócony URL: goo.gle/adk-using-tools.

Wymagania wstępne

• Znajomość pojęć związanych z generatywną AI
• podstawowa znajomość programowania w Pythonie,
• znajomość interfejsu wiersza poleceń gcloud i narzędzia Python uv;
• Ukończony kurs Tworzenie agentów AI z użyciem pakietu ADK: podstawy lub podobny

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 za pomocą wbudowanych narzędzi, takich jak wyszukiwarka Google.
• Skonstruuj agenta z wieloma narzędziami, tworząc wyspecjalizowane subagenty 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 stabilne połączenie Wi-Fi;
• przeglądarka, np. Chrome, do uzyskiwania dostępu do 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 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:

1. Narzędzia funkcji: niestandardowe narzędzia, które opracowujesz, aby spełnić unikalne wymagania aplikacji, takie jak predefiniowane funkcje i agenci.
2. 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.
3. 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ńczysz kurs Tworzenie agentów AI z użyciem pakietu ADK: podstawy, możesz przejść dalej. Możesz kontynuować pracę w istniejącym katalogu projektu ai-agents-adk.

Jeśli w wierszu poleceń Cloud Shell nie widzisz znaku (ai-agents-adk), uruchom te polecenia, aby aktywować wirtualne środowisko Pythona:

cd ~/ai-agents-adk
source .venv/bin/activate

Ścieżka B. Zaczynanie od nowa

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

1. Konfigurowanie usług Google Cloud
2. Tworzenie środowiska wirtualnego Pythona
3. Tworzenie agenta
4. Uruchamianie agenta w interfejsie programistycznym

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.

Wyobraź sobie, że przygotowujesz się do wyjazdu do Japonii w przyszłym miesiącu i musisz sprawdzić aktualny kurs wymiany walut. Zapytaj agenta: „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, wdrożymy funkcję Pythona, która będzie pobierać kursy wymiany za pomocą interfejsu REST API i zintegrujemy ją z agentem jako narzędzie funkcji.

Zakończ działający proces agenta, używając skrótu klawiszowego Ctrl + C w oknie terminala.

Utwórz plik custom_functions.py

Uwaga: zanim przejdziesz dalej, sprawdź, czy jesteś w odpowiednim katalogu (ai-agents-adk). Aby sprawdzić bieżącą lokalizację, możesz w terminalu uruchomić polecenie pwd (print working directory).

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

Uwaga: zwróć szczególną uwagę na tekst opisowy w potrójnych cudzysłowach (”””…”””). Nazywa się on docstring. Dla programistów jest to dobra praktyka, ale dla agenta AI jest to niezbędne.

Podstawowy model LLM agenta odczytuje nazwę funkcji i ten ciąg dokumentu, aby zrozumieć, do czego służy narzędzie, co oznaczają jego argumenty (w tym przypadku base i target) oraz kiedy należy go używać.

Jasny, opisowy docstring to najważniejszy czynnik, który umożliwia agentowi prawidłowe korzystanie z narzędzia.

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

Aktualizowanie pliku 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-3.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)]
)

Uwaga: import względny jest potrzebny do importowania funkcji z innych plików Pythona, ponieważ ADK uruchamia folder agenta jako moduł Pythona. To podejście sprawdza się w przypadku niewielkiego zestawu narzędzi, ale w miarę rozwoju narzędzia będziemy musieli utworzyć pakiet narzędzi.

Po wprowadzeniu zmian uruchom agenta ponownie, wpisując:

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

Uwaga: w większości przypadków wystarczy wykonać polecenie adk web, ale aby zapewnić prawidłowy dostęp podczas uruchamiania serwera z terminala Cloud Shell, musisz dodać flagę --allow_origins.

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

Tym razem powinna się wyświetlić rzeczywista wartość kursu wymiany podana 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 będzie prognoza pogody w Tokio w Japonii w przyszłym miesiącu?”

Jak można się spodziewać, prognoza pogody wymaga informacji w czasie rzeczywistym, których nasz agent nie ma. Moglibyśmy kodować nowe funkcje w Pythonie dla każdego przypadku użycia, który wymaga danych w czasie rzeczywistym, ale dodawanie coraz większej liczby niestandardowych narzędzi 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 Wyszukiwarka 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ć:

Utwórz plik custom_agents.py

Uwaga: zanim przejdziesz dalej, upewnij się, że jesteś w odpowiednim katalogu (ai-agents-adk). Aby potwierdzić bieżącą lokalizację, w terminalu uruchom polecenie pwd (print working directory).

Uruchom w terminalu to polecenie, 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-3.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.

Aktualizowanie pliku 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-3.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 na to, że jedynym narzędziem jest google_search. Jest specjalistą ds. wyszukiwania.
• agent_tool.AgentTool: jest to specjalny moduł 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 niejawnie zdefiniowane 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ć, ponownie zadaj mu pytanie: „Jaka ma być pogoda w Tokio w Japonii w przyszłym miesiącu?”

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 przy użyciu dostępnych narzędzi.

6. Korzystanie z narzędzia LangChain Wikipedia

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 znajdować 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 LangChain.

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

uv pip install langchain-community wikipedia

Utwórz plik third_party_tools.py

Uwaga: zanim przejdziesz dalej, upewnij się, że jesteś w odpowiednim katalogu (ai-agents-adk). Aby potwierdzić bieżącą lokalizację, w terminalu uruchom polecenie pwd (print working directory).

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

Aktualizowanie pliku 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-3.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 rozpoznaje to jako zapytanie historyczne i używa nowego narzędzia Wikipedia. Dzięki zintegrowaniu narzędzia innej firmy i przypisaniu mu konkretnej roli Twój agent stał się znacznie bardziej inteligentny i przydatny w planowaniu podróży.

Aby 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. Oczyszczanie środowiska

Uwaga: jeśli planujesz kontynuować serię, nie musisz wykonywać tego kroku. Jeśli uczestniczysz w tym ćwiczeniu w formie stacjonarnej pod okiem instruktora, przekaże Ci on dalsze instrukcje.

To laboratorium nie obejmuje żadnych długotrwałych produktów, więc wystarczy zatrzymać aktywne sesje agenta (np. instancję adk web w terminalu), naciskając w terminalu Ctrl + C lub Cmd + C.

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 interfejsu Gemini Enterprise Agent Platform API

Aby wyłączyć interfejs 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 zamknąć 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 zaawansowanych 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.

Teraz jesteś 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 procesów. Do zobaczenia!