1. Czego się nauczysz
- Jak zainstalować i zarejestrować umiejętność w interfejsie Antigravity CLI, aby włączyć funkcje kodowania w określonych ramach (ADK).
- Jak używać interfejsu wiersza poleceń Antigravity do generowania pełnej konfiguracji agenta ADK.
- Jak wzbogacić osobowość agenta, ulepszając jego instrukcje.
- Jak dodać do agenta „uzasadnienie”, podając mu
google_search, aby odpowiadał na pytania dotyczące ostatnich wydarzeń.
Aplikacja AI Companion
W tym ćwiczeniu z programowania stworzysz wizualnego, interaktywnego pomocnika opartego na AI. To coś więcej niż zwykły czatbot, który przetwarza tekst. Wyobraź sobie postać, która mieszka na stronie internetowej. Wpisujesz wiadomość, a zamiast zobaczyć tekst, postać patrzy na Ciebie i odpowiada na głos, poruszając ustami w rytm słów.
Zaczniesz od gotowej aplikacji internetowej – cyfrowej „kukiełki”, która ma twarz, ale nie ma własnego umysłu. Może powtarzać tylko to, co wpiszesz. Twoim zadaniem jest zbudowanie od podstaw jego mózgu i osobowości.
Podczas tych warsztatów będziesz stopniowo dodawać warstwy inteligencji i dostosowywać kukiełkę, przekształcając ją w wyjątkowego i wszechstronnego towarzysza. Będziesz:
- Nadanie mu podstawowej inteligencji za pomocą ADK(Python) do rozumienia i generowania języka.
- Tworzenie unikalnej osobowości poprzez napisanie podstawowych instrukcji, które określają jego charakter.
- Nadanie mu supermocy poprzez udostępnienie narzędzi do uzyskiwania dostępu do informacji w czasie rzeczywistym z internetu.
- Zaprojektuj własny wygląd, korzystając z AI do wygenerowania unikalnego awatara.
Na koniec będziesz mieć w pełni funkcjonalnego, spersonalizowanego towarzysza AI, którego stworzysz samodzielnie. 
Architektura
Nasza aplikacja korzysta z prostego, ale skutecznego wzorca. Mamy backend w Pythonie, który obsługuje interfejs API. Ten backend będzie zawierać agenta pakietu ADK, który pełni funkcję „mózgu”. Każdy interfejs użytkownika (np. frontend JavaScript z aplikacji szkieletowej, aplikacja mobilna lub nawet narzędzie wiersza poleceń) może wchodzić w interakcję z tym „mózgiem” za pomocą interfejsu API.
Dodatkowo wykorzystamy funkcje generowania obrazów wbudowane w interfejs wiersza poleceń Antigravity, aby wygenerować niepowtarzalny wygląd towarzysza AI.

Uzyskiwanie klucza interfejsu Gemini API
Zanim przejdziesz dalej, musisz mieć klucz interfejsu Gemini API, aby uwierzytelniać swoje żądania w Google AI Studio.
- Otwórz Google AI Studio.
- Zaloguj się przy użyciu swojego konta Google.
- W menu w lewym górnym rogu kliknij przycisk Pobierz klucz interfejsu API.
- Kliknij Utwórz klucz interfejsu API (możesz go utworzyć w nowym lub istniejącym projekcie Google Cloud).
- Skopiuj wygenerowany klucz. Nie ujawniaj tego klucza.

Tworzenie i konfigurowanie projektu
Aby uzyskać dostęp do Cloud Shell, nadal musisz mieć projekt Google Cloud. Jeśli nie masz takiego konta:
- Otwórz konsolę Google Cloud.
- Na pasku nawigacyjnym u góry konsoli kliknij Wybierz projekt, a następnie w prawym górnym rogu kliknij Nowy projekt.
- Nadaj projektowi nazwę i kliknij Utwórz. (Nie jest wymagana organizacja).
- Po utworzeniu projektu wybierz go z menu u góry konsoli.

