Tworzenie spersonalizowanych agentów za pomocą pakietu ADK, MCP i pamięci

1. Wprowadzenie

Nowoczesny zestaw narzędzi agenta

Stworzenie agenta AI klasy produkcyjnej wymaga czegoś więcej niż tylko dużego modelu językowego (LLM). Model LLM zapewnia możliwości rozumowania, ale solidny agent musi wchodzić w interakcje ze światem zewnętrznym, zarządzać stanem rozmowy i zapamiętywać preferencje użytkownika na przestrzeni czasu.

Z tych warsztatów dowiesz się, jak zaprojektować i zbudować kompleksowy system oparty na agentach przy użyciu 3 podstawowych technologii:

1. Łączność (MCP): aby umożliwić agentowi dostęp do lokalnych narzędzi i danych.
2. Orchestration (ADK): do zarządzania pętlą rozumowania i stanem agenta.
3. Pamięć (Bank zapamiętanych informacji): zapewnia długoterminowy, spersonalizowany kontekst.

Podstawowe pojęcia

Komponent	Funkcja
Model Context Protocol (MCP)	Uniwersalny standard, który łączy modele AI z systemami zewnętrznymi (bazami danych, systemami plików, interfejsami API) bez konieczności stosowania integracji niestandardowych.
Agent Development Kit (ADK)	Platforma, która zapewnia środowisko wykonawcze dla agentów, zarządzając pętlą zdarzeń, przejściami stanu i wykonywaniem narzędzi.
Usługa sesji	Obsługuje pamięć krótkotrwałą. Zachowuje on bezpośredni kontekst rozmowy (np. „O co właśnie zapytał użytkownik?”), ale jest usuwany po zakończeniu sesji.
Vertex AI Memory Bank	Obsługuje pamięć długotrwałą. Przechowuje informacje i preferencje użytkownika (np. „Użytkownik woli Pythona”) bezterminowo, co umożliwia agentowi personalizowanie przyszłych interakcji.
Vertex AI Agent Engine	Zarządzana usługa infrastruktury, która hostuje logikę agenta i komponenty pamięci w skali.

Co utworzysz

Aby zademonstrować te koncepcje, stworzysz asystenta projektowania świątecznego. Ten agent będzie w stanie przyjmować ogólne prośby użytkowników i autonomicznie koordynować lokalne narzędzia w Pythonie, aby generować spersonalizowany kod i obrazy.

Proces ten składa się z 3 etapów:

1. Warstwa narzędziowa: utwórz serwer MCP, aby udostępniać funkcje lokalnego Pythona AI.
2. Warstwa agenta: użyj pakietu ADK, aby utworzyć agenta, który planuje i wykonuje wieloetapowe przepływy pracy.
3. Warstwa pamięci: zintegruj Bank zapamiętanych informacji, aby umożliwić agentowi uczenie się i zapamiętywanie preferencji użytkownika dotyczących stylu.

2. Skonfiguruj

Aby obsługiwać agentów AI, potrzebujemy dwóch rzeczy: projektu Google Cloud, który będzie stanowić podstawę.

Część 1. Włączanie konta rozliczeniowego

Aby wykonać to ćwiczenie, musisz mieć konto rozliczeniowe z pewną ilością środków. Aby rozpocząć, użyj środków z banera u góry tego modułu. Jeśli masz już połączenie z kontem rozliczeniowym, możesz pominąć ten krok.

Część 2. Środowisko otwarte

1. 👉 Kliknij ten link, aby przejść bezpośrednio do edytora Cloud Shell
2. 👉 Jeśli w dowolnym momencie pojawi się prośba o autoryzację, kliknij Autoryzuj, aby kontynuować.
3. 👉 Jeśli terminal nie pojawia się u dołu ekranu, otwórz go:
   • Kliknij Wyświetl.
   • Kliknij Terminal.
4. 👉💻 W terminalu sprawdź, czy uwierzytelnianie zostało już przeprowadzone, a projekt jest już ustawiony na Twój identyfikator projektu, używając tego polecenia:

   gcloud auth list
   

5. 👉💻 Sklonuj projekt początkowy z GitHuba:

   git clone https://github.com/cuppibla/holiday_workshop
   

6. 👉💻 Uruchom skrypt konfiguracji z katalogu projektu.

   cd ~/holiday_workshop
   ./init.sh
   

   ⚠️ Uwaga dotycząca identyfikatora projektu: skrypt zaproponuje losowo wygenerowany domyślny identyfikator projektu. Aby zaakceptować tę wartość domyślną, możesz nacisnąć Enter.

   Jeśli jednak wolisz utworzyć konkretny nowy projekt, możesz wpisać wybrany identyfikator projektu, gdy skrypt o to poprosi.

   Skrypt automatycznie przeprowadzi pozostałą część procesu konfiguracji.
