Szybkie szkolenie z ADK – od początkującego do eksperta

1. Czego się nauczysz

Witamy w ADK Master Class – Twoja droga do systemów z wieloma agentami

Wkraczasz do fascynującego świata agentów AI. Zapomnij o prostych chatbotach, które tylko odpowiadają na pytania. Intensywnie pracujemy nad Agent Development Kit (ADK), aby tworzyć zaawansowane, autonomiczne systemy, które potrafią rozumować, planować i korzystać z narzędzi do wykonywania złożonych zadań.

Całe to główne ćwiczenie w Codelabs będzie praktyczne. Przeprowadzę Cię przez 2 główne notatniki Colab, które zawierają cały kod i przykłady na potrzeby naszych sesji. Colab 1: Narzędzia i pamięć, Colab 2: MultiAgents

Po ukończeniu tego samouczka:

• Tworzenie pierwszego agenta AI: od zera do w pełni funkcjonalnego agenta, który rozumie potrzeby użytkownika, korzysta z narzędzi takich jak wyszukiwarka Google i generuje szczegółowe, przydatne odpowiedzi.
• Opanuj narzędzia niestandardowe: wykorzystaj pełny potencjał agentów, łącząc ich z własnymi funkcjami niestandardowymi i interfejsami API. Nauczysz agenta pobierania danych w czasie rzeczywistym, np. bieżących prognoz pogody.
• Tworzenie systemów wieloagentowych: poznaj wzorzec „Agent jako narzędzie”, rewolucyjną koncepcję, w której agenci delegują zadania do innych wyspecjalizowanych agentów, tworząc zespół ekspertów AI, którzy współpracują ze sobą.
• Administrowanie złożonymi przepływami pracy: wyjdź poza proste delegowanie i opanuj zaawansowane wzorce, takie jak routery, sekwencyjne łańcuchy, pętle i równoległe wykonywanie, aby tworzyć niezawodne, wydajne i inteligentne aplikacje, które mogą obsługiwać niemal każde żądanie.
• Wyposażenie agentów w pamięć: poznaj kluczową rolę pamięci konwersacyjnej, która umożliwia agentom odpowiadanie na dodatkowe pytania, uczenie się na podstawie opinii i płynne wykonywanie wieloetapowych zadań.

Zaczynajmy! 🚀

2. Konfiguracja: uzyskiwanie klucza interfejsu API

Konfigurowanie klucza interfejsu API Google AI Studio

Aby zasilać naszych agentów AI, potrzebujemy klucza interfejsu Gemini API z Google AI Studio. To najszybszy sposób na rozpoczęcie.

Krok 1. Uzyskaj klucz interfejsu Gemini API z AI Studio (1 min)

1. Otwórz stronę https://aistudio.google.com/app/apikey w nowej karcie przeglądarki.
2. Zaloguj się przy użyciu swojego konta Google.
3. Kliknij „Utwórz klucz interfejsu API” (w prawym górnym rogu).
4. Otworzy się okno z menu projektów:
   • Jeśli masz już utworzony projekt Google: wybierz go i kliknij „Utwórz klucz interfejsu API w istniejącym projekcie”.
   • Jeśli nie ma go na liście: kliknij „Utwórz projekt”.

5. Skopiuj wyświetlony klucz interfejsu API. Zaczyna się od AIza... i zawiera około 40 znaków.

✏️ Wklej go w bezpiecznym miejscu – będzie potrzebny w przypadku notatników Colab i konfiguracji ADK Web (w dodatku).

Traktuj klucz interfejsu API jak hasło. Nie wklejaj go na czatach publicznych, zrzutach ekranu ani nie przesyłaj do publicznego repozytorium GitHub.

Krok 2. Dodaj klucz interfejsu API do Colab (1 min)

Każdy notatnik ma komórkę konfiguracji, która wczytuje klucz interfejsu API. Masz 2 możliwości – wybierz tę, która Ci bardziej odpowiada:

Opcja A: Obiekty tajne Colab (zalecana – klucz pozostaje ukryty)

