Ta strona została przetłumaczona przez Cloud Translation API.

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 za pomocą ADK”. W tym praktycznym ćwiczeniu z programowania 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ą pracę z warsztatami „ Tworzenie agentów AI za pomocą ADK: podstawy”, a drugą dla osób, które dopiero zaczynają. Obie ścieżki zapewnią Ci niezbędny podstawowy kod agenta, aby rozpocząć.

Po ukończeniu tego laboratorium będziesz mieć osobistego asystenta wyposażonego w narzędzia do różnych celów. Będzie to kolejny krok w rozwoju tej serii, w której przekształcimy go w zaawansowany system wieloagentowy (MAS).

Wymagania wstępne

Znajomość pojęć związanych z generatywną AI
podstawową znajomość programowania w Pythonie,
Ukończony kurs Tworzenie agentów AI za pomocą 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 wyspecjalizowanych subagentów do złożonych zadań.
Integruj narzędzia z popularnych platform AI, takich jak LangChain, aby szybko zwiększać możliwości.

Czego potrzebujesz

działający komputer i niezawodne połączenie Wi-Fi;
przeglądarka, np. Chrome, do otwierania konsoli Google Cloud;
Projekt Google Cloud z włączonymi płatnościami
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, które opracowujesz, aby spełnić unikalne wymagania 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 LangChain i CrewAI.

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

3. Pierwsze kroki: agent podstawowy

Zanim udostępnisz agentowi 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 za pomocą pakietu ADK: podstawy”, możesz przejść dalej. Możesz kontynuować pracę 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 być już znana Ci metoda tworzenia prostego agenta AI za pomocą 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. 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. Wynika to z tego, że 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 będzie pobierać kursy wymiany za pomocą interfejsu API REST i zintegrujemy ją jako narzędzie funkcji dla agenta.

Zakończ działający proces agenta, używając skrótu klawiszowego Ctrl + C (Windows/Linux) lub Cmd + C (macOS) w oknie terminala.

Utwórz plik `custom_functions.py`:

Utwórz plik Pythona o nazwie custom_functions.py w folderze personal_assistant, wpisując w terminalu to polecenie:.

touch personal_assistant/custom_functions.py

Struktura folderów powinna wyglądać tak:

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

Otwórz custom_functions.py w edytorze kodu. Ten plik będzie zawierać funkcję w języku Python, która pobiera dane o kursach wymiany z zewnętrznego interfejsu API.

Skopiuj i wklej poniższy kod:

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 agenta ponownie, wpisując:

uv run adk web

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?”

Jak można się spodziewać, prognoza pogody wymaga informacji w czasie rzeczywistym, których nasz agent nie ma. Moglibyśmy napisać nowe funkcje Pythona dla każdego rodzaju wymaganych 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 Agent Development Kit (ADK) udostępnia zestaw wbudowanych narzędzi, w tym wyszukiwarkę Google, które są gotowe do użycia i ułatwiają agentowi interakcję ze światem zewnętrznym. Dodajmy do agenta narzędzie wyszukiwarki Google.

Aby to zrobić, musisz edytować plik agent.py w ten sposób:

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

Po edycji pliku uruchom ponownie instancję adk web. Jeśli zapomnisz,

Kliknij terminal, a następnie naciśnij Ctrl + C lub Cmd + C, aby zatrzymać instancję.
uv run adk web, aby uruchomić instancję.
Zadaj to samo pytanie: „Jaka będzie prognoza pogody w Tokio w Japonii w przyszłym miesiącu?”

Zalecane podejście to zastosowanie wzorca wielu agentów: utwórz wyspecjalizowanego agenta, którego jedynym zadaniem będzie przeprowadzanie wyszukiwań w Google. Następnie przypisujemy tego nowego agenta wyszukiwarki Google do naszego głównego personal_assistant jako narzędzie.

Tworzenie pliku `custom_agents.py`

Teraz utwórz plik Pythona o nazwie custom_agents.py w folderze personal_assistant.

touch 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

Ten plik będzie zawierać kod specjalistycznego komponentu google_search_agent. Skopiuj ten kod do pliku custom_agents.py za pomocą edytora kodu.

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

Przyjrzyjmy się nowemu, zaawansowanemu 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. W tym celu wykorzystuje 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: agent_tool.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 kluczowa w przypadku tworzenia złożonych systemów agentów, które można utrzymywać.

Teraz uruchom ponownie

adk web

instancji i ponownie zadać agentowi 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żącej 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 LangChain Wikipedia Tool

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 wykorzystamy narzędzia Wikipedii z biblioteki LangChain.

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

uv add langchain-community
uv add wikipedia

Tworzenie pliku `third_party_tools.py`

Teraz utwórz plik Pythona o nazwie third_party_tools.py w folderze personal_assistant.

touch 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 third_party_tools.py za pomocą edytora Cloud:

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, wklejając do niego poniższą treść:

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

Teraz uruchom ponownie instancję adk web i zadaj agentowi 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 określonej 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 produktów, więc wystarczy zatrzymać 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 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 z pakietem ADK Google.

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 budowania pojedynczego agenta do koordynowania prostego, ale wydajnego systemu wielu agentów.

Teraz możesz przejść do kolejnych warsztatów z tej serii, w których omówimy szczegółowo koordynowanie 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

Utwórz plik 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 LangChain Wikipedia Tool

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

Utwórz plik `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`