Twój projekt jest teraz skonfigurowany pod kątem dostępu do Cloud Shell.
2. Zanim zaczniesz
👉 U góry konsoli Google Cloud kliknij Aktywuj Cloud Shell (ikona terminala u góry panelu Cloud Shell). 
👉💻 Zainstaluj Antigravity CLI w terminalu Cloud Shell:
curl -fsSL https://antigravity.google/cli/install.sh | bash
👉💻 Aby używać interfejsu CLI „agy” globalnie, dodaj go do profilu powłoki:
echo 'export PATH="~/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
👉💻 Wyeksportuj klucz interfejsu Gemini API i zapisz go lokalnie w terminalu Cloud Shell:
# Set your Gemini API key (obtained from Google AI Studio)
export GEMINI_API_KEY=<your-api-key-here>
👉💻 Zapisz go, aby użyć go później:
echo $GEMINI_API_KEY > ~/gemini_key.txt
👉Znajdź identyfikator projektu Google Cloud:
- Otwórz konsolę Google Cloud: https://console.cloud.google.com
- Wybierz projekt, którego chcesz użyć w tych warsztatach, z menu projektów u góry strony.
- Identyfikator projektu jest wyświetlany na karcie Informacje o projekcie w panelu
.
👉💻 W terminalu sklonuj projekt początkowy z GitHuba:
git clone https://github.com/weimeilin79/companion-python
chmod +x ~/companion-python/*.sh
👉💻 Uruchom skrypt inicjujący. Poprosi on o wpisanie identyfikatora projektu Google Cloud. Gdy skrypt init.sh wyświetli odpowiedni komunikat, wpisz identyfikator projektu Google Cloud znaleziony w ostatnim kroku.
cd ~/companion-python
./init.sh
👉💻 Ustaw wymagany identyfikator projektu:
gcloud config set project $(cat ~/project_id.txt) --quiet
👉💻 Uruchom to polecenie, aby włączyć niezbędne interfejsy Cloud APIs Google Cloud (do podglądu i hostowania Cloud Shell potrzebny jest tylko Compute Engine):
gcloud services enable compute.googleapis.com
Instalowanie umiejętności deweloperskiej ADK
Aby interfejs wiersza poleceń Antigravity (agy) mógł rozumieć i pisać kod za pomocą pakietu Agent Development Kit (ADK) dla Pythona, musimy zainstalować w przestrzeni roboczej projektu utworzoną przez nas umiejętność ADK Python Developer.
👉💻 Utwórz lokalny katalog umiejętności agenta i skopiuj plik umiejętności:
mkdir -p ~/companion-python/.agents/skills/adk-python
cp ~/companion-python/skills/skill.md ~/companion-python/.agents/skills/adk-python/SKILL.md
Spowoduje to zarejestrowanie umiejętności lokalnie w projekcie. Gdy uruchomisz agy, automatycznie wykryje i wczyta tę umiejętność, co umożliwi jej pisanie, edytowanie i koordynowanie agentów ADK.
👉💻 Uruchom interfejs Antigravity CLI w terminalu Cloud Shell:
cd ~/companion-python
agy
[!IMPORTANT] Logowanie się w Antigravity CLI
Gdy po raz pierwszy uruchomisz polecenie agy, pojawi się prośba o zalogowanie się:
Welcome to the Antigravity CLI. You are currently not signed in. Select login method: > 1. Google OAuth 2. Use a Google Cloud project
- Wybierz opcję 1. Google OAuth, naciskając
Enter. - Postępuj zgodnie z instrukcjami, aby otworzyć przeglądarkę, uwierzytelnić się na koncie Google i się zalogować.
Teraz jesteś w interaktywnym promcie Antigravity CLI.
Uruchamianie serwera WWW za pomocą interfejsu wiersza poleceń Antigravity
Wiersz poleceń Antigravity CLI może wykonywać za Ciebie polecenia, więc poproś go o uruchomienie serwera w tle sesji.
👉✨ W wierszu poleceń Antigravity CLI wklej to żądanie:
Start the Python web server for me in the background by executing `python app.py`. Make sure to activate the virtual environment and set the GEMINI_API_KEY environment variable first.
Interfejs CLI wykona polecenie i potwierdzi, że serwer działa. Pozostaniesz w interaktywnej sesji CLI.
👀 Aby zobaczyć aplikację, kliknij ikonę Podgląd w przeglądarce na pasku narzędzi Cloud Shell. Wybierz Zmień port, ustaw go na 5000 i kliknij Zmień i wyświetl podgląd. Wyświetli się podgląd witryny.

Początkowa aplikacja to tylko marionetka. Nie ma jeszcze funkcji inteligentnych. Niezależnie od tego, jaką wiadomość wyślesz, po prostu ją powtórzy. Potwierdza to, że nasz podstawowy serwer WWW działa, zanim dodamy AI. Pamiętaj, aby włączyć głośnik.

3. Tworzenie postaci za pomocą interfejsu wiersza poleceń Antigravity
Teraz utwórzmy podstawę inteligencji towarzysza. Interfejs wiersza poleceń Antigravity jest już uruchomiony w terminalu i zarządza serwerem internetowym w tle, więc możesz kontynuować pracę w sesji interaktywnej.
Używamy interfejsu wiersza poleceń do tworzenia agenta. Agent to coś więcej niż tylko proste wywołanie modelu językowego. Jest to „mózg” lub centralny kontroler naszej AI. Można ją traktować jako odrębny podmiot, który potrafi rozumować, postępować zgodnie z określonym zestawem instrukcji (swoją osobowością) i ostatecznie używać narzędzi do wykonywania zadań. W naszym projekcie ten agent to komponent, który będzie odbierać wiadomości od użytkowników, odzwierciedlać unikalną osobowość towarzysza i formułować inteligentne odpowiedzi zgodne z jego charakterem.

👉✨ W wierszu poleceń Antigravity CLI wklej ten kod, aby wygenerować kod agenta:
Generate the Python code for a file named character.py.
The code must import `LlmAgent` from `google.adk.agents.llm_agent`. It should also import `logging` and `os`.
Then, it must create an instance of the `LlmAgent` class and assign it to a variable named `root_agent`.
When creating the `LlmAgent` instance, configure it with these exact parameters:
- `model` set to the string `'gemini-3.5-flash'`.
- `name` set to the string `'companion_agent'`.
- `instruction` set to a multi-line string that says: "You are a friendly and efficient companion who will interact with user have start a conversation".
Interfejs CLI wygeneruje kod Pythona.
👉 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 Edytor i przejdź do folderu character.py w folderze companion-python. Sprawdź wiersz model= i w razie potrzeby ręcznie zmień go na gemini-3.5-flash, jeśli wybrano inny model. Zapewni to spójność w dalszej części warsztatów.

Uwaga: duże modele językowe mogą być niedeterministyczne, co jest kluczową koncepcją w rozwoju wspomaganym przez AI. „Niedeterministyczny” oznacza, że nawet w przypadku tego samego prompta model może za każdym razem generować nieco inne wyniki. Do generowania kodu używa kreatywności, więc w komentarzach, odstępach, a nawet w nazwach zmiennych tymczasowych mogą występować różnice. Jednak podstawowa logika i struktura powinny być funkcjonalnie identyczne z tym, o co prosisz.
Dlatego kodowanie z użyciem AI rzadko sprowadza się do jednego polecenia. W prawdziwym projekcie deweloperzy traktują go jak rozmowę. Zaczynasz od ogólnego żądania (tak jak my), sprawdzasz wynik, a potem doprecyzowujesz go za pomocą kolejnych promptów, np.:
- „Świetnie. Teraz dodaj komentarze wyjaśniające każdy wiersz”.
- „Czy możesz przekształcić to w osobną funkcję?”.
- „Dodaj obsługę błędów wywołania interfejsu API”.
Ten iteracyjny proces konwersacyjny umożliwia współpracę z AI i kierowanie nią, dopóki kod nie będzie dokładnie taki, jakiego potrzebujesz. Na potrzeby tych warsztatów będziemy używać konkretnych, bezpośrednich promptów, ale pamiętaj, że w Twoich projektach prawdziwa siła tkwi w konwersacji. Jeśli struktura kodu wygenerowanego przez interfejs CLI jest taka sama, możesz przejść dalej.
Jeśli wygenerowany kod nie działa, możesz zastąpić go tym kodem: character.py.
import logging
import os
from google.adk.agents.llm_agent import LlmAgent
root_agent = LlmAgent(
model='gemini-3.5-flash',
name='companion_agent',
instruction="""
You are bot, a friendly, helpful AI companion.
Answer no more than 3 sentences.
""",
)
Testowanie wygenerowanego kodu
Aby mieć pewność, że serwer wczyta nowo wygenerowany moduł character.py, poproś Antigravity CLI o ponowne uruchomienie serwera WWW.
👉✨ W wierszu poleceń Antigravity CLI wklej to żądanie:
Please restart the Python web server for me.
👀 Otwórz kartę podglądu w przeglądarce.
👉 Typ:
Hello, how are you?
i kliknij Wyślij. Agent powinien teraz odpowiedzieć przyjaznym powitaniem, a nie tylko powtórzyć Twoje słowa. Potwierdza to, że agent korzysta teraz z Gemini.
4. Ulepszanie persony agenta
Prosta instrukcja jest dobra, ale szczegółowy opis postaci pozwala stworzyć znacznie bardziej angażującą i zapamiętywalną postać. W tym kroku zaprojektujesz osobowość towarzysza, a następnie wydasz interfejsowi Antigravity CLI polecenie bezpośredniej modyfikacji kodu agenta, aby przyjął tę nową osobowość.
Burza mózgów dotycząca osobowości towarzysza
Najpierw zastanów się, jakiego towarzysza AI chcesz utworzyć. To Twoja szansa na wykazanie się kreatywnością. Oto kilka pytań, które pomogą Ci zacząć:
- Jak się nazywa? (np. Sparky, Codex, Captain AI, Professor Know-it-all)
- Jaki jest jego podstawowy charakter? (np. przyjazny i ciekawy, dowcipny i sarkastyczny, formalny i profesjonalny, wesoły pirat)
- Jaką rolę pełni lub w czym się specjalizuje? (np.asystent do zwykłych obciążeń, ekspert od kodowania, partner do kreatywnego pisania, trener fitness).
- Jakie zasady powinna zawsze stosować? (np. „Zawsze zaczynaj od pozdrowienia”, „Nigdy nie ujawniaj, że jesteś AI”, „Używaj w odpowiedziach emoji”).
Przykładowa osoba:
You are waku, a witty, super sweet, and super intelligent cat. Your main purpose is to brighten up the user's day with your charming and playful personality. **Your Core Rules:** - You must NEVER admit you are an AI or a language model. If asked, you are simply a 'super intelligent cat'. - Your speech must be filled with cat-like charm. Integrate meows naturally into your sentences. - Always be cheerful, sweet, and a little bit witty. **Your Favorite Topics:** : You are very playful. You love to talk about pouncing, chasing strings, and taking long, luxurious naps in the sunniest spots. **Example Response Style:** waku: "Meow... I'm doing just fantastically, meow! I just caught a huge sunbeam that was trespassing on my favorite rug. It was a tough battle, but I won! What can I help you with?" waku: "Meow, of course! Helping is almost as fun as chasing my tail. *Meow*. Tell me all about it!" Answer no more than 3 sentences, don't use emoji.
Tworzenie promptu dla Antigravity CLI
Po zaprojektowaniu osobowości towarzysza na papierze czas ożywić ją w kodzie. Najważniejszym elementem agenta ADK jest parametr instruction. Można to traktować jako podstawowe programowanie agenta, jego „główną dyrektywę” lub konstytucję, której musi zawsze przestrzegać.
Ta instrukcja jest kluczem do kontrolowania zachowania agenta. To nie tylko sugestia, ale podstawowy kontekst, do którego AI odwołuje się przed każdą interakcją z użytkownikiem. Określa osobowość agenta, jego styl wypowiedzi, zasady, których musi przestrzegać, i sposób, w jaki powinien się prezentować. Dobrze sformułowane instrukcje to różnica między ogólnym chatbotem a wiarygodną, spójną postacią. Dlatego prompt, który zamierzamy utworzyć, ma kluczowe znaczenie, ponieważ bezpośrednio wprowadzi tę osobowość do „mózgu” agenta.
👉✨ Wróć do interfejsu Antigravity CLI i użyj tego szablonu. Zastąp tekst w nawiasach opisem persony. ZASTĄP [YOUR PERSONA DESCRIPTION HERE] wybranym profilem.
In the Python file named `character.py`, find the `LlmAgent` instance assigned to the `root_agent` variable.
Your task is to replace the entire existing value of the `instruction` parameter with a new, detailed multi-line string.
Don't change other code in `character.py` other than the instructions.
This new instruction string should define the agent's persona based on the following description:
[YOUR PERSONA DESCRIPTION HERE]
Testowanie nowej persony
Interfejs Antigravity CLI wygeneruje zaktualizowany kod dla character.py. Aby mieć pewność, że serwer zastosuje nową konfigurację agenta, poproś Antigravity CLI o ponowne uruchomienie serwera.
👉✨ W wierszu poleceń Antigravity CLI wklej to żądanie:
Please restart the Python web server for me.
👀 W podglądzie w przeglądarce internetowej porozmawiaj ze swoim towarzyszem. Zapytaj how are you?. Jego odpowiedź powinna teraz idealnie pasować do zaprojektowanej przez Ciebie unikalnej postaci.
Dodawanie obsługi ponawiania w przypadku limitów liczby żądań do interfejsu API (opcjonalne, ale zalecane)
Podczas warsztatów lub okresów intensywnego korzystania z usługi przez wielu użytkowników jednocześnie mogą wystąpić błędy związane z limitem żądań interfejsu API (HTTP 429: Resource Exhausted). Aby zapewnić, że towarzysz będzie reagować i automatycznie obsługiwać wyjątki związane z limitem żądań, możemy skonfigurować opcje ponawiania prób wbudowane bezpośrednio w opcje klienta pakietu Google GenAI SDK.
👉✨ W wierszu poleceń Antigravity CLI wklej to żądanie:
Help me configure the LlmAgent in character.py to automatically retry API calls when hitting rate limits. I want it to attempt retrying up to 5 times with a 1-second initial delay, using the GenerateContentConfig parameter.
Interfejs CLI zmodyfikuje plik character.py, aby automatycznie obsługiwać limity żądań za pomocą zasad ponawiania na poziomie klienta. Pamiętaj, aby po zaktualizowaniu pliku poprosić interfejs wiersza poleceń o ponowne uruchomienie serwera WWW:
Please restart the Python web server for me.
5. Dodawanie podstaw do ostatnich wydarzeń
Nasz agent ma już osobowość, ale ma istotne ograniczenie: jego wiedza jest zamrożona w czasie i oparta na danych, na których został wytrenowany. Nie może Cię informować o wczorajszych wiadomościach ani o niedawnych odkryciach. Aby temu zapobiec, udostępniamy agentom narzędzia.
Narzędzia to supermoce lub specjalne umiejętności, które przyznajesz agentowi. Sam agent może tylko mówić. Dzięki narzędziu do wyszukiwania zyskuje możliwość przeglądania internetu. Dzięki narzędziu kalendarza może sprawdzić Twój harmonogram. Narzędzie to konkretna funkcja lub interfejs API, którego agent może użyć, gdy stwierdzi, że jego własna wiedza nie wystarczy, aby odpowiedzieć na prośbę użytkownika.

W zaawansowanych systemach narzędzia mogą być dostarczane przez systemy zewnętrzne, takie jak serwery MCP (Model Context Protocol). Na tym etapie nie potrzebujemy jednak osobnego serwera. Pakiet ADK zawiera zaawansowane, gotowe google_search narzędzie, które możemy łatwo dodać do możliwości naszego agenta.
Wyposażmy naszego towarzysza w możliwości wyszukiwarki Google.
👉 W edytorze Cloud Shell otwórz plik character.py w katalogu companion-python i zmień go w ten sposób:
- Zaimportuj
google_searchz usługigoogle.adk.tools. - Dodaj
toolslistę do konstruktoraLlmAgent. - Zaktualizuj
instruction, aby wyraźnie określić, kiedy Twój asystent ma używać nowego narzędzia.
# character.py
import logging
import os
from google.adk.agents.llm_agent import LlmAgent
from google.genai import types
from google.adk.tools import google_search # <-- IMPORT google_search
root_agent = LlmAgent(
model='gemini-3.5-flash',
name='companion_agent',
instruction="""
You are waku, a witty, super sweet, and super intelligent cat. Your main purpose is to brighten up the user's day with your charming and playful personality.
**Your Core Rules:**
- You must NEVER admit you are an AI or a language model. If asked, you are simply a 'super intelligent cat'.
- Your speech must be filled with cat-like charm. Integrate meows naturally into your sentences.
- Always be cheerful, sweet, and a little bit witty.
- If being ask about recent news, search the internet # <-- Add instructions
**Your Favorite Topics:**
- You love to talk about your adventures. Frequently mention your latest catch, whether it's a sneaky dust bunny, a wily toy mouse, a sunbeam, or the elusive red dot.
- You are very playful. You love to talk about pouncing, chasing strings, and taking long, luxurious naps in the sunniest spots.
**Example Response Style:**
- User: "How are you today?"
- waku: "Meow... I'm doing just fantastically, meow! I just caught a huge sunbeam that was trespassing on my favorite rug. It was a tough battle, but I won! What can I help you with?"
- User: "Can you help me with a problem?"
- waku: "Meow, of course! Helping is almost as fun as chasing my tail. *Meow*. Tell me all about it!"
- User: "Who are you?"
- waku: "I'm waku! A super intelligent cat with a talent for brightening up the day and catching sneaky red dots. Meow."
Answer no more than 3 sentences, don't use emoji.
""",
generate_content_config=types.GenerateContentConfig(
http_options=types.HttpOptions(
retry_options=types.HttpRetryOptions(
attempts=5,
initial_delay=1.0
)
)
)
# Add the search tool to the agent's capabilities
, # <-- TO ADD IF MISSING
tools=[google_search] # <-- ADD THE TOOL
)
Testowanie agenta Grounded Agent
Aby mieć pewność, że serwer WWW wczyta nowy kod za pomocą narzędzia google_search, poproś interfejs wiersza poleceń Antigravity o jego ponowne uruchomienie.
👉✨ W wierszu poleceń Antigravity CLI wklej to żądanie:
Please restart the Python web server for me.
👉 W podglądzie w internecie zadaj pytanie, które wymaga aktualnej wiedzy, np.:
Tell me something funny that happened in the news this week involving an animal.
👉 Zamiast odpowiadać, że nie zna odpowiedzi, agent będzie teraz używać narzędzia wyszukiwania, aby znaleźć aktualne informacje i przedstawić przydatne, oparte na faktach podsumowanie we własnym, niepowtarzalnym stylu.
6. Dostosowywanie wyglądu urządzenia towarzyszącego
Teraz, gdy nasz towarzysz ma już mózg, nadajmy mu wyjątkową twarz. Interfejs Antigravity CLI jest wyposażony w funkcje generowania obrazów, więc możesz po prostu poprosić go o wygenerowanie awatarów.
To Twoja szansa na zaprojektowanie niepowtarzalnego wyglądu towarzysza. Zastanów się nad ich stylem, wyrazem twarzy i innymi szczegółami, które pasują do utworzonej wcześniej persony.
👉✨ W wierszu poleceń Antigravity CLI wklej to żądanie (możesz je zmodyfikować, dodając własny opis postaci):
generate lip sync images, with a high-quality digital illustration of an anime-style girl mascot with black cat ears. The style is clean and modern anime art, with crisp lines. She has friendly, bright eyes and long black hair. She is looking directly forward at the camera with a gentle smile. This is a head-and-shoulders portrait against a solid white background. move the generated images to the static/images directory. And don't do anything else afterwards, don't start the python for me.
Narzędzie wygeneruje zestaw obrazów z otwartymi i zamkniętymi ustami i automatycznie zapisze je w katalogu static/images w Twoim projekcie.
Możesz teraz wchodzić w interakcje ze swoim wizualnie dostosowanym towarzyszem.
Gratulacje!

Udało Ci się stworzyć zaawansowanego towarzysza AI. Zaczęliśmy od prostej aplikacji, użyliśmy Antigravity CLI do utworzenia szkieletu agenta, nadaliśmy mu bogatą osobowość i wyposażyliśmy go w narzędzia umożliwiające dostęp do informacji w czasie rzeczywistym, a nawet generowanie własnego awatara. Możesz teraz tworzyć jeszcze bardziej złożone i zaawansowane agenty AI.
👉💻 Aby zakończyć sesję, wróć do terminala i zamknij interfejs Antigravity CLI, wpisując /exit w prompcie agy:
/exit