1. W notatniku Colab na pasku bocznym po lewej stronie kliknij ikonę klucza 🔑.
2. Kliknij „Add new secret” (Dodaj nowy klucz tajny).
3. W polu Nazwa ustaw GOOGLE_API_KEY.
4. Wklej klucz interfejsu API (z kroku 1) w polu Wartość.
5. Ustaw przełącznik „Dostęp do notatnika” w pozycji WŁ.

Gdy uruchomisz komórkę konfiguracji, automatycznie pobierze ona klucz:

✅ API key loaded from Colab Secrets.

Opcja B. Wklejanie po wyświetleniu prośby (szybkie i łatwe)

Jeśli pominiesz Colab Secrets i uruchomisz bezpośrednio codelab1 i codelab2, w notatniku pojawi się pole hasła:

🔑 Enter your Google AI Studio API key: ••••••••

Wklej klucz interfejsu API i naciśnij Enter. Klucz nie będzie widoczny na ekranie.

✅ API key entered manually.

⚠️ Niezależnie od wybranej opcji przed przejściem dalej sprawdź, czy widzisz komunikat z potwierdzeniem. Jeśli zobaczysz błąd dotyczący nieprawidłowego lub brakującego klucza interfejsu API, sprawdź, czy klucz zaczyna się od znaku AIza... i ma około 40 znaków.

Po uruchomieniu komórki klucza interfejsu API następna komórka konfiguruje środowisko:

✅ API key configured (starts with 'AIzaSy...')
✅ Using Google AI Studio (not Vertex AI).

✅ Sprawdź: w notatniku widzisz oba powyższe komunikaty ✅. Klucz interfejsu API jest skonfigurowany i możesz zacząć tworzyć agentów.

3. Sesja 1. Twój pierwszy agent z Runnerem

Zacznijmy od podstaw. Tworzymy tu pierwszego prostego agenta, czyli day_trip_agent. Zadaniem tego agenta jest generowanie planu podróży na cały dzień na podstawie prośby użytkownika, z uwzględnieniem budżetu. W tym przykładzie przedstawiamy 3 główne komponenty każdej interakcji agenta w pakiecie ADK:

• Agent: główny element operacji. Jest on określony przez instrukcje (osobowość i misję), model AI, z którego korzysta (np. Gemini), oraz narzędzia, do których ma dostęp.
• Sesja: pamięć rozmowy. Przechowuje historię interakcji (wiadomości użytkownika i odpowiedzi agenta), co umożliwia ciągły dialog.
• Runner: mechanizm, który wykonuje zadanie. Pobiera agenta i sesję, przetwarza nowe zapytanie użytkownika i koordynuje kroki w celu wygenerowania odpowiedzi.

➡️ Gdzie znaleźć te informacje w notatniku

👉 Odpowiada to komórkom w sekcji Część 1. Twój pierwszy agent – Genie od wycieczek jednodniowych 🧞.🌟

• Definicja agenta: poszukaj funkcji create_day_trip_agent(). W tym miejscu jest zdefiniowany agent. Zwróć uwagę na szczegółowy ciąg instrukcji – to prompt, który informuje agenta, jak ma się zachowywać. Dajemy jej też pierwsze narzędzie: wyszukiwarkę Google.
• Funkcja pomocnicza: funkcja pomocnicza run_agent_query() jest zdefiniowana tutaj. Będziemy używać tego narzędzia w całym notatniku, aby uprościć wykonywanie zapytań.
• Test: funkcja run_day_trip_genie() symuluje użytkownika, który prosi o „przystępną cenowo” i „relaksującą” wycieczkę jednodniową. Agent korzysta z instrukcji i narzędzia wyszukiwarki Google, aby znaleźć odpowiednie miejsca i utworzyć plan podróży w formacie Markdown.

➡️ Działanie: sprawdź prompta z instrukcjami dla day_trip_agent. Zobacz, jak prośba o „tani” przejazd w zapytaniu testowym jest bezpośrednio powiązana z wytyczną agenta, aby „pamiętać o budżecie”.

4. Sesja 2. Narzędzia niestandardowe 🛠️

Wyszukiwarka Google jest potężnym narzędziem, ale prawdziwy potencjał agentów AI można wykorzystać, gdy połączysz ich z własnymi, unikalnymi źródłami danych, interfejsami API lub niestandardową logiką. W tej sekcji utworzymy niestandardowe narzędzie na podstawie prostej funkcji Pythona.