7. 👉💻 Ustaw wymagany identyfikator projektu:

   gcloud config set project $(cat ~/project_id.txt) --quiet
   

Część 3. Konfigurowanie uprawnień

1. 👉💻 Włącz wymagane interfejsy API za pomocą tego polecenia. Może to potrwać kilka minut.

   gcloud services enable \
       cloudresourcemanager.googleapis.com \
       servicenetworking.googleapis.com \
       run.googleapis.com \
       aiplatform.googleapis.com \
       compute.googleapis.com
   

2. 👉💻 Przyznaj niezbędne uprawnienia, uruchamiając w terminalu te polecenia:

   . ~/holiday_workshop/set_env.sh
   

Zwróć uwagę, że utworzyliśmy dla Ciebie .env. Wyświetlą się informacje o Twoim projekcie.

3. Zwiększanie mocy dzięki MCP

Moment „USB-C” dla AI

Wyobraź sobie, że za każdym razem, gdy kupujesz nową mysz, musisz ją przylutować do płyty głównej. Tak wyglądały narzędzia AI do niedawna. Deweloperzy musieli pisać niestandardowy „kod łączący”, aby połączyć LLM z bazami danych, systemami plików lub interfejsami API.

Wpisz Model Context Protocol (MCP). MCP to port USB-C dla aplikacji AI. Umożliwia standardowe łączenie modeli AI ze źródłami danych i narzędziami.

Jeśli utworzysz serwer MCP dla swoich narzędzi raz, możesz podłączyć go do interfejsu wiersza poleceń Gemini, środowiska IDE lub dowolnego innego klienta zgodnego z MCP bez zmiany ani jednej linii kodu.

Co utworzysz

W tym ćwiczeniu utworzysz Asystenta projektowania świątecznego, który:

1. Łączy się z lokalnym środowiskiem (narzędzia w Studio) za pomocą MCP.
2. Zarządza kontekstem rozmowy w niezawodny sposób za pomocą pakietu Agent Development Kit (ADK).
3. Zapamiętuje Twoje preferencje (np. „Wolę kod w Pythonie”) w różnych sesjach za pomocą Banku zapamiętanych informacji Vertex AI.

Ostrzeżenie: przed uruchomieniem przykładów kodu sprawdź, czy interfejs wiersza poleceń Google Cloud (gcloud auth login) został uwierzytelniony.

Tworzenie logiki serwera

Przygotowaliśmy środowisko, ale logika serwera jest niekompletna. Musimy wdrożyć 4 konkretne narzędzia, których nasz agent będzie ostatecznie używać do tworzenia kartki świątecznej.

Część 1. Otwórz szkielet serwera

Będziemy pracować w katalogu 01-MCP-Files-Testing/01-starter.

1. W terminalu Cloud Shell upewnij się, że jesteś w odpowiednim katalogu:

   cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
   

2. Otwórz plik w edytorze Cloud Shell, uruchamiając to polecenie:

   cloudshell edit ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py
   

Zauważysz, że powtarzalny kod (konfigurowanie serwera MCP, obsługa połączeń i inicjowanie klienta Vertex AI) jest już gotowy. Cztery podstawowe funkcje są jednak obecnie pustymi obiektami zastępczymi.

Część 2. Wdrażanie generatora scen świątecznych

Najpierw potrzebujemy narzędzia, które na podstawie zainteresowań użytkownika (np. „ptaki”) tworzy szczegółową podpowiedź zoptymalizowaną pod kątem generowania obrazów.

Znajdź komentarz #REPLACE_GENERATE_HOLIDAY_SCENE w funkcji generate_holiday_scene.

Zastąp cały ten wiersz tym kodem:

    prompt = (
        f"""
        Create a cozy, high-fidelity 3D render of a winter holiday scene.
        The scene should be warm and inviting with soft cinematic lighting.
        
        Seamlessly integrate the following specific theme/interest into the 
        holiday decor or landscape: {interest}.
        
        The style should be whimsical but detailed.
        Aspect Ratio: 16:9 Landscape.
        """
    )
    generate_image(prompt, "16:9", "static/generated_scene.png")
    return "Done! Saved at generated_scene.png"

Część 3. Wdrażanie końcowego wyniku zdjęcia

Na koniec chcemy, aby oświetlenie i styl wyglądały fotorealistycznie i świątecznie.

Znajdź komentarz #REPLACE_GENERATE_FINAL_PHOTO.

Zastąp cały ten wiersz tym kodem, aby przeprowadzić ostateczne przeniesienie stylu i renderowanie:

    prompt = (
        """
        Generate a photorealistic close-up shot of a rustic wooden fireplace mantle.
        
        Lighting: Warm, glowing ambient light from a fire below (out of frame).
        Background: Softly blurred (bokeh) pine garland and twinkling lights.
        
        Foreground Composition:
        1. A wooden picture frame containing the [attached selfie image]. 
           The face in the photo must be clearly visible.
        2. A folded holiday greeting card standing upright next to the frame. 
           The front of the card displays the [attached holiday scene image] as a print.
           
        Ensure the perspective is grounded and realistic, as if taken with a 50mm lens.
        """
    )
    generate_image(prompt, "16:9", "static/generated_final_photo.png", ["static/generated_selfie.png", "static/generated_scene.png"])
    return "Done! Saved at generated_final_photo.png"

