Tworzenie pierwszego towarzysza AI: warsztaty dla początkujących

1. Czego się nauczysz

  • Jak używać interfejsu wiersza poleceń Gemini do generowania pełnej konfiguracji agenta ADK.
  • Jak wzbogacić osobowość agenta, ulepszając jego instrukcje.
  • Jak dodać do agenta „powiązanie ze źródłem informacji”, aby mógł odpowiadać na pytania dotyczące ostatnich wydarzeń.google_search
  • Jak wygenerować niestandardowego awatara towarzysza za pomocą serwera MCP z Imagen.

Aplikacja AI Companion

W tym ćwiczeniu z programowania stworzysz wizualnego, interaktywnego towarzysza opartego na AI. To coś więcej niż zwykły czatbot, który przetwarza tekst na 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 powtórzyć 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 dostosowywania, przekształcając tę prostą marionetkę w wyjątkowego i wszechstronnego towarzysza. Będziesz:

  • Nadanie mu podstawowej inteligencji za pomocą pakietu 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 utworzysz samodzielnie.

Architektura

Nasza aplikacja opiera się na prostym, ale skutecznym wzorcu. 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.

Oprócz tego przyjrzymy się bardziej zaawansowanej koncepcji, uruchamiając lokalny serwer MCP (Model Context Protocol). Ten serwer działa jako specjalistyczne narzędzie do generowania obrazów. Następnie użyjemy interfejsu wiersza poleceń Gemini, aby wydać polecenie serwerowi MCP, nakazując mu wygenerowanie unikalnego wyglądu towarzysza AI.

Odbierz środki

Aby udostępnić zasoby warsztatowe, postępuj zgodnie z tymi instrukcjami.

Zanim zaczniesz

OSTRZEŻENIE!

  • korzystasz z osobistego konta Gmail. Nie będą działać konta firmowe ani konta zarządzane przez szkołę.
  • Używaj Google Chrome w trybie incognito, aby uniknąć konfliktów między kontami.

Otwórz nowe okno incognito, wklej link do wydarzenia i zaloguj się za pomocą osobistego konta Gmail.

👉 Kliknij poniżej, aby skopiować link do wydarzenia specjalnego:

goo.gle/devfest-boston-ai

Zaakceptuj Warunki korzystania z usługi Google Cloud Platform. Gdy to zrobisz, zobaczysz komunikat informujący o zastosowaniu środków.

Tworzenie i konfigurowanie projektu

Po zastosowaniu środków skonfiguruj środowisko projektu.

👉 Otwórz konsolę Google Cloud. Aby skopiować link, kliknij poniżej:

https://console.cloud.google.com/

👉 Na pasku nawigacyjnym u góry konsoli kliknij Wybierz projekt, a potem w prawym górnym rogu kliknij Nowy projekt.

👉 Nadaj projektowi nazwę i kliknij Utwórz. (Brak organizacji)

👉 Po utworzeniu wybierz ją. W menu po lewej stronie kliknij Płatności.

👉 Kliknij Połącz konto rozliczeniowe, w menu wybierz Próbne konto rozliczeniowe Google Cloud Platform i kliknij Ustaw konto. (Jeśli nie widzisz menu, poczekaj minutę, aż środki zostaną zastosowane, i odśwież stronę).

Twoje środki są aktywne, a projekt jest skonfigurowany.

2. Zanim zaczniesz

👉 U góry konsoli Google Cloud kliknij Aktywuj Cloud Shell (jest to ikona terminala u góry panelu Cloud Shell).

👉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 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

👉💻 Aby włączyć niezbędne interfejsy Google Cloud API, uruchom to polecenie:

gcloud services enable  compute.googleapis.com \
                        aiplatform.googleapis.com

Uruchom aplikację

Uruchommy projekt startowy. Ta początkowa wersja to prosty serwer „echo” – nie ma żadnej inteligencji i tylko powtarza to, co do niego wyślesz.