Najważniejszą częścią narzędzia funkcji jest jego ciąg dokumentujący. ADK automatycznie analizuje ciąg dokumentu, aby zrozumieć, co robi narzędzie, jakie parametry przyjmuje (Args) i co zwraca (Returns). Duży model językowy (LLM) odczytuje ten opis, aby zdecydować, kiedy i jak użyć narzędzia.

➡️ Gdzie znaleźć te informacje w notatniku

👉 Odpowiada to komórkom w sekcji 2.1 Proste narzędzie funkcyjne: wywoływanie interfejsu Weather API w czasie rzeczywistym. 🌟

• Definicja narzędzia: funkcja get_live_weather_forecast(location: str) jest podstawą naszego narzędzia niestandardowego. Pobiera nazwę miasta, wywołuje publiczny interfejs API National Weather Service i zwraca słownik z temperaturą i prognozą.
• Definicja agenta: agent weather_agent jest tworzony i wyposażany w nasze nowe narzędzie przez przekazanie wartości tools=[get_live_weather_forecast] podczas jego inicjowania. Instrukcje agenta wyraźnie nakazują mu używanie tego narzędzia przed zaproponowaniem aktywności na świeżym powietrzu.
• Test: zapytanie „Chcę wybrać się na wędrówkę w pobliżu jeziora Tahoe. Jaka będzie pogoda?” bezpośrednio powoduje użycie narzędzia get_live_weather_forecast przez agenta, ponieważ wymagają tego jego instrukcje.

➡️ Działanie: przeczytaj ciąg dokumentujący funkcję get_live_weather_forecast i instrukcję dotyczącą weather_agent. Zwróć uwagę na bezpośrednią zależność między nimi.

5. Sesja 3. Agent jako narzędzie 🧑🍳

Po co tworzyć jednego monolitycznego agenta, skoro można stworzyć zespół specjalistów? Wzorzec Agent-as-a-Tool to skuteczny sposób na tworzenie złożonych systemów, w których główny agent, często nazywany koordynatorem lub routerem, deleguje zadania do innych, bardziej wyspecjalizowanych agentów.

Ten wzorzec umożliwia tworzenie modułowych agentów wielokrotnego użytku. Możesz na przykład mieć jednego agenta, który jest ekspertem w zakresie zapytań do bazy danych, drugiego, który jest ekspertem w zakresie kreatywnego pisania, i trzeciego, który pełni rolę przyjaznego konsjerża. Jego zadaniem jest zrozumienie prośby użytkownika i przekierowanie jej do odpowiedniego specjalisty.

➡️ Gdzie znaleźć te informacje w notatniku

👉 Odpowiada to komórkom w sekcji 2.2 Agent jako narzędzie: konsultacja ze specjalistą 🧑🍳.🌟

Ten przykład pokazuje, jak zbudować zaawansowany, wielowarstwowy system agentów:

• Specjaliści:
  • food_critic_agent: wysoce wyspecjalizowany agent, który podaje tylko sugestie dotyczące restauracji.
  • db_agent: przykładowy agent, który symuluje wysyłanie zapytań do bazy danych w celu uzyskania informacji o hotelach.
  • concierge_agent: pracownik obsługi klienta średniego szczebla, który pełni rolę uprzejmego konsjerża. Co ważne, ma on food_critic_agent jako własne narzędzie.
• Aranżer (trip_data_concierge_agent): to agent najwyższego poziomu, z którym wchodzi w interakcję użytkownik. Jego instrukcje czynią go „głównym planistą podróży”, a do dyspozycji ma 2 narzędzia, które wywołują pozostałych agentów:
  • call_db_agent: funkcja, która wywołuje db_agent.
  • call_concierge_agent: funkcja, która wywołuje concierge_agent.
• Przebieg: test przeprowadzony w run_trip_data_concierge() pokazuje pełny łańcuch delegowania.
  • Użytkownik prosi koordynatora o znalezienie hotelu i pobliskiej restauracji.
  • Instrukcje dla koordynatora mówią, że najpierw ma on użyć narzędzia call_db_agent, aby uzyskać dane o hotelach.
  • Orchestrator używa następnie narzędzia call_concierge_agent, aby uzyskać rekomendację.
  • concierge_agent po otrzymaniu prośby korzysta z własnego narzędzia, czyli food_critic_agent, aby znaleźć pomysł na restaurację.