Konfiguracja środowiska

Gdy kod jest już na miejscu, musimy się upewnić, że zainstalowane są zależności. Użyjemy uv, szybkiego menedżera pakietów i projektów Pythona.

👉💻 W terminalu uruchom to polecenie, aby dodać FastMCP jako zależność naszego projektu:

cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
uv add fastmcp

W pliku ~/holiday_workshop/01-MCP-Files-Testing/01-starter/pyproject.toml pojawi się nowa zależność fastmcp>=2.13.3.

4. Testowanie za pomocą interfejsu wiersza poleceń Gemini dla serwera MCP

Nasz kod serwera jest już gotowy. Jak go przetestować?

Zwykle testowanie serwera backendu wymaga utworzenia interfejsu użytkownika lub napisania złożonych żądań curl. W tym przypadku możemy jednak użyć interfejsu wiersza poleceń Gemini.

Czym jest interfejs wiersza poleceń Gemini?

Interfejs wiersza poleceń Gemini to narzędzie wiersza poleceń, które umożliwia bezpośrednie czatowanie z modelem Gemini w terminalu, ale z dodatkową funkcją: może automatycznie wykrywać i używać narzędzi działających na lokalnym serwerze MCP.

Jest to niezwykle przydatne podczas tworzenia aplikacji, ponieważ izoluje logikę. Możesz sprawdzić, czy model rozumie Twoje narzędzia i prawidłowo je wywołuje, zanim zaczniesz się martwić o tworzenie interfejsu internetowego lub platformy agenta.

Connect and Run

Za pomocą polecenia mcp add poinformujemy interfejs wiersza poleceń Gemini, że ma zarządzać naszym serwerem.

W terminalu uruchom:

gemini mcp add holidays uv run ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py

• add holidays: Nadaliśmy naszemu serwerowi pseudonim („holidays”).
• uv run ...: podaliśmy wyraźne polecenie uruchomienia zmodyfikowanego serwera Pythona.

Zróbmy coś magicznego!

Teraz rozpocznij sesję czatu:

gemini

Wypróbuj ten prompt, aby sprawdzić, czy Gemini „widzi” Twoje nowe narzędzia. Pamiętaj, że może być konieczne zezwolenie interfejsowi wiersza poleceń Gemini na korzystanie z naszego narzędzia do obsługi świąt.

• 👉 Użytkownik:

  "I want to create a festive holiday photo. I like birds a lot."
  

• Gemini:

  *Thinking...*
  *Calling tool: generate_holiday_scene(interest='birds')*
  
  Done! Saved at generated_scene.png
  

• 👉 Użytkownik:

  "Great! Now generate a knitting pattern for a sweater with reindeer on it."
  

• Gemini:

  *Thinking...*
  *Calling tool: generate_sweater_pattern(motif='reindeer')*
  
  Done! Saved at generated_pattern.png
  

  Dzięki użyciu MCP AI dokładnie wiedziała, którą funkcję Pythona wywołać, aby spełnić Twoją prośbę.

Sprawdź zdjęcie

• Zakończ pracę z interfejsem wiersza poleceń Gemini, naciskając Control+C.
• Sprawdź wygenerowane zdjęcie w folderze: ~/holiday_workshop/01-MCP-Files-Testing/01-starter/static.

Sprawdź swoje zdjęcie tutaj:

Podsumowanie i dalsze kroki

Gratulacje! Udało Ci się utworzyć działający serwer MCP. Masz teraz funkcjonalny zestaw „narzędzi AI”, które mogą generować wzory, łączyć obrazy i ulepszać sceny.

Czy jednak zauważyłeś(-aś) coś w powyższym teście? Ty musiałeś/aś kierować tym procesem. Musiałeś(-aś) poprosić o scenę, a potem o wzór, a następnie o połączenie ich.

Gemini jest inteligentny, ale w przypadku złożonego procesu produkcyjnego, w którym musimy wygenerować wzór zanim umieścimy go na swetrze, i obsługiwać błędy, jeśli generowanie obrazu się nie powiedzie, potrzebujemy większej kontroli. Chcemy mieć dedykowany system, który będzie mógł planować, oceniać własną pracę i zarządzać stanem naszej kartki świątecznej bez naszej ciągłej pomocy.

W następnej sekcji uporządkujemy ten kreatywny chaos. Aby utworzyć strukturalnego agenta, który będzie koordynować te narzędzia MCP w doskonałym procesie produkcyjnym, użyjemy pakietu Agent Development Kit (ADK).

