1. Wprowadzenie
Nowoczesny zestaw narzędzi dla 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 tego warsztatu dowiesz się, jak zaprojektować i zbudować kompleksowy system oparty na agentach przy użyciu 3 podstawowych technologii:
- Łączność (MCP): aby umożliwić agentowi dostęp do lokalnych narzędzi i danych.
- Orchestration (ADK): do zarządzania pętlą rozumowania i stanem agenta.
- Pamięć (bank pamięci): 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 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 użytkownik właśnie zapytał?”), ale jest usuwana po zakończeniu sesji. |
Vertex AI Memory Bank | Odpowiada za pamięć długotrwałą. Zapamiętuje fakty i preferencje dotyczące konkretnego użytkownika (np. „Użytkownik woli Pythona”) na czas nieokreślony, co pozwala agentowi personalizować przyszłe interakcje. |
Vertex AI Agent Engine | Zarządzana usługa infrastruktury, która hostuje logikę agenta i komponenty pamięci na dużą skalę. |
Co utworzysz
Aby zademonstrować te koncepcje, utworzysz asystenta projektowania świątecznego. Ten agent będzie w stanie przyjmować ogólne prośby użytkowników i samodzielnie koordynować lokalne narzędzia w Pythonie, aby generować spersonalizowany kod i obrazy.
Będziesz przechodzić przez 3 etapy:
- Warstwa narzędzi: utwórz serwer MCP, aby udostępnić lokalne funkcje Pythona AI.
- Warstwa agenta: użyj ADK, aby utworzyć agenta, który planuje i wykonuje wieloetapowe przepływy pracy.
- Warstwa pamięci: zintegruj Memory Bank, 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 odebrać konto rozliczeniowe z 5-dolarowym kredytem, musisz je wykorzystać w procesie wdrażania. Zaloguj się na konto Gmail.
Część 2. Środowisko otwarte
- 👉 Kliknij ten link, aby przejść bezpośrednio do edytora Cloud Shell
- 👉 Jeśli w dowolnym momencie pojawi się prośba o autoryzację, kliknij Autoryzuj, aby kontynuować.
- 👉 Jeśli terminal nie pojawi się u dołu ekranu, otwórz go:
- Kliknij Wyświetl.
- Kliknij Terminal
.
- 👉💻 W terminalu sprawdź, czy użytkownik jest już uwierzytelniony i czy projekt jest ustawiony na identyfikator projektu, używając tego polecenia:
gcloud auth list - 👉💻 Sklonuj projekt bootstrap z GitHuba:
git clone https://github.com/cuppibla/holiday_workshop - 👉💻 Uruchom skrypt konfiguracji z katalogu projektu.
cd ~/holiday_workshop ./init.sh - 👉💻 Ustaw wymagany identyfikator projektu:
gcloud config set project $(cat ~/project_id.txt) --quiet
Część 3. Konfigurowanie uprawnień
- 👉💻 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 - 👉💻 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 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 on standardowe łączenie modeli AI ze źródłami danych i narzędziami.
Jeśli raz utworzysz serwer MCP dla swoich narzędzi, możesz podłączyć go do interfejsu Gemini CLI, środowiska IDE lub dowolnego innego klienta zgodnego z MCP bez zmiany ani jednej linii kodu.
Co utworzysz
W tym ćwiczeniu z programowania utworzysz Asystenta projektowania świątecznego, który:
- Łączy się z lokalnym środowiskiem (narzędzia w Studio) za pomocą MCP.
- Zarządza kontekstem rozmowy w niezawodny sposób za pomocą pakietu Agent Development Kit (ADK).
- zapamiętuje Twoje preferencje (np. „Wolę kod Pythona”) w różnych sesjach za pomocą Vertex AI Memory Bank.
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.
- W terminalu Cloud Shell upewnij się, że jesteś w odpowiednim katalogu:
cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/ - 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 kod standardowy (konfigurowanie serwera MCP, obsługa połączeń i inicjowanie klienta Vertex AI) jest już gotowy. Cztery podstawowe funkcje są jednak obecnie pustymi symbolami zastępczymi.
Część 2. Wdrażanie generatora scen świątecznych
Najpierw potrzebujemy narzędzia, które uwzględnia zainteresowania użytkownika (np. „ptaki”) i przekształca go w bogaty, szczegółowy prompt zoptymalizowany 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 poniższym 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
Po umieszczeniu kodu 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 na serwerze 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. Możemy jednak użyć interfejsu wiersza poleceń Gemini.
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
Polecimy interfejsowi wiersza poleceń Gemini zarządzać naszym serwerem za pomocą polecenia mcp add.
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
Sprawdź zdjęcie
- Aby zakończyć korzystanie z interfejsu wiersza poleceń Gemini, naciśnij
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 dopracowywać sceny.
Czy jednak zauważyłeś 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. Wdrożymy Agent Development Kit (ADK), aby stworzyć uporządkowanego agenta, który będzie koordynować te narzędzia MCP w doskonałym potoku produkcyjnym.
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óre narzędzie ma wywołać i kiedy.
W tej sekcji utworzymy agenta AI, czyli system, który potrafi autonomicznie wnioskować, planować i wykonywać wieloetapowe zadania. W tym celu użyjemy 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 („Przygotuj 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 „instalacjami”, takimi jak zarządzanie historią czatu, łączenie się 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 tym procesem.
/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 Pythona. Sprawdź, czy wygląda prawidłowo, a potem zastosuj lub zaakceptuj zmiany.
4. Krok 2. Dodawanie serwera MCP (narzędzia)
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.
- Jeśli GeminiCLI jest nadal otwarty, naciśnij
control+C, aby go zamknąć. Teraz w terminalu(w folderzesolution, możesz przejść do folderustarter, aby przetestować kod, uruchamiającuv run adk webw folderzestarter) uruchom:cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/02-solution uv run adk web --port 8000 - 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ń to w zaśnieżoną wioskę”.
- (Pracownik obsługi klienta powinien zadzwonić pod numer
generate_holiday_scene. Zwróć uwagę, że automatycznie stosuje styl „słodki/kreskówkowy” zdefiniowany w instrukcjach systemowych.
- (Pracownik obsługi klienta powinien zadzwonić pod numer
- „Wygeneruj wzór swetra z małymi kawałkami pizzy”.
- (Przedstawiciel powinien zadzwonić pod numer
generate_sweater_pattern).
- (Przedstawiciel powinien zadzwonić pod numer
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ć wibracyjnie” agenta Google ADK przy użyciu podejścia zależnego od kontekstu.
- Ustaliliśmy kontekst: użyliśmy
/memory add, aby zdefiniować profil eksperta. - Zbudowaliśmy Iteratively: 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.
7. Łączenie ADK z interfejsem
Teraz, gdy mamy definicję agenta, musimy ją uruchomić. W tym celu używane są Runner i Session Service.
Implementacja
- 👉 Wpisz w poleceniu:
cloudshell edit ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.pyw edytorze. - Zastąp symbol
# TODO: Create Session Servicetymi elementami:from google.adk.sessions import InMemorySessionService from google.adk.memory import InMemoryMemoryService session_service = InMemorySessionService() memory_service = InMemoryMemoryService() - Zastąp symbol
# TODO: Initialize Runnertymi elementami:runner = Runner( app_name="agents", agent=christmas_agent, session_service=session_service, memory_service=memory_service, )
- 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 )
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 dane wejściowe/wyjściowe (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_idiSessionService. 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
- 👉💻 Wpisz w poleceniu:
cd ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter ./start_app.sh~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.pyw edytorze. - Wynik będzie wyglądać tak:
👉👉 Kliknij http://localhost:5173/lub otwórz nowe okno i wpiszhttp://localhost:5173/. - Następnie zobaczysz witrynę z interfejsem czatu:
- Przetestuj, przesyłając 1 zdjęcie(może to być Twoje zdjęcie lub zdjęcie Twojego zwierzaka).
- 👉 Następnie zadaj pytanie.
Can you generate a picture my cat wearing snowflake pattern sweater?
- 👉💻 Po zakończeniu testowania naciśnij
control+Cw 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.
Vertex AI Memory Bank zapewnia długoterminowe przechowywanie. Umożliwia to 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 ona 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 konkretnegouser_id, co zapewnia prywatność i izolację.
- 👉💻 Wpisz w poleceniu:
cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.pyw edytorze. - Znajdź
# TODO: Create Vertex AI Session Service & Memory Bank Servicei 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 )
- 👉💻 Wpisz w poleceniu:
cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.pyw edytorze. - Zastąp symbol
# TODO: Set Up Configurationtymi 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 )
- 👉 W tym samym pliku:
04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. Znajdź# TODO: Set up topici 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." """, ) ) ] - 👉 W tym samym pliku:
04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. Znajdź# TODO: Create Agent Enginei 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] } }, } )
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.
- Funkcja: Bank pamięci działa jak wyszukiwarka dla Twojego agenta. Pobiera tylko odpowiednie fakty.
- 👉💻 Wpisz w poleceniu:
cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.pyw edytorze. - W pliku
~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.pyzastąp# TODO: Add PreloadMemoryTooltymi elementami:if USE_MEMORY_BANK: agent_tools.append(PreloadMemoryTool())
PreloadMemoryTool i add_session_to_memory
W sekcji agent.py znajdziesz 2 główne komponenty:
PreloadMemoryTool: to narzędzie, które umożliwia agentowi „wyszukiwanie informacji o sobie w Google”. Jeśli użytkownik zapyta o coś niejasnego, np. „Poproszę o moją zwykłą kawę”, agent może użyć tego narzędzia, aby przed udzieleniem odpowiedzi wysłać do bazy pamięci zapytanie o „preferencje dotyczące kawy”.add_session_to_memory: to wywołanie zwrotne w tle.- Dlaczego warto używać asynchroniczności? Zapisywanie pamięci zajmuje czas (podsumowywanie czatu, wyodrębnianie faktów). Nie chcemy, aby użytkownik musiał na to czekać. Uruchamiamy go w tle (
add_session_to_memory) za pomocąafter_agent_callback.
- Dlaczego warto używać asynchroniczności? Zapisywanie pamięci zajmuje czas (podsumowywanie czatu, wyodrębnianie faktów). Nie chcemy, aby użytkownik musiał na to czekać. Uruchamiamy go w tle (
10. Bank zapamiętanych informacji w akcji
- 👉💻 Wpisz w poleceniu:
cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter ./use_memory_bank.sh
Sprawdź plik ~/holiday_workshop/.env. Zobaczysz komunikat (nie musisz niczego robić).USE_MEMORY_BANK=TRUE AGENT_ENGINE_ID={agent_engine_id} - 👉💻 Sprawdź pamięć za pomocą interfejsu aplikacji. Wpisz w poleceniu:
cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter ./start_app.shhttp://localhost:5173/lub otwórz nowe okno i wpiszhttp://localhost:5173/. Pamiętaj, żeUvicorn running on http://0.0.0.0:8000to tylko serwer backendu, a nie link, który chcemy kliknąć. Interfejs czatu w witrynie stał się teraz Twoim spersonalizowanym agentem. - 👉 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 pamięci.
Jeśli w przyszłym tygodniu(lub w dowolnym momencie po ponownym uruchomieniu aplikacji przez Control+C i ./start_app.sh) zapytasz:
what is my preference on sweater pattern?
Agent wyśle zapytanie do banku pamięci, sprawdzi Twoje preferencje i wygeneruje wzór swetra bez konieczności zadawania pytań. 
- Sprawdź w Vertex AI Agent Engine, otwierając Google Cloud Console Agent Engine
- .
- 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.sh
Kliknij utworzony silnik agenta.
- Wybierz projekt w selektorze projektów w lewym górnym rogu:
- Kliknij kartę
Memoriesw 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ą wnioskowania wymaganą w przypadku zadań wieloetapowych używasz ADK.
- Personalizacja: za pomocą Memory Bank utworzono trwałą warstwę uczenia się, która zapamiętuje kontekst użytkownika.
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.