Odpowiedź krytyka kulinarnego jest przekazywana z powrotem do konsjerża, który ją formatuje i wysyła z powrotem do koordynatora, który ostatecznie prezentuje ją użytkownikowi.

➡️ Działanie: śledź przebieg wykonania w sesji testowej w sekcji run_trip_data_concierge(). Zwróć uwagę, jak TOOL CALLED wydruki pokazują łańcuch delegowania od koordynatora do specjalistów. Jest to sekwencyjny łańcuch dowodzenia.

6. Sesja 4. Informacje zapamiętane przez agenta 🧠

Prawdziwie inteligentny agent musi robić więcej niż tylko odpowiadać na jednorazowe zapytania. Musi zapamiętywać rozmowę, rozumieć kontekst i dostosowywać się do opinii. Jest to możliwe dzięki odpowiedniemu zarządzaniu sesjami. „Agent pętli” to agent zaangażowany w ciągłą pętlę konwersacyjną, która jest oparta na jego pamięci.

Jeśli używasz tego samego obiektu sesji w przypadku wielu kolejnych zapytań, agent może „widzieć” całą historię rozmowy. Dzięki temu może odpowiadać na kolejne pytania, poprawiać się na podstawie opinii i planować wieloetapowe zadania.

➡️ Gdzie znaleźć te informacje w notatniku

👉 Odpowiada to komórkom w sekcji Część 3. Agent z pamięcią – adaptacyjny planer 🗺️. 🌟

• Definicja agenta: funkcja create_multi_day_trip_agent() definiuje agenta zaprojektowanego do stopniowego planowania podróży. Instrukcje podkreślają, że należy pamiętać o kontekście, reagować na opinie i planować każdy dzień z osobna.

Scenariusz 3a. Agent Z PAMIĘCIĄ (✅)

Ten test jest przeprowadzany w funkcji run_adaptive_memory_demonstration().

• Jeden trip_session jest tworzony i ponownie wykorzystywany w 3 kolejnych turach.
• Tura 1: użytkownik rozpoczyna planowanie 2-dniowej wycieczki.
• Tura 2: użytkownik przekazuje opinię („Nie przepadam za zamkami”). Ponieważ agent pamięta turę 1, wie, którą część planu zmienić, i proponuje alternatywę.
• Tura 3: użytkownik potwierdza zmianę i prosi o kolejny krok. Agent pamięta wszystko i przystępuje do planowania drugiego dnia.

Scenariusz 3b. Agent BEZ pamięci (❌)

Ten test jest przeprowadzany w funkcji run_memory_failure_demonstration().

Pokazuje to, jak ważne jest zarządzanie sesjami, ponieważ celowo popełniono błąd. Dla każdej tury tworzona jest nowa sesja.

• Tura 1: użytkownik rozpoczyna podróż w sesji 1. Agent odpowiada prawidłowo.
• Tura 2: użytkownik prosi o zaplanowanie dnia 2, ale zapytanie jest wysyłane w ramach nowej sesji session_two. Ponieważ nowa sesja nie ma historii, agent jest zdezorientowany. Ma amnezję. Nie wie, jaka podróż jest planowana.

Działanie: porównaj odpowiedzi pracownika obsługi klienta w run_adaptive_memory_demonstration() i run_memory_failure_demonstration(). To najważniejsza koncepcja w notatniku: jedna ciągła rozmowa wymaga jednej ciągłej sesji.

7. Sesja 5. Agent routera 🚏

Jeden agent może zrobić tylko tyle. Aby rozwiązywać naprawdę złożone problemy użytkowników, potrzebujemy zespołu specjalistów. Ale skąd wiemy, którego agenta użyć w przypadku danego zapytania? Właśnie tu do gry wkracza agent routera.

Agent routera działa jako agent „główny” lub dyspozytor. Jego jedynym celem jest analizowanie przychodzących zapytań użytkowników i określanie, który agent specjalistyczny (lub przepływ pracy agentów) najlepiej się do tego nadaje. Nie odpowiada na zapytanie, tylko przekazuje je do odpowiedniego agenta niższego poziomu.