5. Tworzenie agenta ADK z podejściem vibe coding

Mamy działający zestaw narzędzi (nasz serwer MCP), ale obecnie to my wykonujemy całą ciężką pracę – mówimy Gemini, którego narzędzia ma użyć i kiedy.

W tej sekcji utworzymy agenta AI, czyli system, który może autonomicznie wnioskować, planować i wykonywać wieloetapowe zadania. Użyjemy do tego pakietu Agent Development Kit (ADK).

Co to jest agent?

Jeśli narzędzia MCP są „rękami” (wykonują pracę), agent jest „mózgiem”. Agent używa modelu LLM, aby zrozumieć intencje użytkownika („Zrób kartkę świąteczną”), rozkłada je na etapy („Najpierw potrzebuję sceny, potem wzoru…”) i decyduje, których narzędzi użyć, aby osiągnąć cel.

Co to jest ADK?

Pakiet Agent Development Kit (ADK) to platforma Google, która ułatwia tworzenie takich agentów. Zajmuje się złożonymi „mechanizmami”, takimi jak zarządzanie historią czatu, łączenie z narzędziami i przełączanie się między różnymi modelami, dzięki czemu możesz skupić się na osobowości i logice aplikacji.

Kodowanie wibracji na podstawie kontekstu

Często stosuje się jeden obszerny prompt do generowania kodu. Jednak w przypadku tworzenia złożonych aplikacji lepiej jest traktować AI jako partnera, który z czasem zachowuje kontekst.

Zanim napiszemy choć jedną linię kodu, użyjemy funkcji Pamięć interfejsu wiersza poleceń Gemini, aby przygotować środowisko.

1. Przygotowywanie środowiska

Otwórz terminal i przejdź do katalogu początkowego:

cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter

Uruchom interfejs wiersza poleceń Gemini:

gemini

2. Zarządzanie kontekstem i pamięcią

Podczas kodowania nastroju AI musi wiedzieć, kim jest i co wie. Interfejs wiersza poleceń Gemini umożliwia nam jawne zarządzanie tymi ustawieniami.

• /memory show: wpisz to, aby sprawdzić, co AI wie obecnie o Twoim projekcie i sesji.
• /memory add: użyj tej opcji, aby przekazać podstawową wiedzę, którą AI powinna zapamiętać w trakcie rozmowy.

Zacznijmy od określenia profilu naszego partnera w zakresie kodowania. Uruchom to polecenie w interfejsie wiersza poleceń Gemini:

/memory add "You are an expert Python developer specialized in the Google Agent Development Kit (ADK). You write clean, modular code and prefer using the latest ADK patterns."

Gemini rozumie teraz swoją rolę. Ten kontekst będzie wpływać na każdą kolejną odpowiedź, zapewniając wysokiej jakości kod zgodny z ADK.

3. Krok 1. Vibe-Coding podstawowego agenta

Zamiast próbować wygenerować cały system naraz, zacznijmy od szkieletu. Chcemy ustalić strukturę pliku i podstawową osobowość agenta.

Wpisz w interfejsie wiersza poleceń Gemini ten prompt:

Let's start by building the basic agent structure. 

Please create a file structure for a `root_agent`. 
1. Create `root_agent/__init__.py` that imports `agent`.
2. Create `root_agent/agent.py` by following exactly how this file is doing import and agent creation @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py

In `agent.py`:
- Create an `Agent` named "root_agent" using the model "gemini-2.5-flash".
- The instruction string should define a "Holiday Magic Assistant". 
- The personality should be enthusiastic (`🎄✨`) and prefer "cute, kawaii, cartoon" styles for any visual tasks.

Gemini wygeneruje strukturę pliku i początkowy kod w Pythonie. Sprawdź, czy wygląda prawidłowo, a potem zastosuj lub zaakceptuj zmiany.

4. Krok 2. Dodawanie serwera MCP (narzędzia)

Teraz, gdy mamy już podstawowego agenta, musimy dać mu „ręce”. Musimy połączyć agenta z serwerem MCP, który został utworzony w poprzednim module.

Wpisz w interfejsie wiersza poleceń Gemini ten prompt:

Now, let's give the agent access to tools. Update `agent.py` to include our local MCP server. By following exactly how this agent is connecting to mcp tool @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py

In `agent.py`:
- Import `McpToolset` to define our STDIO MCP server. as @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
- Connect to the python file located at `../mcp_server.py` relative to agent.py.

Gemini przekształci teraz istniejący kod agent.py, aby uwzględnić definicje narzędzi i logikę połączenia.

Uwaga: jeśli chcesz sprawdzić swoją pracę lub wygenerowany kod nie działa zgodnie z oczekiwaniami, możesz porównać swoje pliki z rozwiązaniem referencyjnym znajdującym się w tym miejscu: ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/solution

