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

ADK로 AI 에이전트 빌드: 기초

1. 시작하기 전에

'ADK로 AI 에이전트 빌드' 시리즈의 첫 번째 파트에 오신 것을 환영합니다. 이 실습 Codelab 시리즈에서는 Google의 에이전트 개발 키트 (ADK)를 사용하여 나만의 지능형 AI 에이전트를 만드는 흥미로운 여정을 시작합니다.

개발 환경을 설정하고 기본적인 대화형 에이전트를 만드는 방법을 안내하는 등 절대적으로 필요한 사항부터 시작합니다. 이 Codelab을 마치면 첫 번째 대화형 AI를 빌드하게 됩니다. 이 AI는 이 시리즈의 후속 파트에서 정교한 멀티 에이전트 시스템 (MAS)으로 변환되면서 확장될 예정입니다.

로컬 환경 또는 Google Cloud에서 이 Codelab을 완료할 수 있습니다. 일관된 환경을 위해서는 Google Cloud 환경에서 Cloud Shell을 사용하는 것이 좋습니다. Cloud Shell은 $HOME 디렉터리에 5GB의 영구 스토리지도 제공합니다. 스크립트, 구성 파일 또는 클론된 저장소를 저장하는 데 유용합니다.

기본 요건

생성형 AI 개념에 대한 이해
Python 프로그래밍에 대한 기본적인 숙련도
명령줄 / 터미널에 대한 지식

학습할 내용

Python 환경을 설정하는 방법
ADK를 사용하여 간단한 개인 비서 에이전트를 만드는 방법
에이전트를 실행, 테스트, 디버그하는 방법

필요한 항목

작동하는 컴퓨터와 안정적인 Wi-Fi
Google Cloud 콘솔에 액세스하기 위한 브라우저(예: Chrome)
호기심과 학습에 대한 열의

무료 체험 결제 계정 사용

이 Codelab을 완료하려면 활성 상태의 Google Cloud 결제 계정도 필요합니다. 아직 없는 경우 다음 단계에 따라 무료 체험 결제 계정을 사용하세요.

브라우저에서 시크릿 창을 엽니다.
이 신청 포털로 이동합니다.
개인 Gmail 계정을 사용하여 로그인합니다.
포털의 단계별 안내를 따릅니다.

2. 소개

생성형 AI (GenAI)의 세계는 빠르게 발전하고 있으며 현재 AI 에이전트가 큰 관심을 받고 있습니다. AI 에이전트는 개인 비서와 마찬가지로 사용자를 대신하여 작업을 수행하도록 설계된 스마트 컴퓨터 프로그램입니다. 디지털 환경을 인식하고, 결정을 내리고, 직접적인 인간의 통제 없이 특정 목표를 달성하기 위해 행동을 취할 수 있습니다. 학습하고 적응하여 작업을 완료할 수 있는 사전 대응적이고 자율적인 엔티티라고 생각하면 됩니다.

기본적으로 AI 에이전트는 대규모 언어 모델 (LLM)을 '두뇌'로 사용하여 이해하고 추론합니다. 이를 통해 텍스트, 이미지, 소리 등 다양한 소스의 정보를 처리할 수 있습니다. 그런 다음 에이전트는 이 이해를 바탕으로 계획을 세우고 일련의 작업을 실행하여 사전 정의된 목표를 달성합니다.

이제 에이전트 개발 키트 (ADK)와 같은 바로 사용할 수 있는 프레임워크 덕분에 깊은 전문 지식이 없어도 AI 에이전트를 쉽게 빌드할 수 있습니다. 이 여정은 작업을 지원하는 개인 어시스턴트 에이전트를 구성하는 것으로 시작합니다. 지금부터 시작하겠습니다

3. Google Cloud 서비스 구성

Google Cloud 프로젝트 만들기

이 Codelab의 활동이 이 새 프로젝트 내에서만 격리되도록 새 Google Cloud 프로젝트를 만듭니다.

console.cloud.google.com/projectcreate로 이동합니다.
필수 정보를 입력합니다.

프로젝트 이름 - 원하는 이름을 입력할 수 있습니다 (예: genai-workshop).
위치 - 조직 없음으로 유지합니다.
결제 계정 - 이 옵션이 표시되면 Google Cloud Platform 평가판 결제 계정을 선택합니다. 이 옵션이 표시되지 않더라도 걱정하지 마세요. 다음 단계로 진행하세요.

생성된 프로젝트 ID를 복사해 둡니다. 나중에 필요합니다.

모든 것이 올바르면 만들기 버튼을 클릭합니다.