Na przykład zapytanie o „najlepsze sushi” powinno trafić do agenta foodie_agent, a pytanie o „koncerty w ten weekend” powinno być obsługiwane przez weekend_guide_agent.

➡️ Gdzie znaleźć te informacje w notatniku:

👉 Ta koncepcja jest kluczowa dla całego notatnika, ale po raz pierwszy pojawia się w części 1: Multi-Agent Mayhem – sekwencyjne przepływy pracy 🧠→🤖→🤖 🌟

• Definicje agentów: komórka kodu definiuje kilku agentów specjalistycznych (day_trip_agent, foodie_agent, transportation_agent) i co najważniejsze, agenta routera. Zwróć szczególną uwagę na prompt z instrukcjami dla router_agent. Jest w nim wyraźnie napisane, że ma zwracać tylko nazwę najlepszego agenta do wykonania zadania.
• Logika wykonania: funkcja run_sequential_app pokazuje, jak najpierw wywołać router_agent, aby uzyskać decyzję (chosen_route), a następnie użyć tej decyzji w bloku if/elif do wykonania odpowiedniego agenta specjalistycznego.

8. Sesja 6. SequentialAgent ⛓️

Niektóre zadania wymagają wykonania kilku czynności w określonej kolejności. Na przykład: „Znajdź najlepsze sushi w Palo Alto, a potem powiedz mi, jak tam dojechać”. Proces ten składa się z 2 etapów: najpierw znajdź restaurację, a potem wyznacz trasę.

ADK zapewnia przejrzysty i skuteczny sposób zarządzania tym za pomocą klasy SequentialAgent. Jest to specjalny agent przepływu pracy, który wykonuje listę podrzędnych agentów w zdefiniowanej kolejności.

Magia tkwi w udostępnionym stanie. Dane wyjściowe jednego agenta w sekwencji można automatycznie zapisać w słowniku stanu współdzielonego, a następnie użyć jako dane wejściowe dla następnego agenta, co eliminuje potrzebę złożonego kodu ręcznego do przekazywania informacji między krokami.

➡️ Gdzie znaleźć te informacje w notatniku:

👉 Omówiliśmy to w części 2 (ADK): Multi-Agent Mayhem with SequentialAgent 🧠→⛓️→🤖. 🌟

• Refaktoryzacja agenta: w pierwszej komórce kodu w tej sekcji zwróć uwagę na kluczowe zmiany w funkcjach foodie_agent i transportation_agent:
  • foodie_agent ma teraz output_key="destination". Informuje to ADK, że ostateczna odpowiedź ma zostać zapisana w zmiennej o nazwie destination w stanie udostępnionym.
  • transportation_agent ma teraz w prompcie instrukcji obiekt zastępczy {destination}. ADK automatycznie wstawia do tego symbolu zastępczego wartość ze stanu udostępnionego.
• Definiowanie przepływu pracy: find_and_navigate_agent jest zdefiniowany jako SequentialAgent, a jego sub_agents są ustawione na [foodie_agent, transportation_agent], co zapewnia, że będą one uruchamiane w tej kolejności.
• Uproszczone wykonywanie: w tej sekcji znajdziesz funkcję run_sequential_app. Złożona logika if/elif zniknęła. find_and_navigate_agent jest teraz traktowany jako pojedyncza jednostka, którą można wywołać, a pakiet ADK automatycznie obsługuje wewnętrzne kroki sekwencyjne.

9. Sesja 7. LoopAgent 🔁

Nie wszystkie problemy mają proste, jednorazowe rozwiązanie. Czasami musimy zaproponować rozwiązanie, skrytykować je i ulepszyć, aż spełni określone wymagania.

W tym celu ADK udostępnia LoopAgent. Ten agent przepływu pracy wielokrotnie wykonuje sekwencję subagentów, dopóki nie zostanie spełniony określony warunek. To idealne rozwiązanie do tworzenia „perfekcjonistycznych” agentów, którzy potrafią planować, krytykować i ulepszać własną pracę.

