Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Tworzenie agentów AI za pomocą ADK: podstawy

1. Zanim zaczniesz

Witamy w pierwszej części serii „Tworzenie agentów AI z użyciem pakietu ADK”. W tej serii ćwiczeń praktycznych 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 programistyczne i utworzyć podstawowego agenta konwersacyjnego. Po ukończeniu tego ćwiczenia z programowania będziesz mieć pierwszą interaktywną AI, którą możesz rozbudowywać w kolejnych częściach tej serii, aby przekształcić ją w zaawansowany system wieloagentowy (MAS).

To ćwiczenie możesz wykonać w środowisku lokalnym lub w Google Cloud. Aby uzyskać najbardziej spójne wyniki, zalecamy korzystanie z Cloud Shell w środowisku Google Cloud. Cloud Shell udostępnia też 5 GB pamięci trwałej w katalogu $HOME. Jest to przydatne do przechowywania skryptów, plików konfiguracyjnych lub sklonowanych repozytoriów.

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

Wymagania wstępne

Znajomość pojęć związanych z generatywną AI
podstawowa znajomość programowania w Pythonie,
Znajomość wiersza poleceń lub terminala

Czego się nauczysz

Jak skonfigurować środowisko Pythona
Tworzenie prostego agenta asystenta 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
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 on 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 i 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 do użycia platformom, takim jak pakiet Agent Development Kit (ADK), możesz teraz łatwo tworzyć własne agenty AI, nawet bez specjalistycznej wiedzy. Na początek stworzysz osobistego asystenta, który pomoże Ci w wykonywaniu zadań. Zaczynajmy!

3. Tworzenie projektu Google Cloud (opcjonalnie)

Zacznij od utworzenia nowego projektu w chmurze Google Cloud, aby działania z tego ćwiczenia były odseparowane od innych projektów.

Otwórz stronę console.cloud.google.com/projectcreate.
Wpisz wymagane informacje:

Nazwa projektu – możesz wpisać dowolną nazwę (np.genai-workshop).
Lokalizacja – pozostaw Brak organizacji.
Konto rozliczeniowe – jeśli widzisz tę opcję, wybierz Próbne konto rozliczeniowe Google Cloud Platform. Nie martw się, jeśli nie widzisz tej opcji. Przejdź do następnego kroku.

Skopiuj wygenerowany identyfikator projektu, ponieważ będzie potrzebny później.

Jeśli wszystko jest w porządku, kliknij przycisk Utwórz.

4. Konfiguracja środowiska

W tej sekcji skonfigurujesz środowisko programistyczne, tworząc katalog projektu, włączając wymagane interfejsy API, konfigurując wirtualne środowisko Pythona i instalując niezbędne pakiety.

Konfigurowanie Cloud Shell

Po utworzeniu projektu wykonaj te czynności, aby skonfigurować Cloud Shell.

Krok 1. Uruchom Cloud Shell

Otwórz stronę shell.cloud.google.com. Jeśli pojawi się wyskakujące okienko z prośbą o autoryzację, kliknij Autoryzuj.

Krok 2. Ustawianie identyfikatora projektu

Aby ustawić prawidłowy identyfikator projektu, uruchom to polecenie w terminalu Cloud Shell. Zastąp <your-project-id> rzeczywistym identyfikatorem projektu skopiowanym w kroku tworzenia projektu powyżej.

gcloud config set project <your-project-id>

W terminalu Cloud Shell powinien być teraz wybrany prawidłowy projekt. Wybrany identyfikator projektu jest wyróżniony na żółto.

Krok 3. Włącz wymagane interfejsy API

Aby korzystać z usług Google Cloud, musisz najpierw aktywować odpowiednie interfejsy API w swoim projekcie. Aby włączyć usługi na potrzeby tego modułu, uruchom w terminalu Cloud Shell te polecenia:

gcloud services enable aiplatform.googleapis.com

Jeśli operacja się powiedzie, w terminalu pojawi się Operation/... finished successfully.

Tworzenie środowiska wirtualnego 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.

Krok 1. Utwórz katalog projektu i przejdź do niego:

mkdir -p ai-agents-adk
cd ai-agents-adk