Cloud Shell 구성

프로젝트가 성공적으로 생성되면 다음 단계에 따라 Cloud Shell을 설정합니다.

1. Cloud Shell 실행

shell.cloud.google.com으로 이동하고 승인을 요청하는 팝업이 표시되면 승인을 클릭합니다.

2. 프로젝트 ID 설정

Cloud Shell 터미널에서 다음 명령어를 실행하여 올바른 프로젝트 ID를 설정합니다. <your-project-id>를 위의 프로젝트 생성 단계에서 복사한 실제 프로젝트 ID로 바꿉니다.

gcloud config set project <your-project-id>

이제 Cloud Shell 터미널에서 올바른 프로젝트가 선택되어 있는 것을 확인할 수 있습니다. 선택한 프로젝트 ID가 노란색으로 강조 표시됩니다.

3. 필요한 API 사용 설정

Google Cloud 서비스를 사용하려면 먼저 프로젝트에 대해 해당 API를 활성화해야 합니다. Cloud Shell 터미널에서 아래 명령어를 실행하여 이 Codelab의 서비스를 사용 설정합니다.

gcloud services enable aiplatform.googleapis.com

작업이 성공하면 터미널에 Operation/... finished successfully가 출력됩니다.

4. Python 가상 환경을 만듭니다.

Python 프로젝트를 시작하기 전에 가상 환경을 만드는 것이 좋습니다. 이렇게 하면 프로젝트의 종속 항목이 격리되어 다른 프로젝트나 시스템의 전역 Python 패키지와의 충돌을 방지할 수 있습니다.

1. 프로젝트 디렉터리를 만들고 해당 디렉터리로 이동합니다.

mkdir ai-agents-adk
cd ai-agents-adk

2. 가상 환경을 만들고 활성화합니다.

uv venv --python 3.12
source .venv/bin/activate

터미널 프롬프트 앞에 (ai-agents-adk)가 표시되어 가상 환경이 활성화되었음을 나타냅니다.

3. ADK 설치 페이지

uv pip install google-adk

5. 에이전트 만들기

환경이 준비되었으므로 이제 AI 에이전트의 기반을 만들 차례입니다. ADK에는 에이전트의 로직과 구성을 정의하는 몇 가지 파일이 필요합니다.

agent.py: 에이전트의 기본 Python 코드가 포함되어 있으며, 에이전트의 이름, 사용하는 LLM, 핵심 지침을 정의합니다.
__init__.py: 디렉터리를 Python 패키지로 표시하여 ADK가 에이전트 정의를 검색하고 로드하도록 지원합니다.
.env: API 키, 프로젝트 ID, 위치와 같은 민감한 정보와 구성 변수를 저장합니다.

이 명령어는 필수 파일 3개가 포함된 personal_assistant라는 새 디렉터리를 만듭니다.

adk create personal_assistant

명령어가 실행되면 에이전트를 구성하기 위해 몇 가지 옵션을 선택하라는 메시지가 표시됩니다.

첫 번째 단계에서는 옵션 1을 선택하여 대화형 작업에 적합한 빠르고 효율적인 모델인 gemini-2.5-flash 모델을 사용합니다.

Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1

두 번째 단계에서는 Google Cloud의 강력한 관리형 AI 플랫폼인 Vertex AI (옵션 2)를 백엔드 서비스 제공업체로 선택합니다.

1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

그런 다음 대괄호 [...] 에 표시된 프로젝트 ID가 올바르게 설정되어 있는지 확인해야 합니다. 그렇다면 Enter 키를 누릅니다. 그렇지 않으면 다음 프롬프트에 올바른 프로젝트 ID를 입력합니다.

Enter Google Cloud project ID [your-project-id]:

마지막으로 다음 질문에서 Enter 키를 누릅니다. 그러면 이 Codelab의 리전으로 us-central1가 사용됩니다.

Enter Google Cloud region [us-central1]:

터미널에 다음과 비슷한 출력이 표시됩니다.

Agent created in /home/<your-username>/ai-agent-adk/personal_assistant:
- .env
- __init__.py
- agent.py

6. 상담사 코드 살펴보기

생성된 파일을 보려면 Cloud Shell 편집기에서 ai-agents-adk 폴더를 엽니다.

상단 메뉴에서 파일 > 폴더 열기...를 클릭합니다.
ai-agents-adk 폴더를 찾아 선택합니다.
확인을 클릭합니다.

상단 메뉴 바가 표시되지 않으면 폴더 아이콘을 클릭하고 폴더 열기를 선택해도 됩니다.