Diagram pokazuje, że najpierw Planner Agent tworzy plan. Następnie wpisujemy LoopAgent. Critic Agent sprawdza plan. Jeśli jest wadliwa, Refiner Agent tworzy nową wersję i pętla się powtarza. Jeśli plan jest dobry, Refiner Agent wywołuje narzędzie exit_loop i zwraca ostateczny, zweryfikowany plan.

➡️ Gdzie znaleźć te informacje w notatniku:

👉 Wyjaśniamy to w artykule Iteracyjne pomysły z LoopAgentem 🧠→🔁→🤖. 🌟

• Centrum agentów: przepływ pracy korzysta z agentów planner_agent, critic_agent i refiner_agent.
• Definicja pętli: refinement_loop to LoopAgent, który koordynuje critic_agent, refiner_agent i sets max_iterations=3.
• Warunek zakończenia: pętla kończy się, gdy critic_agent zatwierdzi plan, co spowoduje, że refiner_agent wywoła niestandardowe narzędzie exit_loop.

10. Sesja 8. ParallelAgent⚡️

Wydajność jest kluczowa. Jeśli użytkownik poprosi o kilka niezwiązanych ze sobą informacji naraz, wykonywanie tych wyszukiwań po kolei będzie powolne.

Rozwiązaniem jest ParallelAgent. Ten agent przepływu pracy wykonuje listę subagentów jednocześnie. Gdy wszystkie zadania równoległe zostaną ukończone, ich wyniki można zebrać i zsyntetyzować w jedną, kompleksową odpowiedź.

Ten diagram pokazuje ParallelAgent, jak pojedyncze zapytanie jest dzielone na 3 równoległe ścieżki. museum_finder, concert_finder i restaurant_finder działają w tym samym czasie. Gdy wszystkie 3 agenty zakończą pracę, ich indywidualne wyniki (zapisane w stanie współdzielonym) zostaną połączone i przekazane do końcowego agenta syntezy, który połączy je w jedną odpowiedź.

➡️ Gdzie znaleźć te informacje w notatniku:

👉 Ten przepływ pracy został szczegółowo opisany w sekcji Równoległa moc dzięki ParallelAgent 🧠→⚡️→🤖🤖🤖. 🌟

• Agenci specjalistyczni: zdefiniowano 3 rodzaje agentów specjalistycznych, z których każdy ma unikalny klucz wyjściowy (np. museum_result).
• Przepływ pracy równoległej: agent parallel_research_agent jest zdefiniowany jako ParallelAgent, a 3 agenci wyszukiwania są wymienieni jako jego agenci podrzędni.
• Krok syntezy: po kroku równoległym końcowy agent syntezy zbiera wszystkie wyniki ze stanu udostępnionego za pomocą symboli zastępczych ({museum_result}, {concert_result} itp.), aby sformatować zwięzłe podsumowanie.

11. Dodatek: ADK Web – 🍎 Mac/Linux

Ten przewodnik przeprowadzi Cię przez proces konfigurowania i uruchamiania na komputerze lokalnym agenta do planowania wycieczek jednodniowych w pakiecie ADK.

Wymagania wstępne

• Python 3.8 lub nowszy
  • Python 3.9 lub nowszy: instaluje google-adk==1.5.0 (najnowszą wersję z pełnym zakresem funkcji)
  • Python 3.8: instaluje google-adk==0.3.0 (kompatybilna wersja)
• Klucz interfejsu Google AI Studio API (z kroku konfiguracji powyżej)
• Połączenie z internetem

Krok 1. Sklonuj repozytorium

Otwórz Terminal i uruchom:

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

Krok 2. Skonfiguruj środowisko wirtualne i zainstaluj zależności

Opcja A: automatyczna konfiguracja (zalecana)

# Run the setup script
chmod +x setup_venv.sh
./setup_venv.sh

Opcja B. Konfiguracja ręczna

# Create virtual environment
python3 -m venv .adk_env

# Activate virtual environment
source .adk_env/bin/activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

Krok 3. 🔥 WAŻNE – utwórz zmienne środowiskowe

⚠️ Nie pomijaj tego kroku! Utwórz plik .env w katalogu agent/:

# Create the .env file
touch agent/.env

# Open it in your default text editor
open agent/.env

