Ersten KI-Begleiter erstellen: Workshop für Anfänger

1. Lerninhalte

  • So verwenden Sie die Gemini-Befehlszeile, um eine vollständige ADK-Agent-Konfiguration zu generieren.
  • So verbessern Sie die Persönlichkeit eines Agenten, indem Sie seine Anweisungen optimieren.
  • So fügen Sie Ihrem Agenten eine „Fundierung“ hinzu, indem Sie ihm google_search geben, um Fragen zu aktuellen Ereignissen zu beantworten.
  • So generieren Sie einen benutzerdefinierten Avatar für Ihren Companion mithilfe eines MCP-Servers mit Imagen.

Die AI Companion App

In diesem Codelab erstellen Sie einen visuellen, interaktiven KI-Assistenten. Es handelt sich um mehr als nur einen Standard-Chatbot, bei dem Text eingegeben und Text ausgegeben wird. Stellen Sie sich eine Figur vor, die auf einer Webseite lebt. Sie geben eine Nachricht ein und anstatt nur Text zurückzubekommen, schaut Sie die Figur an und antwortet laut, wobei sich ihr Mund synchron zu ihren Worten bewegt.

Sie beginnen mit einer vorgefertigten Webanwendung – einer digitalen „Puppe“ mit einem Gesicht, aber ohne eigenen Verstand. Es kann nur wiederholen, was Sie eingeben. Ihre Aufgabe ist es, das Gehirn und die Persönlichkeit von Grund auf neu zu entwickeln.

Im Laufe dieses Workshops fügen Sie nach und nach Ebenen von Intelligenz und Anpassung hinzu und verwandeln diese einfache Puppe in einen einzigartigen und leistungsfähigen Begleiter. Sie werden:

  • Kernintelligenz mit dem ADK(Python) bereitstellen, um Sprache zu verstehen und zu generieren.
  • Eigene Persönlichkeit entwickeln: Sie schreiben die Kernanweisungen, die den Charakter definieren.
  • Superkräfte verleihen, indem Sie ihm Tools zur Verfügung stellen, mit denen es auf Echtzeitinformationen aus dem Internet zugreifen kann.
  • Ein individuelles Aussehen entwerfen: Mithilfe von KI können Sie einen einzigartigen Avatar erstellen.

Am Ende haben Sie einen voll funktionsfähigen und personalisierten KI-Begleiter erstellt.

Architektur

Unsere Anwendung folgt einem einfachen, aber leistungsstarken Muster. Wir haben ein Python-Backend, das eine API bereitstellt. Dieses Backend enthält unseren ADK-Agenten, der als „Gehirn“ fungiert. Jede Benutzeroberfläche (z. B. das JavaScript-Frontend der Skeleton-App, eine mobile App oder sogar ein Befehlszeilentool) kann dann über die API mit diesem Brain interagieren.

Außerdem werden wir ein komplexeres Konzept kennenlernen, indem wir einen lokalen MCP-Server (Model Context Protocol) starten. Dieser Server dient als spezielle Tool-Bridge für die Bildgenerierung. Anschließend verwenden wir die Gemini CLI, um diesen MCP-Server anzuweisen, ein einzigartiges Aussehen für unseren KI-Begleiter zu generieren.

Guthaben sichern

Folgen Sie dieser Anleitung sorgfältig, um Ihre Workshop-Ressourcen bereitzustellen.

Vorbereitung

ACHTUNG!

  • Sie verwenden ein privates Gmail-Konto. Konten, die von Unternehmen oder Bildungseinrichtungen verwaltet werden, funktionieren NICHT.
  • Verwenden Sie Google Chrome im Inkognitomodus, um Konflikte mit Konten zu vermeiden.

Öffnen Sie ein neues Inkognitofenster, fügen Sie den Veranstaltungslink ein und melden Sie sich mit Ihrem privaten Gmail-Konto an.

👉 Klicke unten, um den Link für das Special Event zu kopieren:

goo.gle/devfest-boston-ai