6. Uruchamianie internetowego interfejsu agenta

ADK ma wbudowany interfejs testowy o nazwie adk web. Spowoduje to uruchomienie uproszczonego interfejsu czatu, dzięki czemu będziemy mogli od razu porozmawiać z pracownikiem obsługi klienta.

1. Jeśli GeminiCLI jest nadal otwarty, naciśnij control+C, aby go zamknąć. Teraz w terminalu(w folderze solution możesz przejść do folderu starter, aby przetestować kod, uruchamiając uv run adk web w folderze starter) uruchom:

   cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/02-solution
   uv run adk web --port 8000
   

2. Cloud Shell powiadomi Cię, że usługa jest uruchomiona na porcie 8000. Kliknij „Podgląd w przeglądarce” –> „Podejrzyj na porcie 8000”.

Testowanie agenta

Powinien pojawić się interfejs czatu. Sprawdźmy, czy nasz agent postępuje zgodnie z nowymi instrukcjami i ma prawidłowy dostęp do narzędzi MCP.

Wypróbuj te prompty:

• „Cześć! Kim jesteś?”.
  • (Spodziewaj się radosnej, entuzjastycznej odpowiedzi).
• „Potrzebuję tła do kartki świątecznej. Zmień ją w ośnieżoną wioskę”.
  • (Agent powinien zadzwonić pod numer generate_holiday_scene. Zwróć uwagę, że automatycznie stosuje styl „słodki/kreskówkowy” zdefiniowany w instrukcjach systemowych).
• „Wygeneruj wzór swetra z małymi kawałkami pizzy”.
  • (Przedstawiciel powinien zadzwonić pod numer generate_sweater_pattern).

Wygenerowany obraz możesz wyświetlić tutaj:

Jeśli skończysz testowanie, naciśnij Control+C, aby wyjść.

Podsumowanie i dalsze kroki

Udało Ci się „zakodować” agenta Google ADK za pomocą podejścia uwzględniającego kontekst.

• Ustaliliśmy kontekst: użyliśmy /memory add, aby zdefiniować profil eksperta.
• Zaczęliśmy od szkieletu: najpierw stworzyliśmy szkielet, a potem dodaliśmy połączenia z narzędziami.

Wbudowany podgląd internetowy ADK świetnie sprawdza się podczas testowania, ale w przypadku produktu końcowego chcemy zapewnić użytkownikom niestandardowe, markowe wrażenia. W następnej sekcji zintegrujemy tego agenta z niestandardowym interfejsem internetowym.

Jeśli w dowolnym momencie warsztatów napotkasz Unexpected response from metadata server: service account info is missing 'email' field, oznacza to, że musisz odświeżyć Cloud Shell i ponownie uruchomić gcloud config set project $(cat ~/project_id.txt) --quiet, aby ustawić project id przed kontynuowaniem.

7. Łączenie pakietu ADK z interfejsem

Teraz, gdy mamy definicję agenta, musimy ją stosować. W tym celu używane są Runner i Session Service.

Implementacja

1. 👉 Wpisz w poleceniu:

   cloudshell edit ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py
   

   Otworzy się ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py w edytorze.
2. Zastąp symbol # TODO: Create Session Service tymi elementami:

   from google.adk.sessions import InMemorySessionService
   from google.adk.memory import InMemoryMemoryService
   session_service = InMemorySessionService()
   memory_service = InMemoryMemoryService()
   

   Usługa sesji to „pamięć robocza” agenta.

   • Rola: przechowuje nieuporządkowaną, bieżącą historię obecnej rozmowy (np. „O co właśnie zapytałem?”).
   • 2 smaki:
   • InMemorySessionService: Szybki i łatwy, ale z amnezją. Jeśli ponownie uruchomisz serwer, agent zapomni wszystko. Świetnie nadaje się do testowania.
   • VertexAiSessionService: Solidna, oparta na bazie danych. Zapisuje stan w Google Cloud, dzięki czemu rozmowa może być kontynuowana nawet po kilku tygodniach lub po ponownym uruchomieniu serwera.
3. Zastąp symbol # TODO: Initialize Runner tymi elementami:

   runner = Runner(
       app_name="agents",
       agent=christmas_agent,
       session_service=session_service,
       memory_service=memory_service,
   )
   

Runner: jeśli agent jest „mózgiem”, Runner jest „sercem”. Utrzymuje przepływ krwi. Kurier jest odpowiedzialny za:

• Powiązanie agenta z użytkownikiem i sesją.
• wykonywanie pętli zdarzeń;
• Zarządzanie zmianami stanu.

4. Sprawdź wiersz 158 w tym ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py(nie musisz nic robić): jeśli zastanawiasz się, jak aplikacja uzyskuje ostateczną odpowiedź. Poniżej znajduje się pętla zdarzeń obsługiwana przez moduł wykonawczy:

   async for event in runner.run_async(
       user_id=user_id,
       session_id=session_id,
       new_message=content
   )
   