👉💻 W terminalu Cloud Shell utwórz i aktywuj wirtualne środowisko Pythona oraz zainstaluj wymagane biblioteki z pliku requirements.txt.

cd ~/companion-python
.  ~/companion-python/set_env.sh
python -m venv env
source env/bin/activate
pip install -r requirements.txt

👉💻 Uruchom serwer WWW.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 Aby zobaczyć aplikację, kliknij ikonę podglądu 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 Twojej witryny.

Czasami w nowym środowisku Cloud Shell przeglądarka może potrzebować pomocy przy pierwszym wczytywaniu wszystkich zasobów aplikacji (takich jak obrazy i biblioteki audio). Wykonajmy szybki krok, aby „przygotować przeglądarkę” i upewnić się, że wszystko jest prawidłowo załadowane.

  1. Nie zamykaj karty podglądu w przeglądarce.
  2. Otwórz nową kartę przeglądarki.
  3. Na nowej karcie wklej adres URL aplikacji, ale na końcu dodaj ścieżkę: /static/images/char-mouth-open.png.Adres URL będzie wyglądać na przykład tak: https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png
  4. Naciśnij Enter. Powinien pojawić się tylko obraz postaci z otwartymi ustami. Dzięki temu będziesz mieć pewność, że przeglądarka prawidłowo pobrała pliki z instancji Cloud Shell.

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.

👉 Aby zatrzymać serwer, naciśnij CTRL+C.

3. Tworzenie postaci za pomocą interfejsu wiersza poleceń Gemini

Teraz utwórzmy podstawę inteligencji towarzysza. W tym celu będziemy pracować jednocześnie w 2 terminalach (to jest terminal Google Cloud Shell):

  • Terminal 1: będzie używany do uruchamiania serwera WWW w Pythonie, co pozwoli nam testować zmiany na żywo.
  • Terminal 2: będzie to nasze „stanowisko tworzenia”, na którym będziemy korzystać z interfejsu wiersza poleceń Gemini.

Użyjemy interfejsu wiersza poleceń Gemini, czyli zaawansowanego interfejsu wiersza poleceń, który działa jako asystent AI do kodowania. Umożliwia opisanie w prostym języku angielskim kodu, którego potrzebujemy, a następnie wygenerowanie struktury, co znacznie przyspiesza proces tworzenia.

👉💻 W terminalu interfejsu wiersza poleceń Geminizakończ bieżącą sesję interfejsu wiersza poleceń Gemini, klikając dwukrotnie ctrl+c, ponieważ katalog projektu znajduje się w ~/companion-python, i uruchom ponownie interfejs wiersza poleceń Gemini.

cd ~/companion-python
clear
gemini --yolo

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ębną jednostkę, która 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 prompcie interfejsu wiersza poleceń Gemini wklej ten tekst, 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-2.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 w Pythonie.

👉 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-2.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 możesz zauważyć różnice w komentarzach, odstępach, a nawet w nazwach zmiennych tymczasowych. Jednak podstawowa logika i struktura powinny być funkcjonalnie identyczne z tym, o co prosisz.

Dlatego kodowanie z użyciem AI rzadko jest poleceniem jednorazowym. W prawdziwym projekcie programiści traktują to 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 refaktoryzować 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 użyjemy konkretnych, bezpośrednich promptów, ale pamiętaj, że w Twoich projektach prawdziwa siła tkwi w rozmowie. 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-2.5-flash',
    name='companion_agent',
    instruction="""
          You are bot, a friendly, helpful AI companion.
          Answer no more than 3 sentences.
    """,
)

Testowanie wygenerowanego kodu:

👉💻 Przejdź do pierwszego terminala (tego, w którym uruchamiasz kod Pythona) i uruchom serwer WWW.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 Otwórz kartę podglądu w przeglądarce.

👉 Wpisz 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.