Krok 2. Utwórz i aktywuj środowisko wirtualne:

uv venv --python 3.12
source .venv/bin/activate

Przed promptem terminala zobaczysz prefiks (ai-agents-adk), który oznacza, że środowisko wirtualne jest aktywne.

Krok 3. Strona instalacji pakietu ADK

uv pip install --no-cache google-adk

5. Utwórz agenta

Gdy środowisko będzie gotowe, możesz utworzyć podstawy agenta AI. ADK wymaga kilku plików do zdefiniowania logiki i konfiguracji agenta:

agent.py: zawiera główny kod Pythona agenta, który określa jego nazwę, używany model LLM i podstawowe instrukcje.
__init__.py: oznacza katalog jako pakiet Pythona, co pomaga pakietowi ADK wykrywać i wczytywać definicję agenta.
.env: przechowuje informacje poufne i zmienne konfiguracyjne, takie jak klucz interfejsu API, identyfikator projektu i lokalizacja.

To polecenie utworzy nowy katalog o nazwie personal_assistant, który będzie zawierać 3 niezbędne pliki.

adk create personal_assistant

Po wykonaniu polecenia pojawi się prośba o wybranie kilku opcji konfiguracyjnych 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-3.5-flash
2. Other models (fill later)
Choose model (1, 2): 1

W drugim etapie 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
3. Login with Google
Choose a backend (1, 2, 3): 2

Następnie musisz sprawdzić, czy identyfikator projektu wyświetlany w nawiasach kwadratowych [...] jest prawidłowy. Jeśli tak, naciśnij Enter. Jeśli nie, wpisz prawidłowy identyfikator projektu w oknie wiersza poleceń:

Enter Google Cloud project ID [your-project-id]:

Na następne pytanie naciśnij Enter, aby użyć global jako regionu dla tego laboratorium.

Enter Google Cloud region [us-central1]: global

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

6. Poznaj kody agentów

Aby wyświetlić utworzone pliki, otwórz folder ai-agents-adk w edytorze Cloud Shell.

W górnym menu kliknij Plik > Otwórz folder….
Znajdź i wybierz folder ai-agents-adk.
Kliknij OK.

Jeśli górny pasek menu nie jest widoczny, możesz też kliknąć ikonę folderów i wybrać Otwórz folder.

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

Plik .env jest często domyślnie ukryty. Aby był widoczny w edytorze Cloud Shell:

otwórz pasek menu u góry,
kliknij Wyświetl,
kliknij Przełącz ukryte pliki.

Przeglądaj zawartość 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-3.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: ta linia importuje niezbędną klasę Agent z biblioteki ADK.
root_agent = Agent(...): w tym miejscu tworzysz instancję agenta AI.
name="root_agent": 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, rozumowania i generowania odpowiedzi. gemini-2.5-flash to szybki i wydajny model odpowiedni do zadań konwersacyjnych.
description="...": krótkie podsumowanie celu lub możliwości agenta. Opis jest przeznaczony dla ludzi lub innych agentów w systemie wieloagentowym, aby mogli zrozumieć, do czego służy dany agent. Jest często używany do rejestrowania, debugowania lub wyświetlania informacji o agencie.
instruction="...": to prompt systemowy, który określa zachowanie agenta i jego osobowość. Informuje model LLM, jak powinien działać i jakie jest jego główne przeznaczenie. 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: ta linia wykonuje import względny, informując Pythona, aby szukał modułu o nazwie agent (który odpowiada agent.py) w bieżącym pakiecie (personal-assistant). Ta prosta linia zapewnia, że gdy ADK próbuje załadować agenta personal-assistant, może znaleźć i zainicjować root_agent zdefiniowany w agent.py. Nawet jeśli jest pusty, obecność pliku __init__.py sprawia, że katalog jest pakietem Pythona.

.env

Ten plik zawiera konfiguracje specyficzne dla środowiska i dane uwierzytelniające o charakterze kontrowersyjnym.

GOOGLE_GENAI_USE_ENTERPRISE=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 Google Agent Platform 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 mógł 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 lub global). Użycie prawidłowej lokalizacji zapewnia skuteczną komunikację agenta z usługami Agent Platform w tym regionie.