에디터 창이 완전히 로드되면 personal-assistant 폴더로 이동합니다. 위에서 언급한 필수 파일 (agent.py, __init__.py, .env)이 표시됩니다.

.env 파일은 기본적으로 숨겨져 있는 경우가 많습니다. Cloud Shell 편집기에 표시하려면 다음 단계를 따르세요.

상단의 메뉴 바로 이동합니다.
보기를 클릭하고
숨김 파일 전환을 선택합니다.

각 파일의 콘텐츠를 살펴봅니다.

agent.py

이 파일은 google.adk.agents 라이브러리의 Agent 클래스를 사용하여 에이전트를 인스턴스화합니다.

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

from google.adk.agents import Agent: 이 줄은 ADK 라이브러리에서 필요한 Agent 클래스를 가져옵니다.
root_agent = Agent(...): 여기서는 AI 에이전트의 인스턴스를 만듭니다.
name="root_agent": 에이전트의 고유 식별자입니다. ADK가 에이전트를 인식하고 참조하는 방식입니다.
model="gemini-2.5-flash": 이 중요한 매개변수는 에이전트가 이해, 추론, 응답 생성의 기본 '두뇌'로 사용할 대규모 언어 모델 (LLM)을 지정합니다. gemini-2.5-flash는 대화형 작업에 적합한 빠르고 효율적인 모델입니다.
description="...": 에이전트의 목적이나 기능을 간략하게 요약합니다. 설명은 사람이 이해하거나 멀티 에이전트 시스템의 다른 에이전트가 이 특정 에이전트가 하는 일을 이해하기 위한 것입니다. 로깅, 디버깅 또는 에이전트에 관한 정보를 표시할 때 자주 사용됩니다.
instruction="...": 에이전트의 동작을 안내하고 페르소나를 정의하는 시스템 프롬프트입니다. LLM에 어떻게 행동해야 하는지, 기본 목적이 무엇인지 알려줍니다. 이 경우 에이전트를 '유용한 어시스턴트'로 설정합니다. 이 명령은 에이전트의 대화 스타일과 기능을 형성하는 데 중요합니다.

init.py

이 파일은 Python이 personal-assistant를 패키지로 인식하여 ADK가 agent.py 파일을 올바르게 가져올 수 있도록 하는 데 필요합니다.

from . import agent

from . import agent: 이 줄은 상대 가져오기를 실행하여 Python에 현재 패키지 (personal-assistant) 내에서 agent (agent.py에 해당)라는 모듈을 찾도록 지시합니다. 이 간단한 줄을 통해 ADK가 personal-assistant 에이전트를 로드하려고 할 때 agent.py에 정의된 root_agent를 찾아 초기화할 수 있습니다. 비어 있더라도 __init__.py가 있으면 디렉터리가 Python 패키지가 됩니다.

.env

이 파일에는 환경별 구성과 민감한 사용자 인증 정보가 포함되어 있습니다.

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION

GOOGLE_GENAI_USE_VERTEXAI: 생성형 AI 작업에 Google의 Vertex AI 서비스를 사용할 것임을 ADK에 알립니다. 이는 Google Cloud의 관리형 서비스와 고급 모델을 활용하는 데 중요합니다.
GOOGLE_CLOUD_PROJECT: 이 변수는 Google Cloud 프로젝트의 고유 식별자를 보유합니다. ADK는 에이전트를 클라우드 리소스와 올바르게 연결하고 결제를 사용 설정하기 위해 이 정보가 필요합니다.
GOOGLE_CLOUD_LOCATION: Vertex AI 리소스가 있는 Google Cloud 리전을 지정합니다 (예: us-central1). 올바른 위치를 사용하면 에이전트가 해당 리전의 Vertex AI 서비스와 효과적으로 통신할 수 있습니다.

7. 터미널에서 에이전트 실행

세 파일이 모두 준비되면 터미널에서 직접 에이전트를 실행할 수 있습니다. 이렇게 하려면 터미널에서 다음 adk run 명령어를 실행하세요.

adk run personal_assistant

모든 것이 올바르게 설정되어 있다면 터미널에 다음과 비슷한 출력이 표시됩니다. [user]:가 표시되면 경고는 무시하고 계속 진행해도 됩니다.

...
Running agent personal_assistant, type exit to exit.
[user]: 
...

에이전트와 채팅을 시작하세요. 'hello. What can you do for me?(무엇을 도와드릴까요?)'라고 물으면 대답이 돌아옵니다.

