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

1. Czego się nauczysz

Witamy w ADK Master Class – Twojej podróży do systemów wieloagentowych

Wkrótce wkroczysz do ekscytującego świata agentów AI. Zapomnij o prostych chatbotach, które tylko odpowiadają na pytania. Zagłębiamy się w 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 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 będziesz w stanie:

• 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.
• Twórz systemy wieloagentowe: 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ą.
• Orkiestracja złożonych przepływów 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żanie 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. Konfigurowanie GCP i klucza interfejsu Gemini API

Konfigurowanie projektu GCP i klucza interfejsu Gemini API

Aby uruchomić naszych agentów AI, potrzebujemy dwóch rzeczy: projektu Google Cloud, który będzie stanowić podstawę, oraz klucza interfejsu Gemini API, który umożliwi dostęp do zaawansowanych modeli Google.

Krok 1. Włącz konto rozliczeniowe

• Aby odebrać konto rozliczeniowe z 5-dolarowym kredytem, musisz je wykorzystać w procesie wdrażania. Zaloguj się na konto Gmail.

Nie musisz podawać karty kredytowej ani dokonywać płatności – otrzymasz 5 USD w środkach. Zajmie Ci to mniej niż 2 minuty. Wystarczy, że wpiszesz swoje imię i nazwisko oraz zaakceptujesz środki.

Krok 2. Utwórz nowy projekt GCP

• Otwórz konsolę Google Cloud i utwórz nowy projekt.

• Otwórz konsolę Google Cloud i utwórz nowy projekt.
• Otwórz panel po lewej stronie, kliknij Billing i sprawdź, czy konto rozliczeniowe jest połączone z tym kontem GCP.

Jeśli widzisz tę stronę, sprawdź manage billing account, wybierz Google Cloud Trial One i połącz go.

Krok 3. Wygeneruj klucz interfejsu Gemini API

Zanim zabezpieczysz klucz, musisz go mieć.

• Otwórz Google AI Studio : https://aistudio.google.com/
• Zaloguj się na konto Gmail.
• Kliknij przycisk „Uzyskaj klucz API”, który zwykle znajduje się w panelu nawigacyjnym po lewej stronie lub w prawym górnym rogu.
• W oknie „Klucze interfejsu API” kliknij „Utwórz klucz interfejsu API w nowym projekcie”.
• Wybierz utworzony przez siebie nowy projekt, w którym skonfigurowano konto rozliczeniowe.
• Wygenerujemy dla Ciebie nowy klucz interfejsu API. Natychmiast skopiuj ten klucz i tymczasowo zapisz go w bezpiecznym miejscu (np. w menedżerze haseł lub bezpiecznej notatce). Tej wartości użyjesz w kolejnych krokach.

3. Sesja 1. Pierwszy agent z Runnerem

