이 페이지는 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)
결제가 사용 설정된 Google Cloud 프로젝트
호기심과 학습에 대한 열의

2. 소개

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

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

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

3. Google Cloud 서비스 설정

Google Cloud 프로젝트 만들기

이 Codelab에서는 결제가 사용 설정된 Google Cloud 프로젝트를 이미 만들었다고 가정합니다. 아직 프로젝트가 없다면 다음 단계에 따라 프로젝트를 만드세요.

Google Cloud 프로젝트 선택 또는 만들기

Google Cloud 콘솔로 이동합니다.
상단에서 프로젝트 선택기 드롭다운 (Google Cloud 로고 옆)을 클릭합니다.
기존 프로젝트를 선택하거나 새 프로젝트를 만듭니다.

결제 사용 설정

선택한 Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.
Google Cloud Billing 문서의 안내에 따라 프로젝트에 결제가 사용 설정되어 있는지 확인할 수 있습니다.

Cloud Shell 구성

이제 Google Cloud 콘솔 내에서 바로 사용할 수 있는 편리한 명령줄 인터페이스인 Cloud Shell에서 올바르게 설정되어 있는지 확인해 보겠습니다.

Cloud Shell 실행

Google Cloud 콘솔의 오른쪽 상단에 터미널과 같은 아이콘 (>_)이 표시됩니다. 이 아이콘을 클릭하여 Cloud Shell을 활성화합니다.

액세스 승인

메시지가 표시되면 승인을 클릭하여 Google Cloud 프로젝트와 상호작용하는 데 필요한 권한을 Cloud Shell에 부여합니다.

계정 확인:

Cloud Shell이 로드되면 올바른 Google Cloud 계정을 사용하고 있는지 확인합니다. 다음 명령어를 실행합니다.

gcloud auth list

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

Credentialed Accounts

ACTIVE: *
ACCOUNT: current_account@example.com

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

계정 전환 (필요한 경우):

활성 계정이 이 Codelab에 사용할 계정이 아닌 경우 다음 명령어를 사용하여 올바른 계정으로 전환합니다. <your_desired_account@example.com>을 이 실습에 사용할 실제 이메일로 바꿉니다.

gcloud config set account <your_desired_account@example.com

프로젝트 확인

다음으로 Cloud Shell이 올바른 Google Cloud 프로젝트를 사용하도록 구성되었는지 확인합니다. 실행:

gcloud config list project

구성 목록이 표시됩니다. [core] 섹션을 찾아 프로젝트 값이 이 Codelab에 사용할 Google Cloud 프로젝트의 ID와 일치하는지 확인합니다.

[core]
project = <current-project-id>

프로젝트 설정 (필요한 경우)

project ID 값이 올바르지 않으면 다음 명령어를 사용하여 원하는 프로젝트로 설정합니다.

gcloud config set project <your-desired-project-id>

필요한 API 사용 설정

Google Cloud 서비스를 사용하려면 먼저 프로젝트에 대해 해당 API를 활성화해야 합니다. Cloud Shell 터미널에서 아래 명령어를 실행하면 이 Codelab에 필요한 모든 서비스를 사용할 수 있습니다.

gcloud services enable aiplatform.googleapis.com

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

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

Python 프로젝트를 시작하기 전에 가상 환경을 만드는 것이 좋습니다. 이렇게 하면 프로젝트의 종속 항목이 격리되어 다른 프로젝트나 시스템의 전역 Python 패키지와의 충돌을 방지할 수 있습니다. 에이전트 개발 키트 (ADK)에는 Python 3.9 이상이 필요하므로 uv와 같은 도구를 사용하여 가상 환경을 관리하고 올바른 Python 버전이 사용되도록 합니다.

uv은 Python 프로젝트와 환경을 관리하는 최신식의 빠르고 효율적인 도구로, 기존에 pip, venv, pip-tools, pipx과 같은 도구에서 제공되던 기능을 결합합니다. 속도를 위해 Rust로 작성되었습니다.

Cloud Shell에는 이미 uv가 제공되므로 바로 시작할 수 있습니다.

uv가 올바르게 설치되었는지 확인

uv --version

AI 에이전트의 새 프로젝트 폴더 만들기

uv init ai-agents-adk
cd ai-agents-adk

Python 3.12로 가상 환경 만들기

uv venv --python 3.12

가상 환경 내에 Google ADK 라이브러리 설치

uv add google-adk

google-adk 패키지가 성공적으로 설치되었는지 확인

uv pip list | grep google-adk

google-adk와 버전이 포함된 출력 줄이 표시되면 다음 단계로 진행해도 됩니다.

5. 에이전트 만들기

이제 개발 환경이 설정되었으므로 AI 에이전트의 기반을 마련할 차례입니다. 에이전트 개발 키트 (ADK)는 이 프로세스를 간소화하여 에이전트의 핵심 로직과 구성을 정의하는 데 몇 가지 필수 파일만 있으면 됩니다.

이 세 파일은 함께 작동하여 에이전트를 검색 가능하고 실행 가능하며 구성 가능하게 만듭니다.