Pętla zdarzeń: agenci ADK nie tylko „odpowiadają”. Myślą w pętli. Gdy zadzwonisz pod numer runner.run_async():

1. Dane wejściowe użytkownika wchodzą w pętlę.
2. Planowanie: agent analizuje swoje narzędzia i cele.
3. Działanie: w odpowiednich przypadkach wywołuje narzędzie (np. list_files).
4. Obserwacja: odczytuje wynik działania narzędzia.
5. Zastanów się: model decyduje, czy potrzebuje więcej informacji, czy może odpowiedzieć.
6. Pętla: powtarza kroki 2–5, aż uzna, że wynik jest zadowalający.
7. Odpowiadanie: dostarcza użytkownikowi ostateczną odpowiedź.

Szczegółowe omówienie: architektura i wdrażanie

Do obsługi tego agenta używamy FastAPI.

• Dlaczego warto używać FastAPI? Agenci często czekają na operacje wejścia/wyjścia (oczekując na modele LLM). Asynchroniczny charakter FastAPI doskonale sobie z tym radzi.
• Brak stanu: zwróć uwagę, że nasz punkt końcowy API jest bezstanowy. Nie zapisujemy zmiennych w zakresie globalnym. Aby odtworzyć stan dla każdego żądania, korzystamy z session_id i SessionService. Oznacza to, że możesz wdrożyć tę usługę w Cloud Run (bezserwerowo) i skalować ją do zera.

8. Wypróbuj aplikację z magią agenta

1. 👉💻 Wpisz w poleceniu:

   cd ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter
   ./start_app.sh
   

   Otworzy się ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py w edytorze.
2. Wynik będzie wyglądać tak:👉👉 Kliknij http://localhost:5173/ lub otwórz nowe okno i wpisz http://localhost:5173/.

   Pamiętaj, że NIE jest to link do serwera backendu: Uvicorn running on http://0.0.0.0:8000

3. Następnie zobaczysz witrynę z interfejsem czatu:
4. Przetestuj, przesyłając 1 zdjęcie(może to być Twoje zdjęcie lub zdjęcie Twojego zwierzaka).
5. 👉 Następnie zadaj pytanie.

   Can you generate a picture my cat wearing snowflake pattern sweater?
   

   Wygenerowany obraz pojawi się tutaj:
6. 👉💻 Po zakończeniu testowania naciśnij control+C w terminalu, aby zakończyć proces.

Jeśli nie widzisz, że wszystko działa zgodnie z oczekiwaniami, możesz przejść do ~/holiday_workshop/03-Connect-ADK-MCP-UI/02-solution i uruchomić ./start_app.sh, a następnie wykonać te same czynności co powyżej.

9. Vertex AI Memory Bank

Pamięć krótkotrwała a długotrwała

• Krótkoterminowy kontekst: „Co właśnie powiedziałem?”. (Historia sesji). Zostanie ona utracona po zamknięciu okna czatu.
• Pamięć długotrwała: „Jaki jest mój ulubiony język programowania?” (Ustawienia użytkownika). Powinno ono pozostać na zawsze.

Bank zapamiętanych informacji Vertex AI zapewnia długoterminowe przechowywanie. Umożliwia agentowi przechowywanie i pobieranie spersonalizowanych informacji o użytkowniku.

Sesje a Bank zapamiętanych informacji

• Sesje (VertexAiSessionService): to dziennik. Zawiera ona surową, chronologiczną sekwencję każdej wiadomości, wywołania narzędzia i wydarzenia (AppendEvent, ListEvents). Stanowi podstawę do określenia co się wydarzyło.
• Bank zapamiętanych informacji (VertexAiMemoryBankService): to wiedza. Przechowuje ona zsyntetyzowane fakty długoterminowe (GenerateMemories, RetrieveMemories). Jest ona ograniczona do konkretnego user_id, co zapewnia prywatność i izolację.

1. 👉💻 Wpisz w poleceniu:

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py
   

   Otworzy się ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py w edytorze.
2. Znajdź # TODO: Create Vertex AI Session Service & Memory Bank Service i zastąp cały wiersz tymi wierszami:

       session_service = VertexAiSessionService(
           project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID
       )
       memory_service = VertexAiMemoryBankService(
           project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID
       )
   
   

3. 👉💻 Wpisz w poleceniu:

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py
   

   Otworzy się ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py w edytorze.
