이 페이지는 Cloud Translation API를 통해 번역되었습니다.

첫 번째 AI 컴패니언 빌드: 초보자 워크숍

1. 학습할 내용

Gemini CLI를 사용하여 완전한 ADK 에이전트 구성을 생성하는 방법
안내를 개선하여 에이전트의 성격을 향상하는 방법
최근 이벤트에 관한 질문에 답변할 수 있도록 google_search를 제공하여 에이전트에 '그라운딩'을 추가하는 방법
Imagen을 사용하여 MCP 서버로 컴패니언의 맞춤 아바타를 생성하는 방법

AI 컴패니언 앱

이 Codelab에서는 시각적이고 대화형 AI 동반자를 구현합니다. 이는 단순한 표준 텍스트 입력-텍스트 출력 챗봇이 아닙니다. 웹페이지에 사는 캐릭터를 상상해 보세요. 메시지를 입력하면 텍스트만 표시되는 대신 캐릭터가 나를 바라보며 음성으로 대답하고 입이 단어와 동기화되어 움직입니다.

사전 빌드된 웹 애플리케이션(얼굴은 있지만 자체적인 마음이 없는 디지털 '인형')으로 시작합니다. 사용자가 입력한 내용만 반복할 수 있습니다. 처음부터 AI의 두뇌와 성격을 구축하는 것이 여러분의 임무입니다.

이 워크숍에서는 지능과 맞춤설정 레이어를 점진적으로 추가하여 이 간단한 꼭두각시를 유능한 나만의 동반자로 변신시킵니다. 다음과 같은 작업을 할 수 있습니다.

ADK(Python)를 사용하여 언어를 이해하고 생성하는 핵심 인텔리전스 제공
고유한 성격 만들기: 캐릭터를 정의하는 핵심 지침을 작성합니다.
인터넷의 실시간 정보에 액세스할 수 있는 도구를 제공하여 초능력을 부여합니다.
AI를 사용하여 고유한 아바타를 생성하여 맞춤 디자인

이 과정을 마치면 직접 만든 완전한 기능을 갖춘 맞춤형 AI 동반자를 갖게 됩니다.

아키텍처

애플리케이션은 간단하지만 강력한 패턴을 따릅니다. API를 제공하는 Python 백엔드가 있습니다. 이 백엔드에는 '브레인' 역할을 하는 ADK 에이전트가 포함됩니다. 그러면 모든 사용자 인터페이스 (스켈레톤 앱의 JavaScript 프런트엔드, 모바일 앱, 명령줄 도구 등)가 API를 통해 이 브레인과 상호작용할 수 있습니다.

이 외에도 로컬 MCP (모델 컨텍스트 프로토콜) 서버를 시작하여 더 고급 개념을 살펴봅니다. 이 서버는 이미지 생성을 위한 특수 도구 브리지 역할을 합니다. 그런 다음 Gemini CLI를 사용하여 이 MCP 서버에 AI 컴패니언의 고유한 외모를 생성하도록 지시합니다.

크레딧 신청

워크숍 리소스를 프로비저닝하려면 다음 안내를 주의 깊게 따르세요.

시작하기 전에

경고!

개인 Gmail 계정을 사용합니다. 회사 또는 학교에서 관리하는 계정은 사용할 수 없습니다.
계정 충돌을 방지하려면 시크릿 모드에서 Google Chrome을 사용하세요.

새 시크릿 모드 창을 열고 이벤트 링크를 붙여넣은 다음 개인 Gmail로 로그인합니다.

👉 아래를 클릭하여 특별 이벤트 링크를 복사하세요.

goo.gle/devfest-boston-ai

Google Cloud Platform 서비스 약관에 동의합니다. 적용되면 크레딧이 적용되었다는 메시지가 표시됩니다.

프로젝트 생성 및 구성

크레딧이 적용되었으므로 프로젝트 환경을 설정합니다.

👉 Google Cloud 콘솔로 이동합니다. 아래를 클릭하여 링크를 복사하세요.

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

👉 콘솔의 상단 탐색 메뉴에서 프로젝트 선택을 클릭한 다음 오른쪽 상단에 있는 새 프로젝트를 클릭합니다.

