1. Zanim zaczniesz
Witamy w pierwszej części serii „Tworzenie agentów AI za pomocą ADK”. W tej serii ćwiczeń w Codelabs wyruszysz w ekscytującą podróż, aby stworzyć własnego inteligentnego agenta AI za pomocą pakietu Agent Development Kit (ADK) od Google.
Zaczniemy od podstaw, pokazując, jak skonfigurować środowisko deweloperskie i stworzyć podstawowego agenta konwersacyjnego. Po ukończeniu tego ćwiczenia z programowania będziesz mieć pierwszą interaktywną AI, którą w kolejnych częściach tej serii będziemy rozwijać, aby przekształcić ją w zaawansowany system wieloagentowy (MAS).
To ćwiczenie możesz wykonać w środowisku lokalnym lub w Google Cloud. Aby zapewnić sobie jak największą spójność, zalecamy korzystanie z Cloud Shell w środowisku Google Cloud. Cloud Shell udostępnia też 5 GB trwałego miejsca na dane w katalogu $HOME. Jest to przydatne do przechowywania skryptów, plików konfiguracyjnych lub sklonowanych repozytoriów.
Wymagania wstępne
- Znajomość pojęć związanych z generatywną AI
- podstawową znajomość programowania w Pythonie,
- Znajomość wiersza poleceń lub terminala
Czego się nauczysz
- Jak skonfigurować środowisko Pythona
- Tworzenie prostego agenta osobistego za pomocą pakietu ADK
- Jak uruchamiać, testować i debugować agenta
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
Świat generatywnej AI (GenAI) szybko się rozwija, a agenci AI są obecnie gorącym tematem. Agent AI to inteligentny program komputerowy zaprojektowany do działania w Twoim imieniu, podobnie jak osobisty asystent. Może ona postrzegać swoje środowisko cyfrowe, podejmować decyzje i wykonywać działania w celu osiągnięcia określonych celów bez bezpośredniej kontroli człowieka. Można ją traktować jako proaktywną, autonomiczną jednostkę, która może się uczyć i dostosowywać, aby realizować zadania.
U podstaw działania agenta AI leży duży model językowy (LLM), który pełni funkcję „mózgu” i umożliwia rozumienie oraz wnioskowanie. Dzięki temu może przetwarzać informacje z różnych źródeł, takich jak tekst, obrazy i dźwięki. Następnie agent wykorzystuje tę wiedzę do utworzenia planu i wykonania serii zadań, aby osiągnąć zdefiniowany cel.
Dzięki gotowym platformom, takim jak Agent Development Kit (ADK), możesz teraz łatwo tworzyć własnych agentów AI, nawet bez specjalistycznej wiedzy. Zaczniemy od stworzenia osobistego asystenta, który pomoże Ci w wykonywaniu zadań. Zaczynamy!
3. Konfigurowanie usług Google Cloud
Tworzenie projektu Google Cloud
W tym laboratorium zakłada się, że masz już utworzony projekt Google Cloud z włączonymi płatnościami. Jeśli nie masz jeszcze projektu, wykonaj te czynności, aby go utworzyć:
Wybieranie lub tworzenie projektu Google Cloud
- Otwórz Google Cloud Console.
- U góry kliknij menu wyboru projektu (obok logo Google Cloud).
- Wybierz istniejący projekt lub utwórz nowy.
Włącz płatności
- Sprawdź, czy w wybranym projekcie Google Cloud włączone są płatności.
- Instrukcje sprawdzania, czy w projekcie włączone są płatności, znajdziesz w dokumentacji Rozliczeń usługi Google Cloud.
Konfigurowanie Cloud Shell
Teraz sprawdźmy, czy wszystko jest prawidłowo skonfigurowane w Cloud Shell, czyli w wygodnym interfejsie wiersza poleceń bezpośrednio w konsoli Google Cloud.
Uruchom Cloud Shell
W prawym górnym rogu konsoli Google Cloud zobaczysz ikonę przypominającą terminal (>_). Kliknij ją, aby aktywować Cloud Shell.
Przyznaj dostęp
Jeśli pojawi się pytanie o autoryzację Cloud Shell, kliknij Autoryzuj, aby przyznać jej uprawnienia niezbędne do interakcji z Twoim projektem Google Cloud.
Weryfikacja konta:
Po załadowaniu Cloud Shell sprawdź, czy używasz właściwego konta Google Cloud. Uruchom to polecenie:
gcloud auth list
W terminalu powinny pojawić się dane wyjściowe podobne do tych:
Credentialed Accounts
ACTIVE: *
ACCOUNT: current_account@example.com
To set the active account, run:
$ gcloud config set account `ACCOUNT`
Przełącz konta (w razie potrzeby):
Jeśli aktywne konto nie jest tym, którego chcesz użyć w tym Codelabie, przełącz się na właściwe konto za pomocą tego polecenia, zastępując <your_desired_account@example.com> adresem e-mail, którego będziesz używać w tym laboratorium:
gcloud config set account <your_desired_account@example.com
Potwierdź projekt
Następnie sprawdź, czy Cloud Shell jest skonfigurowany do używania prawidłowego projektu Google Cloud. Uruchomienie:
gcloud config list project
Wyświetli się lista konfiguracji. Znajdź sekcję [core] i sprawdź, czy wartość projektu jest zgodna z identyfikatorem projektu Google Cloud, którego chcesz użyć w tym Codelabie:
[core] project = <current-project-id>
Ustawianie projektu (w razie potrzeby)
Jeśli wartość project ID jest nieprawidłowa, ustaw ją na wybrany projekt za pomocą tego polecenia:
gcloud config set project <your-desired-project-id>
Włącz wymagane interfejsy API
Aby korzystać z usług Google Cloud, musisz najpierw aktywować odpowiednie interfejsy API w swoim projekcie. Uruchomienie w terminalu Cloud Shell poleceń podanych poniżej włącza wszystkie usługi potrzebne w tym laboratorium:
gcloud services enable aiplatform.googleapis.com
Jeśli operacja się powiedzie, w terminalu pojawi się Operation/... finished successfully.
4. Utwórz środowisko wirtualne Pythona
Przed rozpoczęciem dowolnego projektu w Pythonie warto utworzyć środowisko wirtualne. Izoluje to zależności projektu, zapobiegając konfliktom z innymi projektami lub globalnymi pakietami Pythona w systemie. Pakiet Agent Development Kit (ADK) wymaga Pythona w wersji 3.9 lub nowszej, dlatego do zarządzania środowiskiem wirtualnym i zapewnienia używania prawidłowej wersji Pythona użyjemy narzędzia takiego jak uv.
uv to nowoczesne, szybkie i wydajne narzędzie do zarządzania projektami i środowiskami Pythona, które łączy funkcje tradycyjnie dostępne w narzędziach takich jak pip, venv, pip-tools i pipx. Jest napisany w języku Rust, co zapewnia szybkość działania.
Cloud Shell ma już dostępną usługę uv, więc możemy od razu zacząć.
Sprawdzanie, czy uv jest prawidłowo zainstalowany
uv --version
Utwórz nowy folder projektu dla agenta AI
uv init ai-agents-adk
cd ai-agents-adk
Utwórz środowisko wirtualne w Pythonie 3.12
uv venv --python 3.12
Zainstaluj bibliotekę Google ADK w środowisku wirtualnym
uv add google-adk
Sprawdź, czy pakiet google-adk został zainstalowany
uv pip list | grep google-adk
Jeśli zobaczysz wiersz wyjściowy z informacjami o pakiecie google-adk i jego wersji, możesz przejść do następnego kroku.
5. Utwórz agenta
Środowisko programistyczne jest już skonfigurowane i gotowe, więc czas na stworzenie podstaw agenta AI. Pakiet Agent Development Kit (ADK) upraszcza ten proces, ponieważ do zdefiniowania podstawowej logiki i konfiguracji agenta wystarczy kilka niezbędnych plików.
Te 3 pliki współpracują ze sobą, aby umożliwić wykrywanie, uruchamianie i konfigurowanie agenta:
agent.py: To jest najważniejsza część Twojego agenta. Zawiera on główny kod w języku Python, który określa zachowanie agenta, w tym jego nazwę, duży model językowy (LLM), który służy mu jako „mózg”, oraz podstawowe instrukcje, które kierują jego odpowiedziami.__init__.py: w Pythonie plik__init__.pyoznacza katalog jako pakiet Pythona. W przypadku ADK jest to kluczowe, ponieważ pomaga platformie wykrywać i wczytywać definicję agenta zagent.py. W prostych projektach ADK często zawiera jeden wiersz do importowania modułuagent, dzięki czemu agent jest dostępny dla narzędzia ADK Runner..env: ten plik (skrót od „environment”) służy do przechowywania informacji poufnych i zmiennych konfiguracyjnych, których potrzebuje Twój agent, takich jak klucze interfejsu API, identyfikatory projektów i lokalizacje geograficzne. Przechowywanie tych informacji w osobnym pliku.envto sprawdzona metoda zapewniająca bezpieczeństwo i przenośność, ponieważ zapobiega zakodowaniu poufnych danych bezpośrednio w kodzie. Umożliwia też łatwe zmienianie konfiguracji bez modyfikowania głównej logiki agenta.
Aby utworzyć te pliki w odpowiednim folderze dla agenta osobistego asystenta, użyj tych poleceń:
uv run adk create personal_assistant
Po wykonaniu polecenia pojawi się prośba o wybranie kilku opcji konfiguracji agenta. W pierwszym kroku wybierz opcję 1, aby użyć modelu gemini-2.5-flash, który jest szybki i wydajny, a także idealny do zadań konwersacyjnych.
Choose a model for the root agent: 1. gemini-2.5-flash 2. Other models (fill later) Choose model (1, 2): 1
W drugim kroku wybierz Vertex AI (opcja 2), czyli zaawansowaną, zarządzaną platformę AI od Google Cloud, jako dostawcę usługi backendu.
1. Google AI 2. Vertex AI Choose a backend (1, 2): 2
Na koniec poprosimy Cię o potwierdzenie identyfikatora projektu Google Cloud i regionu. Jeśli chcesz użyć wstępnie wypełnionych wartości (current-project-id i current-region), po prostu naciśnij Enter przy każdym pytaniu.
Enter Google Cloud project ID [current-project-id]: Enter Google Cloud region [current-region]:
W terminalu powinny pojawić się podobne dane wyjściowe.
Agent created in /home/<your-username>/ai-agent-adk/personal_assistant: - .env - __init__.py - agent.py
Teraz kliknij przycisk Otwórz edytor u góry okna Cloud Shell. Kliknięcie tego przycisku spowoduje przejście do okna Edytor, w którym możesz łatwiej przeglądać zawartość plików. Przełączenie może chwilę potrwać. Jeśli ekran wczytywania wyświetla się dłużej niż kilka minut, spróbuj odświeżyć przeglądarkę.
Gdy okno Edytora wczyta się w całości, otwórz folder personal-assistant. Zobaczysz niezbędne pliki wymienione powyżej (agent.py, __init__.py i .env). Przyjrzyjmy się ich zawartości.
Jeśli nie widzisz pliku .env w folderze, na pasku menu u góry kliknij Widok, a następnie wybierz Przełącz ukryte pliki. Jest to powszechne ustawienie, ponieważ .env pliki są często domyślnie ukryte, aby zapobiec przypadkowemu ujawnieniu.
Przyjrzyjmy się zawartości każdego pliku.
agent.py
Ten plik tworzy instancję agenta za pomocą klasy Agent z biblioteki google.adk.agents.
from google.adk.agents import Agent
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',
)
from google.adk.agents import Agent: ten wiersz importuje niezbędną klasęAgentz biblioteki ADK.root_agent = Agent(...): w tym miejscu tworzysz instancję agenta AI.name="personal_assistant": unikalny identyfikator agenta. W ten sposób pakiet ADK będzie rozpoznawać Twojego agenta i się do niego odnosić.model="gemini-2.5-flash": ten kluczowy parametr określa, którego dużego modelu językowego (LLM) będzie używać Twój agent jako podstawowego „mózgu” do rozumienia, wnioskowania i generowania odpowiedzi.gemini-2.5-flashto szybki i wydajny model odpowiedni do zadań związanych z rozmową.description="...": krótkie podsumowanie celu lub możliwości agenta. Opis jest przeznaczony dla ludzi lub innych agentów w systemie wieloagentowym, aby zrozumieć, co robi dany agent. Jest często używany do rejestrowania, debugowania lub wyświetlania informacji o agencie.instruction="...": jest to prompt systemowy, który określa zachowanie agenta i jego osobowość. Informuje on model LLM, jak powinien działać i jaki jest jego główny cel. W tym przypadku określa agenta jako „pomocnego asystenta”. Ta instrukcja ma kluczowe znaczenie dla kształtowania stylu konwersacji i możliwości agenta.
init.py
Ten plik jest niezbędny, aby Python rozpoznał personal-assistant jako pakiet, co umożliwi ADK prawidłowe zaimportowanie pliku agent.py.
from . import agent
from . import agent: ten wiersz wykonuje import względny, informując Pythona, aby szukał modułu o nazwieagent(który odpowiadaagent.py) w bieżącym pakiecie (personal-assistant). Ten prosty wiersz zapewnia, że gdy ADK próbuje wczytać agentapersonal-assistant, może znaleźć i zainicjowaćroot_agentzdefiniowany wagent.py. Nawet jeśli jest pusty, obecność pliku__init__.pysprawia, że katalog jest pakietem Pythona.
.env
Ten plik zawiera konfiguracje specyficzne dla środowiska i dane uwierzytelniające o charakterze kontrowersyjnym.
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION
GOOGLE_GENAI_USE_VERTEXAI: informuje ADK, że zamierzasz używać usługi Vertex AI od Google do operacji związanych z generatywną AI. Jest to ważne w przypadku korzystania z usług zarządzanych i zaawansowanych modeli Google Cloud.GOOGLE_CLOUD_PROJECT: ta zmienna będzie zawierać unikalny identyfikator Twojego projektu Google Cloud. Jest to niezbędne, aby ADK mogło prawidłowo powiązać agenta z zasobami w chmurze i włączyć rozliczenia.GOOGLE_CLOUD_LOCATION: określa region Google Cloud, w którym znajdują się zasoby Vertex AI (np.us-central1). Użycie prawidłowej lokalizacji zapewnia skuteczną komunikację agenta z usługami Vertex AI w tym regionie.
6. Uruchamianie agenta w terminalu
Gdy wszystkie 3 pliki będą na miejscu, możesz uruchomić agenta bezpośrednio z terminala. Aby to zrobić, musisz otworzyć okno terminala. Wystarczy, że na pasku menu klikniesz Terminal, a potem wybierzesz New Terminal (Nowy terminal).
Gdy terminal będzie dostępny, możesz uruchomić agenta za pomocą polecenia adk run. Ponieważ jest to nowe okno terminala i używamy uv, musisz najpierw przejść do folderu ai-agent-adk, a następnie dodać przed poleceniem adk run prefiks uv run.
Wpisz w terminalu te polecenia:
cd ai-agents-adk
uv run adk run personal_assistant
Jeśli wszystko jest skonfigurowane prawidłowo, w terminalu zobaczysz podobne dane wyjściowe.
... Running agent personal_assistant, type exit to exit. [user]: hello. What can you do for me? [personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as: ...
Śmiało, porozmawiaj z pracownikiem obsługi klienta. Zauważysz, że dane wyjściowe są czasami formatowane za pomocą Markdown, co może utrudniać odczytanie ich w terminalu. W następnym kroku użyjemy interfejsu programistycznego, aby uzyskać znacznie bardziej rozbudowane środowisko przypominające aplikację do czatowania.
7. Uruchamianie agenta w interfejsie programistycznym
Pakiet ADK umożliwia też wygodne uruchomienie agenta jako aplikacji do czatu za pomocą interfejsu programistycznego. Zamiast polecenia adk run. użyj polecenia adk web.
Jeśli nadal jesteś w poprzedniej sesji, wpisz w terminalu exit, aby ją zamknąć. Po zamknięciu poprzedniej sesji wpisz w terminalu to polecenie:
uv run adk web
W terminalu powinny pojawić się dane wyjściowe podobne do tych:
... INFO: Started server process [4978] INFO: Waiting for application startup. +------------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://localhost:8000. | +------------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
Interfejs programistyczny możesz otworzyć na 2 sposoby:
- Otwieranie za pomocą Terminala
- Ctrl + kliknięcie lub Cmd + kliknięcie adresów URL (np.
http://localhost:8000) z terminala.
- Otwórz za pomocą Podglądu w przeglądarce
- Kliknij przycisk Podgląd w przeglądarce.
- Kliknij Zmień port.
- Wpisz numer portu (np. 8000)
- Kliknij Zmień i wyświetl podgląd.
W przeglądarce pojawi się interfejs podobny do aplikacji do czatowania. Możesz czatować ze swoim osobistym asystentem w tym interfejsie. Zauważysz, że formatowanie Markdown jest teraz wyświetlane prawidłowo. Ten interfejs umożliwia też debugowanie i sprawdzanie każdego zdarzenia związanego z wysyłaniem wiadomości, stanu agenta, próśb użytkowników i wielu innych elementów. Udanych rozmów na czacie!
8. Czyszczenie
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.
9. Podsumowanie
Gratulacje! Udało Ci się utworzyć prostego agenta osobistego przy użyciu pakietu Agent Development Kit (ADK).
Jak zapewne wiesz, ten osobisty asystent nie jest jeszcze zbyt zaawansowany (np. nie ma dostępu do internetu, aby uzyskać najnowsze informacje). W kolejnych warsztatach z tej serii „Tworzenie agentów AI za pomocą ADK” dowiesz się, jak wzbogacić swojego osobistego asystenta o funkcje i narzędzia. Do zobaczenia!