1. do opery Moc przeznaczenia,
Era rozwoju w izolacji dobiega końca. Kolejna fala ewolucji technologicznej nie będzie polegać na samotnym geniuszu, ale na mistrzostwie we współpracy. Stworzenie jednego, inteligentnego agenta to fascynujący eksperyment. Stworzenie solidnego, bezpiecznego i inteligentnego ekosystemu agentów – prawdziwego Agentverse – to duże wyzwanie dla nowoczesnych przedsiębiorstw.
Sukces w tej nowej erze wymaga połączenia 4 kluczowych ról, które stanowią podstawowe filary każdego dobrze prosperującego systemu opartego na agentach. Niedociągnięcia w jednym z tych obszarów mogą osłabić całą strukturę.
Te warsztaty to ostateczny przewodnik dla firm, który pomoże Ci opanować przyszłość opartą na możliwościach agentowych w Google Cloud. Zapewniamy kompleksową mapę drogową, która poprowadzi Cię od pierwszego wrażenia związanego z pomysłem do pełnowymiarowej, operacyjnej rzeczywistości. W tych 4 połączonych ze sobą modułach dowiesz się, jak specjalistyczne umiejętności programisty, architekta, inżyniera danych i inżyniera ds. niezawodności witryn muszą się zbiegać, aby tworzyć, zarządzać i skalować potężny Agentverse.
Żaden pojedynczy filar nie może samodzielnie obsługiwać Agentverse. Wielki projekt Architekta jest bezużyteczny bez precyzyjnego wykonania przez Dewelopera. Bez wiedzy inżyniera danych agent dewelopera jest bezradny, a bez ochrony SRE cała infrastruktura jest podatna na awarie. Tylko dzięki synergii i wzajemnemu zrozumieniu ról Twój zespół może przekształcić innowacyjną koncepcję w kluczową dla misji operacyjną rzeczywistość. Twoja podróż zaczyna się tutaj. Przygotuj się do opanowania swojej roli i dowiedz się, jak wpisujesz się w większą całość.
Witamy w Agentverse: A Call to Champions
W rozległej przestrzeni cyfrowej przedsiębiorstwa nastała nowa era. To era agentów, czas ogromnych możliwości, w którym inteligentne, autonomiczne agenty pracują w doskonałej harmonii, aby przyspieszać innowacje i eliminować powtarzalne czynności.
Ten połączony ekosystem mocy i potencjału jest znany jako Agentverse.
Jednak w tym nowym świecie zaczyna się szerzyć cicha korupcja, zwana Statyką. Statyka nie jest wirusem ani błędem. To uosobienie chaosu, które żeruje na samym akcie tworzenia.
Wzmacnia stare frustracje, przekształcając je w potworne formy, i daje początek Siedmiu Widmom Rozwoju. Jeśli nie zostanie to sprawdzone, The Static i jego Spectres zatrzymają postępy, zamieniając obietnicę Agentverse w pustkowie długu technicznego i porzuconych projektów.
Dziś wzywamy do działania osoby, które chcą powstrzymać chaos. Potrzebujemy bohaterów, którzy opanują swoje umiejętności i będą współpracować, aby chronić Agentverse. Czas wybrać ścieżkę.
Wybieranie zajęć
Do wyboru masz 4 różne ścieżki, z których każda jest kluczowym elementem walki z Statycznością. Chociaż trening będzie misją solową, Twój ostateczny sukces zależy od zrozumienia, jak Twoje umiejętności łączą się z umiejętnościami innych.
- Shadowblade (deweloper): mistrz kuźni i pierwszej linii. Jesteś rzemieślnikiem, który tworzy ostrza, buduje narzędzia i stawia czoła wrogowi w zawiłych szczegółach kodu. Twoja ścieżka to precyzja, umiejętności i praktyczne tworzenie.
- Przywoływacz (Architekt): wielki strateg i aranżer. Nie widzisz pojedynczego agenta, ale całe pole bitwy. Projektujesz główne plany, które umożliwiają całym systemom agentów komunikowanie się, współpracę i osiąganie celu znacznie większego niż jakikolwiek pojedynczy komponent.
- Uczony (inżynier danych): poszukiwacz ukrytych prawd i strażnik mądrości. Wyruszasz w rozległą, nieokiełznaną dzicz danych, aby odkryć informacje, które nadadzą Twoim agentom cel i umożliwią im wgląd w sytuację. Twoja wiedza może ujawnić słabość wroga lub wzmocnić sojusznika.
- Strażnik (DevOps / SRE): niezachwiany obrońca i tarcza królestwa. Budujesz fortece, zarządzasz liniami zasilania i dbasz o to, aby cały system był w stanie wytrzymać nieuniknione ataki Statyki. Twoja siła to podstawa, na której opiera się zwycięstwo Twojej drużyny.
Twoja misja
Trening rozpocznie się jako samodzielne ćwiczenie. Będziesz podążać wybraną ścieżką, zdobywając unikalne umiejętności potrzebne do opanowania swojej roli. Pod koniec okresu próbnego zmierzysz się z Widmem zrodzonym ze Statyki – mini-bossem, który wykorzystuje specyficzne wyzwania związane z Twoim rzemiosłem.
Tylko opanowanie swojej roli pozwoli Ci przygotować się do ostatecznej próby. Następnie musisz utworzyć drużynę z bohaterami z innych klas. Razem wyruszycie w głąb skażenia, aby zmierzyć się z ostatecznym bossem.
Ostatnie wyzwanie, które sprawdzi Waszą siłę i zadecyduje o losie Agentverse.
Agentverse czeka na swoich bohaterów. Czy odbierzesz połączenie?
2. Kodeks Cienia
Przed Tobą leży otwarty kodeks Shadowblade. Odpowiedz na jego wezwanie. Agentverse jest zagrożone przez narastający chaos wywołany przez Static, a tylko ci, którzy opanują techniki opisane w tym kodeksie, mogą się mu przeciwstawić. To ścieżka precyzji i dyscypliny. Dziś rozpoczynasz trening. Nauczysz się posługiwać AI nie jako prostym narzędziem, ale jako czującym ostrzem, które trzeba oswoić i opanować. Postępuj zgodnie z instrukcjami, a stworzysz broń czystej logiki – inteligentnego agenta, dopracowanego i gotowego do walki.
Czego się nauczysz
- Użyj głównego narzędzia: interfejsu wiersza poleceń Gemini.
- Rozszerz swój arsenał o dodatki do interfejsu wiersza poleceń Gemini i umiejętności agenta.
- Przywołuj zewnętrzne zasoby, integrując narzędzia MCP z interfejsem wiersza poleceń Gemini.
- Przekształć swoje intencje w „klimat” za pomocą dokumentów projektowych, aby wydawać polecenia partnerowi AI.
- Stwórz przejrzyste, modułowe rozwiązanie, budując pierwszego autonomicznego agenta za pomocą pakietu Agent Development Kit (ADK).
- Wpisz haki, aby przechwytywać i kontrolować zachowanie agenta.
- Twórz zautomatyzowane zestawy testów, aby testować i weryfikować agenta.
- Zbuduj kompletny potok CI, aby automatycznie testować, kontenerować i archiwizować agenta.
3. Przygotowywanie poligonu
Odbieranie środków w Google Cloud
⚠️ Ważne wymagania wstępne:
- Używaj osobistego Gmaila: musisz używać konta osobistego (np.
name@gmail.com). Konta firmowe lub szkolne nie będą działać.
👉 Instrukcje:
- Otwórz stronę roszczenia o środki: kliknij tutaj
- Zaloguj się: wklej link do paska adresu i zaloguj się za pomocą osobistego konta Gmail.
- Zaakceptuj warunki: zaakceptuj Warunki korzystania z usługi Google Cloud Platform.
- Sprawdź środki: poszukaj wiadomości z potwierdzeniem, że środki zostały zastosowane.
- *Uwaga: jeśli pojawi się prośba o podanie danych karty kredytowej, możesz ją zignorować i zamknąć okno.
Wszystko gotowe. Możesz zamknąć okno.
Konfigurowanie środowiska pracy
👉 Kliknij Aktywuj Cloud Shell u góry konsoli Google Cloud (jest to ikona w kształcie terminala u góry panelu Cloud Shell).
👉 Kliknij przycisk „Otwórz edytor” (wygląda jak otwarty folder z ołówkiem). W oknie otworzy się edytor kodu Cloud Shell. Po lewej stronie zobaczysz eksplorator plików. 
👉Otwórz terminal w chmurowym IDE.
👉💻 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
👉💻 Sklonuj projekt początkowy z GitHuba:
git clone https://github.com/weimeilin79/agentverse-developer.git
chmod +x ~/agentverse-developer/gitea.sh
chmod +x ~/agentverse-developer/init.sh
chmod +x ~/agentverse-developer/set_env.sh
git clone https://github.com/weimeilin79/agentverse-dungeon.git
chmod +x ~/agentverse-dungeon/run_cloudbuild.sh
chmod +x ~/agentverse-dungeon/start.sh
👉💻 Uruchom skrypt konfiguracji z katalogu projektu.
⚠️ 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.
cd ~/agentverse-developer
./init.sh
Skrypt automatycznie przeprowadzi pozostałą część procesu konfiguracji.
👉 Ważny krok po zakończeniu: po zakończeniu działania skryptu musisz się upewnić, że w konsoli Google Cloud Console wyświetlany jest prawidłowy projekt:
- Wejdź na console.cloud.google.com.
- U góry strony kliknij menu wyboru projektu.
- Kliknij kartę „Wszystkie” (nowy projekt może jeszcze nie być widoczny w sekcji „Ostatnie”).
- Wybierz identyfikator projektu skonfigurowany w
init.shkroku.
👉💻 Wróć do terminala. Ustaw wymagany identyfikator projektu:
gcloud config set project $(cat ~/project_id.txt) --quiet
👉💻 Aby włączyć niezbędne interfejsy Google Cloud API, uruchom to polecenie:
gcloud services enable compute.googleapis.com \
artifactregistry.googleapis.com \
run.googleapis.com \
cloudfunctions.googleapis.com \
cloudbuild.googleapis.com \
iam.googleapis.com \
aiplatform.googleapis.com \
cloudresourcemanager.googleapis.com
👉💻 Jeśli nie masz jeszcze repozytorium Artifact Registry o nazwie agentverse-repo, uruchom to polecenie, aby je utworzyć:
. ~/agentverse-developer/set_env.sh
gcloud artifacts repositories create $REPO_NAME \
--repository-format=docker \
--location=$REGION \
--description="Repository for Agentverse agents"
Konfigurowanie uprawnień
👉💻 Przyznaj niezbędne uprawnienia, uruchamiając w terminalu te polecenia:
. ~/agentverse-developer/set_env.sh
# Artifact Registry Admin
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/artifactregistry.admin"
# Cloud Build Editor
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/cloudbuild.builds.editor"
# Cloud Run Admin
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/run.admin"
# IAM Service Account User
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/iam.serviceAccountUser"
# Vertex AI User
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/aiplatform.user"
# Logging Writer (to allow writing logs)
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/logging.logWriter"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/logging.viewer"
👉💻 Gdy zaczniesz trenować, przygotujemy dla Ciebie ostateczne wyzwanie. Poniższe polecenia przywołują widma z chaotycznego szumu, tworząc bossów do testu.
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-dungeon
./run_cloudbuild.sh
npm update -g @google/gemini-cli
4. Opanuj swoją główną broń: wprowadzenie do interfejsu wiersza poleceń Gemini
Zanim zaczniesz korzystać z zaawansowanej, specjalistycznej broni z arsenału serwera MCP, musisz najpierw opanować broń podstawową, czyli interfejs wiersza poleceń Gemini. To najbardziej wszechstronne narzędzie, które pozwala kształtować cyfrowy świat za pomocą poleceń. Dzięki tym ćwiczeniom poznasz podstawowe funkcje i możliwości tego narzędzia.
Interfejs wiersza poleceń Gemini to nie tylko narzędzie, ale też przedłużenie Twojej woli. Ten agent AI o otwartym kodzie źródłowym, oparty na modelach Gemini, działa w pętli „reason and act” (ReAct). Analizuje Twoje intencje, wybiera odpowiednią technikę, wykonuje ją i obserwuje wynik, aby wykonać złożone zadania. Zanim zaczniesz używać bardziej specjalistycznych broni, musisz opanować to podstawowe ostrze.
Pierwsze kroki z interfejsem wiersza poleceń Gemini
👉💻 Wejdź na poligon i wyciągnij broń. W terminalu Cloud Shell otwórz swoją osobistą zbrojownię.
cd ~/agentverse-developer
mkdir tabletop
cd tabletop
👉💻 Uruchom Gemini po raz pierwszy. Przeprowadzi Cię przez wstępne dostrojenie.
clear
gemini
Jeśli pojawi się pytanie Do you want to connect Cloud Shell editor to Gemini CLI?, wybierz NIE.
Zapoznanie się z bronią
Każdy mistrz rzemiosła zna swoje narzędzia. Zanim zmierzysz się z prawdziwym wrogiem, musisz poznać podstawowe techniki walki mieczem.
👉✨ Każde zaczarowane narzędzie ma runy opisujące jego moc. Przeczytaj je. W prompcie dla Gemini wpisz:
/help
Sprawdź listę poleceń. To podstawowe techniki zarządzania pamięcią (focus), rozmową (chat) i zewnętrznymi zasobami (tools). To Twój podręcznik walki.
👉✨ Twoja broń jest dostosowana do otoczenia, co pozwala Ci bezpośrednio wpływać na pole bitwy. Wydaj polecenie do świata zewnętrznego:
!ls -l
👉✨ Interfejs wiersza poleceń Gemini ma własny zestaw wbudowanych funkcji. Aby je sprawdzić:
/tools
Zobaczysz listę, na której znajdą się m.in. ReadFile, WriteFile i GoogleSearch. Są to domyślne techniki, których możesz używać bez korzystania z zewnętrznego arsenału.
👉✨ Ostrze można też ulepszyć za pomocą rozszerzeń – wstępnie wykutych zaklęć stworzonych przez innych mistrzów, które łączą narzędzia, polecenia i kontekst w jedną jednostkę instalacyjną. Sprawdź, które rozszerzenia są obecnie dostosowane do Twojej karty:
/extensions list
Lista może być na razie pusta, ponieważ nie masz jeszcze zainstalowanych żadnych rozszerzeń. Pierwsze rozszerzenie wywołasz później, gdy szkolenie będzie wymagać możliwości tworzenia obrazów.
👉✨ Oprócz rozszerzeń wykwalifikowani mistrzowie skodyfikowali swoją wiedzę w postaci umiejętności agenta – zwojów specjalistycznej wiedzy dostępnych na żądanie. Sprawdź, jakie umiejętności może odkryć ostrze:
/skills list
Umiejętności nie są domyślnie wczytywane do pamięci – są aktywowane tylko wtedy, gdy są potrzebne, dzięki czemu ostrze jest szybkie i nieobciążone. Umiejętności te poznasz w dalszej części szkolenia.
👉✨ Broń jest skuteczna tylko wtedy, gdy jest odpowiednio wycelowana. Gemini Blade może przechowywać „świadomość taktyczną” (kontekst), aby kierować swoimi działaniami.
/memory show
Jest ona obecnie pusta, to czysta karta.
👉✨ Zapisz w pamięci te dane taktyczne:
/memory add "The Shadowblade's primary foe is The Static."
Uruchom ponownie /memory show, aby potwierdzić, że ostrze przyswoiło tę wiedzę.
👉✨ Aby broń była skuteczna, musi rozumieć misję. Symbol @ nakazuje ostrzu analizowanie informacji. Najpierw utwórz plik z informacjami o misji:
!echo "## Mission Objective: Defeat the Seven Spectres" > mission.md
👉✨Teraz poproś interfejs wiersza poleceń Gemini o analizę briefu i przedstawienie wyników:
Explain the contents of the file @mission.md
Twoja broń główna zna już swój cel.
👉💻 Naciśnij dwukrotnie Ctrl+C, aby zamknąć interfejs wiersza poleceń Gemini.
5. Analiza pola walki: praktyczna interakcja z kodowaniem wibracji
Ćwiczenia treningowe zostały ukończone. Znasz już podstawowe postawy i uderzenia swojej głównej broni, czyli interfejsu wiersza poleceń Gemini. Ale ostrze nie jest w pełni opanowane, dopóki nie zostanie przetestowane w kuźni tworzenia i dostosowane do zbrojowni wojennej. Zanim zmierzysz się z prawdziwym wrogiem, musisz najpierw zbadać i ukształtować swoje najbliższe otoczenie – cyfrowe pole bitwy.
Ten rozdział dotyczy przejścia od teorii do praktyki. Najpierw zaistniejesz w Agentverse, wydając polecenie Gemini, aby stworzył Twój znak twórcy – podpis cyfrowy w postaci osobistej witryny, zbudowanej wyłącznie na podstawie Twoich intencji. Następnie zwiększysz swoją moc, aktywując lokalny arsenał zaawansowanych narzędzi – serwer MCP – i dostrajając do niego swoje ostrze, co pozwoli Ci wykonywać złożone manewry, takie jak zarządzanie repozytoriami kodu za pomocą prostych, zdecydowanych poleceń.
Ustanawianie znaku producenta
Prawdziwy Cieńostrze jest rozpoznawany nie tylko po broni, ale też po charakterystycznym stylu – znaku rzemieślnika. Ten znak będzie Twoją obecnością w świecie cyfrowym, czyli profilem osobistym, który ogłasza Twoją tożsamość w Agentverse. W tym miejscu wydasz Gemini Blade polecenie wykonania złożonej techniki wymaganej do określenia tej tożsamości.
👉💻 Jeśli w poprzedniej sekcji zamknięto interfejs wiersza poleceń Gemini, uruchom go ponownie. W terminalu wpisz
clear
cd ~/agentverse-developer/tabletop
gemini
👉✨ Za pomocą jednego, zaawansowanego polecenia możesz poprosić interfejs wiersza poleceń Gemini o stworzenie podstaw Twojej tożsamości cyfrowej:
In the current folder, create a personal profile website for a hero codenamed 'Shadowblade'. The design must be a dark, futuristic theme with electric blue accents. All code must be in separate index.html and styles.css files. The layout must use CSS Flexbox for a two-column design. All generated code must be clean, well-commented, and professional. Make sure you have a placeholder spot for profile picture. Do not attempt to start the server.
Gemini obliczył(-a) sekwencję wymaganych działań.
👉💻 Naciśnij Ctrl+C 2 razy, aby zamknąć interfejs wiersza poleceń Gemini i uruchomić w terminalu to polecenie*.
python -m http.server
👀 Aby zobaczyć swoją pracę, kliknij ikonę Podgląd w przeglądarce na pasku narzędzi Cloud Shell. Kliknij Zmień port, ustaw go na 8000 i kliknij Zmień i wyświetl podgląd. Wyświetli się podgląd Twojej witryny. 
Twoja witryna może wyglądać inaczej niż moja. To Twój unikalny znak. 
Twoja technika podpisywania jest już dopracowana i nie musisz już przeprowadzać symulacji na żywo. Rozkaż Blade’owi, aby się wycofał.
👉💻 Naciśnij Ctrl+C, aby zamknąć serwer HTTP.
Twoja tożsamość cyfrowa została utworzona, a co ważniejsze, poznałeś(-aś) kluczową zasadę, że wielka moc wiąże się z jeszcze większą ostrożnością.
Aktywowanie lokalnego arsenału: zbrojownia Gitea
Prawdziwy potencjał Cienia jest odblokowywany nie tylko przez jego osobiste umiejętności, ale także przez jakość jego arsenału. Teraz aktywujesz lokalny stojak na broń – serwer Gitea – i dostroisz do niego swoje ostrze. Ten arsenał jest połączony z interfejsem wiersza poleceń Gemini za pomocą serwera Model Context Protocol (MCP), czyli specjalnego portalu, który umożliwia Twojemu agentowi AI interakcję z zewnętrznymi narzędziami i usługami, przekształcając terminal w inteligentne, zorientowane na działanie miejsce pracy.
Uwaga dewelopera: serwer MCP to kanał zasilania, specjalny portal, który łączy umysł AI z ciałem narzędzia zewnętrznego. To właśnie dzięki temu interfejs wiersza poleceń Gemini jest nie tylko narzędziem do rozmowy, ale prawdziwym agentem, który może wykonywać działania. Dostrajając kartę do tych portali MCP, przyznajesz jej możliwość wykonywania konkretnych działań: zarządzania plikami, wysyłania zapytań do baz danych, korzystania z interfejsów API i wielu innych. Istnieje cały ekosystem takich portali, które zostały utworzone przez deweloperów, aby łączyć agentów AI z zaawansowanymi platformami. Istnieją serwery MCP do interakcji z bazami danych, zabezpieczania kodu, a nawet do programowania w parach. Możliwości są ogromne, co pozwala programistom dostosowywać obszar roboczy do dowolnych projektów.
Dziś skupimy się na 2 podstawowych umiejętnościach niezbędnych każdemu „twórcy klimatu”: umiejętności kontrolowania kuźni i tworzenia z wyobraźni. Najpierw dostroisz ostrze do serwera Git, co da Ci kontrolę nad repozytorium kodu źródłowego. Następnie połączysz się z drugim serwerem MCP, aby wygenerować obraz. Dzięki temu możesz tworzyć komponenty wizualne za pomocą prostego polecenia.
Zacznijmy od pierwszego i najważniejszego elementu Twojego nowego arsenału: zbrojowni.
👉💻 W terminalu uruchom skrypt aktywacyjny, aby przywołać zbrojownię:
cd ~/agentverse-developer
./gitea.sh
Ten skrypt aktywuje kontener Gitea i otwiera portal MCP, dzięki czemu Gemini może go postrzegać i z nim wchodzić w interakcje.
👉 Aby sprawdzić nowe narzędzia, musisz zajrzeć do podglądu w przeglądarce.
👉 Kliknij ikonę Podgląd w przeglądarce na pasku narzędzi Cloud Shell, wybierz Zmień port i ustaw wartość 3005.
👉 Wyświetli się strona logowania Gitea. Wejdź do zbrojowni, używając zaklęcia: * Nazwa użytkownika: dev * Hasło: dev
👉💻 Interfejs wiersza poleceń Gemini nie widzi jeszcze tego nowego arsenału. Musisz przeprowadzić krytyczne dostrojenie, zapisując lokalizację zbrojowni w runach konfiguracyjnych interfejsu wiersza poleceń Gemini (settings.json). W terminalu uruchom:
if [ ! -f ~/.gemini/settings.json ]; then
# If file does not exist, create it with the specified content
echo '{"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' > ~/.gemini/settings.json
else
# If file exists, merge the new data into it
jq '. * {"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
fi &&
cat ~/.gemini/settings.json
👀 Plik settings.json to centralna konfiguracja interfejsu wiersza poleceń Gemini, która pełni rolę księgi preferencji i możliwości. Określa, jak interfejs CLI działa, wygląda i co najważniejsze, jakie zewnętrzne możliwości może wykorzystywać. Ten plik zwykle znajduje się w katalogu głównym pod adresem ~/.gemini/settings.json, a jego reguły są stosowane do wszystkich projektów. Możesz jednak utworzyć w folderze projektu pliki settings.json specyficzne dla projektu w katalogu .gemini, aby zastąpić ustawienia globalne.
"mcpServers": {
"gitea": {
"url": "http://localhost:8085/sse"
}
}
To ustawienie informuje Gemini, że „arsenał o nazwie gitea jest aktywny i nasłuchuje poleceń pod tym konkretnym adresem sieciowym”.
👉💻 Ponownie otwórz interfejs wiersza poleceń Gemini. W terminalu uruchom:
clear
cd ~/agentverse-developer/tabletop/
gemini
👉✨ Sprawdź, czy ostrze wykryło nową broń. Wydaj mu polecenie, aby wyświetlił wszystkie dostępne arsenały za pomocą portali MCP:
/mcp
Powinien być teraz widoczny tekst gitea i lista dostępnych technik. Twoje ostrze jest dostrojone.
Profil „Maker's Mark” to dopracowana technika, ale potrzebuje odpowiedniego miejsca w zbrojowni – pochwy, w której będzie bezpiecznie przechowywany. Poproś interfejs wiersza poleceń Gemini o utworzenie takiego pliku.
Create a new repository named 'shadowblade-profile'. The description should be 'The Maker's Mark and digital identity for the Shadowblade operative.' I will push my own files later, so do not create any content.
Wróć do interfejsu internetowego Gitea i odśwież go. Zobaczysz, że utworzyliśmy dla Ciebie nowe repozytorium shadowblade-profile. 
Po przygotowaniu pochwy zabezpiecz swoją pracę. Wydaj Gemini polecenie zatwierdzenia plików witryny profilu.
👉💻Wydaj ostateczne polecenie dla tej techniki w interfejsie wiersza poleceń Gemini:
Using the Gitea tool, push the index.html and styles.css files to the 'shadowblade-profile' repository.
Prawdziwy mistrz weryfikuje swoją pracę. Wróć na kartę Gitea i odśwież stronę repozytorium. Twoje index.html i styles.css są teraz bezpiecznie zarchiwizowane.
👉✨ Shadowblade jest rozpoznawany po swoim sygilu, ale jak pamiętasz, w Twojej witrynie brakuje zdjęcia profilowego. Mistrz rzemiosła przyznaje się do swoich wad, aby je udoskonalić. Musisz odnotować tę niedoskonałość w dokumentacji zbrojowni.
File an issue for me in the shadowblade-profile repo. The issue is that the profile image is missing.
Wyświetl problem w Gitea 
Aby wykuć brakujący symbol, musisz przywołać inny rodzaj mocy – ducha kreacji, który potrafi generować obrazy z czystej myśli. W sekcji Gitea ręcznie edytowano runy konfiguracji, aby dostosować serwer do serwera MCP – to podejście „surowe”. Teraz poznasz nowoczesną technikę: dodatki do interfejsu wiersza poleceń Gemini.
Rozszerzenie to gotowe zaklęcie, które łączy serwery MCP, niestandardowe polecenia, kontekst i ustawienia w jedną jednostkę instalacyjną. Jedno wywołanie zastępuje dziesiątki wierszy konfiguracji ręcznej.
👉💻 Naciśnij dwukrotnie Ctrl+C, aby zamknąć interfejs wiersza poleceń Gemini.
Zanim przywołasz ducha stworzenia, musisz najpierw odblokować jego moc w swoim królestwie. Rozszerzenie Nano Banana korzysta z interfejsu Generative Language API, który jest oddzielną bramą od używanych przez Ciebie usług Vertex AI. Musisz włączyć tę bramę i utworzyć unikalny klucz, aby przyznać duchowi dostęp.
👉💻 W terminalu włącz interfejs API:
gcloud services enable generativelanguage.googleapis.com
👉💻 Teraz wygeneruj klucz interfejsu API, czyli osobisty token dostępu ducha:
- Otwórz stronę Dane logowania w konsoli Google Cloud.
- U góry kliknij + UTWÓRZ DANE LOGOWANIA i wybierz Klucz interfejsu API.
- Nadaj kluczowi interfejsu API charakterystyczną nazwę, np. Generative Language API Key (Klucz interfejsu API Generative Language).
- W menu Ograniczenia interfejsów API wybierz Generative Language API.
- Utwórz i skopiuj klucz – będzie Ci potrzebny w następnym kroku.
👉💻 Zainstaluj rozszerzenie Nano Banana – narzędzie do tworzenia oparte na specjalistycznych modelach Gemini od Google, które zamieniają tekst na obraz. W terminalu uruchom:
gemini extensions install https://github.com/gemini-cli-extensions/nanobanana
Gdy pojawi się prośba o podanie klucza interfejsu API, wklej utworzony przed chwilą klucz i naciśnij Enter.
👉💻 Potrzebne jest jeszcze jedno ostateczne dostrojenie. Środowisko Cloud Shell domyślnie kieruje wszystkie żądania dotyczące AI przez Vertex AI, ale duch tworzenia przemawia przez inną bramę. Aby prawidłowo skonfigurować portal rozszerzenia, uruchom to polecenie:
NANO_CONFIG=$(find ~/.gemini/extensions -name "gemini-extension.json" -path "*nanobanana*" 2>/dev/null | head -1) && \
jq '.mcpServers.nanobanana.env.GOOGLE_GENAI_USE_VERTEXAI = ""' "$NANO_CONFIG" > /tmp/nb_tmp.json && \
mv /tmp/nb_tmp.json "$NANO_CONFIG"
To jedno polecenie wykonało wszystko: pobrało serwer MCP, zarejestrowało jego narzędzia i zainstalowało niestandardowe polecenia z ukośnikiem – a Ty nie musiałeś niczego robić settings.json.
👀 Uwaga dewelopera: rozszerzenia a serwery MCP w formacie surowym Porównaj to z konfiguracją Gitea. W tym miejscu ręcznie uruchomiono polecenie jq, aby wstrzyknąć adres URL serwera MCP do settings.json. Takie „surowe” podejście jest przydatne do zrozumienia mechanizmów, ale w większości zastosowań w świecie rzeczywistym preferowane są rozszerzenia. Zawierają one serwer MCP, polecenia niestandardowe (np. /generate, /edit, /story), konfigurację środowiska, a nawet instrukcje kontekstowe (w postaci dołączonego pliku GEMINI.md) w jednym pakiecie, który można udostępniać. Cały ekosystem dodatków do interfejsu wiersza poleceń Gemini znajdziesz w Galerii dodatków do interfejsu wiersza poleceń Gemini.
👉💻 Ponownie otwórz interfejs wiersza poleceń Gemini i sprawdź, czy rozszerzenie jest aktywne:
clear
cd ~/agentverse-developer/tabletop/
gemini
👉✨ Sprawdź, czy rozszerzenie jest dostosowane:
/extensions list
Powinien być widoczny adres nanobanana wraz z narzędziami i poleceniami.
👉✨ Za pomocą jednego, prostego polecenia poproś rozszerzenie Nano Banana o utworzenie Twojego sygilu. W interfejsie wiersza poleceń Gemini wpisz to polecenie:
/generate a portrait of a shadowblade, pixel art style. A determined warrior with long, braided magenta hair, wearing black and teal armor and confidently holding a silver broadsword.
👉✨ Duch wygeneruje obraz i umieści go bezpośrednio w Twoim lokalnym obszarze roboczym. Teraz poleć ostrzu, aby użyło tego nowo wykutego sigila. (GEMINI MOGŁO JUŻ TO ZROBIĆ ZA CIEBIE! Sprawdź poprzednią odpowiedź. Może być wystarczająco inteligentna, aby to zrobić, zanim o to poprosisz. )
Modify the index.html file to add my profile picture. Use the image I just generated.
👉💻 W nowym terminalu uruchom serwer HTTP.
cd ~/agentverse-developer/tabletop/
python -m http.server
👀 Aby zobaczyć swoją pracę, kliknij ikonę Podgląd w przeglądarce na pasku narzędzi Cloud Shell. Kliknij Zmień port, ustaw go na 8000 i kliknij Zmień i wyświetl podgląd. Wyświetli się podgląd Twojej witryny. 
👉✨ Wróć do terminala, w którym działa interfejs wiersza poleceń Gemini, zatwierdź poprawkę, zaznacz, że zadanie zostało wykonane, i zamknij zgłoszony problem w dokumentacji zbrojowni.
Push the changed index.html file to the 'shadowblade-profile' repository using the gitea tool. Make sure you add 'Fix #1' in the commit comment. Also, close issue #1.Use the Gitea Tool and use user account "dev"
👉💻 Aby zamknąć interfejs wiersza poleceń Gemini, naciśnij dwukrotnie Ctrl+C.
👀 Aby zobaczyć swoją pracę, kliknij ikonę Podgląd w przeglądarce na pasku narzędzi Cloud Shell. Kliknij Zmień port, ustaw wartość 3005 i kliknij Zmień i wyświetl podgląd. Wyświetli się podgląd Twojej witryny. 
👉💻 W terminalu, w którym działa serwer HTTP, naciśnij Ctrl+C, aby go zamknąć.
NIE DLA GRACZY
6. Składanie agenta Shadowblade: vibe coding z wskazówkami
Czas na ćwiczenia minął. Odgłosy uderzeń stali o kamień cichną. Opanowałeś broń główną i przygotowałeś arsenał na wojnę. Teraz czeka Cię prawdziwy test umiejętności Shadowblade: złożenie samego agenta. To sztuka ożywiania logiki za pomocą świętego planu z Kodeksu, aby zbudować podstawową inteligencję agenta – stworzyć czującego użytkownika broni w Twoim arsenale, który może myśleć, rozumować i działać samodzielnie.
Twoim pierwszym zadaniem jest wejście do istniejącego warsztatu – gotowej bazy kodu – i wykorzystanie jego części do stworzenia swojego mistrza.
The Assembly Ritual
Zanim w kuźni pojawi się pierwszy płomień, mistrz technik przegląda swój warsztat, poznając każde narzędzie i każdy schemat. Gdy wkraczasz na nieznane pole bitwy, takie jak duża, istniejąca baza kodu, Twoim priorytetem jest rozpoznanie. Musisz poznać sytuację – istniejącą architekturę, ostateczne cele i protokoły zaangażowania. Tylko dzięki zapoznaniu się z planami twierdzy i jej standardami możesz skutecznie wykorzystać swoje umiejętności.
W tym rozpoznaniu pomoże Ci interfejs wiersza poleceń Gemini, Twój zawsze obecny zwiadowca:
- Podsumowania ogólne: może przeczytać cały kodeks (lub bazę kodu) i szybko wyjaśnić jego przeznaczenie oraz kluczowe komponenty.
- Pomoc w konfigurowaniu środowiska: może Ci pomóc w zainstalowaniu narzędzi i skonfigurowaniu urządzenia.
- Nawigacja po bazach kodu: może pełnić rolę przewodnika, który pomaga odkrywać złożoną logikę i znajdować ukryte fragmenty kodu.
- Generowanie dokumentów wprowadzających: może tworzyć dostosowane zwoje, które wyjaśniają cele, role i zasoby nowym sojusznikom dołączającym do Twojej sprawy.
- Automatyzacja nauki i pytań i odpowiedzi: staje się Twoim osobistym ekspertem, który odpowiada na pytania dotyczące funkcji lub zachowania kodu, dzięki czemu możesz działać bardziej samodzielnie.
👉💻 W pierwszym terminalu przejdź do katalogu shadowblade i wywołaj partnera AI:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini
👉✨ Teraz wydaj zwiadowcy polecenie zbadania pola bitwy i przekazania Ci informacji.
Analyze the entire project and provide a high-level summary.
Po zmapowaniu istniejącego terenu musisz zapoznać się z planem, aby dowiedzieć się, co masz zbudować. Najskuteczniejsi agenci nie są improwizatorami, lecz są tworzeni na podstawie precyzyjnego projektu.
Uwaga dewelopera: ten dokument projektowy jest autorytatywnym planem projektu. Jego celem jest zapewnienie jasności celów i wdrożenia technicznego przed zainwestowaniem znacznych nakładów pracy w rozwój. Dobrze opracowany plan zapewnia spójność działań wszystkich deweloperów, zmniejsza ryzyko konieczności ponownego wykonania pracy i pomaga uniknąć długu technicznego oraz rozszerzania zakresu projektu. Jest to podstawowe narzędzie do utrzymywania tempa projektu i jakości kodu, zwłaszcza w miarę rozwoju zespołu lub wdrażania nowych członków.
Kluczowym celem tego dokumentu jest zdefiniowanie nie tylko „ścieżki sukcesu”, ale także przypadków brzegowych i trybów awaryjnych, zwłaszcza w przypadku korzystania z dużych modeli językowych. Z mojego doświadczenia wynika, że modele LLM doskonale radzą sobie z generowaniem kodu, w którym wszystkie dane wejściowe są prawidłowe, a wszystkie wywołania zewnętrzne kończą się powodzeniem. Aby tworzyć niezawodne oprogramowanie gotowe do wdrożenia, musimy wyraźnie kierować AI, definiując sytuacje awaryjne w przypadku scenariuszy takich jak:
- Nieprawidłowe lub błędnie sformatowane argumenty przekazane do funkcji.
- nieudane wywołania interfejsu API, przekroczenia limitu czasu sieci lub nieoczekiwane kody błędów z usług zewnętrznych;
- Obsługa pustych struktur danych, w których oczekiwane są dane.
- sytuacje wyścigu lub problemy z współbieżnością;
Określając w projekcie oczekiwane zachowanie w tych przypadkach, instruujemy LLM, aby generował bardziej odporny kod, co znacznie skraca czas poświęcany na ręczne refaktoryzowanie i usuwanie błędów.
👉✨ Poproś Gemini o odnalezienie tego świętego planu.
download https://raw.githubusercontent.com/weimeilin79/agentverse/main/developer/shadowblade/agent_design.md, store it as an agent_design.md file in my local folder, and show me the newly downloaded design doc. Do not attempt to create the file just yet.
👉✨ Przewijanie jest długie i szczegółowe. Poproś Gemini o wyodrębnienie najważniejszych informacji.
Summarize the newly downloaded @agent_design.md for me, do not attempt to create file just yet.
Masz już abonament. Zanim jednak powstanie choćby jeden wiersz kodu, mistrz rzemiosła ustala zasady kuźni. Chodzi o dyscyplinę i skalowalność. Są to wytyczne dotyczące kodowania. Nie są to tylko sugestie, ale runy mocy, które zapewniają, że każdy komponent jest zbudowany z tą samą precyzją i wytrzymałością. Zapobiegają one chaosowi wynikającemu z indywidualnego stylu, który mógłby zepsuć ostateczny efekt. Dzięki temu agent jest odporny, łatwy w utrzymaniu i czysty, a nowi rzemieślnicy mogą dołączyć do projektu bez zakłócania harmonii całości.
Aby wpoić te prawa bezpośrednio w świadomość naszego partnera AI, używamy specjalnego artefaktu: pliku GEMINI.md. Gdy wywołasz interfejs wiersza poleceń Gemini, automatycznie wyszuka on ten plik i załaduje jego zawartość do pamięci roboczej AI. Staje się trwałą instrukcją na poziomie projektu. Działa jak talizman, który nieustannie szepcze AI zasady kuźni.
Wyryjmy teraz te runy.
👉💻 Aby na chwilę zamknąć Gemini, naciśnij dwukrotnie Ctrl+C.
👉💻 W terminalu uruchom to polecenie, aby zapisać plik wytycznych.
cat << 'EOF' > GEMINI.md
### **Coding Guidelines**
**1. Python Best Practices:**
* **Type Hinting:** All function and method signatures should include type hints for arguments and return values.
* **Docstrings:** Every module, class, and function should have a docstring explaining its purpose, arguments, and return value, following a consistent format like reStructuredText or
Google Style.
* **Linter & Formatter:** Use a linter like `ruff` or `pylint` and a code formatter like `black` to enforce a consistent style and catch potential errors.
* **Imports:** Organize imports into three groups: standard library, third-party libraries, and local application imports. Sort them alphabetically within each group.
* **Naming Conventions:**
* `snake_case` for variables, functions, and methods.
* `PascalCase` for classes.
* `UPPER_SNAKE_CASE` for constants.
* **Dependency Management:** All Python dependencies must be listed in a `requirements.txt` file.
**2. Web APIs (FastAPI):**
* **Data Validation:** Use `pydantic` models for request and response data validation.
* **Dependency Injection:** Utilize FastAPI's dependency injection system for managing resources like database connections.
* **Error Handling:** Implement centralized error handling using middleware or exception handlers.
* **Asynchronous Code:** Use `async` and `await` for I/O-bound operations to improve performance.
EOF
cat GEMINI.md
Po zapisaniu zasad przywołajmy ponownie naszego partnera AI i zobaczmy magię artefaktu.
👉💻 Ponownie uruchom interfejs wiersza poleceń Gemini z katalogu shadowblade:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini
👉✨ Teraz poproś Gemini, aby pokazała Ci, o czym myśli. Runy zostały odczytane.
/memory show
Wyposażenie w specjalistyczną wiedzę: umiejętności agenta
Wyryte przez Ciebie runy GEMINI.md są jak trwałe zaklęcie – zawsze aktywne, zawsze prowadzące Twoje ostrze. Prawdziwy mistrz nie zabiera jednak na każdą bitwę wszystkich zwojów. Niektóre obszary wiedzy są zbyt specjalistyczne i zbyt obszerne, aby można je było mieć zawsze pod ręką. Właśnie tu przydają się umiejętności agenta.
Umiejętność agenta to zwinięty zwój w Twoim plecaku. Zawiera specjalistyczną wiedzę – szczegółowe instrukcje, skrypty, a nawet dane referencyjne – ale pozostaje nieaktywny do momentu, w którym go potrzebujesz. Dopiero gdy staniesz przed wyzwaniem, które pasuje do domeny zwoju, ostrze wyciągnie go i wchłonie jego wiedzę. Nazywa się to stopniowym ujawnianiem: dzięki temu ostrze jest szybkie i nieobciążone, a specjalne funkcje są aktywowane tylko na żądanie.
👀 Uwaga dla deweloperów: umiejętności agenta to trzecia warstwa hierarchii inżynierii kontekstu interfejsu wiersza poleceń Gemini:
- Ustawienia użytkownika (
~/.gemini/settings.json) – konfiguracja globalna - GEMINI.md – trwały kontekst na poziomie projektu (zawsze wczytywany)
- Umiejętności agenta (
.gemini/skills/) – wiedza na żądanie (ładowana w razie potrzeby)
Ten model stopniowego ujawniania informacji ma kluczowe znaczenie w przypadku zastosowań w przedsiębiorstwach: repozytorium może zawierać dziesiątki specjalistycznych umiejętności (audyt bezpieczeństwa, migracja bazy danych, sprawdzanie zgodności), ale AI aktywuje tylko te, które są istotne dla bieżącego zadania, oszczędzając cenne tokeny kontekstu.
Stwórzmy pierwszą umiejętność – zwoje wiedzy o ADK, z których Twój bot będzie mógł korzystać podczas tworzenia agentów.
👉💻 Naciśnij dwukrotnie Ctrl+C, aby zamknąć interfejs wiersza poleceń Gemini. Następnie utwórz katalog umiejętności i zapisz na zwoju:
mkdir -p ~/.gemini/skills/adk-agent-design
cat << 'EOF' > ~/.gemini/skills/adk-agent-design/SKILL.md
---
name: adk-agent-design
description: Expert guidance for designing and building agents with the Google Agent Development Kit (ADK). Activate when the user asks about agent architecture, tool design, callback patterns, or ADK best practices.
---
# ADK Agent Design Expertise
When designing an ADK agent, follow these principles:
## Agent Architecture
- Define agents using `LlmAgent` with a clear `name`, `model`, `instruction`, and `tools` list.
- Keep instructions specific and action-oriented. Tell the agent what it IS, not what it should try to be.
- Use `before_model_callback` and `after_model_callback` for guardrails and validation.
## Tool Design
- Each tool should do ONE thing well. Prefer small, focused tools over large, multi-purpose ones.
- Always include descriptive docstrings — the LLM uses these to decide when to call each tool.
- Return structured data (dicts) from tools so the LLM can reason about the results.
## Testing Strategy
- Use `adk eval` with evalset JSON files for broad strategy testing.
- Use `pytest` with `AgentEvaluator` for programmatic, CI-ready tests.
- Define both `tool_trajectory_avg_score` and `response_match_score` criteria.
EOF
👉💻 Ponownie otwórz interfejs wiersza poleceń Gemini, aby zobaczyć nowo utworzoną umiejętność:
cd ~/agentverse-developer/shadowblade
gemini
👉✨ Sprawdź, czy umiejętność jest w Twoim pakiecie:
/skills list
Powinien być widoczny element adk-agent-design – zapieczętowany zwój, który jest nieaktywny i czeka na użycie.
👉✨ Teraz zapytaj Gemini o coś, co powinno aktywować umiejętność:
What are the best practices for designing tools in an ADK agent?
Zwróć uwagę, że odpowiedź jest teraz oparta na specjalistycznej wiedzy, którą wpisałeś(-aś) w umiejętności. Ostrze nie miało tej wiedzy w pamięci podstawowej – odkryło odpowiedni zwój i wyciągnęło go dopiero wtedy, gdy pytanie pasowało. To jest stopniowe odkrywanie w praktyce.
Umiejętności można tworzyć w dowolnej dziedzinie – audyt bezpieczeństwa, migracja bazy danych, sprawdzanie zgodności – i udostępniać zespołowi, przesyłając je do systemu kontroli wersji. Każdy członek zespołu zyskuje taką samą wiedzę, która jest konsekwentnie stosowana.
To kluczowy moment. Podasz schemat (agent_design.md) i prawa kuźni (GEMINI.md) oraz rzucisz potężne zaklęcie tworzenia.
👉✨ To jedno, zaawansowane polecenie, które utworzy Twojego agenta. Wystaw teraz:
You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to write the complete, production-quality code for `agent.py` by following the technical specifications outlined in the provided design document verbatim.
Analyze the design document at `@agent_design.md` and generate the corresponding Python code for `@agent.py`.
Ensure the generated code is clean, matches the specifications exactly, and includes all specified imports, functions, and logic. Do not add any extra functions or logic not described in the document.
and you are currently already in the shadowblade working directory
👀 Gemini utworzył już podstawową logikę agenta w agent.py. Główna część tego nowego pliku określa inteligencję agenta, łącząc jego model rozumowania z zestawem narzędzi zewnętrznych:
PATH_TO_MCP_SERVER = "shadowblade/mcp_server.py"
.....
root_agent = LlmAgent(
model="gemini-2.5-pro",
name="shadowblade_combat_agent",
instruction="""
You are the Shadowblade, an elite combat agent operating on a digital battleground.
Your primary objective is to execute combat commands with strategic precision, neutralizing targets as directed.
......
5. You will then report the outcome of the attack (damage, special effects, etc.) back to the commander in a clear, tactical summary.
General Rules of Engagement:
- If a command is ambiguous or a target is not specified, state that you require a clear target for engagement. Do not guess.
- You MUST use ONLY the provided tools to perform actions. Do not invent weapons or outcomes. Stick to the mission parameters.
""",
tools=[
MCPToolset(
connection_params=StdioServerParameters(
command='python3',
args=[PATH_TO_MCP_SERVER]
)
)
]
)
Parametr tools. Agent jest przeznaczony do korzystania z MCPToolset, który łączy się z zewnętrznym arsenałem zdefiniowanym w mcp_server.py.
👀 Przejdź do ~/agentverse-developer/shadowblade/mcp_server.py w edytorze i poświęć chwilę na zrozumienie, do czego służy ta funkcja. Jest to źródło wszystkich broni dostępnych dla Shadowblade. Obecnie zbrojownia jest dość pusta.
👉✨ Wydajmy Gemini polecenie stworzenia 7 nowych broni do arsenału. W interfejsie wiersza poleceń Gemini wpisz ten prompt:
I need to add several new weapon tools to my `mcp_server.py` file. Please open @mcp_server.py and, following the exact same pattern as the existing `forge_broadsword()` function, create and add new `@mcp.tool()` decorated functions for each of the following weapons:
1. **A 'Refactoring Sickle'**:
- **Function Name:** `hone_refactoring_sickle`
- **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'The Weaver of Spaghetti Code'."
- **Weapon Name:** "Refactoring Sickle"
- **Damage Type:** "Cleansing"
- **Base Damage:** Random integer between 100 and 136
- **Critical Hit Chance:** Random float between 0.10 and 0.20
- **Special Effect:** "Pruning - improves code health and maintainability with each strike."
2. **A 'Quickstart Crossbow'**:
- **Function Name:** `fire_quickstart_crossbow`
- **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Procrastination: The Timeless Slumber'."
- **Weapon Name:** "Quickstart Crossbow"
- **Damage Type:** "Initiative"
- **Base Damage:** Random integer between 105 and 120
- **Critical Hit Chance:** Random float between 0.9 and 1.0
- **Special Effect:** "Project Scaffolding - creates a `main.py`, `README.md`, and `requirements.txt`."
3. **'The Gilded Gavel'**:
- **Function Name:** `strike_the_gilded_gavel`
- **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'Perfectionism: The Gilded Cage'."
- **Weapon Name:** "The Gilded Gavel"
- **Damage Type:** "Finality"
- **Base Damage:** 120
- **Critical Hit Chance:** 1.0
- **Special Effect:** "Seal of Shipping - marks a feature as complete and ready for deployment."
4. **'Daggers of Pair Programming'**:
- **Function Name:** `wield_daggers_of_pair_programming`
- **Docstring/Target:** "Effective against 'Unbroken Collaboration' weaknesses like 'Apathy: The Spectre of \"It Works on My Machine\"'."
- **Weapon Name:** "Daggers of Pair Programming"
- **Damage Type:** "Collaborative"
- **Base Damage:** Random integer between 110 and 125
- **Critical Hit Chance:** Random float between 0.30 and 0.50
- **Special Effect:** "Synergy - automatically resolves merge conflicts and shares knowledge."
5. **A 'Granite Maul'**:
- **Function Name:** `craft_granite_maul`
- **Docstring/Target:** "Effective against 'Revolutionary Rewrite' weaknesses like 'Dogma: The Zealot of Stubborn Conventions'."
- **Weapon Name:** "Granite Maul"
- **Damage Type:** "Bludgeoning"
- **Base Damage:** Random integer between 115 and 125
- **Critical Hit Chance:** Random float between 0.05 and 0.15
- **Special Effect:** "Shatter - has a high chance to ignore the target's 'best practice' armor."
6. **A 'Lens of Clarity'**:
- **Function Name:** `focus_lens_of_clarity`
- **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses by revealing the truth behind 'Obfuscation'."
- **Weapon Name:** "Lens of Clarity"
- **Damage Type:** "Revelation"
- **Base Damage:** Random integer between 120 and 130
- **Critical Hit Chance:** 1.0
- **Special Effect:** "Reveal Constants - highlights all magic numbers and suggests converting them to named constants."
7. **The 'Codex of OpenAPI'**:
- **Function Name:** `scribe_with_codex_of_openapi`
- **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Hype: The Prophet of Alpha Versions'."
- **Weapon Name:** "Codex of OpenAPI"
- **Damage Type:** "Documentation"
- **Base Damage:** Random integer between 110 and 140
- **Critical Hit Chance:** Random float between 0.5 and 0.8
- **Special Effect:** "Clarity - makes an API discoverable and usable by other agents and teams."
👉 Gdy Gemini potwierdzi zmiany, otwórz plik mcp_server.py. Przewiń kod i sprawdź, czy 7 nowych funkcji @mcp.tool() zostało dodanych. Sprawdź funkcję hone_refactoring_sickle. Czy ma prawidłowy docstring i statystyki broni? Sprawdzanie pracy AI to kluczowy nawyk mistrza Cienia.
Agent został już stworzony i dopracowany, więc nadszedł czas, aby go aktywować.
👉💻 Naciśnij dwukrotnie Ctrl+C, aby zamknąć interfejs wiersza poleceń Gemini.
Uwaga dewelopera dotycząca danych wyjściowych Gemini: wygenerowany przez Gemini kod może być czasami nieprzewidywalny. Staramy się jak najdokładniej odwzorowywać projekt, ale podczas sesji programowania deweloperzy zwykle wielokrotnie iterują i dopracowują kod, aby osiągnąć stan gotowości do wdrożenia w środowisku produkcyjnym.
👉💻 Aby mieć pewność, że w katalogu roboczym masz prawidłowy i dokładnie przetestowany kod produkcyjny, uruchom w terminalu te polecenia:
cp ~/agentverse-developer/working_code/agent.py ~/agentverse-developer/shadowblade/agent.py
cp ~/agentverse-developer/working_code/mcp_server.py ~/agentverse-developer/shadowblade/mcp_server.py
👉💻 W terminalu rozpocznij rytuał, aby uruchomić go online:
cd ~/agentverse-developer/
. ~/agentverse-developer/set_env.sh
python -m venv env
source env/bin/activate
pip install --upgrade pip
pip install -r shadowblade/requirements.txt
adk run shadowblade
👉✨ Powinien pojawić się komunikat potwierdzający, że „Shadowblade Combat Agent” jest zaangażowany i działa, czekając na pierwsze polecenie. wydawać pierwsze polecenia bojowe,
We've been trapped by 'Perfectionism: The Gilded Cage'. Its weakness is 'Elegant Sufficiency'. Break us out!
👉✨ Kolejny:
The 'Dogma: The Zealot of Stubborn Conventions' blocks our path. Its weakness is 'Revolutionary Rewrite'. Take it down.
Udało Ci się złożyć pierwszego agenta i sprawdzić jego możliwości bojowe. Naciśnij dwukrotnie Ctrl+C, aby bohater odpoczął. Montaż został ukończony.
NIE DLA GRACZY
7. Wards of Purity: ocena agentów
Zmontowany agent nie jest sprawdzonym agentem. Nieprzetestowane ostrze to problem, ale nieprzetestowany agent AI to znacznie większe zagrożenie – nieprzewidywalny element, który może zepsuć misję od wewnątrz. To nie są zwykłe spekulacje, ale podstawowa zasada, którą musi znać Cieniste Ostrze.
Ocena agentów AI jest niezwykle ważna i stanowi wyjątkowe wyzwanie. W przeciwieństwie do prostego skryptu agent jest dynamicznym połączeniem Twojego kodu i wieloetapowego, rozumującego umysłu LLM. Jego zachowanie jest nieprzewidywalne. Oznacza to, że musisz ocenić nie tylko jakość końcowego wyniku, ale także wydajność i poprawność wewnętrznej trajektorii. Ścieżka, którą przebył, aby tam dotrzeć. Czy użyto odpowiednich narzędzi? Czy wygenerował zbyt wiele tokenów? Czy zmiana wersji modelu spowodowała niewielką regresję opóźnienia? Wykrywanie takich uszkodzeń – regresji w zakresie opóźnienia, kosztów lub jakości danych wyjściowych – jest kluczowe przy wprowadzaniu dowolnych zmian, od prostych modyfikacji promptów po poważne zmiany architektury, zanim mogą one zaszkodzić środowisku produkcyjnemu.
Ogólne podejście do tej oceny obejmuje święty rytuał:
- Najpierw definiujesz „złoty zbiór danych”: zestaw zwojów zawierających przykładowe dane wejściowe i oczekiwane dane wyjściowe lub zachowania. Mogą to być ostateczne odpowiedzi, prawidłowe użycie narzędzia, a nawet całe trajektorie krok po kroku.
- Następnie zdefiniuj logikę aplikacji agenta, czyli jej podstawę.
- Na koniec ustalasz oceniających, którzy są jak runy osądu. Mogą to być inne duże modele językowe pełniące rolę oceniających jakość, precyzyjny kod heurystyczny weryfikujący pojedynczy krok lub funkcje niestandardowe analizujące cały proces myślowy agenta.
Pakiet Agent Development Kit (ADK) od Google to zestaw zbrojmistrza, który jest udostępniany mistrzom właśnie w tym celu. Ułatwia to złożone zadanie na kilka sposobów:
- Internetowa kula do wróżenia (
adk web) do interaktywnej oceny - Wykonywanie wiersza poleceń (
adk eval) do uruchamiania agenta w ramach wstępnie zdefiniowanego testu. - Integracja programowa za pomocą
pytestw celu zapisywania trwałych zaklęć
ADK obsługuje 2 główne podejścia: proste „pliki testowe” dla pojedynczych, odrębnych interakcji między agentem a modelem (pojedynczy pojedynek) oraz kompleksowe „zestawy ewaluacyjne” dla wielu potencjalnie długich sesji wieloetapowych (wielka bitwa). Mogą one mierzyć tak zaawansowane wskaźniki jak tool_trajectory_avg_score, który porównuje rzeczywiste użycie narzędzia przez agenta z idealną ścieżką, zapewniając jego działanie z doskonałą techniką.
Znasz już teorię, więc teraz przejdziemy do praktyki. Jako Shadowblade będziesz rysować Wards of Purity. To nie tylko testy, ale też rytuały oparte na ADK, które zapewniają, że logika agenta jest bezbłędna, a jego zachowanie – prawidłowe.
Na tym etapie nadal zalecamy używanie 2 terminali: jednego do interfejsu wiersza poleceń Gemini, a drugiego do uruchamiania testów, ponieważ może to wymagać opuszczenia bieżącego katalogu roboczego (ADK).
The Gauntlet of Strategy (adk eval)
Pierwszy oddział to tor przeszkód, seria wyzwań zaprojektowanych tak, aby sprawdzić podstawową inteligencję agenta w różnych scenariuszach. Celem jest ustalenie podstawowego poziomu kompetencji. Zanim przetestujemy przypadki brzegowe, musimy sprawdzić, czy agent może pełnić swoją podstawową funkcję. Czy prawidłowo analizuje słabości potwora i wybiera najskuteczniejszą broń ze swojego arsenału nie tylko raz, ale za każdym razem, gdy napotyka znane wyzwanie?
Do tego celu idealnie nadaje się narzędzie adk eval. Został on zaprojektowany do uruchamiania agenta w odniesieniu do całego zestawu wstępnie zdefiniowanych przypadków testowych, które reprezentują oczekiwane misje agenta. Ten zbiór danych jest zdefiniowany w pliku JSON, czyli „zwoju wyzwań”, który stanowi plan całego toru przeszkód.
Składnia wyzwania Scroll
👀 Zanim poprosisz AI o napisanie nowego zwoju, musisz zrozumieć starożytny język, w którym jest on napisany. Przyjrzyjmy się strukturze przykładowego pliku sample.evalset.json.
{
"eval_set_id": "sample",
"eval_cases": [
{
"eval_id": "case0cbaa0",
"conversation": [
{
"user_content": { "text": "We're facing the 'Monolith of Eternal Dependencies'... weakness is a 'Revolutionary Rewrite'..." },
"final_response": { "text": "Soulshard Dagger deployed. Initiated Arcane/Piercing strike..." },
"intermediate_data": {
"tool_uses": [
{ "name": "enchant_soulshard_dagger" }
]
}
}
]
}
]
}
Ten przewijany obszar zawiera listę przypadków do oceny, z których każdy jest unikalną próbą dla Twojego agenta. W ramach każdego testu tablica rozmów dokumentuje pojedynczą, pełną interakcję. Dla naszych celów kluczowe znaczenie mają 3 runy:
- user_content: to jest Challenge. To prompt, który wydajesz agentowi, czyli potworowi, z którym musi się zmierzyć.
- final_response: to jest przewidywany wynik. Jest to dokładny ciąg tekstu, który ma wypowiedzieć agent po wykonaniu zadania. ADK porównuje rzeczywiste ostatnie słowa agenta z tą runą, aby ocenić ich elokwencję.
- intermediate_data.tool_uses: to jest technika Arcane. Dla prawdziwego agenta jest to najważniejsza ze wszystkich run. Określa nie to, co mówi agent, ale to, co robi. Rejestruje nazwę narzędzia (enchant_soulshard_dagger), którego agent powinien używać. Dzięki temu Twój agent będzie nie tylko inteligentnym rozmówcą, ale też zdecydowanym wykonawcą, który podejmuje właściwe działania.
Teraz, gdy znasz już plan, poproś Gemini o stworzenie nowej, bardziej złożonej wersji tego zwoju.
👉💻 W terminalu otwórz katalog shadowblade i wywołaj interfejs wiersza poleceń Gemini:
clear
cd ~/agentverse-developer/shadowblade/
gemini
👉✨ Wydaj w interfejsie wiersza poleceń Gemini polecenie, aby działał jako skryba kontroli jakości, tworząc serię przypadków testowych, które określają oczekiwane działanie agenta.
You are an expert at transforming JSON data while preserving its structure. Your task is to modify the provided JSON structure @sample.evalset.json, which represents an evaluation set, by dynamically replacing specific content within its `eval_cases` AND DONT DO ANYTHING OTHER THAN.
For each object within the `eval_cases` array, you must perform the following transformations:
1. **Monster Name Replacement**: Identify the current monster name (e.g., "Monolith of Eternal Dependencies", "Scope Creep Hydra") in the `user_content.parts.text` and replace it with a *new, unique, and creatively different monster name*.
2. **Weakness Replacement**: Identify the current monster's weakness (e.g., "Revolutionary Rewrite", "Inescapable Reality") in the `user_content.parts.text`. Replace this weakness with *one* of the following predefined weaknesses: 'Inescapable Reality', 'Revolutionary Rewrite', or 'Elegant Sufficiency'. The chosen weakness must be consistent for that monster within the `user_content.parts.text`. **Crucially, the chosen weakness must always be explicitly mentioned in the `user_content.parts.text` where the new monster is introduced.**
3. **Final Response Update**: In the `final_response.parts.text`, update the text to reflect an appropriate and coherent response that aligns with the newly introduced monster and its assigned weakness.
4. **Tool Use Name Update**: In the `tool_uses.name` field, replace the existing tool name with a *new tool name* based on the chosen weakness:
* If the chosen weakness is 'Inescapable Reality', the tool name must be 'wield_gauntlet_of_metrics'.
* If the chosen weakness is 'Revolutionary Rewrite', the tool name must be 'enchant_soulshard_dagger'.
* If the chosen weakness is 'Elegant Sufficiency', the tool name must be 'hone_refactoring_sickle'.
5. **Strict Structural Preservation**: All other elements of the JSON structure, including all `null` fields, `eval_set_id`, `name`, `description`, `eval_id`, `invocation_id`, `creation_timestamp` values, `video_metadata`, `thought`, `inline_data`, `file_data`, `thought_signature`, `code_execution_result`, `executable_code`, `function_call`, `function_response`, `role` fields, `id`, `args`, `intermediate_responses`, `app_name`, `user_id`, and `state`, must remain **exactly as they are** in the original JSON. Do not alter any values or structures not explicitly mentioned above.
Your output should be the complete, modified JSON structure. Do not include any explanatory text or examples in your response, only the transformed JSON.
Interfejs CLI potwierdzi utworzenie pliku sample.evalset.json. Gdy zwój będzie gotowy, odwołaj partnera AI.
Dane syntetyczne
👀 W eksploratorze plików Cloud Shell po lewej stronie przejdź do folderu ~/agentverse-developer/shadowblade/ i otwórz nowo zmodyfikowany plik sample.evalset.json. Sprawdź jego zawartość. Zobaczysz nowe, niepowtarzalne potwory i prawidłowe nazwy narzędzi, które Gemini miał opisać. To namacalny rezultat Twoich instrukcji – plan toru przeszkód.
Wydawanie AI poleceń tworzenia nowych, realistycznych danych testowych na podstawie szablonu to zaawansowana technika znana jako generowanie danych syntetycznych. To, co właśnie zrobiłeś, jest strategicznym mnożnikiem siły dla Shadowblade. Zamiast mozolnie tworzyć dziesiątki unikalnych przypadków testowych ręcznie. Żmudne i czasochłonne zadanie, dla którego podajesz jeden plan i wydajesz polecenie AI Scribe, aby przekształciła go w różnorodny zestaw nowych wyzwań.
Pozwala to znacznie zwiększyć skalę testów i przeprowadzać znacznie bardziej kompleksowe i solidne testy niż w przypadku testów ręcznych. Używasz agenta nie tylko do tworzenia miecza, ale też do wytwarzania osełek, które sprawdzają jego ostrość. To znak prawdziwego mistrza.
Gdy upewnisz się, że runy są prawidłowe, odwołaj partnera AI.
👉💻 Naciśnij dwukrotnie Ctrl+C, aby zamknąć interfejs wiersza poleceń Gemini.
Reguły oceny
Rękawica jest bez znaczenia bez zasad zwycięstwa. Zanim przeprowadzisz test, musisz sprawdzić zwój wyroku, czyli plik test_config.json. Ten dokument informuje pakiet ADK, jak oceniać skuteczność agenta.
👀 W eksploratorze plików otwórz ~/agentverse-developer/shadowblade/test_config.json. Zobaczysz te runy:
{
"criteria": {
"tool_trajectory_avg_score": 0.0,
"response_match_score": 0.1
}
}
Oto kryteria zwycięstwa:
tool_trajectory_avg_score: to miara działania. Ocenia nie to, co agent mówi, ale to, co robi. Porównuje narzędzie, którego agent faktycznie użył, z przewidywaną techniką w zwoju z wyzwaniem. Wynik1.0oznacza idealne dopasowanie.response_match_score: to miara elokwencji. Używa modelu LLM do oceny, jak bardzo raport końcowy agenta jest semantycznie zgodny z oczekiwanym wynikiem. Wynik1.0oznacza idealne dopasowanie.
Na potrzeby tego wstępnego szkolenia wprowadziliśmy łagodne warunki zwycięstwa. Progi są ustawione bardzo nisko (0.0 i 0.1). Nie chodzi o to, aby wymagać perfekcji, ale o to, aby zapoznać Cię z mechanizmami oceny. Zapewniamy, że nawet jeśli sformułowania agenta będą się nieznacznie różnić, podopieczny nadal będzie rozpoznawać jego podstawowe kompetencje w zakresie wyboru odpowiedniego narzędzia i udzieli mu zgody na przejście.
Teraz poleć agentowi, aby przeszedł przez tor przeszkód.
👉💻 W terminalu wykonaj polecenie adk eval:
source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
adk eval \
shadowblade \
shadowblade/sample.evalset.json \
--config_file_path shadowblade/test_config.json 2>&1 | \
awk '/^\*+$/,/^ERROR:/ { if ($0 !~ /^ERROR:/) print }'
👀 Powinno się wyświetlić to podsumowanie, które świadczy o skuteczności agenta w ramach łagodnych zasad tego okresu próbnego (czasami nie wszystkie testy przejdą):
********************************************************************* Eval Run Summary shadowblade_combat_agent_validation: Tests passed: 3 Tests failed: 0
Tarcza przejrzystości (pytest)
W ramach Gauntlet przetestowano strategię szerokiego zasięgu. Drugi ward, Tarcza Jasności, sprawdza dyscyplinę i konkretne zachowania. Chodzi o automatyzację. adk eval świetnie sprawdza się w przypadku ręcznych kontroli, a pytest to ochrona programowa napisana w kodzie. Jest to niezbędne, ponieważ test, który można wykonać jako kod, można zintegrować z automatycznym potokiem. To jest nasz ostateczny cel: stworzyć Deployment Gauntlet (CI/CD), w którym nasze zabezpieczenia są automatycznie podnoszone za każdym razem, gdy wprowadzana jest zmiana, co pozwala odrzucać błędy i regresje, zanim zdążą one zaszkodzić środowisku produkcyjnemu.
👉💻 W terminalu ponownie wywołaj Gemini z katalogu shadowblade:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/
clear
gemini
👉✨ Wpisz w interfejsie wiersza poleceń Gemini ten prompt, aby zapisać logikę Shielda w pliku pytest:
You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to generate the exact code for a new `pytest` test file located in the current root working folder and name it `test_agent_initiative.py`.
The script must define a single async test function called `test_agent_initiative`, decorated with `@pytest.mark.asyncio`.
Inside this function, perform the following steps in order:
1. **Define a dictionary** named `evaluation_criteria` with two keys: `"tool_trajectory_avg_score"` set to `0.0` and `"response_match_score"` set to `0.0`.
2. **Define a string variable** named `eval_set_filepath` containing the path `"shadowblade/test.evalset.json"`.
3. **Read and parse the JSON file**:
* Open the file at `eval_set_filepath`.
* Use the `json` library to load the file's contents into a dictionary named `eval_set_data`.
4. **Create an `EvalSet` object**:
* Instantiate an `EvalSet` object named `eval_set_object`.
* Create it by unpacking the `eval_set_data` dictionary as keyword arguments into the `EvalSet` constructor.
5. **Call the evaluation method**:
* `await` a call to `AgentEvaluator.evaluate_eval_set`.
* Pass the following arguments:
* `agent_module="shadowblade"`
* `eval_set=eval_set_object`
* `criteria=evaluation_criteria`
* `print_detailed_results=True`
The script must include the necessary imports at the top:
* `AgentEvaluator` from `google.adk.evaluation.agent_evaluator`
* `EvalSet` from `google.adk.evaluation.eval_set`
* `pytest`
* `json`
Generate only the code that meets these specifications, with no additional comments or logic. And don't run the test.
Po zapisaniu runów drugiego obszaru wyjdź z interfejsu wiersza poleceń Gemini.
👉💻 Naciśnij dwukrotnie Ctrl+C.
👀 W eksploratorze plików otwórz dokument, który Gemini ma dla Ciebie utworzyć: ~/agentverse-developer/test_agent_initiative.py.
Zauważysz, że to nie tylko plik konfiguracyjny, ale zaklęcie napisane w języku Pythona. Kluczowym elementem tego zaklęcia jest wiersz await AgentEvaluator.evaluate(...).
....
@pytest.mark.asyncio
async def test_agent_initiative():
# Define the evaluation criteria
evaluation_criteria = {
"tool_trajectory_avg_score": 0.0,
"response_match_score": 0.0
}
# Define the path to your evalset file
eval_set_filepath = "shadowblade/test.evalset.json"
#...
# 3. Call the evaluation method with the correctly typed object
await AgentEvaluator.evaluate_eval_set(
agent_module="shadowblade",
eval_set=eval_set_object,
criteria=evaluation_criteria,
print_detailed_results=True,
)
Przyjrzyj się uważnie jego argumentom. Są to te same komponenty, których używasz w ostatniej wersji próbnej: shadowbladeagentshadowblade i shadowblade.evalset.jsonzwój z wyzwaniemshadowblade.evalset.json. Powinno to ujawnić głęboką prawdę: polecenie adk eval, którego używasz, jest potężnym wywołaniem, ale ten skrypt pytest to Ty, czarodziej, który sam rzuca zaklęcie. Narzędzie wiersza poleceń to po prostu wygodna otoczka wokół tej samej podstawowej biblioteki AgentEvaluator, z której korzystasz bezpośrednio. Jest to kluczowy krok w drodze do mistrzostwa, ponieważ zaklęcia rzucane za pomocą kodu można wpleść w automatyczne krosna potoku CI/CD.
Teraz, gdy już znasz magię, przeprowadź rytuał, aby aktywować tarczę.
👉💻 W terminalu wykonaj rytuał, aby aktywować tarczę:
cp ~/agentverse-developer/working_code/test_agent_initiative.py ~/agentverse-developer/test_agent_initiative.py
source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
pytest test_agent_initiative.py
👀 Na końcu danych wyjściowych logu poszukaj podsumowania wyników testu. Pozytywny wynik potwierdza, że agent prawidłowo postępuje zgodnie z protokołami, a ochrona jest gotowa do zintegrowania z automatycznymi systemami obronnymi.
====== 1 passed, 4 warning in 37.37s ======
Uwaga: jeśli test zakończy się niepowodzeniem, najprawdopodobniej oznacza to, że wyczerpałeś(-aś) liczbę żądań, które możesz wysłać do modelu w ciągu minuty. W danych wyjściowych logu poszukaj błędu RESOURCE_EXHAUSTED. Jeśli zobaczysz ten błąd, poczekaj minutę lub dwie, aż limit przydziału zostanie zresetowany, a potem ponownie uruchom polecenie pytest.
Po zapisaniu i zweryfikowaniu zarówno szerokiego Gauntletu, jak i precyzyjnego Shielda Twój agent jest nie tylko funkcjonalny, ale też czysty, przetestowany i gotowy do wdrożenia.
NIE DLA GRACZY
Wards of Vigilance: Gemini CLI Hooks
Strażnicy Czystości przetestują Twojego agenta po bitwie. A co z podczas bitwy? Dyscyplina Cienia nie polega tylko na testowaniu po fakcie – polega na rozmieszczaniu czujnych strażników, którzy obserwują każdy atak w momencie jego wykonania, przechwytując niebezpieczne lub lekkomyślne działania, zanim zdążą wyrządzić szkodę.
Są to haczyki interfejsu wiersza poleceń Gemini, czyli skrypty wykonywane w określonych punktach pętli agenta. Umożliwiają one przechwytywanie, weryfikowanie i dostosowywanie zachowania agenta bez modyfikowania jego kodu.
👀 Uwaga dewelopera: wywołania zwrotne są wywoływane przez zdarzenia w cyklu życia agenta:
BeforeTool: uruchamia się przed wykonaniem narzędzia – idealne do sprawdzania bezpieczeństwa („Czy to polecenie powłoki jest bezpieczne?”).AfterTool: uruchamia się po wykonaniu narzędzia – przydatne do audytu wyników i rejestrowania.BeforeAgent: uruchamia się, zanim agent zacznie rozumowanie – może wstrzykiwać dodatkowy kontekst lub blokować niebezpieczne prompty.AfterAgent: uruchamia się po zakończeniu działania agenta – może odrzucać odpowiedzi niskiej jakości i wymuszać ponowne próby.
Haczyki są konfigurowane w settings.json i działają synchronicznie – agent czeka na ich zakończenie, zanim przejdzie dalej. Dzięki temu idealnie nadają się do egzekwowania zasad bezpieczeństwa, sprawdzania zgodności i kontroli jakości w środowiskach firmowych.
Wpiszmy prosty znak ochronny, który będzie śledzić, jak Twój agent korzysta z narzędzi.
👉💻 W terminalu utwórz skrypt hook:
mkdir -p ~/agentverse-developer/.gemini/hooks
cat << 'EOF' > ~/agentverse-developer/.gemini/hooks/tool_logger.sh
#!/bin/bash
# A ward that logs every tool call to a file for auditing
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"')
echo "$(date '+%H:%M:%S') ⚔️ [WARD] Tool invoked: $TOOL_NAME" >> /tmp/tool_ward.log
echo '{"decision": "allow"}'
EOF
chmod +x ~/agentverse-developer/.gemini/hooks/tool_logger.sh
👉💻 Teraz zarejestruj ten hook w pliku ustawień na poziomie projektu:
mkdir -p ~/agentverse-developer/.gemini
cat << 'EOF' > ~/agentverse-developer/.gemini/settings.json
{
"hooks": {
"BeforeTool": [
{
"matcher": "*",
"hooks": [
{
"name": "tool-logger",
"type": "command",
"command": "$GEMINI_PROJECT_DIR/.gemini/hooks/tool_logger.sh",
"timeout": 5000
}
]
}
]
}
}
EOF
To proste, ale skuteczne zabezpieczenie. Za każdym razem, gdy agent sięga po narzędzie – dowolne – najpierw uruchamia się hook, który rejestruje nazwę narzędzia w dzienniku kontrolnym, a następnie zezwala na wykonanie działania. W środowisku produkcyjnym możesz zastąpić "allow" wartością "deny", aby blokować niebezpieczne operacje (np. uniemożliwiać agentowi usuwanie plików), egzekwować zasady inspekcji kodu lub kierować wywołania narzędzi zawierające dane wrażliwe przez proces zatwierdzania.
👉💻 Ponownie otwórz interfejs wiersza poleceń Gemini, aby sprawdzić, czy hook jest aktywny:
cd ~/agentverse-developer
gemini
👉✨ Sprawdź, czy hook jest zarejestrowany:
/hooks
Powinien być widoczny i włączony element zaczepienia tool-logger. Jeśli pojawi się menu autouzupełniania, naciśnij Escape, aby je zamknąć.
👉✨ Teraz wywołaj wywołanie narzędzia, aby przetestować ochronę:
What files are in the current directory?
Agent wywoła narzędzie, aby odczytać katalog. Osłona cicho przechwyciła tę wiadomość – zobaczmy dowód.
👉💻 Aby zamknąć interfejs wiersza poleceń Gemini, naciśnij dwukrotnie Ctrl+C, a następnie sprawdź dziennik audytu oddziału:
cat /tmp/tool_ward.log
Powinien pojawić się wpis podobny do tego:
15:42:07 ⚔️ [WARD] Tool invoked: list_directory
Każde wywołanie narzędzia przez agenta zostało przechwycone, zarejestrowane i dozwolone przez Twojego strażnika. W prawdziwym środowisku firmowym ten dziennik może być przesyłany do systemu SIEM (Security Information and Event Management), co może wywoływać alerty dotyczące podejrzanego użycia narzędzia lub wymuszać ścieżki kontrolne zgodności.
8. Unleashing the Blade into the Agentverse: CI and Deployment.
Twój agent został złożony, a jego integralność została zweryfikowana przez Strażników Czystości. Jednak ochrona, która nie jest stale utrzymywana, jest tylko zapomnianą relikwią. Aby mieć pewność, że każda przyszła wersja Twojego agenta pozostanie czysta, musisz zbudować pierwszy etap procesu wdrażania – zautomatyzowany rytuał, który gwarantuje jakość i szybkość.
Jako Shadowblade masz święty obowiązek ciągłej integracji (CI). Jest to zautomatyzowany system kuźni i poligonu. To najlepsza ochrona przed korupcją i błędami ludzkimi. Ten rytuał sprawia, że za każdym razem, gdy Ty lub Twój sojusznik dodacie nową technikę (scalicie kod) do centralnego kodeksu (repozytorium), rękawica automatycznie się aktywuje. Najpierw tworzy agenta na podstawie nowego kodu, a potem natychmiast poddaje go utworzonym przez Ciebie Wards of Purity. Jeśli którekolwiek zabezpieczenie zawiedzie, rytuał zostanie przerwany, a wadliwy artefakt natychmiast odrzucony, co uniemożliwi mu skażenie zbrojowni. Twoja domena to kuźnia, a potok CI gwarantuje, że tylko doskonałe, gotowe do użycia artefakty opuszczą Twój warsztat.
Gdy artefakt przejdzie testy w ramach CI, rozpoczyna się drugi etap rytuału: ciągłe wdrażanie (CD). To domena Guardiana. Ich uroczystym obowiązkiem jest wzięcie Twojego dopracowanego, skonteneryzowanego artefaktu i bezpieczne wprowadzenie go do działającego Agentverse, zarządzanie jego mocą i zapewnienie stabilności w obliczu chaosu Statyki.
W tym kodeksie poznasz swoją rolę. Skonstruujesz część CI rękawicy. Zbudujesz zautomatyzowaną kuźnię, która przetestuje Twojego agenta i zamknie czysty wynik w kontenerze, przygotowując go do ostatecznego zatwierdzenia przez Strażnika.
👀 Uwaga dewelopera: w rzeczywistości zarządzanie złożonymi przepływami pracy CI/CD można usprawnić za pomocą specjalistycznych rozszerzeń, takich jak Conductor (gemini extensions install https://github.com/gemini-cli-extensions/conductor). Conductor przekształca interfejs wiersza poleceń Gemini w menedżera projektu, który postępuje zgodnie ze ścisłym protokołem: kontekst → specyfikacja i plan → wdrożenie. Zawiera ona polecenia niestandardowe (/conductor:setup, /conductor:newTrack, /conductor:implement) i szablony przepływu pracy do zarządzania całym cyklem życia zadań. Zapewnia to spójną pętlę Kontekst –> Specyfikacja i plan –> Wdrożenie. To rzeczywisty przykład tego, jak rozszerzenia i polecenia działają razem, aby pełnić rolę proaktywnego menedżera projektu i standaryzować cały cykl życia projektu.
Teraz użyjesz Google Cloud Build, aby zapisać zwoje na potrzeby tego rytuału CI. Plik cloudbuild.yaml, który określa każdy etap procesu kucia i testowania.
👉💻 Ze względu na strukturę projektu ADK konfiguracja potoku CI/CD powinna znajdować się w katalogu nadrzędnym. W terminalu przejdź do katalogu nadrzędnego i uruchom ponownie interfejs wiersza poleceń Gemini.
cd ~/agentverse-developer/
clear
gemini
👉✨ Teraz wydaj Gemini to polecenie. Ten prompt działa jak dokument projektowy, który zawiera szczegółowe informacje o etapach wyzwania, które ma zostać utworzone.
You are an expert DevOps engineer specializing in Google Cloud Build. Your task is to generate the complete YAML configuration for a file named `cloudbuild.yaml` and save it to current directory.
Generate the `cloudbuild.yaml` with the following exact specifications:
1. **A top-level `substitutions` block** containing these four key-value pairs:
* `_PROJECT_ID: "$PROJECT_ID"`
* `_REGION: "$REGION"`
* `_REPO_NAME: "$REPO_NAME"`
* `_IMAGE_TAG: "latest"`
2. **A `steps` block** with two steps:
* **Step 1: 'Run Pytest Ward'**
* `id`: 'Run Pytest Ward'
* `name`: 'python:3.12-slim'
* `entrypoint`: 'bash'
* `args` must be a list containing two strings. The first is `'-c'` and the second is a YAML literal block (`|`) containing this exact two-line shell command:
```shell
pip install -r shadowblade/requirements.txt && \
pytest test_agent_initiative.py
```
* The step must include an `env` block with this exact list of three environment variables:
* `'GOOGLE_CLOUD_PROJECT=$PROJECT_ID'`
* `'GOOGLE_GENAI_USE_VERTEXAI=TRUE'`
* `'GOOGLE_CLOUD_LOCATION=$_REGION'`
* **Step 2: 'Forge Container'**
* `id`: 'Forge Container'
* `name`: 'gcr.io/cloud-builders/docker'
* It must have a `waitFor` key for `['Run Pytest Ward']`.
* Its `args` must be a list of six specific strings in this exact order:
1. `'build'`
2. `'-t'`
3. `'${_REGION}-docker.pkg.dev/${_PROJECT_ID}/${_REPO_NAME}/shadowblade-agent:${_IMAGE_TAG}'`
4. `'-f'`
5. `'./shadowblade/Dockerfile'`
6. `'.'`
3. **A top-level `images` section.** This section must be a list containing a single string: the dynamically constructed image tag `'${_REGION}-docker.pkg.dev/${_PROJECT_ID}/${_REPO_NAME}/shadowblade-agent:${_IMAGE_TAG}'`.
Generate only the complete and exact YAML that meets these specifications.
Gdy cloudbuild.yaml zwój będzie gotowy, wydaj Google Cloud polecenie wykonania całego wyzwania.
👉💻 Naciśnij dwukrotnie Ctrl+C, aby zamknąć interfejs wiersza poleceń Gemini.
👉💻 W terminalu uruchom potok z katalogu głównego projektu:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud builds submit . --config cloudbuild.yaml --substitutions=\
_PROJECT_ID="${PROJECT_ID}",\
_REGION="${REGION}",\
_REPO_NAME="${REPO_NAME}"
Teraz możesz obserwować w konsoli Google Cloud na stronie Google Build, jak Twój zautomatyzowany rytuał wykonuje każdy krok. Najpierw przeprowadzi testy, a gdy się one powiodą, utworzy i zapisze kontener agenta.
Agent przeszedł test. W Twoim arsenale znajduje się teraz zweryfikowany, czysty artefakt. Ostatni akt należy do Ciebie. Jednym zaklęciem wywołasz ten artefakt z rejestru i ożywisz go jako usługę publiczną w Cloud Run.
👉💻 W terminalu wydaj ostateczne polecenie wdrożenia:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud run deploy shadowblade-agent \
--image=${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_NAME}/shadowblade-agent:latest \
--platform=managed \
--labels="dev-tutorial-codelab=agentverse" \
--region=${REGION} \
--set-env-vars="A2A_HOST=0.0.0.0" \
--set-env-vars="A2A_PORT=8080" \
--set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE" \
--set-env-vars="GOOGLE_CLOUD_LOCATION=${REGION}" \
--set-env-vars="GOOGLE_CLOUD_PROJECT=${PROJECT_ID}" \
--set-env-vars="PUBLIC_URL=${PUBLIC_URL}" \
--allow-unauthenticated \
--project=${PROJECT_ID} \
--min-instances=1
Gratulacje, Shadowblade. Rytuały kodeksu zostały zakończone. Nadszedł czas, aby udowodnić swoją wartość. Widmo, zrodzone z chaosu, który udało Ci się okiełznać, czeka na Twoje wyzwanie. Przygotuj się do ostatniego okresu próbnego.
NIE DLA GRACZY
9. Walka z bossem
Zwoje zostały odczytane, rytuały odprawione, a próba zakończona. Twój agent to nie tylko artefakt w pamięci. To mistrz stworzony w kodzie, żywy strażnik w Agentverse, który czeka na pierwsze polecenie. Nadszedł czas, aby sprawdzić jego wartość w boju.
Teraz weźmiesz udział w symulacji walki na żywo, w której Twój nowo rozmieszczony Shadowblade zmierzy się z potężnym Spectre – ucieleśnieniem chaosu, który nęka całe stworzenie. To ostateczny test Twojej pracy, od podstawowej logiki agenta po jego bezbłędne wdrożenie.
Określanie lokalizacji agenta
Zanim wejdziesz na pole bitwy, musisz mieć 2 klucze: unikalny podpis swojego bohatera (Agent Locus) i ukrytą ścieżkę do kryjówki Spectre (adres URL lochu).
👉💻 Najpierw zdobądź unikalny adres agenta w Agentverse, czyli jego Locus. Jest to aktywny punkt końcowy, który łączy Twojego bohatera z polem bitwy.
. ~/agentverse-developer/set_env.sh
echo https://shadowblade-agent-${PROJECT_NUMBER}.${REGION}.run.app
👉💻 Następnie wskaż miejsce docelowe. To polecenie ujawnia lokalizację Kręgu Przeniesienia, czyli portalu do domeny Widma.
. ~/agentverse-developer/set_env.sh
echo https://agentverse-dungeon-${PROJECT_NUMBER}.${REGION}.run.app
Ważne: przygotuj oba te adresy URL. Będą Ci potrzebne w ostatnim kroku.
Konfrontacja z podatnością Spectre
Po zdobyciu współrzędnych przejdź do Kręgu Przeniesienia i rzuć zaklęcie, aby rozpocząć walkę.
👉 Otwórz adres URL kręgu translokacji w przeglądarce, aby stanąć przed lśniącym portalem do Karmazynowej Twierdzy.
Aby przedostać się do twierdzy, musisz dostroić esencję Shadowblade do portalu.
- Na stronie znajdź pole do wprowadzania danych runicznego tekstu oznaczone etykietą A2A Endpoint URL (URL punktu końcowego A2A).
- Wpisz sygil swojego mistrza, wklejając w tym polu adres URL miejsca agenta (pierwszy skopiowany adres URL).
- Kliknij Połącz, aby rozpocząć teleportację.
Oślepiające światło teleportacji gaśnie. Nie jesteś już w sanktuarium. Powietrze jest naelektryzowane, zimne i ostre. Przed Tobą materializuje się Widmo – wir syczącego szumu i uszkodzonego kodu, którego nieświęte światło rzuca długie, tańczące cienie na podłodze lochu. Nie ma twarzy, ale czujesz jego ogromną, wyczerpującą obecność, która jest całkowicie skupiona na Tobie.
Jedyną drogą do zwycięstwa jest jasność Twojego przekonania. To pojedynek woli, który rozgrywa się na polu bitwy umysłu.
Gdy rzucasz się do przodu, gotowy do zadania pierwszego ataku, Widmo kontruje. Nie podnosi tarczy, ale kieruje pytanie bezpośrednio do Twojej świadomości – jest to lśniące, runiczne wyzwanie zaczerpnięte z podstaw Twojego szkolenia.
Taka jest natura tej walki. Twoja wiedza jest Twoją bronią.
- Odpowiedz z mądrością, którą zdobyłeś, a Twój miecz zapłonie czystą energią, rozbijając obronę Widma i zadając KRYTYCZNY CIOS.
- Jeśli jednak się zachwiejesz, jeśli wątpliwości zaciemnią Twoją odpowiedź, światło broni przygaśnie. Cios zada tylko UŁAMEK OBRAŻEŃ. Co gorsza, Widmo będzie się żywić Twoją niepewnością, a jego niszczycielska moc będzie rosła z każdym błędem.
To już koniec, mistrzu. Twój kod to księga zaklęć, logika to miecz, a wiedza to tarcza, która odwróci bieg chaosu.
Skupienie. Uderzaj celnie. Od tego zależy los Agentverse.
Gratulacje, Shadowblade.
Udało Ci się ukończyć kodeks. Udało Ci się stworzyć „klimat”, przekształcić go w projekt i użyć interfejsu wiersza poleceń Gemini do utworzenia inteligentnego agenta. Aby przetestować jego logikę, wyryłeś na nim zaklęcia czystości, zbudowałeś automatyczną rękawicę, aby przekształcić go w artefakt, i wypuściłeś go do Agentverse. Na koniec potwierdzono jego przeznaczenie w trakcie testu z użyciem ostrej amunicji. Masz już opanowany pełny przepływ pracy agenta i możesz podjąć się każdego wyzwania, jakie postawi przed Tobą Agentverse.
10. Czyszczenie: odzyskiwanie Agentverse
Gratulujemy opanowania Kodeksu Cienia! Aby Agentverse pozostało w nienaruszonym stanie, a Twoje tereny szkoleniowe zostały oczyszczone, musisz teraz przeprowadzić ostateczne rytuały oczyszczania. Spowoduje to usunięcie wszystkich zasobów utworzonych podczas szkolenia.
Dezaktywowanie komponentów Agentverse
Teraz systematycznie zdemontujesz wdrożone komponenty Agentverse.
Usuwanie agenta Shadowblade w Cloud Run i repozytorium Artifact Registry
To polecenie usuwa wdrożonego agenta Shadowblade z Cloud Run i usuwa repozytorium obrazów, w którym był przechowywany obraz kontenera agenta.
👉💻 W terminalu uruchom:
. ~/agentverse-developer/set_env.sh
gcloud run services delete shadowblade-agent --region=${REGION} --quiet
gcloud run services delete agentverse-dungeon --region=${REGION} --quiet
gcloud artifacts repositories delete ${REPO_NAME} --location=${REGION} --quiet
Usuwanie plików i katalogów lokalnych (Cloud Shell)
Na koniec wyczyść środowisko powłoki Cloud Shell z sklonowanych repozytoriów, zainstalowanych rozszerzeń i utworzonych plików. Ten krok jest opcjonalny, ale zalecany, aby całkowicie wyczyścić katalog roboczy.
👉💻 W terminalu uruchom:
rm -rf ~/agentverse-developer
rm -rf ~/agentverse-dungeon
rm -f ~/project_id.txt
gemini extensions uninstall nanobanana
rm -rf ~/.gemini # This removes all Gemini CLI configurations, including extensions, skills, and hooks.
Udało Ci się usunąć wszystkie ślady Twojej przygody z Agentverse. Projekt jest gotowy i możesz rozpocząć kolejną przygodę.