Akzeptieren Sie die Nutzungsbedingungen für die Google Cloud Platform. Nachdem das Guthaben angewendet wurde, wird eine entsprechende Meldung angezeigt.

Projekt erstellen und konfigurieren

Nachdem Ihre Guthabenpunkte angewendet wurden, richten Sie Ihre Projektumgebung ein.

👉 Google Cloud Console aufrufen Klicken Sie unten, um den Link zu kopieren:

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

👉 Klicken Sie in der oberen Navigationsleiste der Console auf Projekt auswählen und dann oben rechts auf Neues Projekt.

👉 Geben Sie Ihrem Projekt einen Namen und klicken Sie auf Erstellen. (Keine Organisation)

👉 Wählen Sie die erstellte Vorlage aus. Klicken Sie im Menü links auf Abrechnung.

👉 Klicken Sie auf Rechnungskonto verknüpfen, wählen Sie im Drop-down-Menü das Google Cloud Platform-Testrechnungskonto aus und klicken Sie auf Konto festlegen. Wenn das Drop-down-Menü nicht angezeigt wird, warten Sie eine Minute, bis die Gutschrift angewendet wurde, und laden Sie die Seite neu.

Ihre Guthaben sind aktiv und Ihr Projekt ist konfiguriert.

2. Hinweis

👉 Klicken Sie oben in der Google Cloud Console auf „Cloud Shell aktivieren“ (das Symbol oben im Cloud Shell-Bereich hat die Form eines Terminals), .

👉 Google Cloud-Projekt-ID suchen:

  • Öffnen Sie die Google Cloud Console: https://console.cloud.google.com.
  • Wählen Sie oben auf der Seite im Drop-down-Menü das Projekt aus, das Sie für diesen Workshop verwenden möchten.
  • Ihre Projekt-ID wird im Dashboard  auf der Karte „Projektinformationen“ angezeigt.

👉💻 Klonen Sie im Terminal das Bootstrap-Projekt von GitHub:

git clone https://github.com/weimeilin79/companion-python
chmod +x ~/companion-python/*.sh

👉💻 Führen Sie das Initialisierungsskript aus. Sie werden aufgefordert, Ihre Google Cloud-Projekt-ID einzugeben. Geben Sie die Google Cloud-Projekt-ID ein, die Sie im letzten Schritt gefunden haben, wenn Sie vom init.sh-Script dazu aufgefordert werden.

cd ~/companion-python
./init.sh

👉💻 Legen Sie die erforderliche Projekt-ID fest:

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

👉💻 Führen Sie den folgenden Befehl aus, um die erforderlichen Google Cloud APIs zu aktivieren:

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

App starten

Lassen Sie uns das Startprojekt ausführen. Diese erste Version ist ein einfacher „Echo“-Server – sie hat keine Intelligenz und wiederholt nur, was Sie ihr senden.

👉💻 Erstellen und aktivieren Sie in Ihrem Cloud Shell-Terminal eine virtuelle Python-Umgebung und installieren Sie die erforderlichen Bibliotheken aus der Datei requirements.txt.

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

👉💻 Starten Sie den Webserver.

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

👀 Klicken Sie in der Cloud Shell-Symbolleiste auf das Symbol für die Webvorschau, um die App aufzurufen. Wählen Sie „Port ändern“ aus, legen Sie den Port auf 5000 fest und klicken Sie auf „Ändern und Vorschau“. Eine Vorschau Ihrer Website wird angezeigt.

Manchmal benötigt der Browser in einer neuen Cloud Shell-Umgebung etwas Unterstützung, um alle Assets der Anwendung (z. B. Bilder und Audiobibliotheken) zum ersten Mal zu laden. Wir führen einen kurzen Schritt aus, um den Browser vorzubereiten und sicherzustellen, dass alles richtig geladen wird.

  1. Lassen Sie den Tab mit der Webvorschau für Ihre Anwendung geöffnet.
  2. Öffnen Sie einen neuen Browsertab.
  3. Fügen Sie auf diesem neuen Tab die URL Ihrer Anwendung ein, aber hängen Sie den folgenden Pfad an: /static/images/char-mouth-open.png.Ihre URL sieht dann etwa so aus: https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png
  4. Drücken Sie die Eingabetaste. Sie sollten nur das Bild der Figur mit offenem Mund sehen. So wird sichergestellt, dass Ihr Browser die Dateien korrekt von Ihrer Cloud Shell-Instanz abgerufen hat.

Die ursprüngliche Anwendung ist nur eine Marionette. Es ist noch nicht intelligent. Egal, welche Nachricht Sie senden, sie wird einfach wiederholt. So können wir sichergehen, dass unser einfacher Webserver funktioniert, bevor wir die KI hinzufügen. Denke daran, den Lautsprecher einzuschalten.

👉 Drücken Sie CTRL+C, um den Server zu beenden.

3. Charakter mit der Gemini-Befehlszeile erstellen

Jetzt erstellen wir den Kern der KI unseres Begleiters. Dazu arbeiten wir gleichzeitig mit zwei Terminals (dies ist Ihr Google Cloud Shell-Terminal):

  • Terminal 1:Hier wird unser Python-Webserver ausgeführt, damit wir unsere Änderungen live testen können.
  • Terminal 2:Hier interagieren wir mit der Gemini CLI.

Wir verwenden die Gemini CLI, eine leistungsstarke Befehlszeile, die als KI-basierter Programmierassistent fungiert. Wir können den gewünschten Code in einfachem Deutsch beschreiben und das Tool generiert die Struktur für uns. Das beschleunigt die Entwicklung erheblich.

👉💻 Beenden Sie im Gemini CLI-Terminal die aktuelle Gemini CLI-Sitzung mit exit, indem Sie zweimal auf ctrl+c klicken, da sich unser Projektverzeichnis unter ~/companion-python befindet, und starten Sie die Gemini CLI neu.

cd ~/companion-python
clear
gemini --yolo

Wir verwenden die CLI, um einen Agent zu erstellen. Ein Agent ist mehr als nur ein einfacher Aufruf eines Sprachmodells. Er ist das „Gehirn“ oder die zentrale Steuerung unserer KI. Stellen Sie sich das als eigenständige Einheit vor, die denken, einer bestimmten Reihe von Anweisungen (ihrer Persönlichkeit) folgen und schließlich Tools verwenden kann, um Aufgaben zu erledigen. In unserem Projekt ist dieser Agent die Komponente, die Nutzernachrichten empfängt, die einzigartige Persönlichkeit unseres Begleiters verkörpert und intelligente, charakteristische Antworten formuliert.

👉✨ Fügen Sie im Gemini CLI-Prompt Folgendes ein, um den Code des Agents zu generieren:

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".

Die CLI generiert den Python-Code.

👉 Klicken Sie auf die Schaltfläche „Editor öffnen“ (sie sieht aus wie ein geöffneter Ordner mit einem Stift). Dadurch wird der Cloud Shell-Codeeditor im Fenster geöffnet. Auf der linken Seite sehen Sie einen Datei-Explorer.

👉 Öffnen Sie den Editor und rufen Sie im Ordner companion-python die Datei character.py auf. Prüfen Sie die Zeile model= und bearbeiten Sie sie manuell zu gemini-2.5-flash, wenn ein anderes Modell ausgewählt wurde. So sorgen wir für Konsistenz im weiteren Verlauf des Workshops.

Hinweis: Large Language Models können nicht deterministisch sein. Dies ist ein wichtiges Konzept bei der KI-gestützten Entwicklung. „Nicht deterministisch“ bedeutet, dass das Modell selbst bei genau demselben Prompt jedes Mal leicht unterschiedliche Ergebnisse liefern kann. Der Code wird kreativ generiert. Daher kann es zu Abweichungen bei Kommentaren, Abständen oder sogar bei der Benennung temporärer Variablen kommen. Die Kernlogik und ‑struktur sollten jedoch funktional identisch mit dem sein, was angefordert wurde.

Deshalb ist das Programmieren mit einer KI selten ein einmaliger Befehl. In einem realen Projekt behandeln Entwickler es wie ein Gespräch. Sie beginnen mit einer allgemeinen Anfrage (wie gerade geschehen), prüfen die Ausgabe und verfeinern sie dann mit Folgeprompts wie:

  • „Das ist toll. Füge jetzt Kommentare hinzu, in denen jede Zeile erklärt wird.“
  • „Can you refactor that into a separate function?“ (Kannst du das in eine separate Funktion umgestalten?)
  • „Bitte füge eine Fehlerbehandlung für den API-Aufruf hinzu.“

Dieser iterative, dialogorientierte Prozess ermöglicht es Ihnen, mit der KI zusammenzuarbeiten und sie so zu steuern, bis der Code genau Ihren Anforderungen entspricht. In diesem Workshop verwenden wir spezifische, direkte Prompts. Denken Sie aber daran, dass in Ihren eigenen Projekten die Unterhaltung die eigentliche Stärke ist. Solange die von der CLI generierte Codestruktur gleich ist, können Sie fortfahren.

Wenn der generierte Code nicht funktioniert, können Sie den folgenden Code durch Ihren character.py ersetzen.

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.
    """,
)

Generierten Code testen:

👉💻 Wechseln Sie zum ersten Terminal (das zum Ausführen von Python-Code), und starten Sie den Webserver.

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

👀 Rufen Sie den Tab „Webvorschau“ auf.

👉 Geben Sie Hello, how are you? ein und drücken Sie auf „Senden“. Der Agent sollte jetzt mit einer freundlichen Begrüßung antworten, anstatt nur Ihre Worte zu wiederholen. Das bestätigt, dass unser Agent jetzt auf Gemini basiert.

👉 Wenn Sie mit dem Testen fertig sind, beenden Sie den Server mit CTRL+C. Um die Gemini-Befehlszeile zu beenden, geben Sie im Terminal, in dem die Gemini-Befehlszeile ausgeführt wird, zweimal CTRL+C ein.

4. Persönlichkeit des Agents verbessern

Eine einfache Anweisung ist gut, aber eine detaillierte Persona führt zu einer viel ansprechenderen und einprägsameren Figur. In diesem Schritt entwerfen Sie die Persönlichkeit Ihres Begleiters und weisen dann die Gemini CLI an, den Code des Agents direkt zu ändern, um diese neue Persönlichkeit anzunehmen.

Persona Ihres Begleiters entwickeln

Nehmen Sie sich zuerst einen Moment Zeit, um über den KI-Begleiter nachzudenken, den Sie erstellen möchten. Hier können Sie kreativ werden. Hier sind einige Fragen, die Ihnen den Einstieg erleichtern:

  • Wie heißt es? (z. B. mit der Sparky, Codex, Captain AI, Professor Know-it-all)
  • Was ist die Kernpersönlichkeit? (z. B. mit der Freundlich und neugierig, witzig und sarkastisch, formell und professionell, ein fröhlicher Pirat?)
  • Welche Rolle oder Expertise hat die Person? (z. B. mit der Ein Allzweck-Assistent, ein Programmierexperte, ein Partner für kreatives Schreiben oder ein Fitnesscoach?
  • Welche Regeln sollte sie immer befolgen? (z. B. mit der „Beginne immer mit einer Begrüßung“, „Gib niemals an, dass du eine KI bist“, „Verwende Emojis in deinen Antworten“

Beispiel-Persona:

 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.

Prompt für die Gemini CLI erstellen

Nachdem Sie die Persönlichkeit Ihres Begleiters auf Papier entworfen haben, ist es an der Zeit, sie im Code zum Leben zu erwecken. Der wichtigste Teil eines ADK-Agents ist der Parameter instruction. Stellen Sie sich das als die Kernprogrammierung des Agenten vor, seine „oberste Direktive“ oder die Verfassung, die er immer befolgen muss.

Diese Anleitung ist der Schlüssel zur Steuerung des Verhaltens des Agenten. Es ist nicht nur ein Vorschlag, sondern der grundlegende Kontext, auf den sich die KI vor jeder einzelnen Interaktion mit dem Nutzer bezieht. Sie bestimmt die Persönlichkeit des Kundenservicemitarbeiters, seinen Tonfall, die Regeln, die er befolgen muss, und wie er sich präsentieren soll. Eine gut formulierte Anleitung macht den Unterschied zwischen einem generischen Chatbot und einer glaubwürdigen, konsistenten Figur aus. Der Prompt, den wir gleich erstellen, ist daher von entscheidender Bedeutung, da er die Persönlichkeit unseres Agenten direkt beeinflusst.

👉✨ Verwenden Sie diese Vorlage in der Gemini CLI. Ersetzen Sie den Text in Klammern durch die Beschreibung Ihrer Persona. ERSETZEN SIE [YOUR PERSONA DESCRIPTION HERE] durch Ihre bevorzugte Persona.

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]

Neue Persona testen

Die Gemini-Befehlszeile generiert den aktualisierten Code für character.py.

👉💻 Starten Sie den Webserver neu.

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

👀 Führen Sie in der Webvorschau ein Gespräch mit Ihrem Companion. Fragen Sie how are you?. Die Antwort sollte jetzt perfekt zu der von Ihnen entworfenen Figur passen.

👉 Wenn Sie fertig sind, beenden Sie den Server mit CTRL+C.

5. Grundlage für aktuelle Ereignisse hinzufügen

Unser Agent hat jetzt eine Persönlichkeit, aber eine erhebliche Einschränkung: Sein Wissen ist auf dem Stand der Daten, mit denen er trainiert wurde. Es kann Ihnen keine Informationen zu den Nachrichten von gestern oder zu aktuellen Entdeckungen geben. Um dies zu beheben, stellen wir Kundenservicemitarbeitern Tools zur Verfügung.

Stellen Sie sich Tools als Superkräfte oder besondere Fähigkeiten vor, die Sie Ihrem Agenten verleihen. Der Agent kann nur sprechen. Mit einem Suchtool kann es im Internet suchen. Mit einem Kalendertool könnte es Ihren Terminplan prüfen. Ein Tool ist technisch gesehen eine bestimmte Funktion oder API, die der Agent intelligent verwenden kann, wenn er feststellt, dass sein eigenes Wissen nicht ausreicht, um die Anfrage eines Nutzers zu beantworten.

In komplexen Systemen können Tools von externen Systemen wie den MCP-Servern (Model Context Protocol) bereitgestellt werden, die wir in unserer Architektur erwähnt haben. Dies werden wir später für die Bildgenerierung tun. Für diesen Schritt ist jedoch kein separater Server erforderlich. Das ADK enthält ein leistungsstarkes, vordefiniertes google_search-Tool, das wir ganz einfach in die Funktionen unseres Agents einbinden können.

Geben wir unserem Begleiter die Leistungsfähigkeit der Google Suche.

👉 Öffnen Sie im Cloud Shell-Editor character.py unter companion-python und ändern Sie die Datei so:

  • google_search aus google.adk.tools importieren.
  • Fügen Sie dem LlmAgent-Konstruktor eine tools-Liste hinzu.
  • Aktualisieren Sie die instruction, um Ihrem Companion explizit mitzuteilen, wann er das neue Tool verwenden soll.
# 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
)

Grounded Agent testen

👉💻 Starten Sie den Server noch einmal.

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

👉 Stellen Sie in der Webvorschau eine Frage, für die aktuelles Wissen erforderlich ist, z. B.:

Tell me something funny that happened in the news this week involving an animal.

👉 Anstatt zu sagen, dass es etwas nicht weiß, verwendet der Agent jetzt sein Suchtool, um aktuelle Informationen zu finden und eine hilfreiche, fundierte Zusammenfassung in seinem eigenen Stil zu erstellen.

Drücken Sie CTRL+C, um den Server zu beenden.

6. Look Ihres Companion anpassen (optional)

Nachdem unser Companion nun ein Gehirn hat, geben wir ihm ein einzigartiges Gesicht. Wir verwenden einen lokalen MCP-Server (Model Context Protocol), mit dem die Gemini CLI Bilder generieren kann. Auf diesem Server werden die generativen KI-Modelle verwendet, die über Google AI Studio verfügbar sind.

Was genau ist also ein MCP-Server?

Das Model Context Protocol (MCP) ist ein offener Standard, der ein häufiges und komplexes Problem lösen soll: Wie kommunizieren KI-Modelle mit externen Tools und Datenquellen? Anstatt für jede Integration benutzerdefinierten Einmalcode zu schreiben, bietet MCP eine universelle „Sprache“ für diese Kommunikation.

Stellen Sie sich das als universellen Adapter oder USB-Anschluss für KI vor. Jedes Tool, das MCP unterstützt, kann eine Verbindung zu jeder KI-Anwendung herstellen, die ebenfalls MCP unterstützt.

In unserem Workshop fungiert der nano-banana-mcp-Server, den wir gleich ausführen, als diese wichtige Brücke. Die Gemini CLI sendet eine standardisierte Anfrage an unseren lokalen MCP-Server. Der Server übersetzt diese Anfrage dann in einen spezifischen Aufruf an die generativen KI-Modelle, um das Bild zu erstellen. So können wir leistungsstarke Funktionen zur Bildgenerierung direkt in unseren Befehlszeilen-Workflow einbinden.

Lokalen Server für die Bildgenerierung einrichten

Wir klonen und führen jetzt einen vorgefertigten MCP-Server aus, der Anfragen zur Bildgenerierung verarbeitet.

👉💻 Klonen Sie in einem ersten Cloud Shell-Terminal (in dem Sie Python ausführen) das Repository des Servers.

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

Sehen wir uns die Datei „server.mcp_server.py“ im Ordner „nano-banana-mcp“ an. Dieser Server ist so konzipiert, dass er zwei bestimmte „Tools“ bereitstellt, die von der Gemini CLI verwendet werden können. Das sind zwei unterschiedliche Fähigkeiten, die unser Bildgenerierungsdienst gelernt hat.

  1. generate_image:Dies ist ein Allzwecktool. Es wird ein einzelner Text-Prompt verwendet, um ein Bild zu generieren. Sie ist unkompliziert und für viele Aufgaben nützlich.
  2. generate_lip_sync_images:Dieses hochspezialisierte Tool ist perfekt auf unsere Bedürfnisse zugeschnitten. Wenn Sie einen Basis-Prompt mit einer Beschreibung einer Figur eingeben, wird ein cleverer zweistufiger Prozess ausgeführt:
    • Zuerst wird Ihrem Prompt „mit offenem Mund“ hinzugefügt und das erste Bild wird generiert.
    • Zweitens wird das neu erstellte Bild verwendet und mit einer neuen Anweisung an das Modell zurückgesendet: „Schließe den Mund.“

Gemini 2.5 Flash Image (Nano Banana) kann vorhandene Bilder anhand eines Befehls in natürlicher Sprache ändern oder bearbeiten. Das Modell zeichnet nur die erforderlichen Teile des Bildes neu und lässt alles andere unverändert. So sind beide Bilder in Stil, Beleuchtung und Charakterdesign absolut konsistent und unterscheiden sich nur in der Position des Mundes – genau das, was wir für einen überzeugenden Lippensynchronisationseffekt brauchen.

In den folgenden Schritten weisen wir die Gemini CLI an, das spezielle Tool generate_lip_sync_images zu verwenden, um den einzigartigen Avatar unseres Begleiters zu erstellen.

👉💻 Aktivieren Sie die virtuelle Umgebung Ihres Projekts und installieren Sie die spezifischen Anforderungen des Servers.

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

👉💻 Führen Sie den MCP-Server jetzt im Hintergrund aus, damit er auf Anfragen von der Gemini CLI warten kann.

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

Mit diesem Befehl wird der Server gestartet und das Symbol & sorgt dafür, dass er im Hintergrund ausgeführt wird.

Als Nächstes müssen wir die Gemini CLI so konfigurieren, dass Bildgenerierungsanfragen an unseren neu ausgeführten lokalen Server gesendet werden. Dazu ändern wir die zentrale Konfigurationsdatei der CLI.

Was ist also diese settings.json-Datei?

Die Datei ~/.gemini/settings.json ist die zentrale Konfigurationsdatei für die Gemini-Befehlszeile. Hier speichert die CLI ihre Einstellungen, Präferenzen und das Verzeichnis aller externen Tools, die sie verwenden kann.

In dieser Datei gibt es einen speziellen Abschnitt namens mcpServers. Stellen Sie sich diesen Abschnitt als Adressbuch oder Dienstverzeichnis speziell für Tools vor, die das Model Context Protocol verwenden. Jeder Eintrag in diesem Verzeichnis hat einen Alias (z.B. „nano-banana“) und die Anleitung zum Herstellen einer Verbindung (in unserem Fall eine URL).

Mit dem Befehl, den wir gleich ausführen, wird dem Dienstverzeichnis programmatisch ein neuer Eintrag hinzugefügt. Dadurch wird der Gemini-Befehlszeile mitgeteilt:

„Hey, ab jetzt kennst du ein Tool namens nano-banana. Immer wenn ein Nutzer Sie auffordert, das Tool zu verwenden, müssen Sie eine Verbindung zum MCP-Server herstellen, der unter der URL http://localhost:8000/sse ausgeführt wird.“

Durch die Änderung dieser Konfiguration wird die Gemini CLI leistungsfähiger. Wir bringen ihm dynamisch eine neue Fähigkeit bei – die Kommunikation mit unserem lokalen Bildgenerierungsserver – ohne den Kerncode der CLI zu berühren. Dank dieses erweiterbaren Designs kann die Gemini CLI komplexe Aufgaben ausführen, indem sie ein ganzes Ökosystem spezialisierter Tools aufruft.

👉💻 Führen Sie im ersten Terminal den folgenden Befehl aus. Dadurch wird Ihre Gemini-Einstellungsdatei erstellt oder aktualisiert und es wird angegeben, wo der „nano-banana“-Dienst zu finden ist.

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

Der Inhalt der Datei sollte jetzt ausgegeben werden, einschließlich der nano-banana-Konfiguration.

Charakter-Avatare erstellen

Nachdem der Server ausgeführt und die CLI konfiguriert wurde, können Sie die Bilder jetzt generieren. Bevor wir die KI bitten, kreativ zu werden, sollten wir aber erst einmal das tun, was jeder gute Entwickler tut: die Einrichtung überprüfen. Wir müssen bestätigen, dass die Gemini CLI erfolgreich mit unserem lokalen MCP-Server kommunizieren kann.

👉💻 Zurück in Ihrem Gemini CLI-Terminal (auf dem kein Server ausgeführt wird) starten wir die interaktive Gemini-Shell. Wenn die App bereits ausgeführt wird, beenden Sie sie zweimal mit CTRL+C und starten Sie sie neu, damit unsere neuen Einstellungen geladen werden.

clear
gemini --yolo

Sie befinden sich jetzt in der interaktiven Umgebung der Gemini CLI. Hier können Sie mit der KI chatten, aber auch direkte Befehle an die CLI selbst senden.

👉✨ Um zu prüfen, ob unser MCP-Server verbunden ist, verwenden wir einen speziellen „Slash-Befehl“. Dies ist kein Prompt für die KI, sondern eine Anweisung für die CLI-Anwendung selbst. Geben Sie Folgendes ein und drücken Sie die Eingabetaste:

/mcp list

Mit diesem Befehl wird der Gemini CLI mitgeteilt: „Gehe deine Konfiguration durch, suche alle MCP-Server, die du kennst, versuche, eine Verbindung zu jedem herzustellen, und melde ihren Status.“

👀 Sie sollten die folgende Ausgabe sehen, die bestätigt, dass alles einwandfrei funktioniert:

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

Eine Aufschlüsselung der erfolgreichen Antwort ergibt Folgendes:

  • 🟢 nano-banana: Der grüne Kreis ist unser Erfolgsindikator. Dies bestätigt, dass die CLI den nano-banana-Server unter der URL erreichen konnte, die wir in settings.json angegeben haben.
  • - Ready: Dieser Status bestätigt, dass die Verbindung stabil ist.
  • (2 tools): Das ist der wichtigste Teil. Das bedeutet, dass die CLI nicht nur eine Verbindung hergestellt, sondern auch unseren MCP-Server gefragt hat: „Was kannst du tun?“ Unser Server hat mit Werbung für die beiden Tools geantwortet, die wir im Code gesehen haben: generate_image und generate_lip_sync_images.

So wird bestätigt, dass die gesamte Kommunikationskette eingerichtet ist. Die CLI kennt jetzt unseren lokalen Dienst zum Generieren von Bildern und kann ihn für unseren Befehl verwenden.

Jetzt kommt der kreativste Teil des Workshops. Wir verwenden einen einzelnen, leistungsstarken Prompt, um die Gemini CLI anzuweisen, das spezielle Tool generate_lip_sync_images auf unserem laufenden MCP-Server zu verwenden.

Hier haben Sie die Möglichkeit, das einzigartige Aussehen Ihres Begleiters zu gestalten. Denken Sie an den Stil, die Haarfarbe, den Gesichtsausdruck und alle anderen Details, die zur Persona passen, die Sie zuvor erstellt haben.

👉✨ Hier ist ein gut strukturierter Beispiel-Prompt. Sie können sie als Ausgangspunkt verwenden oder den beschreibenden Teil vollständig durch Ihre eigene Vision ersetzen.

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.

Das Tool generiert eine Reihe von Bildern (mit offenem und geschlossenem Mund usw.) und speichert sie. Es werden die Pfade ausgegeben, in denen die Dateien gespeichert wurden.

Anwendung neu starten

Nachdem Sie die benutzerdefinierten Avatare eingerichtet haben, können Sie den Webserver neu starten, um den neuen Look Ihres Charakters zu sehen.

👉💻 Server ein letztes Mal im ersten Terminal starten

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

👀 Damit Ihre neuen Bilder richtig geladen werden, laden wir das Bild char-mouth-open.png im Voraus.

  1. Lassen Sie den Tab mit der Webvorschau für Ihre Anwendung geöffnet.
  2. Öffnen Sie einen neuen Browsertab.
  3. Fügen Sie auf diesem neuen Tab die URL Ihrer Anwendung ein, aber hängen Sie den folgenden Pfad an: /static/images/char-mouth-open.png.Ihre URL sieht dann etwa so aus: https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png
  4. Drücken Sie die Eingabetaste. Sie sollten nur das Bild der Figur mit offenem Mund sehen. So wird sichergestellt, dass Ihr Browser die Dateien korrekt von Ihrer Cloud Shell-Instanz abgerufen hat.

Sie können jetzt mit Ihrem visuell angepassten Companion interagieren.

Glückwunsch!

Sie haben einen ausgefeilten KI-Begleiter erstellt. Sie haben mit einer einfachen App begonnen, die Gemini-Befehlszeile verwendet, um einen Agenten zu erstellen, ihm eine ausgeprägte Persönlichkeit verliehen und ihn mit Tools ausgestattet, um auf Echtzeitinformationen zuzugreifen und sogar einen eigenen Avatar zu generieren. Sie sind jetzt bereit, noch komplexere und leistungsfähigere KI-Agents zu entwickeln.