👉 Po zakończeniu testowania zatrzymaj serwer za pomocą symbolu CTRL+C. Aby wyjść z interfejsu wiersza poleceń Gemini, w terminalu, w którym jest uruchomiony interfejs wiersza poleceń Gemini, naciśnij dwukrotnie CTRL+C.

4. Ulepszanie profilu agenta

Prosta instrukcja jest dobra, ale szczegółowa charakterystyka postaci pozwala stworzyć znacznie bardziej angażującą i zapamiętywalną postać. W tym kroku zaprojektujesz osobowość swojego towarzysza, a następnie poprosisz interfejs wiersza poleceń Gemini o bezpośrednie zmodyfikowanie 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)
  • Jaka jest jego podstawowa osobowość? (np. przyjazny i ciekawy, dowcipny i sarkastyczny, formalny i profesjonalny, wesoły pirat)
  • Jaką rolę pełni lub w czym się specjalizuje? (np.asystent ogólnego przeznaczenia, ekspert od kodowania, partner do kreatywnego pisania, trener fitness).
  • Jakich zasad powinien zawsze przestrzegać? (np. „Zawsze zaczynaj od powitania”, „Nigdy nie ujawniaj, że jesteś AI”, „Używaj emoji w odpowiedziach”).

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 prompta dla interfejsu wiersza poleceń Gemini

Teraz, gdy masz już zaprojektowaną osobowość 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 ton głosu, 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 wiersza poleceń Gemini 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 wiersza poleceń Gemini wygeneruje zaktualizowany kod dla character.py.

👉💻 Ponownie uruchom serwer WWW.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 W podglądzie w przeglądarce porozmawiaj z towarzyszem. Zapytaj how are you?. Jego odpowiedź powinna teraz idealnie pasować do zaprojektowanej przez Ciebie unikalnej postaci.

👉 Gdy skończysz, zatrzymaj serwer za pomocą polecenia CTRL+C.

5. Dodawanie oparcia na faktach dla niedawnych 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 przekazać informacji 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 do kalendarza może sprawdzić Twój harmonogram. Narzędzie to konkretna funkcja lub interfejs API, z którego agent może inteligentnie korzystać, gdy stwierdzi, że jego własna wiedza nie wystarcza do udzielenia odpowiedzi na prośbę użytkownika.

W zaawansowanych systemach narzędzia mogą być dostarczane przez systemy zewnętrzne, takie jak serwery MCP (Model Context Protocol), o których wspomnieliśmy w naszej architekturze. Zrobimy to później w przypadku generowania obrazów. Na tym etapie nie potrzebujemy jednak osobnego serwera. ADK zawiera zaawansowane, gotowe google_search narzędzie, które możemy łatwo dodać do możliwości naszego agenta.

Dajmy naszemu towarzyszowi moc wyszukiwarki Google.

👉 W edytorze Cloud Shell otwórz plik character.py w katalogu companion-python i zmień go w ten sposób:

  • Importuj google_search z usługi google.adk.tools.
  • Dodaj toolslistę do konstruktora LlmAgent.
  • Zaktualizuj instruction, aby wyraźnie określić, kiedy ma używać nowego narzędzia.
# character.py
import logging
import os
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools import google_search # <-- IMPORT google_search

