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

Tworzenie agentów AI za pomocą ADK: podstawy

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;
ciekawość i chęć do nauki,

Wykorzystywanie testowego konta rozliczeniowego

Aby ukończyć to ćwiczenie, musisz też mieć aktywne konto rozliczeniowe Google Cloud. Jeśli nie masz jeszcze konta rozliczeniowego, wykonaj te czynności, aby aktywować konto próbne:

Otwórz okno incognito w przeglądarce.
Otwórz ten portal odbioru nagród.
Zaloguj się za pomocą osobistego konta Gmail.
Postępuj zgodnie z instrukcjami krok po kroku w portalu.

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 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ń w celu osiągnięcia zdefiniowanego celu.

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

Zacznij od utworzenia nowego projektu Google Cloud, aby działania z tego laboratorium były odizolowane tylko w tym nowym projekcie.

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 on potrzebny później.

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

Konfigurowanie Cloud Shell

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

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.

2. Ustawianie identyfikatora projektu

Aby ustawić prawidłowy identyfikator projektu, wykonaj 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.

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.

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.

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

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

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.

3. Strona instalacji pakietu ADK

uv pip install 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ę, model LLM, z którego korzysta, oraz podstawowe instrukcje.
__init__.py: oznacza katalog jako pakiet Pythona, co pomaga 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 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

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ć us-central1 jako regionu dla tego laboratorium.

Enter Google Cloud region [us-central1]:

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,
kliknąć 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-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ę 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, wnioskowania 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 z wieloma agentami, 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 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 język 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 nazwie agent (który odpowiada agent.py) w bieżącym pakiecie (personal-assistant). Ten prosty wiersz zapewnia, że gdy ADK próbuje wczytać 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_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.

7. Uruchamianie agenta w terminalu

Gdy wszystkie 3 pliki będą na miejscu, 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ć? i 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żyjemy interfejsu programistycznego, aby uzyskać znacznie bardziej rozbudowane środowisko przypominające aplikację do czatowania.

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 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 w terminalu nadal działa polecenie adk run, wpisz exit, aby zamknąć terminal, zanim wpiszesz to polecenie:

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)

Dostęp do interfejsu programisty możesz uzyskać na 2 sposoby:

Otwieranie za pomocą Terminala

Naciśnij Ctrl i kliknij lub Cmd i kliknij link (np. http://localhost:8000), jak pokazano w terminalu.

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ć z 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!

9. Czyszczenie (opcjonalnie)

Ten przewodnik nie obejmuje żadnych długotrwałych usług, więc wystarczy zatrzymać aktywne sesje agenta (np. instancję adk web w terminalu), naciskając klawisze Ctrl + C lub Cmd + 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.

10. Podsumowanie

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

Kolejnym krokiem może być znaczne zwiększenie możliwości agenta przez udostępnienie mu narzędzi do uzyskiwania dostępu do informacji w czasie rzeczywistym i interakcji z usługami zewnętrznymi. Jeśli chcesz kontynuować, następny codelab z tej serii, Tworzenie agentów AI za pomocą ADK: zwiększanie możliwości dzięki narzędziom, przeprowadzi Cię przez ten proces.