Zacznijmy od podstaw. Utworzymy tu pierwszego prostego agenta, czyli day_trip_agent. Jego zadaniem jest generowanie planu całodniowej wycieczki na podstawie prośby użytkownika, z uwzględnieniem budżetu. W tym przykładzie przedstawiamy 3 główne komponenty każdej interakcji z agentem 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 prowadzenie ciągłego dialogu.
• 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 – Dżin 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 pracownika obsługi klienta, jak ma się zachowywać. Dajemy mu też pierwsze narzędzie: wyszukiwarkę Google.
• Funkcja pomocnicza: definicja funkcji pomocniczej run_agent_query(). Będziemy używać tego narzędzia w całym notatniku, aby uprościć wykonywanie zapytań.
• Test Run (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 „przystępną cenowo” wycieczkę w zapytaniu testowym jest bezpośrednio powiązana z wytyczną agenta, aby „brać pod uwagę budżet”.

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

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 określić, kiedy i jak używać narzędzia.

➡️ Gdzie znaleźć te informacje w notatniku

👉 Odpowiada to komórkom w sekcji 2.1 Proste narzędzie FunctionTool: wywoływanie interfejsu API prognozy pogody 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 dla agenta wyraźnie nakazują mu użycie 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 docstring funkcji 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, których można używać wielokrotnie. 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 przekazanie 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 złożony, 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: agent średniego poziomu, 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 sprawiają, że jest „głównym planistą podróży”, i ma 2 narzędzia, które wywołują pozostałe agenty:
  • 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 orkiestratora o znalezienie hotelu i pobliskiej restauracji.
  • Instrukcje dla narzędzia do orkiestracji mówią, że najpierw ma ono użyć narzędzia call_db_agent do pobrania danych 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, 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 orkiestratora, który ostatecznie prezentuje ją użytkownikowi.

➡️ Działanie: śledź przepływ wykonania w teście 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. Pamięć agenta 🧠

Prawdziwie inteligentny agent musi robić więcej niż tylko odpowiadać na jednorazowe zapytania. Musi pamiętać 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 dodatkowe 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, który ma stopniowo planować podróż. 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().

• Tworzony jest jeden trip_session, który jest używany przez 3 kolejne tury.
• 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 należy zmienić, i proponuje alternatywę.
• Tura 3: użytkownik potwierdza zmianę i prosi o kolejny krok. Agent pamięta wszystko i przystępuje do planowania dnia 2.

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łniliśmy błąd. Dla każdej tury tworzona jest nowa sesja.

• Tura 1: użytkownik rozpoczyna podróż w sesji 1. Pracownik obsługi klienta 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, pracownik obsługi klienta 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 wyspecjalizowanych agentów. Ale skąd wiemy, którego agenta użyć w przypadku danego zapytania? W tym momencie do akcji wkracza agent routera.

Agent routera pełni funkcję agenta „głównego” lub dyspozytora. 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 notebooku:

👉 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 instrukcję dla router_agent, która wyraźnie mówi, że ma on 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 wielu czynności w określonej kolejności. Na przykład: „Znajdź najlepsze sushi w Palo Alto, a potem powiedz mi, jak tam dojechać”. To proces dwuetapowy: najpierw znajdź restaurację, a potem wyznacz trasę.

ADK zapewnia przejrzysty i skuteczny sposób zarządzania tym procesem za pomocą klasy SequentialAgent. Jest to specjalny agent przepływu pracy, który wykonuje listę subagentó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 notebooku:

👉 Ten temat omawiamy 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 ma zapisać ostateczną odpowiedź w zmiennej o nazwie destination w stanie udostępnionym.
  • transportation_agent ma teraz w prompcie instrukcji symbol zastępczy {destination}. ADK automatycznie wstawia do tego obiektu 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 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 dopracować, aż spełni określone ograniczenie.

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

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

• Podstawowe klienty: przepływ pracy korzysta z klientó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 ⚡️

Najważniejsza jest efektywność. 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 równocześnie. Po zakończeniu wszystkich zadań równoległych ich wyniki można zebrać i zsyntetyzować w jedną, wyczerpującą 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 notebooku:

👉 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 agenty wyszukiwania są wymienione jako jego agenty podrzędne.
• Etap syntezy: po etapie równoległym agent syntezy zbiera wszystkie wyniki ze stanu udostępnionego, używając 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 agenta do planowania jednodniowych wycieczek w pakiecie ADK na komputerze lokalnym.

Wymagania wstępne

• Python 3.8 lub nowszy
  • Python 3.9 lub nowszy: instaluje google-adk==1.5.0 (najnowsza wersja z pełnym zakresem funkcji)
  • Python 3.8: instaluje google-adk==0.3.0 (kompatybilna wersja)
• Klucz interfejsu API Google AI Studio
• Połączenie z internetem

Krok 1. Sklonuj repozytorium

Otwórz terminal i uruchom to polecenie:

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.

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

source .adk_env/bin/activate

Na początku prompta terminala powinien pojawić się znak (.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 rozmowę 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 na komputerach Mac/Linux i Windows. Zauważysz, że prefiks (.adk_env) zniknie z prompta terminala.

Rozwiązywanie problemów na komputerach Mac

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

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

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

Wymagania wstępne

• Python 3.8 lub nowszy
  • Python 3.9 lub nowszy: instaluje google-adk==1.5.0 (najnowsza wersja z pełnym zakresem funkcji)
  • Python 3.8: instaluje google-adk==0.3.0 (kompatybilna wersja)
• Klucz interfejsu API Google AI Studio
• 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 polecenia:

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

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

Wiersz polecenia:

.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 rozmowę 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 na komputerach Mac/Linux i Windows. Zauważysz, że prefiks (.adk_env) zniknie z prompta terminala.