Dodaj do tego pliku te wiersze:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 KRYTYCZNE: zastąp your_actual_api_key_here rzeczywistym kluczem interfejsu API z kroku Konfiguracja: pobieranie klucza interfejsu API.

Krok 4. Aktywuj środowisko wirtualne (jeśli nie jest jeszcze aktywne)

source .adk_env/bin/activate

Na początku prompta terminala powinien pojawić się tekst (.adk_env).

Krok 5. Uruchom interfejs internetowy ADK

adk web

Krok 6. Otwórz przeglądarkę

1. Otwórz przeglądarkę i przejdź do adresu URL wyświetlanego w terminalu (zwykle http://localhost:8000).
2. W menu u góry po lewej stronie kliknij agent.
3. Rozpocznij czat z pracownikiem obsługi klienta, który pomoże Ci zaplanować wycieczkę jednodniową.

Zobaczysz rozmowę podobną do tej:

Dezaktywowanie środowiska

Gdy skończysz pracę nad projektem:

deactivate

To polecenie działa tak samo w systemach Mac/Linux i Windows. Zauważysz, że z prompta terminala zniknie prefiks (.adk_env).

Rozwiązywanie problemów na komputerach Mac

• Nie znaleziono Pythona: użyj python3 zamiast python
• Odmowa dostępu: przed uruchomieniem skryptu wykonaj działanie chmod +x setup_venv.sh.

12. Dodatek: ADK Web – 🪟 dla użytkowników systemu Windows

Ten przewodnik przeprowadzi Cię przez proces konfigurowania i uruchamiania na komputerze lokalnym agenta do planowania wycieczek jednodniowych w pakiecie ADK.

Wymagania wstępne

• Python 3.8 lub nowszy
  • Python 3.9 lub nowszy: instaluje google-adk==1.5.0 (najnowszą wersję z pełnym zakresem funkcji)
  • Python 3.8: instaluje google-adk==0.3.0 (kompatybilna wersja)
• Klucz interfejsu Google AI Studio API (z kroku konfiguracji powyżej)
• Połączenie z internetem

Krok 1. Sklonuj repozytorium

Otwórz wiersz polecenia lub PowerShell i uruchom:

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

Krok 2. Skonfiguruj środowisko wirtualne i zainstaluj zależności

Opcja A: automatyczna konfiguracja (zalecana)

# Run the setup script in Command Prompt
setup_venv.bat

Opcja B. Konfiguracja ręczna

W przypadku wiersza poleceń:

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

W przypadku programu PowerShell:

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\Activate.ps1

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

Krok 3. 🔥 WAŻNE – utwórz zmienne środowiskowe

⚠️ Nie pomijaj tego kroku! Utwórz plik .env w katalogu agent/:

# Create the .env file
type nul > agent\.env

# Open it in Notepad
notepad agent\.env

Dodaj do tego pliku te wiersze:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 KRYTYCZNE: zastąp your_actual_api_key_here rzeczywistym kluczem interfejsu API z kroku Konfiguracja: pobieranie klucza interfejsu API.

Krok 4. Aktywuj środowisko wirtualne (jeśli nie jest jeszcze aktywne)

Wiersz poleceń:

.adk_env\Scripts\activate

PowerShell:

.adk_env\Scripts\Activate.ps1

Na początku promptu powinien pojawić się tekst (.adk_env).

Krok 5. Uruchom interfejs internetowy ADK

adk web

Krok 6. Otwórz przeglądarkę

1. Otwórz przeglądarkę i przejdź do adresu URL wyświetlanego w terminalu (zwykle http://localhost:8000).
2. W menu u góry po lewej stronie kliknij agent.
3. Rozpocznij czat z pracownikiem obsługi klienta, który pomoże Ci zaplanować wycieczkę jednodniową.

Rozwiązywanie problemów z systemem Windows

• Błąd zasad wykonywania PowerShell: uruchom Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Zobaczysz rozmowę podobną do tej:

Dezaktywowanie środowiska

Gdy skończysz pracę nad projektem:

deactivate

To polecenie działa tak samo w systemach Mac/Linux i Windows. Zauważysz, że z prompta terminala zniknie prefiks (.adk_env).