7. Uruchamianie agenta w terminalu

Gdy wszystkie 3 pliki będą gotowe, możesz uruchomić agenta bezpośrednio z terminala. Aby to zrobić, uruchom w terminalu to polecenie: adk run

adk run personal_assistant

Jeśli wszystko jest skonfigurowane prawidłowo, w terminalu zobaczysz podobne dane wyjściowe. Na razie nie przejmuj się ostrzeżeniami. Jeśli widzisz [user]:, możesz kontynuować.

...
Running agent personal_assistant, type exit to exit.
[user]: 
...

Śmiało, porozmawiaj z pracownikiem obsługi klienta. Wpisz na przykład „cześć. Co możesz dla mnie zrobić?”, a powinnaś otrzymać odpowiedź.

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

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żyjesz interfejsu Development UI, który zapewnia znacznie bogatsze wrażenia przypominające aplikację do czatu.

Rozwiązywanie problemów

Ta metoda API wymaga włączenia płatności

Jeśli pojawi się komunikat {‘message': ‘This API method requires billing to be enabled'}, wykonaj te czynności:

Sprawdź, czy w pliku .env używasz prawidłowego identyfikatora projektu.
Otwórz stronę połączonego konta rozliczeniowego i sprawdź, czy konto rozliczeniowe jest już połączone.
Jeśli nie, wybierz opcję Próbne konto rozliczeniowe Google Cloud Platform.

Interfejs Vertex AI API nie był używany w projekcie

Jeśli pojawi się komunikat o błędzie zawierający {'message': 'Vertex AI API has not been used in project...'}, włącz interfejs Vertex AI API, wpisując w terminalu:

gcloud services enable aiplatform.googleapis.com

Jeśli operacja się powiedzie, w terminalu pojawi się Operation/... finished successfully.

Inne błędy

Jeśli pojawi się inny błąd niż wymienione powyżej, spróbuj ponownie załadować kartę Cloud Shell w przeglądarce (i w razie potrzeby ponownie autoryzować).

8. Uruchamianie agenta w interfejsie internetowym Development

Pakiet Agent Development Kit umożliwia też wygodne uruchomienie agenta jako aplikacji do czatowania za pomocą interfejsu programistycznego. Zamiast polecenia adk run. użyj polecenia adk web.

Jeśli terminal nadal działa w adk run, przed wpisaniem polecenia wpisz exit, aby go zamknąć.

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

Terminal powinien wyświetlić 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)

Do interfejsu programistycznego możesz uzyskać dostęp za pomocą jednej z tych dwóch metod:

Bezpośrednio w Terminalu: kliknij podany link, np. http://localhost:8000, przytrzymując klawisz Ctrl (lub Cmd).
Korzystanie z 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ć z osobistym asystentem w tym interfejsie.

Zauważysz, że formatowanie Markdown jest teraz wyświetlane prawidłowo. Ten interfejs umożliwia też debugowanie i badanie poszczególnych zdarzeń związanych z wiadomościami, stanu agenta, próśb użytkowników i wielu innych elementów. Udanych rozmów na czacie!

9. Czyszczenie (opcjonalnie)

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

10. Podsumowanie

Gratulacje! Udało Ci się utworzyć prostego osobistego asystenta za pomocą pakietu Agent Development Kit (ADK). Znasz już podstawy i główne komponenty agenta ADK.

Następnie możesz znacznie rozszerzyć możliwości agenta, udostępniając mu narzędzia do uzyskiwania dostępu do informacji w czasie rzeczywistym i interakcji z usługami zewnętrznymi. Jeśli chcesz kontynuować, następne ćwiczenie z tej serii, Tworzenie agentów AI z użyciem pakietu ADK: wzbogacanie narzędziami, przeprowadzi Cię przez ten proces.

Możesz też wziąć udział w naszym flagowym programie GEAR (Gemini Enterprise Agent Ready), aby uzyskać dostęp do cennych materiałów edukacyjnych. Możesz też wziąć udział w programie Get Certified, czyli w strukturalnym szkoleniu praktycznym prowadzonym przez ekspertów.