1. 학습할 내용
- 특정 프레임워크 (ADK)에서 코딩 기능을 사용 설정하기 위해 Antigravity CLI의 스킬을 설치하고 등록하는 방법
- Antigravity CLI를 사용하여 완전한 ADK 에이전트 구성을 생성하는 방법
- 지침을 개선하여 에이전트의 페르소나를 향상하는 방법
- 최근 이벤트에 관한 질문에 답변할 수 있도록
google_search를 제공하여 에이전트에 '그라운딩'을 추가하는 방법
AI 컴패니언 앱
이 Codelab에서는 시각적이고 대화형 AI 컴패니언을 구현합니다. 이는 일반적인 텍스트 입력-텍스트 출력 챗봇 그 이상입니다. 웹페이지에 있는 캐릭터를 상상해 보세요. 메시지를 입력하면 텍스트가 다시 표시되는 대신 캐릭터가 사용자를 바라보고 입을 움직여 단어와 동기화하면서 큰 소리로 응답합니다.
얼굴은 있지만 자체적인 생각이 없는 디지털 '인형'인 사전 빌드된 웹 애플리케이션으로 시작합니다. 입력한 내용만 반복할 수 있습니다. 미션은 처음부터 뇌와 페르소나를 구축하는 것입니다.
이 워크숍에서는 지능과 맞춤설정 레이어를 점진적으로 추가하여 이 간단한 인형을 고유하고 유능한 컴패니언으로 변환합니다. 다음 작업을 수행합니다.
- ADK(Python)를 사용하여 언어를 이해하고 생성하는 핵심 지능 제공
- 캐릭터를 정의하는 핵심 지침을 작성하여 고유한 페르소나 만들기
- 인터넷에서 실시간 정보에 액세스할 수 있는 도구를 제공하여 초능력 부여
- AI를 사용하여 고유한 아바타를 생성하여 맞춤 디자인
결국 직접 만든 완전한 기능을 갖춘 맞춤형 AI 컴패니언을 갖게 됩니다. 
아키텍처
애플리케이션은 간단하지만 강력한 패턴을 따릅니다. API를 제공하는 Python 백엔드가 있습니다. 이 백엔드에는 '뇌' 역할을 하는 ADK 에이전트가 포함됩니다. 그러면 모든 사용자 인터페이스 (예: 스켈레톤 앱의 JavaScript 프런트엔드, 모바일 앱 또는 명령줄 도구)가 API를 통해 이 뇌와 상호작용할 수 있습니다.
또한 Antigravity CLI에 내장된 이미지 생성 기능을 활용하여 AI 컴패니언의 고유한 디자인을 생성하도록 지시합니다.
Gemini API 키 가져오기
계속하기 전에 Google AI Studio로 요청을 인증하려면 Gemini API 키가 필요합니다.
- Google AI Studio로 이동합니다.
- Google 계정으로 로그인합니다.
- 왼쪽 상단 메뉴에서 API 키 가져오기 버튼을 클릭합니다.
- API 키 만들기 를 클릭합니다 (새 Google Cloud 프로젝트 또는 기존 Google Cloud 프로젝트에서 만들 수 있음).
- 생성된 키를 복사합니다. 이 키는 비공개로 안전하게 보관하세요.
프로젝트 만들기 및 구성
Cloud Shell에 액세스하려면 Google Cloud 프로젝트가 계속 필요합니다. 프로젝트가 없는 경우 다음 단계를 따르세요.
- Google Cloud 콘솔로 이동합니다.
- 콘솔의 상단 탐색 메뉴에서 프로젝트 선택 을 클릭한 다음 오른쪽 상단에서 새 프로젝트 를 클릭합니다.
- 프로젝트 이름을 지정하고 만들기 를 클릭합니다. 조직은 필요하지 않습니다.
- 프로젝트가 생성되면 콘솔 상단의 프로젝트 드롭다운에서 프로젝트를 선택합니다.
이제 프로젝트가 Cloud Shell 액세스를 위해 구성되었습니다.
2. 시작하기 전에
👉Google Cloud 콘솔 상단에서 Cloud Shell 활성화를 클릭합니다 (Cloud Shell 창 상단의 터미널 모양 아이콘). 
👉💻 Cloud Shell 터미널에서 Antigravity CLI를 설치합니다.
curl -fsSL https://antigravity.google/cli/install.sh | bash
👉💻 'agy' CLI를 전역적으로 사용하려면 셸 프로필에 추가합니다.
echo 'export PATH="~/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
👉💻 Gemini API 키를 내보내고 Cloud Shell 터미널에 로컬로 저장합니다.
# Set your Gemini API key (obtained from Google AI Studio)
export GEMINI_API_KEY=<your-api-key-here>
👉💻 나중에 사용할 수 있도록 저장합니다.
echo $GEMINI_API_KEY > ~/gemini_key.txt
👉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를 사용 설정합니다 (Cloud Shell 미리보기/호스팅에는 Compute Engine만 필요함).
gcloud services enable compute.googleapis.com
ADK 개발자 스킬 설치
Antigravity CLI (agy)가 Python 에이전트 개발 키트 (ADK)를 사용하여 코드를 이해하고 작성할 수 있도록 하려면 만든 ADK Python 개발자 스킬을 프로젝트 작업공간에 설치해야 합니다.
👉💻 로컬 에이전트 스킬 디렉터리를 만들고 스킬 파일을 복사합니다.
mkdir -p ~/companion-python/.agents/skills/adk-python
cp ~/companion-python/skills/skill.md ~/companion-python/.agents/skills/adk-python/SKILL.md
이렇게 하면 스킬이 프로젝트 내에 로컬로 등록됩니다. agy를 실행하면 이 스킬이 자동으로 감지되고 로드되어 ADK 에이전트를 작성, 수정, 조정할 수 있습니다.
👉💻 Cloud Shell 터미널에서 Antigravity CLI를 시작합니다.
cd ~/companion-python
agy
[!IMPORTANT] Antigravity CLI에 로그인
agy 명령어를 처음 실행하면 로그인하라는 메시지가 표시됩니다.
Welcome to the Antigravity CLI. You are currently not signed in. Select login method: > 1. Google OAuth 2. Use a Google Cloud project
- `Enter`를 눌러 1. Google OAuth 옵션을 선택합니다.
Enter - 메시지에 따라 브라우저를 열고 Google 계정으로 인증한 후 안내에 따라 로그인합니다.
이제 대화형 Antigravity CLI 프롬프트가 표시됩니다.
Antigravity CLI를 통해 웹 서버 시작
Antigravity CLI는 명령어를 실행할 수 있으므로 세션의 백그라운드에서 서버를 실행하도록 요청해 보겠습니다.
👉✨ Antigravity CLI 프롬프트에서 다음 요청을 붙여넣습니다.
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.
CLI가 명령어를 실행하고 서버가 실행 중인지 확인합니다. 대화형 CLI 세션에 계속 머무르게 됩니다.
👀 앱을 보려면 Cloud Shell 툴바에서 웹 미리보기 아이콘을 클릭합니다. 포트 변경을 선택하고 5000으로 설정한 후 변경 및 미리보기를 클릭합니다. 웹사이트 미리보기가 표시됩니다.
초기 애플리케이션은 인형일 뿐입니다. 아직 지능이 없습니다. 어떤 메시지를 보내든 그대로 반복합니다. 이렇게 하면 AI를 추가하기 전에 기본 웹 서버가 작동하는지 확인할 수 있습니다. 스피커를 켜는 것을 잊지 마세요.
3. Antigravity CLI로 캐릭터 만들기
이제 컴패니언 지능의 핵심을 만들어 보겠습니다. Antigravity CLI가 이미 터미널에서 실행 중이고 백그라운드 웹 서버를 관리하고 있으므로 대화형 세션에서 직접 계속할 수 있습니다.
CLI를 사용하여 에이전트 를 빌드합니다. 에이전트는 언어 모델에 대한 단순한 호출 그 이상입니다. AI의 '뇌' 또는 중앙 컨트롤러입니다. 추론하고, 특정 지침 세트 (페르소나)를 따르고, 결국 도구를 사용하여 작업을 완료할 수 있는 고유한 항목이라고 생각하면 됩니다. 프로젝트에서 이 에이전트는 사용자 메시지를 수신하고, 컴패니언의 고유한 페르소나를 구현하고, 지능적이고 캐릭터에 맞는 응답을 공식화하는 구성요소입니다.
👉✨ Antigravity 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-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".
CLI가 Python 코드를 생성합니다.
👉'편집기 열기' 버튼 (연필이 있는 열린 폴더 모양)을 클릭합니다. 이렇게 하면 창에서 Cloud Shell 코드 편집기가 열립니다. 왼쪽에 파일 탐색기가 표시됩니다. 
👉 편집기를 사용하여 companion-python 폴더 아래의 character.py로 이동합니다. model= 줄을 확인하고 다른 모델이 선택된 경우 gemini-3.5-flash로 수동으로 수정합니다. 이렇게 하면 워크숍의 나머지 부분에서 일관성을 유지할 수 있습니다.
참고: 대규모 언어 모델은 비결정적일 수 있으며 이는 AI 지원 개발의 핵심 개념입니다. '비결정적'이란 정확히 동일한 프롬프트가 있더라도 모델이 매번 약간 다른 결과를 생성할 수 있음을 의미합니다. 창의성을 사용하여 코드를 생성하므로 주석, 간격 또는 임시 변수의 이름 지정에 차이가 있을 수 있습니다. 하지만 핵심 로직과 구조는 요청된 내용과 기능적으로 동일해야 합니다.
이것이 AI로 코딩하는 것이 일회성 명령어인 경우가 드문 이유입니다. 실제 프로젝트에서 개발자는 이를 대화처럼 취급합니다. 방금 한 것처럼 광범위한 요청으로 시작하고, 출력을 검토한 다음, 다음과 같은 후속 프롬프트로 세부적으로 조정합니다.
- '좋습니다. 이제 각 줄을 설명하는 주석을 추가하세요.'
- '별도의 함수로 리팩터링할 수 있나요?'
- 'API 호출에 오류 처리를 추가해 주세요.'
이 반복적인 대화형 프로세스를 통해 AI와 공동작업하고 코드가 정확히 필요한 코드가 될 때까지 AI를 안내할 수 있습니다. 이 워크숍에서는 구체적이고 직접적인 프롬프트를 사용하지만 자체 프로젝트에서는 대화가 실제 성능을 발휘한다는 점을 기억하세요. CLI가 생성하는 코드 구조가 동일하면 계속 진행할 수 있습니다.
생성된 코드가 작동하지 않으면 다음 코드를 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.
""",
)
생성된 코드 테스트
서버가 새로 생성된 character.py 모듈을 로드하도록 하려면 Antigravity CLI에 웹 서버를 다시 시작하도록 요청해 보겠습니다.
👉✨ Antigravity CLI 프롬프트에서 다음 요청을 붙여넣습니다.
Please restart the Python web server for me.
👀 웹 미리보기 탭으로 이동합니다.
👉 다음을 입력합니다.
Hello, how are you?
전송을 누릅니다. 이제 에이전트가 사용자의 말을 그대로 반복하는 대신 친절한 인사말로 응답해야 합니다. 이렇게 하면 에이전트가 이제 Gemini를 기반으로 작동하는지 확인할 수 있습니다.
4. 에이전트의 페르소나 향상
간단한 지침도 좋지만 자세한 페르소나를 사용하면 훨씬 더 매력적이고 기억에 남는 캐릭터를 만들 수 있습니다. 이 단계에서는 자체 컴패니언의 페르소나를 디자인한 다음 Antigravity CLI에 에이전트의 코드를 직접 수정하여 이 새 페르소나를 채택하도록 지시합니다.
컴패니언의 페르소나 브레인스토밍
먼저 만들려는 AI 컴패니언에 관해 잠시 생각해 보세요. 창의력을 발휘할 수 있는 기회입니다. 시작하는 데 도움이 되는 몇 가지 질문은 다음과 같습니다.
- 이름이 무엇인가요? (예: Sparky, Codex, Captain AI, Professor Know-it-all)
- 핵심 페르소나는 무엇인가요? (예: 친절하고 호기심이 많음, 재치 있고 냉소적임, 형식적이고 전문적임, 명랑한 해적?)
- 역할 또는 전문 분야는 무엇인가요? (예: 범용 어시스턴트, 코딩 전문가, 창의적 글쓰기 파트너, 피트니스 코치?)
- 항상 따라야 하는 규칙은 무엇인가요? (예: '항상 인사말로 시작', '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.
Antigravity CLI의 프롬프트 만들기
이제 컴패니언의 페르소나를 종이에 디자인했으므로 코드 내에서 구현할 차례입니다. ADK 에이전트에서 가장 중요한 부분은 instruction 매개변수입니다. 이를 에이전트의 핵심 프로그래밍, '최우선 지침' 또는 항상 따라야 하는 헌법이라고 생각하면 됩니다.
이 지침은 에이전트의 동작을 제어하는 데 핵심입니다. 단순한 제안이 아니라 AI가 사용자와의 모든 상호작용 전에 다시 참조하는 기본 컨텍스트입니다. 에이전트의 페르소나, 어조, 준수해야 하는 규칙, 자신을 표현하는 방법을 규정합니다. 잘 만들어진 지침은 일반적인 챗봇과 믿을 수 있고 일관된 캐릭터의 차이입니다. 따라서 만들려는 프롬프트는 이 페르소나를 에이전트의 뇌에 직접 삽입하므로 매우 중요합니다.
👉✨ Antigravity 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]
새 페르소나 테스트
Antigravity CLI가 character.py의 업데이트된 코드를 생성합니다. 서버가 새 에이전트 구성을 선택하도록 하려면 Antigravity CLI에 다시 시작하도록 요청해 보겠습니다.
👉✨ Antigravity CLI 프롬프트에서 다음 요청을 붙여넣습니다.
Please restart the Python web server for me.
👀 웹 미리보기에서 컴패니언과 대화합니다. how are you?라고 질문합니다. 이제 응답이 디자인한 고유한 캐릭터와 완벽하게 일치해야 합니다.
API 비율 제한에 대한 재시도 처리 추가 (선택사항이지만 권장됨)
워크숍 또는 동시 사용량이 많은 기간에는 API 비율 제한 오류 (HTTP 429: 리소스 소진)가 발생할 수 있습니다. 컴패니언이 계속 응답하고 비율 제한 예외를 자동으로 처리하도록 하려면 Google GenAI SDK 클라이언트 옵션에 직접 빌드된 재시도 옵션을 구성하면 됩니다.
👉✨ Antigravity CLI 프롬프트에서 다음 요청을 붙여넣습니다.
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.
CLI가 클라이언트 수준 재시도 정책을 사용하여 비율 제한을 자동으로 처리하도록 character.py 파일을 수정합니다. 파일을 업데이트한 후 CLI에 웹 서버를 다시 시작하도록 요청하는 것을 잊지 마세요.
Please restart the Python web server for me.
5. 최근 이벤트에 대한 그라운딩 추가
이제 에이전트가 페르소나로 가득하지만 중요한 제한사항이 있습니다. 지식은 학습한 데이터를 기반으로 시간이 지나면 오래된 정보가 됩니다. 어제 뉴스나 최근 발견에 관해 알려줄 수 없습니다. 이 문제를 해결하기 위해 에이전트에 도구 를 제공합니다.
도구를 에이전트에 부여하는 초능력 또는 특수 능력이라고 생각하면 됩니다. 에이전트는 자체적으로만 말할 수 있습니다. 검색 도구를 사용하면 인터넷을 탐색할 수 있습니다. 캘린더 도구를 사용하면 일정을 확인할 수 있습니다. 기술적으로 도구는 에이전트가 사용자 요청에 답변하기에 자체 지식이 충분하지 않다고 판단할 때 지능적으로 선택하여 사용할 수 있는 특정 함수 또는 API입니다.
고급 시스템에서는 MCP (모델 컨텍스트 프로토콜) 서버 와 같은 외부 시스템에서 도구를 제공할 수 있습니다. 하지만 이 단계에서는 별도의 서버가 필요하지 않습니다. ADK에는 에이전트의 기능에 쉽게 추가할 수 있는 강력한 사전 빌드된 google_search 도구가 함께 제공됩니다.
컴패니언에게 Google 검색의 기능을 제공해 보겠습니다.
👉 Cloud Shell 편집기에서 companion-python 아래의 character.py를 열고 다음과 같이 수정합니다.
- 에서
google_search를google.adk.tools가져옵니다. tools목록을LlmAgent생성자에 추가합니다.instruction을 업데이트 하여 컴패니언에게 새 도구를 사용할 시기 를 명시적으로 알려줍니다.
# 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
)
그라운딩된 에이전트 테스트
웹 서버가 google_search 도구로 새 코드를 로드하도록 하려면 Antigravity CLI에 다시 시작하도록 요청합니다.
👉✨ Antigravity CLI 프롬프트에서 다음 요청을 붙여넣습니다.
Please restart the Python web server for me.
👉 웹 미리보기에서 다음과 같이 최신 지식이 필요한 질문을 합니다.
Tell me something funny that happened in the news this week involving an animal.
👉 이제 에이전트는 모른다고 말하는 대신 검색 도구를 사용하여 최신 정보를 찾고 고유한 어조로 유용하고 그라운딩된 요약을 제공합니다.
6. 컴패니언의 디자인 맞춤설정
이제 컴패니언에게 뇌가 있으므로 고유한 얼굴을 제공해 보겠습니다. Antigravity CLI에는 이미지 생성 기능이 기본으로 제공되므로 Antigravity CLI에 직접 아바타를 생성하도록 요청하면 됩니다.
컴패니언의 고유한 디자인을 만들 수 있는 기회입니다. 스타일, 표현, 이전에 만든 페르소나에 맞는 기타 세부정보를 생각해 보세요.
👉✨ Antigravity 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.
이 도구는 입을 벌린 이미지와 입을 다문 이미지 세트를 생성하고 프로젝트의 static/images 디렉터리에 자동으로 저장합니다.
이제 시각적으로 맞춤설정된 컴패니언과 상호작용할 수 있습니다.
축하합니다.
정교한 AI 컴패니언을 성공적으로 빌드했습니다. 기본 앱으로 시작하여 Antigravity CLI를 사용하여 에이전트를 스캐폴딩하고, 풍부한 페르소나를 제공하고, 실시간 정보에 액세스하고 자체 아바타를 생성할 수 있는 도구를 제공했습니다. 이제 훨씬 더 복잡하고 유능한 AI 에이전트를 빌드할 준비가 되었습니다.
👉💻 마무리하고 세션을 종료하려면 터미널로 돌아가서 agy 프롬프트에 /exit를 입력하여 Antigravity CLI를 종료합니다.
/exit