4. Zastąp symbol # TODO: Set Up Configuration tymi elementami:

   # Basic configuration types
   MemoryBankConfig = types.ReasoningEngineContextSpecMemoryBankConfig
   SimilaritySearchConfig = (
       types.ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig
   )
   GenerationConfig = types.ReasoningEngineContextSpecMemoryBankConfigGenerationConfig
   
   # Advanced configuration types
   CustomizationConfig = types.MemoryBankCustomizationConfig
   MemoryTopic = types.MemoryBankCustomizationConfigMemoryTopic
   CustomMemoryTopic = types.MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic
   GenerateMemoriesExample = types.MemoryBankCustomizationConfigGenerateMemoriesExample
   ConversationSource = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource
   )
   ConversationSourceEvent = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent
   )
   ExampleGeneratedMemory = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory
   )
   

Najważniejsze funkcje

Vertex AI Bank zapamiętanych informacji to nie tylko baza danych, ale aktywna usługa kognitywna.

• Wydobywanie informacji z pamięci: system wykorzystuje LLM do odczytywania rozmowy i wydobywania istotnych faktów na podstawie zdefiniowanych przez nas CustomMemoryTopic schematów (np. „Preferencje dotyczące swetrów”). Ignoruje pogawędki i zapisuje sygnał.
• Konsolidacja pamięci: automatycznie łączy nowe fakty ze starymi. Jeśli użytkownik powie „Lubię czerwony”, a później „Właściwie wolę niebieski”, Bank zapamiętanych informacji przekształci rekord pamięci, zamiast tworzyć sprzeczne duplikaty.
• Generowanie asynchroniczne: wspomnienia są generowane w tle. Agent nie będzie się zawieszać, gdy Bank zapamiętanych informacji będzie „myśleć” o rozmowie.

5. 👉 W tym samym pliku: 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. Znajdź # TODO: Set up topic i zastąp cały wiersz tym kodem:

       custom_topics = [
           # Topic 1: Sweater Preference
           MemoryTopic(
               custom_memory_topic=CustomMemoryTopic(
                   label="sweater_preference",
                   description="""Extract the user's preferences for sweater styles, patterns, and designs. Include:
                   - Specific patterns (snowflake, reindeer, geometric, fair isle, solid, etc.)
                   - Style preferences (chunky knit, cardigan, pullover, turtleneck, oversized, fitted)
                   - Color preferences (red, green, navy, pastel, etc.)
                   - Material preferences if mentioned (wool, cotton, cashmere, itchy/soft)
                   - Themes (retro, modern, ugly christmas sweater, elegant)
   
                   Example: "User wants a retro style sweater with a pixelated reindeer pattern."
                   Example: "User prefers dark blue colors and hates itchy wool."
                   """,
               )
           ),
           # Topic 2: Personal Context
           MemoryTopic(
               custom_memory_topic=CustomMemoryTopic(
                   label="personal_context",
                   description="""Extract the user's personal context including hobbies, pets, interests, job, and preferred scenes. Include:
                   - Hobbies and activities (skiing, reading, gaming, cooking, etc.)
                   - Pets (type, breed, name, color)
                   - Job or profession if relevant to their style
                   - General interests (sci-fi, nature, vintage, tech)
                   - Preferred scenes or vibes (cozy fireplace, snowy mountain, cyberpunk city, beach)
   
                   Example: "User has a golden retriever named Max."
                   Example: "User loves skiing and wants a snowy mountain background."
                   Example: "User is a software engineer who likes cyberpunk aesthetics."
                   """,
               )
           )
       ]
   

6. 👉 W tym samym pliku: 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. Znajdź # TODO: Create Agent Engine i zastąp cały wiersz tym kodem:

       agent_engine = client.agent_engines.create(
           config={
               "display_name": AGENT_DISPLAY_NAME,
               "context_spec": {
                   "memory_bank_config": {
                       "generation_config": {
                           "model": f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"
                       },
                       "customization_configs": [customization_config]
                   }
               },
           }
       )
   

Silnik agenta

Agent Engine to „sprzęt mózgu” w chmurze. Zarządza on:

• Baza danych wektorowych: do przechowywania wspomnień.
• Indeksowanie: aby można było wyszukiwać wspomnienia.
• API: aby umożliwić agentowi wysyłanie zapytań. Gdy uruchomisz deploy_agent.py, w zasadzie udostępniasz ten sprzęt.

Dlaczego nie używać po prostu promptu?

Możesz zapytać: „Dlaczego po prostu nie wkleimy historii użytkownika do promptu?”.

• Limity rozmiaru: okna kontekstu są duże, ale nie nieskończone. Nie możesz wyświetlić historii z 5 lat.
• Koszt: przetwarzanie miliona tokenów dla każdego słowa „Hello” jest zbyt drogie.
• Skupienie: Bank zapamiętanych informacji działa jak wyszukiwarka dla Twojego agenta. Pobiera tylko odpowiednie fakty.

7. 👉💻 Wpisz w poleceniu:

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py
   

   Otworzy się ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py w edytorze.
8. W pliku ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py zastąp # TODO: Add PreloadMemoryTool tym kodem:

   if USE_MEMORY_BANK:
       agent_tools.append(PreloadMemoryTool())
   