root_agent = LlmAgent(
        model='gemini-2.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.
            """,
        # Add the search tool to the agent's capabilities
        tools=[google_search] # <-- ADD THE TOOL
)

Testowanie agenta z dostępem do informacji

👉💻 Uruchom serwer jeszcze raz.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👉 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 korzystać z narzędzia wyszukiwania, aby znaleźć aktualne informacje i przedstawić przydatne, oparte na faktach podsumowanie własnym, niepowtarzalnym głosem.

Aby zatrzymać serwer, kliknij CTRL+C.

6. Dostosowywanie wyglądu towarzysza (opcjonalnie)

Teraz, gdy nasz towarzysz ma już mózg, nadajmy mu wyjątkową twarz. Użyjemy lokalnego serwera MCP (Model Context Protocol), który umożliwia interfejsowi wiersza poleceń Gemini generowanie obrazów. Ten serwer będzie korzystać z modeli generatywnej AI dostępnych w Google AI Studio.

Czym właściwie jest serwer MCP?

Protokół Model Context Protocol (MCP) to otwarty standard opracowany w celu rozwiązania powszechnego i złożonego problemu: jak modele AI komunikują się z zewnętrznymi narzędziami i źródłami danych? Zamiast pisać niestandardowy, jednorazowy kod dla każdej integracji, MCP zapewnia uniwersalny „język” do tej komunikacji.

Można go traktować jako uniwersalny adapter lub port USB dla AI. Każde narzędzie, które „rozmawia” w MCP, może połączyć się z dowolną aplikacją AI, która również „rozmawia” w MCP.

W naszych warsztatach serwer nano-banana-mcp, który za chwilę uruchomimy, będzie pełnić rolę tego kluczowego pomostu. Interfejs wiersza poleceń Gemini wyśle standardową prośbę do naszego lokalnego serwera MCP. Serwer tłumaczy to żądanie na konkretne wywołanie modeli generatywnej AI w celu utworzenia obrazu. Dzięki temu możemy łatwo włączyć zaawansowane funkcje generowania obrazów bezpośrednio do naszego przepływu pracy w wierszu poleceń.

Konfigurowanie lokalnego serwera generowania obrazów

Teraz sklonujemy i uruchomimy gotowy serwer MCP, który obsługuje żądania generowania obrazów.

👉💻 W pierwszym terminalu Cloud Shell (tym, w którym uruchamiasz Pythona) sklonuj repozytorium serwera.

cd ~
git clone https://github.com/weimeilin79/nano-banana-mcp

Przyjrzyjmy się szybko plikowi mcp_server.py server w folderze nano-banana-mcp. Ten serwer został utworzony w celu udostępniania 2 konkretnych „narzędzi”, z których może korzystać interfejs wiersza poleceń Gemini. Możesz je traktować jako 2 różne umiejętności, których nauczyła się nasza usługa generowania obrazów.

  1. generate_image: jest to narzędzie do zwykłych obciążeń. Przyjmuje 1 prompt tekstowy i na jego podstawie generuje 1 obraz. Jest proste i przydatne w wielu zadaniach.
  2. generate_lip_sync_images: Jest to wysoce wyspecjalizowane narzędzie, które idealnie odpowiada naszym potrzebom. Gdy podasz mu prompta podstawowego opisującego postać, wykona on sprytny proces dwuetapowy:
    • Najpierw dodaje do prompta słowa „z otwartymi ustami” i generuje pierwszy obraz.
    • Po drugie, bierze nowo utworzony obraz i wysyła go z powrotem do modelu z nową instrukcją: „zmień otwarte usta na zamknięte”.

Możliwość zmiany lub edytowania istniejącego obrazu przez Gemini 2.5 Flash Image (Nano Banana) na podstawie polecenia w języku naturalnym jest niezwykle przydatna. Model przerysowuje tylko niezbędne części obrazu, zachowując resztę w nienaruszonym stanie. Dzięki temu oba obrazy są całkowicie spójne pod względem stylu, oświetlenia i projektu postaci, a różnią się tylko położeniem ust, co jest dokładnie tym, czego potrzebujemy, aby uzyskać przekonujący efekt synchronizacji ruchu ust z dźwiękiem.

W poniższych krokach użyjemy interfejsu wiersza poleceń Gemini, aby za pomocą specjalistycznego narzędzia generate_lip_sync_images utworzyć unikalny awatar towarzysza.

👉💻 Aktywuj środowisko wirtualne projektu i zainstaluj wymagania serwera.

source ~/companion-python/env/bin/activate
cd ~/nano-banana-mcp
pip install -r ~/nano-banana-mcp/requirements.txt

👉💻 Teraz uruchom serwer MCP w tle, aby mógł nasłuchiwać żądań z interfejsu wiersza poleceń Gemini.

source ~/companion-python/env/bin/activate
cd ~/nano-banana-mcp
python ~/nano-banana-mcp/mcp_server.py &> /dev/null &

To polecenie uruchomi serwer, a symbol & utrzyma go w tle.

Następnie musimy skonfigurować interfejs wiersza poleceń Gemini, aby wysyłać żądania generowania obrazów do nowo uruchomionego serwera lokalnego. Aby to zrobić, zmodyfikujemy centralny plik konfiguracji interfejsu CLI.

Czym jest plik settings.json?

Plik ~/.gemini/settings.json to centralny plik konfiguracyjny interfejsu wiersza poleceń Gemini. To w nim CLI przechowuje ustawienia, preferencje i katalog wszystkich zewnętrznych narzędzi, z których potrafi korzystać.

W tym pliku znajduje się specjalna sekcja o nazwie mcpServers. Ta sekcja to książka adresowa lub katalog usług przeznaczony specjalnie dla narzędzi, które korzystają z protokołu Model Context Protocol. Każdy wpis w tym katalogu ma pseudonim (np. „nano-banana”) i instrukcje dotyczące sposobu połączenia się z nim (w naszym przypadku jest to adres URL).

Polecenie, które za chwilę uruchomimy, programowo doda nowy wpis do tego katalogu usług. Poinformuje interfejs wiersza poleceń Gemini o tym, że:

„Od teraz wiesz o narzędziu o nazwie nano-banana. Za każdym razem, gdy użytkownik poprosi Cię o jego użycie, musisz połączyć się z serwerem MCP działającym pod adresem URL http://localhost:8000/sse”.

Modyfikując tę konfigurację, zwiększamy możliwości interfejsu wiersza poleceń Gemini. Dynamicznie uczymy go nowej umiejętności – komunikowania się z naszym lokalnym serwerem generowania obrazów – bez modyfikowania podstawowego kodu interfejsu wiersza poleceń. Ta rozszerzalna architektura umożliwia interfejsowi wiersza poleceń Gemini koordynowanie złożonych zadań poprzez wywoływanie całego ekosystemu specjalistycznych narzędzi.

👉💻 W pierwszym terminalu uruchom to polecenie: Utworzy lub zaktualizuje plik ustawień Gemini, informując go, gdzie znaleźć usługę „nano-banana”.

if [ ! -f ~/.gemini/settings.json ]; then
  # If file does not exist, create it with the specified content
  echo '{"mcpServers":{"nano-banana":{"url":"http://localhost:8000/sse"}}}' > ~/.gemini/settings.json
else
  # If file exists, merge the new data into it
  jq '. * {"mcpServers":{"nano-banana":{"url":"http://localhost:8000/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
fi &&
cat ~/.gemini/settings.json

Powinna się wyświetlić zawartość pliku, w tym konfiguracja nano-banana.

Generowanie awatarów postaci

Po uruchomieniu serwera i skonfigurowaniu interfejsu wiersza poleceń możesz wygenerować obrazy. Zanim jednak poprosimy AI o kreatywność, zróbmy to, co robi każdy dobry deweloper: sprawdźmy konfigurację. Musimy potwierdzić, że interfejs wiersza poleceń Gemini może komunikować się z naszym lokalnym serwerem MCP.

👉💻 Wróć do terminala interfejsu wiersza poleceń Gemini (tego, na którym nie działa serwer) i uruchom interaktywną powłokę Gemini. Jeśli jest już uruchomiona, zamknij ją, naciskając dwukrotnie CTRL+C, i uruchom ponownie, aby mieć pewność, że wczytane zostaną nowe ustawienia.

clear
gemini --yolo

Znajdujesz się teraz w interaktywnym środowisku interfejsu wiersza poleceń Gemini. Możesz tu rozmawiać z AI, ale też wydawać bezpośrednie polecenia interfejsowi CLI.

👉✨ Aby sprawdzić, czy nasz serwer MCP jest połączony, użyjemy specjalnego „polecenia po ukośniku”. Nie jest to prompt dla AI, tylko instrukcja dla aplikacji CLI. Wpisz poniższy tekst i naciśnij Enter:

/mcp list

To polecenie informuje interfejs wiersza poleceń Gemini: „Przejrzyj swoją konfigurację, znajdź wszystkie znane Ci serwery MCP, spróbuj połączyć się z każdym z nich i zgłoś ich stan”.

👀 Powinny się wyświetlić te dane wyjściowe, które potwierdzają, że wszystko działa prawidłowo:

Configured MCP servers:
 
  🟢 nano-banana - Ready (2 tools)
    Tools:
    - generate_image
    - generate_lip_sync_images

  💡 Tips:
    • Use /mcp desc to show server and tool descriptions

Zobaczmy, co oznacza ta odpowiedź:

  • 🟢 nano-banana: zielone kółko to sygnał sukcesu. Potwierdza to, że interfejs wiersza poleceń mógł połączyć się z serwerem nano-banana pod adresem URL określonym w settings.json.
  • - Ready: ten stan potwierdza, że połączenie jest stabilne.
  • (2 tools): To najważniejsza część. Oznacza to, że interfejs CLI nie tylko się połączył, ale też zapytał nasz serwer MCP: „Co potrafisz?”. Nasz serwer odpowiedział, rozgłaszając 2 narzędzia, które widzieliśmy w jego kodzie: generate_image i generate_lip_sync_images.

Potwierdza to, że cały łańcuch komunikacji został utworzony. Interfejs CLI zna już naszą lokalną usługę generowania obrazów i jest gotowy do użycia na nasze polecenie.

A teraz czas na najbardziej kreatywną część warsztatów. Użyjemy jednego, zaawansowanego prompta, aby polecić interfejsowi wiersza poleceń Gemini użycie specjalnego narzędzia generate_lip_sync_images na działającym serwerze MCP.

To Twoja szansa na zaprojektowanie niepowtarzalnego wyglądu towarzysza. Zastanów się nad stylem, kolorem włosów, wyrazem twarzy i innymi szczegółami, które pasują do stworzonej wcześniej persony.

👉✨ Oto dobrze skonstruowany przykładowy prompt. Możesz użyć go jako punktu początkowego lub całkowicie zastąpić część opisową własną wizją.

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 itp.) i zapisze je. Wyświetli ścieżki do miejsc, w których zostały zapisane pliki.

Ponowne uruchomienie aplikacji

Po utworzeniu niestandardowych awatarów możesz ponownie uruchomić serwer WWW, aby zobaczyć nowy wygląd postaci.

👉💻 Uruchom serwer po raz ostatni w pierwszym terminalu.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 Aby mieć pewność, że nowe obrazy wczytują się prawidłowo, wczytamy char-mouth-open.png obraz z wyprzedzeniem.

  1. Nie zamykaj karty podglądu w przeglądarce.
  2. Otwórz nową kartę przeglądarki.
  3. Na nowej karcie wklej adres URL aplikacji, ale na końcu dodaj ścieżkę: /static/images/char-mouth-open.png.Adres URL będzie wyglądać na przykład tak: https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png
  4. Naciśnij Enter. Powinien być widoczny tylko obraz postaci z otwartymi ustami. Dzięki temu będziesz mieć pewność, że przeglądarka prawidłowo pobrała pliki z instancji Cloud Shell.

Możesz teraz wchodzić w interakcję ze swoim wizualnie dostosowanym towarzyszem.

Gratulacje!

Udało Ci się stworzyć zaawansowanego towarzysza AI. Zaczęliśmy od prostej aplikacji, użyliśmy interfejsu wiersza poleceń Gemini 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żonych i zaawansowanych agentów AI.