Wzorzec agenta ADK z pamięcią i MCP

1. Czego się nauczysz

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

Wkrótce wkroczysz do fascynującego świata agentów AI. Zapomnij o prostych chatbotach, które tylko odpowiadają na pytania. Zajmujemy się 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 ćwiczenie będzie praktyczne. W tym 1 repozytorium GitHub znajdziesz cały kod i przykłady do naszych sesji. Repozytorium GitHub

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.
• 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 poradzą sobie z niemal każdym żądaniem.
• Wyposażanie agentów w pamięć: poznaj kluczową rolę pamięci konwersacyjnej, która umożliwia agentom odpowiadanie na kolejne pytania, uczenie się na podstawie opinii i płynne wykonywanie wieloetapowych zadań.
• Połącz z MCP: połącz z MCP Toolbox.

Zaczynajmy! 🚀

2. Konfiguracja: uzyskiwanie klucza interfejsu API

Konfigurowanie klucza interfejsu API Google AI Studio

To ćwiczenie z programowania w całości wykorzystuje bezpłatny klucz interfejsu Google AI Studio API. Nie są wymagane żadne projekty Google Cloud, konta rozliczeniowe ani środki – każda sesja, w tym Memory (sesja 6) i MCP (sesja 7), jest uruchamiana lokalnie na podstawie Twojego klucza. Każdy uczeń używa własnego klucza, więc limit interfejsu API jest przypisany do osoby, a nie udostępniany.

Co będzie Ci potrzebne:

• Python 3.9 lub nowszy (python3 --version do sprawdzenia)
• Konto Google (do utworzenia klucza AI Studio)
• Terminal – może to być maszyna lokalna lub Cloud Shell.
• ~10 minut

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 kroku 4 poniżej.

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. Sklonuj repozytorium (1 min)

👉💻 Otwórz terminal (lub Cloud Shell) i sklonuj repozytorium samouczka:

git clone https://github.com/cuppibla/adk_tutorial.git
cd ~/adk_tutorial

Krok 3. Utwórz środowisko wirtualne i zainstaluj zależności

👉💻 Utwórz i aktywuj środowisko wirtualne o nazwie .adk_env, a następnie zainstaluj zależności:

python3 -m venv .adk_env
source .adk_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

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

Krok 4. 🔥 WAŻNE: dodaj klucz interfejsu API

⚠️ Nie pomijaj tego kroku. Utwórz plik .env w katalogu głównym folderu adk_tutorial. Ten jeden plik obsługuje każdą sesję w tym module – sesje ADK Web (1–5) i sesje Memory i MCP w wierszu poleceń (6–7) automatycznie go odczytują.

👉💻 Utwórz plik .env z kluczem (zastąp your_actual_api_key_here kluczem z kroku 1):

cat > .env <<'EOF'
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
EOF

Twój plik ~/adk_tutorial/.env powinien teraz zawierać:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 WAŻNE: zastąp your_actual_api_key_here rzeczywistym kluczem interfejsu API z kroku 1 (zaczyna się od AIza...).

⚠️ Sprawdź, czy zmienna GOOGLE_GENAI_USE_VERTEXAI ma wartość FALSE. Dzięki temu ADK będzie uwierzytelniać się za pomocą klucza interfejsu API Google AI Studio zamiast Vertex AI.

✅ Punkt kontrolny: masz plik .env w lokalizacji ~/adk_tutorial/.env zawierający klucz AIza..., a w wierszu poleceń terminala widzisz (.adk_env). Możesz już tworzyć agenty.

3. Sesja 1. Twój pierwszy agent w ADK Web

Otwórz ADK Web, uruchamiając to polecenie:

cd ~/adk_tutorial
source .adk_env/bin/activate
adk web

Po uruchomieniu poleceń w terminalu powinny pojawić się dane wyjściowe wskazujące, że serwer WWW ADK został uruchomiony. Powinny one wyglądać podobnie do tych:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+


INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

👉 Następnie otwórz przeglądarkę i wpisz adres http://localhost:8000, aby uzyskać dostęp do interfejsu ADK Dev UI.

Uruchamiasz w Cloud Shell zamiast lokalnie? Na pasku narzędzi Cloud Shell (zwykle w prawym górnym rogu) kliknij ikonę Podgląd w przeglądarce, wybierz Zmień port, ustaw port na 8000 i kliknij Zmień i wyświetl podgląd. Cloud Shell otworzy interfejs programisty ADK w nowej karcie przeglądarki.

👉 Rytuał przywołania został zakończony, a agent jest już aktywny. Interfejs programisty ADK w przeglądarce to bezpośrednie połączenie z urządzeniem Familiar.

wybierz pierwszego agenta – w menu u góry interfejsu wybierz a_single_agent.

Możesz wybrać a_single_agent tutaj:

Ślad możesz zobaczyć tutaj:

👉 Test Prompt:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art.

4. Sesja 2. Agent przepływu pracy: agent sekwencyjny, agent równoległy, agent pętli

Otwórz interfejs ADK, wykonując czynności opisane w sesji 1.

Agent usługi Parallel

wybierz agenta przepływu pracy równoległej – w menu u góry interfejsu wybierz b2_parallel_agent.

👉 Test Prompt:

Plan my trip to San Francisco, I want to find some good concert, restaurant and museum.

Możesz wybrać b2_parallel_agent tutaj:

Ślad możesz zobaczyć tutaj:

Agent sekwencyjny

wybierz agenta przepływu pracy sekwencyjnej – w menu u góry interfejsu wybierz b1_sequential_agent.

👉 Test Prompt:

Find a good sushi near Standford and tell me how to get there.

Możesz wybrać b1_sequential_agent tutaj:

Ślad możesz zobaczyć tutaj:

Agent pętli

wybierz agenta przepływu pracy pętli – w menu u góry interfejsu wybierz b3_loop_agent.

👉 Test Prompt:

Plan a trip from Sunnyvale to San Francisco today.

Możesz wybrać b3_loop_agent tutaj:

Ślad możesz zobaczyć tutaj:

5. Sesja 3. Agent niestandardowy

Otwórz interfejs ADK, wykonując czynności opisane w sesji 1.

Po otwarciu interfejsu ADK Web UI wybierz c_custom_agent z menu.

👉 Test Prompt:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art. Make sure within budget of 100 dollars.

Możesz wybrać c_custom_agent tutaj:

Ślad możesz zobaczyć tutaj:

6. Sesja 4. Wzorzec aranżera – agent kierujący

Otwórz interfejs ADK, wykonując czynności opisane w sesji 1.

Po otwarciu interfejsu ADK Web UI wybierz d_routing_agent z menu.

👉 Test Prompt:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Możesz wybrać d_routing_agent tutaj:

Ślad możesz zobaczyć tutaj:

7. Sesja 5. Agent jako narzędzie

Otwórz interfejs ADK, wykonując czynności opisane w sesji 1.

Po otwarciu interfejsu ADK Web UI wybierz e_agent_as_tool z menu.

👉 Test Prompt:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Możesz wybrać e_agent_as_tool tutaj:

Ślad możesz zobaczyć tutaj:

8. Sesja 6. Agent z pamięcią długotrwałą

Działa w pełni lokalnie. Ta sesja przechowuje pamięć konwersacji w lokalnej bazie danych SQLite (w ~/.adk/), dzięki czemu Twoje ustawienia są zachowywane po ponownym uruchomieniu i nie wymagają Google Cloud, płatności ani środków. Agent odczytuje klucz AI Studio z pliku ~/adk_tutorial/.env utworzonego w sekcji Konfiguracja.

👉💻 Sprawdź swoją pamięć długotrwałą, przechodząc do folderu i używając narzędzia do uruchamiania, aby zasilić agenta:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Test Prompt:

I like Art and Italian food.

Następnie zakończ sesję, naciskając Ctrl+C. Uruchom ponownie sesję:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Test Prompt:

Plan a trip to San Francisco based on my preference.

✅ Agent powinien pamiętać „sztukę i włoskie jedzenie” z poprzedniego uruchomienia – to pamięć długotrwała działająca w różnych sesjach.

9. Sesja 7. Zwiększ możliwości agenta dzięki MCP

Działa w pełni lokalnie. Ta sesja uruchamia lokalny serwer MCP Toolbox, który odczytuje lokalną bazę danych SQLite (destinations.db) – nie wymaga to Google Cloud, płatności ani środków. Jedynym pobieranym z zewnątrz elementem jest binarny plik narzędzi MCP Toolbox typu open source.

Krok 1. Przygotuj lokalną bazę danych

👉💻 W katalogu głównym repozytorium utwórz przykładową bazę danych:

cd ~/adk_tutorial
source .adk_env/bin/activate
chmod +x setup_trip_database.py
./setup_trip_database.py

Spowoduje to utworzenie magistrali destinations.db w: ~/adk_tutorial/.

⚠️ Przykładowa baza danych zawiera tylko 4 miasta: Paryż, Rzym, Nowy Jork i Tokio (rodzaje atrakcji: punkt orientacyjny, muzeum, park). Prompty, które odwołują się do innych miast (np. San Francisco lub Sunnyvale), prawidłowo zwrócą brak wyników, ponieważ te wiersze nie istnieją. Podczas testowania tej sesji użyj 4 miast wymienionych powyżej.

Krok 2. Zainstaluj i uruchom serwer MCP Toolbox

👉💻 Pobierz plik binarny Zestawu narzędzi MCP dla swojego systemu operacyjnego:

cd ~/adk_tutorial/mcp_tool_box
export VERSION=0.16.0

# Choose the line that matches your machine:
export OS=linux/amd64      # Cloud Shell or Linux (x86_64)
# export OS=darwin/arm64   # macOS Apple Silicon (M1/M2/M3)
# export OS=darwin/amd64   # macOS Intel

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox

po zakończeniu pobierania, a następnie uruchom

chmod +x toolbox

Nie wiesz, którego Maca używasz? Uruchom uname -m — arm64 = Apple Silicon, x86_64 = Intel. W Windows pobierz .../windows/amd64/toolbox.exe i uruchom go w PowerShellu.

Krok 3

W jednym terminalu uruchom to polecenie (pozostaw je uruchomione – agent połączy się z nim pod adresem http://127.0.0.1:7001):

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/mcp_tool_box
./toolbox --tools-file "trip_tools.yaml" --port 7001

W innym terminalu uruchom to polecenie:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/g_agents_mcp
python main.py

👉 Testowe prompty (użyj miast, które znajdują się w przykładowej bazie danych – Paryża, Rzymu, Nowego Jorku lub Tokio):

What are the top-rated things to do in Tokyo?

Show me the museums in Rome.

What can I do in New York for under 25 dollars?

Rozwiązywanie problemów z sesją 7

• „Connection refused” (Odmowa połączenia) lub agent nie znajduje narzędzi: serwer Toolbox w pierwszym terminalu nie działa – uruchom go ponownie i sprawdź, czy nasłuchuje na porcie 7001.
• Każde zapytanie zwraca puste wyniki: sprawdź, czy wykonano krok 1, aby upewnić się, że istnieje plik ~/adk_tutorial/destinations.db, i czy prompt zawiera jedno z 4 miast (Paryż, Rzym, Nowy Jork, Tokio).
• toolbox: cannot execute binary file w systemie macOS: pobrano kompilację dla systemu Linux – ponownie wykonaj krok 2, używając symbolu OS=darwin/arm64 (Apple Silicon) lub OS=darwin/amd64 (Intel).