👉 프로젝트 이름을 지정하고 만들기를 클릭합니다. (조직 없음)

👉 생성된 후 선택합니다. 왼쪽 메뉴에서 결제로 이동합니다.

👉 결제 계정 연결을 클릭하고 드롭다운에서 Google Cloud Platform 평가판 결제 계정을 선택한 다음 계정 설정을 클릭합니다. (드롭다운 메뉴가 표시되지 않으면 크레딧이 적용될 때까지 1분간 기다린 후 페이지를 새로고침하세요.)

크레딧이 활성 상태이고 프로젝트가 구성되어 있습니다.

2. 시작하기 전에

👉Google Cloud 콘솔 상단에서 Cloud Shell 활성화를 클릭합니다 (Cloud Shell 창 상단의 터미널 모양 아이콘).

👉Google Cloud 프로젝트 ID를 찾습니다.

Google Cloud 콘솔(https://console.cloud.google.com)을 엽니다.
페이지 상단의 프로젝트 드롭다운에서 이 워크숍에 사용할 프로젝트를 선택합니다.
프로젝트 ID는 대시보드의 프로젝트 정보 카드에 표시됩니다.

👉💻 터미널에서 GitHub의 부트스트랩 프로젝트를 클론합니다.

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

👉💻 초기화 스크립트를 실행합니다. 이 스크립트에서 Google Cloud 프로젝트 ID를 입력하라는 메시지가 표시됩니다. init.sh 스크립트에서 메시지가 표시되면 마지막 단계에서 찾은 Google Cloud 프로젝트 ID를 입력합니다.

cd ~/companion-python
./init.sh

👉💻 필요한 프로젝트 ID를 설정합니다.

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

👉💻 다음 명령어를 실행하여 필요한 Google Cloud API를 사용 설정합니다.

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

앱 시작

시작 프로젝트를 실행해 보겠습니다. 이 초기 버전은 간단한 '에코' 서버로, 지능이 없으며 사용자가 전송한 내용만 반복합니다.

👉💻 Cloud Shell 터미널에서 Python 가상 환경을 만들고 활성화하고 requirements.txt 파일에서 필요한 라이브러리를 설치합니다.

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

👉💻 웹 서버를 시작합니다.

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

👀 앱을 보려면 Cloud Shell 툴바에서 웹 미리보기 아이콘을 클릭합니다. 포트 변경을 선택하고 5000으로 설정한 후 변경 및 미리보기를 클릭합니다. 웹사이트 미리보기가 표시됩니다.

새 Cloud Shell 환경에서 브라우저가 처음으로 애플리케이션의 모든 애셋 (예: 이미지 및 오디오 라이브러리)을 로드하는 데 약간의 도움이 필요할 수 있습니다. '브라우저를 준비'하고 모든 항목이 올바르게 로드되었는지 확인하는 간단한 단계를 진행해 보겠습니다.

애플리케이션의 웹 미리보기 탭을 열어 둡니다.
새 브라우저 탭을 엽니다.
새 탭에 애플리케이션의 URL을 붙여넣고 끝에 /static/images/char-mouth-open.png 경로를 추가합니다. 예를 들어 URL은 https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png과 같이 표시됩니다.
Enter를 누릅니다. 입을 벌린 캐릭터의 이미지만 표시됩니다. 이 단계를 통해 브라우저가 Cloud Shell 인스턴스에서 파일을 올바르게 가져왔는지 확인할 수 있습니다.

초기 애플리케이션은 꼭두각시에 불과합니다. 아직 지능이 없습니다. 어떤 메시지를 보내든 그대로 반복해서 대답합니다. 이렇게 하면 AI를 추가하기 전에 기본 웹 서버가 작동하는지 확인할 수 있습니다. 스피커를 켜는 것을 잊지 마세요.

👉 서버를 중지하려면 CTRL+C를 누릅니다.

3. Gemini CLI로 캐릭터 만들기

이제 동반자 지능의 핵심을 만들어 보겠습니다. 이를 위해 두 개의 터미널을 동시에 사용합니다 (Google Cloud Shell 터미널).

터미널 1: Python 웹 서버를 실행하는 데 사용되며, 이를 통해 변경사항을 실시간으로 테스트할 수 있습니다.
터미널 2: Gemini CLI와 상호작용할 '생성 스테이션'입니다.

여기서는 AI 코딩 어시스턴트 역할을 하는 강력한 명령줄 인터페이스인 Gemini CLI를 사용합니다. 원하는 코드를 일반 영어로 설명하면 구조를 생성해 주므로 개발 속도가 크게 빨라집니다.

👉💻 프로젝트 디렉터리가 ~/companion-python 아래에 있으므로 Gemini CLI 터미널에서 ctrl+c를 두 번 클릭하여 현재 Gemini CLI 세션을 종료하고 Gemini CLI를 다시 시작합니다.

cd ~/companion-python
clear
gemini --yolo

CLI를 사용하여 에이전트를 빌드합니다. 에이전트는 언어 모델에 대한 단순한 호출 그 이상입니다. AI의 '두뇌' 또는 중앙 컨트롤러입니다. 추론하고, 특정 요청 사항 (성격)을 따르며, 궁극적으로 도구를 사용하여 작업을 완료할 수 있는 별개의 엔티티로 생각하면 됩니다. 이 프로젝트에서 이 에이전트는 사용자 메시지를 수신하고, 동반자의 고유한 페르소나를 구현하고, 지능적이고 캐릭터에 맞는 응답을 공식화하는 구성요소입니다.

👉✨ Gemini CLI 프롬프트에 다음을 붙여넣어 에이전트의 코드를 생성합니다.

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

CLI에서 Python 코드를 생성합니다.

👉'편집기 열기' 버튼 (연필이 있는 열린 폴더 모양)을 클릭합니다. 이렇게 하면 창에 Cloud Shell 코드 편집기가 열립니다. 왼쪽에 파일 탐색기가 표시됩니다.

👉 편집기를 사용하여 companion-python 폴더 아래의 character.py로 이동합니다. 잠시 시간을 내어 model= 행을 확인하고 다른 모델을 선택한 경우 gemini-2.5-flash로 수동으로 수정하세요. 이렇게 하면 워크숍의 나머지 부분에서 일관성을 유지할 수 있습니다.

참고: 대규모 언어 모델은 비결정적일 수 있으며 이는 AI 지원 개발의 핵심 개념입니다. '비결정적'이란 동일한 프롬프트를 사용하더라도 모델이 매번 약간 다른 결과를 생성할 수 있다는 의미입니다. 창의력을 발휘하여 코드를 생성하므로 주석, 간격 또는 임시 변수 이름에 차이가 있을 수 있습니다. 하지만 핵심 로직과 구조는 요청된 것과 기능적으로 동일해야 합니다.

이러한 이유로 AI를 사용한 코딩은 일회성 명령인 경우가 거의 없습니다. 실제 프로젝트에서 개발자는 이를 대화처럼 취급합니다. 방금 한 것처럼 광범위한 요청으로 시작하고, 출력을 검토한 다음 다음과 같은 후속 프롬프트로 다듬습니다.

'좋아요. 이제 각 줄을 설명하는 주석을 추가하세요.'
'별도의 함수로 리팩터링해 줄 수 있어?'
'API 호출에 대한 오류 처리를 추가해 줘.'

이 반복적인 대화형 프로세스를 통해 AI와 공동작업하여 필요한 코드가 정확히 나올 때까지 안내할 수 있습니다. 이 워크숍에서는 구체적이고 직접적인 프롬프트를 사용하지만, 실제 프로젝트에서는 대화가 진정한 힘을 발휘한다는 점을 기억하세요. CLI에서 생성하는 코드 구조가 동일하면 됩니다.

생성된 코드가 작동하지 않으면 다음 코드를 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.
    """,
)

생성된 코드 테스트:

👉💻 첫 번째 터미널 (Python 코드를 실행하는 터미널)로 이동하여 웹 서버를 시작합니다.

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

👀 웹 미리보기 탭으로 이동합니다.

👉 Hello, how are you?를 입력하고 보내기를 누릅니다. 이제 에이전트가 내 말을 그대로 반복하는 대신 친근한 인사말로 응답합니다. 이제 Gemini로 지원되는 에이전트를 사용할 수 있습니다.

👉 테스트를 완료한 후 CTRL+C를 사용하여 서버를 중지합니다. Gemini CLI를 실행하는 터미널에서 CTRL+C를 두 번 눌러 Gemini CLI를 종료합니다.

4. 에이전트 페르소나 개선

간단한 설명도 좋지만 자세한 페르소나를 사용하면 훨씬 더 매력적이고 기억에 남는 캐릭터를 만들 수 있습니다. 이 단계에서는 나만의 반려견의 성격을 설계한 다음 Gemini CLI에 에이전트의 코드를 직접 수정하여 이 새로운 페르소나를 채택하도록 지시합니다.

반려동물의 페르소나 브레인스토밍하기

먼저 만들고 싶은 AI 친구를 잠시 생각해 보세요. 창의력을 발휘할 기회입니다. 다음은 시작하는 데 도움이 되는 몇 가지 질문입니다.

이름이 무엇인가요? (예: 스파키, 코덱스, 캡틴 AI, 만물박사)
핵심 성격은 무엇인가요? (예: 친근하고 호기심이 많으며, 재치 있고 냉소적이며, 격식 있고 전문적이며, 쾌활한 해적)
이 회사의 역할 또는 전문 분야는 무엇인가요? (예: 다목적 어시스턴트, 코딩 전문가, 창의적인 글쓰기 파트너, 피트니스 코치 등)
항상 따라야 하는 규칙은 무엇인가요? (예: '항상 인사말로 시작해', '내가 AI임을 절대 밝히지 마', '대답에 그림 이모티콘을 사용해')

예시 페르소나:

 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.

Gemini CLI용 프롬프트 작성

이제 종이에 컴패니언의 성격을 디자인했으므로 코드 내에서 이를 구현할 차례입니다. ADK 에이전트에서 가장 중요한 부분은 instruction 매개변수입니다. 이는 에이전트의 핵심 프로그래밍, '최고 지침' 또는 항상 따라야 하는 헌법과 같습니다.

이 명령어가 에이전트의 동작을 제어하는 데 핵심적인 역할을 합니다. 단순한 제안이 아니라 AI가 사용자와의 모든 상호작용 전에 참조하는 기본적인 맥락입니다. 에이전트의 성격, 어조, 준수해야 하는 규칙, 자기 소개 방식을 규정합니다. 잘 만들어진 프롬프트는 일반적인 챗봇과 믿을 수 있고 일관된 캐릭터의 차이를 만듭니다. 따라서 우리가 만들 프롬프트는 이 성격을 에이전트의 두뇌에 직접 주입하므로 매우 중요합니다.

👉✨ Gemini CLI로 돌아가서 이 템플릿을 사용합니다. 괄호 안의 텍스트를 페르소나 설명으로 바꿉니다. [여기에 페르소나 설명 입력]을 원하는 페르소나로 대체하세요.

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]

새 페르소나 테스트

Gemini CLI가 character.py의 업데이트된 코드를 생성합니다.

👉💻 웹 서버를 다시 시작합니다.

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

👀 웹 미리보기에서 동반자와 대화를 나눕니다. how are you?에 질문하세요. 이제 대답이 사용자가 디자인한 고유한 캐릭터와 완벽하게 일치합니다.

👉 완료되면 CTRL+C로 서버를 중지합니다.

5. 최근 이벤트에 그라운딩 추가

이제 에이전트가 개성으로 가득하지만, 학습한 데이터를 기반으로 지식이 고정되어 있다는 심각한 제한이 있습니다. 어제 뉴스나 최근 발견에 대해서는 알려줄 수 없습니다. 이러한 문제를 해결하기 위해 상담사에게 도구를 제공합니다.

도구는 에이전트에게 부여하는 초능력 또는 특수 능력이라고 생각하면 됩니다. 에이전트는 혼자서는 말만 할 수 있습니다. 검색 도구를 사용하면 인터넷을 탐색할 수 있습니다. 캘린더 도구를 사용하면 일정을 확인할 수 있습니다. 기술적으로 도구는 상담사가 사용자의 요청에 답변하기에 자체 지식이 충분하지 않다고 판단될 때 지능적으로 선택하여 사용할 수 있는 특정 기능 또는 API입니다.

고급 시스템에서는 아키텍처에서 언급한 MCP (모델 컨텍스트 프로토콜) 서버와 같은 외부 시스템에서 도구를 제공할 수 있습니다. 이는 나중에 이미지 생성에 사용됩니다. 하지만 이 단계에서는 별도의 서버가 필요하지 않습니다. ADK에는 에이전트의 기능에 쉽게 추가할 수 있는 강력한 사전 빌드된 google_search 도구가 함께 제공됩니다.

반려동물에게 Google 검색 기능을 제공해 보겠습니다.

👉 Cloud Shell 편집기에서 companion-python 아래의 character.py를 열고 다음과 같이 수정합니다.

google.adk.tools에서 google_search를 가져옵니다.
LlmAgent 생성자에 tools 목록을 추가합니다.
instruction를 업데이트하여 언제 새 도구를 사용할지 동반자에게 명시적으로 알려줍니다.

# 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
)

그라운딩된 에이전트 테스트

👉💻 서버를 한 번 더 시작합니다.

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

👉 웹 미리보기에서 다음과 같이 최신 지식이 필요한 질문을 합니다.

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

👉이제 에이전트는 모른다고 말하는 대신 검색 도구를 사용하여 최신 정보를 찾고 유용한 근거 있는 요약을 고유한 음성으로 제공합니다.

서버를 중지하려면 CTRL+C를 누릅니다.

6. 컴패니언의 디자인 맞춤설정 (선택사항)

이제 동반자에게 두뇌가 있으니 고유한 얼굴을 만들어 보겠습니다. Gemini CLI가 이미지를 생성할 수 있도록 로컬 MCP (모델 컨텍스트 프로토콜) 서버를 사용합니다. 이 서버는 Google AI Studio를 통해 제공되는 생성형 AI 모델을 사용합니다.

그렇다면 MCP 서버란 정확히 무엇일까요?

Model Context Protocol (MCP)은 AI 모델이 외부 도구 및 데이터 소스와 통신하는 방법이라는 일반적이고 복잡한 문제를 해결하기 위해 설계된 개방형 표준입니다. MCP는 모든 통합에 대해 맞춤 일회성 코드를 작성하는 대신 이 커뮤니케이션을 위한 범용 '언어'를 제공합니다.

AI용 범용 어댑터 또는 USB 포트라고 생각하면 됩니다. MCP를 '사용'하는 도구는 MCP를 '사용'하는 모든 AI 애플리케이션에 연결할 수 있습니다.

워크숍에서 실행할 nano-banana-mcp 서버는 이 중요한 브리지 역할을 합니다. Gemini CLI는 표준화된 요청을 로컬 MCP 서버로 전송합니다. 그러면 서버가 해당 요청을 생성형 AI 모델에 대한 특정 호출로 변환하여 이미지를 생성합니다. 이를 통해 강력한 이미지 생성 기능을 명령줄 워크플로에 직접 깔끔하게 연결할 수 있습니다.

로컬 이미지 생성 서버 설정

이제 이미지 생성 요청을 처리하는 사전 빌드된 MCP 서버를 클론하고 실행합니다.

👉💻 첫 번째 Cloud Shell 터미널 (Python을 실행하는 터미널)에서 서버의 저장소를 클론합니다.

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

서버, nano-banana-mcp 폴더 내의 mcp_server.py 파일을 간단히 살펴보겠습니다. 이 서버는 Gemini CLI가 사용할 수 있는 두 가지 특정 '도구'를 노출하도록 빌드됩니다. 이미지 생성 서비스가 학습한 두 가지 고유한 기술이라고 생각하면 됩니다.

generate_image: 범용 도구입니다. 단일 텍스트 프롬프트를 입력하면 이를 기반으로 이미지가 하나 생성됩니다. 간단하고 많은 작업에 유용합니다.
generate_lip_sync_images: 이 도구는 Google의 요구사항에 맞게 설계된 매우 전문적인 도구입니다. 캐릭터를 설명하는 기본 프롬프트를 제공하면 다음과 같은 두 단계의 프로세스를 수행합니다.
- 먼저 프롬프트에 '입을 벌린'을 추가하고 첫 번째 이미지를 생성합니다.
- 두 번째로 새로 만든 이미지를 가져와 '입을 벌린 상태에서 다문 상태로 변경해'라는 새로운 명령과 함께 모델에 다시 전송합니다.

Gemini 2.5 Flash Image (Nano Banana)가 자연어 명령에 따라 기존 이미지를 변경하거나 편집하는 기능은 매우 강력합니다. 모델은 다른 모든 부분을 완벽하게 유지하면서 이미지의 필요한 부분만 다시 그립니다. 이렇게 하면 두 이미지가 스타일, 조명, 캐릭터 디자인에서 완전히 일관되게 유지되며 입의 위치만 달라집니다. 이는 설득력 있는 립싱크 효과를 위해 필요한 사항입니다.

다음 단계에서는 Gemini CLI에 특화된 generate_lip_sync_images 도구를 사용하여 내 친구의 고유한 아바타를 만들도록 명령합니다.

👉💻 프로젝트의 가상 환경을 활성화하고 서버의 특정 요구사항을 설치합니다.

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

👉💻 이제 Gemini CLI의 요청을 수신할 수 있도록 백그라운드에서 MCP 서버를 실행합니다.

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

이 명령어는 서버를 시작하고 & 기호는 서버가 백그라운드에서 계속 실행되도록 합니다.

Gemini CLI를 로컬 서버에 연결

다음으로 새로 실행 중인 로컬 서버에 이미지 생성 요청을 전송하도록 Gemini CLI를 구성해야 합니다. 이렇게 하려면 CLI의 중앙 구성 파일을 수정합니다.

그렇다면 이 settings.json 파일은 무엇일까요?

~/.gemini/settings.json 파일은 Gemini CLI의 중앙 구성 파일입니다. CLI가 설정, 환경설정, 사용할 수 있는 모든 외부 도구의 디렉터리를 저장하는 위치입니다.

이 파일에는 mcpServers라는 특별한 섹션이 있습니다. 이 섹션은 모델 컨텍스트 프로토콜을 사용하는 도구를 위한 주소록 또는 서비스 디렉터리라고 생각하면 됩니다. 이 디렉터리의 각 항목에는 닉네임이 있습니다 (예: 'nano-banana') 및 연결 방법에 관한 안내 (이 경우 URL)를 제공합니다.

이제 실행할 명령어는 이 서비스 디렉터리에 새 항목을 프로그래매틱 방식으로 추가합니다. 그러면 Gemini CLI에 다음이 표시됩니다.

'이제부터 nano-banana라는 도구를 알게 되었습니다. 사용자가 사용을 요청할 때마다 URL http://localhost:8000/sse에서 실행되는 MCP 서버에 연결해야 합니다.'

이 구성을 수정하면 Gemini CLI가 더 강력해집니다. CLI의 핵심 코드를 전혀 건드리지 않고도 로컬 이미지 생성 서버와 통신하는 방법을 동적으로 가르치고 있습니다. 이 확장 가능한 설계 덕분에 Gemini CLI는 전문 도구의 전체 생태계를 호출하여 복잡한 작업을 오케스트레이션할 수 있습니다.

👉💻 첫 번째 터미널에서 다음 명령어를 실행합니다. 'nano-banana' 서비스를 찾을 위치를 알려주는 Gemini 설정 파일이 생성되거나 업데이트됩니다.

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

이제 nano-banana 구성이 포함된 파일의 콘텐츠가 출력됩니다.

캐릭터 아바타 생성

서버가 실행되고 CLI가 구성되었으므로 이제 이미지를 생성할 수 있습니다. 하지만 AI에 창의력을 발휘해 달라고 요청하기 전에 모든 훌륭한 개발자가 하는 일, 즉 설정을 확인해 보겠습니다. Gemini CLI가 로컬 MCP 서버와 통신할 수 있는지 확인해야 합니다.

👉💻 서버를 실행하지 않는 Gemini CLI 터미널로 돌아가 Gemini 대화형 셸을 시작합니다. 이미 실행 중인 경우 CTRL+C를 두 번 눌러 종료하고 다시 시작하여 새 설정을 로드합니다.

clear
gemini --yolo

이제 Gemini CLI의 대화형 환경에 있습니다. 여기에서 AI와 채팅할 수 있지만 CLI 자체에 직접 명령어를 입력할 수도 있습니다.

👉✨ MCP 서버가 연결되어 있는지 확인하려면 특수 '슬래시 명령어'를 사용합니다. 이는 AI를 위한 프롬프트가 아니라 CLI 애플리케이션 자체를 위한 명령어입니다. 다음을 입력하고 Enter 키를 누릅니다.

/mcp list

이 명령어는 Gemini CLI에 '구성을 살펴보고, 알고 있는 모든 MCP 서버를 찾아 각 서버에 연결을 시도하고, 상태를 보고해'라고 지시합니다.

👀 모든 것이 완벽하게 작동함을 확인하는 다음과 같은 출력이 표시됩니다.

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

성공적인 응답의 의미를 자세히 살펴보겠습니다.

🟢 nano-banana: 녹색 원은 성공 신호입니다. 이를 통해 CLI가 settings.json에 지정된 URL에서 nano-banana 서버에 연결할 수 있음을 확인할 수 있습니다.
- Ready: 이 상태는 연결이 안정적임을 확인합니다.
(2 tools): 가장 중요한 부분입니다. CLI가 연결되었을 뿐만 아니라 MCP 서버에 '무엇을 할 수 있어?'라고 물었다는 의미입니다. 서버는 코드에서 확인한 두 도구(generate_image 및 generate_lip_sync_images)를 광고하여 응답했습니다.

이렇게 하면 전체 통신 체인이 설정되었는지 확인할 수 있습니다. 이제 CLI가 로컬 이미지 생성 서비스를 인식하고 명령에 따라 사용할 준비가 되었습니다.

이제 워크숍에서 가장 창의적인 부분을 살펴볼 차례입니다. 실행 중인 MCP 서버에서 특수 generate_lip_sync_images 도구를 사용하도록 Gemini CLI에 명령하는 강력한 프롬프트 하나를 사용합니다.

이 기회에 나만의 특별한 동반자를 디자인해 보세요. 앞서 만든 페르소나에 맞는 스타일, 머리 색깔, 표정, 기타 세부정보를 생각해 보세요.

👉✨ 다음은 잘 구조화된 프롬프트의 예입니다. 시작점으로 사용하거나 설명 부분을 완전히 내 비전으로 대체할 수 있습니다.

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.

이 도구는 입이 열린 상태, 닫힌 상태 등의 이미지 세트를 생성하고 저장합니다. 파일이 저장된 경로가 출력됩니다.

애플리케이션 다시 실행

맞춤 아바타를 설정한 후 웹 서버를 다시 시작하면 캐릭터의 새로운 모습을 확인할 수 있습니다.

👉💻 첫 번째 터미널에서 서버를 마지막으로 한 번 시작합니다.

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

👀 새 이미지가 올바르게 로드되도록 char-mouth-open.png 이미지를 미리 로드합니다.

애플리케이션의 웹 미리보기 탭을 열어 둡니다.
새 브라우저 탭을 엽니다.
새 탭에 애플리케이션의 URL을 붙여넣고 끝에 /static/images/char-mouth-open.png 경로를 추가합니다. 예를 들어 URL은 https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png과 같이 표시됩니다.
Enter를 누릅니다. 입을 벌린 캐릭터의 이미지만 표시됩니다. 이 단계를 통해 브라우저가 Cloud Shell 인스턴스에서 파일을 올바르게 가져왔는지 확인할 수 있습니다.

이제 시각적으로 맞춤설정된 반려견과 상호작용할 수 있습니다.

축하합니다.

정교한 AI 동반자를 빌드했습니다. 기본 앱으로 시작하여 Gemini CLI를 사용하여 에이전트를 스캐폴딩하고, 풍부한 개성을 부여하고, 실시간 정보에 액세스하고 자체 아바타를 생성하는 도구를 제공했습니다. 이제 더욱 복잡하고 유능한 AI 에이전트를 빌드할 수 있습니다.