PreloadMemoryTool i add_session_to_memory

W sekcji agent.py znajdziesz 2 główne komponenty:

• PreloadMemoryTool: jest to narzędzie, które umożliwia agentowi „wyszukiwanie informacji o sobie w Google”. Jeśli użytkownik zapyta o coś niejasnego, np. „Przygotuj moją zwykłą kawę”, agent może użyć tego narzędzia, aby przed udzieleniem odpowiedzi wysłać do Banku zapamiętanych informacji zapytanie o „preferencje dotyczące kawy”.
• add_session_to_memory: to wywołanie zwrotne w tle.
  • Dlaczego warto używać funkcji asynchronicznych? Zapisywanie pamięci zajmuje trochę czasu (podsumowywanie czatu, wyodrębnianie faktów). Nie chcemy, aby użytkownik na to czekał. Uruchamiamy go w tle (add_session_to_memory) za pomocą after_agent_callback.

10. Bank zapamiętanych informacji w akcji

1. 👉💻 Wpisz w poleceniu:

   cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter
   ./use_memory_bank.sh
   

   Wynik będzie wyglądać tak:

   Ten use_memory_bank.sh skrypt najpierw używa pliku 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py, aby dołączyć Agent Engine do agenta, dzięki czemu agent może korzystać z banku zapamiętanych informacji Vertex AI. Następnie zaktualizuje za Ciebie plik .env, tak aby identyfikator silnika agenta został zapisany jako environmental variable.

   Sprawdź plik ~/holiday_workshop/.env. Zobaczysz komunikat (nie musisz niczego robić).

   USE_MEMORY_BANK=TRUE
   AGENT_ENGINE_ID={agent_engine_id}
   

2. 👉💻 Sprawdź pamięć za pomocą interfejsu aplikacji. Wpisz w poleceniu:

   cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter
   ./start_app.sh
   

   Kliknij http://localhost:5173/ lub otwórz nowe okno i wpisz http://localhost:5173/. Pamiętaj, że Uvicorn running on http://0.0.0.0:8000 to tylko serwer backendu, a nie link, który chcemy kliknąć. Interfejs czatu w witrynie stał się teraz Twoim spersonalizowanym agentem.
3. 👉 Przetestuj pamięć. Jeśli wpiszesz w interfejsie:

   I want a sweater that matches my dog. He's a golden retriever.
   

   I'm a programmer, so I want something geeky. Maybe a matrix style?
   

   I like snowflake sweater pattern
   

Agent rozpozna to jako preferencję i zapisze ją w Banku zapamiętanych informacji.

Jeśli w przyszłym tygodniu(lub w dowolnym momencie po ponownym uruchomieniu aplikacji za pomocą Control+C i ./start_app.sh) zapytasz:

what is my preference on sweater pattern?

Agent wyszuka Bank zapamiętanych informacji, sprawdzi Twoje preferencje i wygeneruje wzór swetra bez pytania.

Personalizacja: jest kluczowa w tworzeniu przydatnych agentów. Zapamiętując preferencje użytkownika (wzór swetra, osobisty kontekst), agent z czasem staje się bardziej skuteczny i pomocny.

4. Sprawdź w Vertex AI Agent Engine, otwierając konsolę Google Cloud
   .
   • Wybierz projekt w selektorze projektów w lewym górnym rogu:
   • Sprawdź silnik agenta, który został wdrożony za pomocą poprzedniego polecenia. use_memory_bank.shKliknij utworzony silnik agenta.
5. Kliknij kartę Memories w tym wdrożonym agencie, aby wyświetlić wszystkie zapamiętane informacje.

Gratulacje! Pamięć została właśnie dołączona do agenta.

11. Podsumowanie

Podsumowanie

Udało Ci się zaprojektować i zbudować kompletny system oparty na agentach.

• Łączność: używasz MCP, aby ujednolicić sposób, w jaki agent uzyskuje dostęp do narzędzi lokalnych.
• Orchestracja: do zarządzania złożoną pętlą rozumowania wymaganą w przypadku zadań wieloetapowych używasz ADK.
• Personalizacja: do utworzenia trwałej warstwy uczenia się, która zapamiętuje kontekst użytkownika, użyto Banku zapamiętanych informacji.

Następne kroki

• Utwórz własny serwer MCP: utwórz serwer dla wewnętrznego interfejsu API lub bazy danych.
• Poznaj wzorce ADK: w dokumentacji ADK znajdziesz informacje o „pętlach wnioskowania” i „orkiestracji”.
• Wdrażanie: przenieś agenta ze skryptu lokalnego do usługi produkcyjnej w Cloud Run.

Dalsze rozwijanie Połączenie protokołu MCP do nawiązywania połączeń i Banku zapamiętanych informacji do personalizacji tworzy podstawę dla nowej generacji inteligentnych aplikacji.