agent.py: 에이전트의 핵심입니다. 여기에는 이름, '브레인'으로 사용하는 대규모 언어 모델 (LLM), 응답을 안내하는 핵심 명령어를 비롯해 에이전트의 동작을 정의하는 기본 Python 코드가 포함됩니다.
__init__.py: Python에서 __init__.py 파일은 디렉터리를 Python 패키지로 표시합니다. ADK의 경우 프레임워크가 agent.py에서 에이전트 정의를 검색하고 로드하는 데 도움이 되므로 중요합니다. 간단한 ADK 프로젝트에서는 agent 모듈을 가져오는 단일 행이 포함되어 ADK 러너가 에이전트에 액세스할 수 있도록 합니다.
.env: 이 파일('환경'의 약자)은 API 키, 프로젝트 ID, 지리적 위치와 같이 에이전트에 필요한 민감한 정보와 구성 변수를 저장하는 데 사용됩니다. 이러한 세부정보를 별도의 .env 파일에 보관하는 것은 보안 및 이식성을 위한 권장사항입니다. 이렇게 하면 민감한 데이터를 코드에 직접 하드코딩하는 것을 방지할 수 있습니다. 또한 기본 에이전트 로직을 수정하지 않고도 구성을 쉽게 변경할 수 있습니다.

아래 명령어를 사용하여 개인 비서 에이전트 전용 폴더 내에 이러한 파일을 만듭니다.

uv run 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

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

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

마지막으로 Google Cloud 프로젝트 ID와 리전을 확인하라는 메시지가 표시됩니다. 미리 채워진 값 (current-project-id 및 current-region)을 사용하려면 각 질문에 대해 Enter를 누르세요.

Enter Google Cloud project ID [current-project-id]: 
Enter Google Cloud region [current-region]:

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

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

이제 Cloud Shell 창 상단에 있는 편집기 열기 버튼을 클릭합니다. 이 버튼을 클릭하면 편집기 창으로 이동하여 파일의 콘텐츠를 훨씬 쉽게 탐색할 수 있습니다. 전환하는 데 시간이 걸릴 수 있습니다. 로드 화면이 몇 분 이상 멈춰 있으면 브라우저를 새로고침해 보세요.

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

폴더에 .env 파일이 표시되지 않으면 상단의 메뉴 바로 이동하여 보기를 클릭한 다음 숨김 파일 전환을 선택합니다. .env 파일은 실수로 노출되지 않도록 기본적으로 숨겨져 있는 경우가 많으므로 이는 일반적인 설정입니다.

각 파일의 콘텐츠를 살펴보겠습니다.

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="personal_assistant": 에이전트의 고유 식별자입니다. 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 서비스와 효과적으로 통신할 수 있습니다.

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

세 파일이 모두 준비되면 터미널에서 직접 에이전트를 실행할 수 있습니다. 이렇게 하려면 터미널 창을 열어야 합니다. 메뉴 바에서 터미널을 클릭한 다음 새 터미널을 선택하면 됩니다.

터미널을 사용할 수 있게 되면 adk run 명령어를 사용하여 에이전트를 시작할 수 있습니다. 새 터미널 창이고 uv를 사용하므로 먼저 ai-agent-adk 폴더로 이동한 다음 adk run 명령어에 uv run를 접두사로 추가해야 합니다.

터미널에 다음 명령어를 입력합니다.

cd ai-agents-adk
uv run adk run personal_assistant

모든 것이 올바르게 설정되어 있다면 터미널에 다음과 비슷한 출력이 표시됩니다.

...
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를 사용하여 채팅 애플리케이션과 유사한 훨씬 풍부한 환경을 제공합니다.

7. 개발 UI에서 에이전트 실행

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

이전 세션에 아직 있는 경우 터미널에 exit를 입력하여 닫습니다. 이전 세션이 닫히면 터미널에 다음 명령어를 입력합니다.

uv run 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에 액세스하는 방법에는 두 가지가 있습니다.

터미널을 통해 열기

URL (예: http://localhost:8000)를 실행합니다.

웹 미리보기를 통해 열기

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

그러면 채팅 애플리케이션과 유사한 UI가 브라우저에 표시됩니다. 이 인터페이스를 통해 개인 어시스턴트와 채팅하세요. 이제 마크다운 형식이 올바르게 표시되며 이 UI를 사용하면 각 메시지 이벤트, 상담사의 상태, 사용자 요청 등을 디버그하고 조사할 수도 있습니다. 즐겁게 채팅하세요!

8. 삭제

이 Codelab에는 장기 실행 제품이 포함되지 않으므로 터미널에서 Ctrl + 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 프로젝트를 완전히 종료하려면 공식 가이드에서 자세한 안내를 참고하세요.

9. 결론

축하합니다. 에이전트 개발 키트 (ADK)를 사용하여 간단한 개인 비서 에이전트를 성공적으로 빌드했습니다.

눈치채셨겠지만 이 개인 어시스턴트 에이전트는 아직 기능이 뛰어나지 않습니다 (예: 최신 정보를 위해 인터넷에 액세스할 수 없음). 이 'ADK로 AI 에이전트 빌드' 시리즈의 다음 Codelab에서는 함수와 도구를 사용하여 개인 어시스턴트 에이전트를 강화하는 방법을 알아봅니다. 다음 Codelab에서 뵙겠습니다!