...
Running agent personal_assistant, type exit to exit.
[user]: hello. What can you do for me?
[personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as:
...

출력이 마크다운으로 서식이 지정되는 경우가 있는데, 터미널에서 읽기 어려울 수 있습니다. 다음 단계에서는 개발 UI를 사용하여 채팅 애플리케이션과 유사한 훨씬 풍부한 환경을 제공합니다.

문제 해결

이 API 메서드를 사용하려면 결제를 사용 설정해야 합니다

{‘message': ‘This API method requires billing to be enabled'}라는 메시지가 표시되면 다음 단계를 따르세요.

.env 파일에서 올바른 프로젝트 ID를 사용하고 있는지 확인합니다.
연결된 결제 계정 페이지로 이동하여 결제 계정이 이미 연결되어 있는지 확인합니다.
그렇지 않은 경우 옵션에서 Google Cloud Platform 평가판 결제 계정을 선택합니다.

프로젝트에서 Vertex AI API가 사용되지 않음

{'message': 'Vertex AI API has not been used in project...'}이 포함된 오류 메시지가 표시되면 터미널에 다음을 입력하여 Vertex AI API를 사용 설정합니다.

gcloud services enable aiplatform.googleapis.com

작업이 성공하면 터미널에 Operation/... finished successfully가 출력됩니다.

기타 오류

위에 언급되지 않은 다른 오류가 발생하면 브라우저에서 Cloud Shell 탭을 새로고침하고 메시지가 표시되면 다시 승인해 보세요.

8. 개발 웹 UI에서 에이전트 실행

에이전트 개발 키트는 개발 UI를 사용하여 에이전트를 채팅 애플리케이션으로 실행하는 편리한 방법도 제공합니다. adk run. 대신 adk web 명령어를 사용하기만 하면 됩니다.

터미널에서 여전히 adk run이 실행 중인 경우 exit를 입력하여 닫은 후 다음 명령어를 입력합니다.

adk web

터미널에 다음과 비슷한 출력이 표시됩니다.

...
INFO:     Started server process [4978]
INFO:     Waiting for application startup.

+------------------------------------------------------+
| ADK Web Server started                               |
|                                                      |
| For local testing, access at http://localhost:8000.  |
+------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

개발 UI에 액세스하는 방법에는 두 가지 옵션이 있습니다.

터미널을 통해 열기

링크를 Ctrl + 클릭 또는 Cmd + 클릭합니다 (예: http://localhost:8000)와 같이 표시됩니다.

웹 미리보기를 통해 열기

웹 미리보기 버튼을 클릭합니다.
포트 변경을 선택합니다.
포트 번호 (예: 8000)
변경 및 미리보기를 클릭합니다.

그러면 채팅 애플리케이션과 유사한 UI가 브라우저에 표시됩니다. 이 인터페이스를 통해 개인 어시스턴트와 채팅하세요.

이제 마크다운 형식이 올바르게 표시되며 이 UI를 사용하면 각 메시지 이벤트, 상담사의 상태, 사용자 요청 등을 디버그하고 조사할 수도 있습니다. 즐겁게 채팅하세요!

9. 정리 (선택사항)

이 Codelab에는 장기 실행 제품이 포함되지 않으므로 터미널에서 Ctrl + C 또는 Cmd + C를 눌러 활성 에이전트 세션 (예: 터미널의 adk web 인스턴스)을 중지하면 됩니다.

에이전트 프로젝트 폴더 및 파일 삭제

Cloud Shell 환경에서만 코드를 삭제하려면 다음 명령어를 사용하세요.

cd ~
rm -rf ai-agents-adk

Vertex AI API 사용 중지

이전에 사용 설정한 Vertex AI API를 사용 중지하려면 다음 명령어를 실행하세요.

gcloud services disable aiplatform.googleapis.com

전체 Google Cloud 프로젝트 종료

Google Cloud 프로젝트를 완전히 종료하려면 공식 가이드에서 자세한 안내를 참고하세요.

10. 결론

축하합니다. 에이전트 개발 키트 (ADK)를 사용하여 간단한 개인 비서 에이전트를 성공적으로 빌드했습니다. 이제 ADK 에이전트의 핵심 구성요소에 대한 견고한 토대와 이해를 갖추었습니다.

다음 단계로 실시간 정보에 액세스하고 외부 서비스와 상호작용할 수 있는 도구를 제공하여 에이전트의 기능을 크게 확장할 수 있습니다. 여정을 계속하고 싶다면 이 시리즈의 다음 Codelab인 ADK로 AI 에이전트 빌드: 도구로 역량 강화에서 이 프로세스를 안내합니다.