1. 시작하기 전에
Vertex AI란 무엇인가요?
Vertex AI는 엔터프라이즈급 AI 에이전트와 애플리케이션을 빌드, 배포, 확장하기 위한 Google Cloud의 통합 개발 플랫폼입니다. 개발자와 데이터 과학자에게 글로벌 규모 인프라와 긴밀하게 통합된 맞춤형 에이전트형 워크플로를 설계하는 데 필요한 정교한 도구를 제공합니다.
- Model Garden 액세스: 전체 Gemini 제품군, 서드 파티 모델, 전문 오픈소스 모델을 비롯한 150개 이상의 파운데이션 모델 중에서 선택하여 특정 에이전트 작업에 적합한 모델을 찾습니다.
- 복잡한 조정 설계: Vertex AI는 추론을 사용하여 계획하고, 다단계 작업을 실행하고, 외부 API를 호출하는 자율 에이전트를 설계하는 프레임워크를 제공합니다.
- 엔터프라이즈급 그라운딩: 고성능 RAG (검색 증강 생성)를 비롯한 실시간 비즈니스 데이터에 에이전트를 연결하여 할루시네이션을 없애고 사실의 정확성을 보장합니다.
- DevOps: 강력한 SDK, API, 평가 도구를 사용하여 에이전트 개발을 기존 CI/CD 파이프라인에 원활하게 통합하여 에이전트 성능과 안전성을 대규모로 측정합니다.
- 산업 수준의 보안: Vertex AI는 학습 또는 그라운딩에 사용되는 고객 데이터가 비공개로 유지되고 암호화되며 전 세계 데이터 상주 요건을 준수하도록 보장합니다.
- 최적화된 인프라: Google의 세계적 수준의 TPU 및 GPU 클러스터에서 에이전트 워크로드를 손쉽게 확장하여 가장 까다로운 글로벌 애플리케이션에서도 지연 시간이 짧은 성능을 보장합니다.
Google Workspace란 무엇인가요?
Google Workspace는 개인, 학교, 비즈니스를 위해 설계된 클라우드 기반 생산성 및 공동작업 솔루션 모음입니다.
- 커뮤니케이션: 전문 이메일 서비스 (Gmail), 화상 회의 (Meet), 팀 메시지 (Chat)
- 콘텐츠 제작: 문서 작성 (Docs), 스프레드시트 빌드 (Sheets), 프레젠테이션 디자인 (Slides)을 위한 도구입니다.
- 정리: 공유 캘린더 (Calendar) 및 디지털 메모 (Keep)
- 스토리지: 파일을 안전하게 저장하고 공유할 수 있는 중앙 집중식 클라우드 공간 (Drive)
- 관리: 사용자 및 보안 설정을 관리하는 관리 컨트롤 (Workspace 관리 콘솔)
어떤 종류의 맞춤 통합인가요?
Google Workspace와 Vertex AI는 Workspace가 실시간 데이터와 공동작업 컨텍스트를 제공하고 Vertex AI가 지능형 워크플로를 자동화하는 데 필요한 모델, 에이전트 추론, 오케스트레이션을 제공하는 강력한 피드백 루프를 만듭니다.
- 스마트 연결: Google 관리 데이터 저장소, API, MCP 서버 (Google 관리 및 맞춤)를 통해 상담사는 Workspace 데이터에 안전하고 원활하게 액세스하고 사용자를 대신하여 조치를 취할 수 있습니다.
- 맞춤 에이전트: 팀은 노 코드 디자이너 또는 프로 코드 프레임워크를 사용하여 관리자가 관리하는 Workspace 데이터 및 작업을 기반으로 하는 전문 에이전트를 빌드할 수 있습니다.
- 기본 통합: Workspace 부가기능은 전용 UI 구성요소 또는 백그라운드 프로세스를 통해 AI 시스템과 Chat, Gmail과 같은 애플리케이션 간의 격차를 해소합니다. 이를 통해 상담사는 사용자가 있는 곳에서 즉각적이고 상황에 맞는 지원을 제공할 수 있습니다.
Google Workspace의 강력한 생산성 생태계를 Vertex AI의 고급 에이전트 기능과 결합하면 조직은 팀이 이미 매일 사용하고 있는 도구 내에서 복잡한 워크플로를 직접 자동화하는 맞춤형 데이터 기반 AI 에이전트를 통해 운영을 혁신할 수 있습니다.
기본 요건
자체 환경에서 모든 단계를 따르려면 다음이 필요합니다.
- Google Cloud 및 Python에 대한 기본 지식
- 결제가 사용 설정되어 있고 내가 소유자인 Google Cloud 프로젝트 기존 프로젝트에 결제가 사용 설정되어 있는지 확인하려면 프로젝트의 결제 상태 확인을 참고하세요. 프로젝트를 만들고 청구를 설정하려면 Google Cloud 프로젝트 만들기를 참고하세요. 프로젝트 소유권을 변경하려면 프로젝트 구성원 관리 또는 프로젝트 소유권 변경을 참고하세요.
- Google Chat 및 스마트 기능이 사용 설정되어 있는 Business 또는 Enterprise Google Workspace 계정
- Google Cloud 프로젝트에 Google Cloud CLI가 설치되고 초기화되어 있어야 합니다.
- Python 3.11 이상이 설치되어 있어야 합니다. 공식 Python 웹사이트의 안내를 참고하세요.
빌드 대상
이 Codelab에서는 Google Workspace와 긴밀하게 통합된 Vertex AI 에이전트를 사용하여 세 가지 솔루션을 빌드합니다. 데이터, 작업, UI와 상호작용하는 데 사용할 수 있는 아키텍처 패턴을 보여줍니다.
Vertex AI Search 앱
이 에이전트를 사용하면 사용자가 자연어로 Workspace의 데이터를 검색하고 작업을 수행할 수 있습니다. 다음 요소를 사용합니다.
- 모델: Gemini
- 데이터 및 작업: Google Workspace (Calendar, Gmail, Drive)용 Vertex AI 데이터 스토어
- 에이전트 호스트: Vertex AI Search
- UI: Vertex AI Search 웹 위젯

맞춤 에이전트
이 에이전트를 사용하면 사용자가 맞춤 도구와 규칙을 사용하여 자연어로 Workspace의 데이터를 검색하고 작업을 수행할 수 있습니다. 다음 요소를 사용합니다.
- 모델: Gemini
- 데이터 및 작업: Google Workspace (Calendar, Gmail, Drive)용 Vertex AI 데이터 스토어, Google 관리형 Vertex AI Search 모델 컨텍스트 프로토콜 (MCP) 서버, Google Chat 메시지를 전송하는 맞춤 도구 기능 (Google Chat API를 통해)
- 에이전트 빌드 도구: 에이전트 개발 키트 (ADK)
- 에이전트 호스트: Vertex AI Agent Engine
- UI: ADK Web


Google Workspace 부가기능으로 작동하는 에이전트
이 에이전트를 사용하면 사용자가 Workspace 앱 UI의 컨텍스트 내에서 자연어로 Workspace 데이터를 검색할 수 있습니다. 다음 요소를 사용합니다.
- 모델: Gemini
- 데이터 및 작업: Google Workspace (Calendar, Gmail, Drive)용 Vertex AI 데이터 스토어, Google 관리형 Vertex AI Search 모델 컨텍스트 프로토콜 (MCP) 서버, Google Chat 메시지를 전송하는 맞춤 도구 기능 (Google Chat API를 통해)
- 에이전트 빌드 도구: 에이전트 개발 키트 (ADK)
- 에이전트 호스트: Vertex AI Agent Engine
- UI: Chat 및 Gmail용 Google Workspace 부가기능 (Calendar, Drive, Docs, Sheets, Slides로 쉽게 확장 가능)
- Google Workspace 부가기능: Apps Script, Vertex AI Agent Engine API, 컨텍스트 (선택한 Gmail 메시지)


학습할 내용
- 데이터와 작업을 지원하는 Vertex AI Search와 Google Workspace 간 통합 지점
- Vertex AI에서 호스팅되는 맞춤 에이전트를 빌드하는 옵션입니다.
- 사용자가 Vertex AI Search 웹 위젯 및 Google Workspace 애플리케이션과 같은 에이전트에 액세스할 수 있는 방법입니다.
이 Codelab에 쉽게 액세스

2. 설정
솔루션을 빌드하기 전에 프로젝트의 Vertex AI Applications 설정을 초기화하고, 필요한 API를 사용 설정하고, Vertex AI Workspace 데이터 스토어를 만들어야 합니다.
개념 검토
Vertex AI 애플리케이션
Vertex AI 애플리케이션은 Google Cloud의 관리형 엔드 투 엔드 솔루션으로, 머신러닝 모델 (예: 생성형 AI 에이전트 또는 검색 엔진)을 엔터프라이즈 데이터 및 전문 도구와 통합하여 시맨틱 검색, 콘텐츠 생성, 자동화된 고객 상호작용과 같은 복잡한 작업을 실행합니다.
Vertex AI 데이터 스토어
Vertex AI 데이터 스토어는 Google Workspace와 같은 퍼스트 파티 데이터 소스 또는 Jira, Shopify와 같은 서드 파티 애플리케이션에서 수집된 데이터를 포함하는 엔티티입니다. 서드 파티 애플리케이션의 데이터가 포함된 데이터 스토어를 데이터 커넥터라고도 합니다.
Vertex AI Applications 설정 시작
에이전트 생성을 사용 설정하도록 Vertex AI Applications 설정을 초기화합니다.
새 탭에서 Google Cloud 콘솔을 열고 다음 단계를 따르세요.
- 프로젝트를 선택합니다.
- Google Cloud 검색 필드에서 AI 애플리케이션으로 이동합니다.
- 약관을 검토하고 동의한 후 계속 및 API 활성화를 클릭합니다.
- 설정으로 이동합니다.
- 인증 탭에서 global을 수정합니다.

- Google ID를 선택한 다음 저장을 클릭합니다.

API 사용 설정
Vertex AI Workspace 데이터 스토어를 사용하려면 다음 API를 사용 설정해야 합니다.
- Google Cloud 콘솔에서 Calendar, Gmail, People API를 사용 설정합니다.

- 메뉴 ☰ > API 및 서비스 > 사용 설정된 API 및 서비스를 클릭한 다음 Google Calendar API, Gmail API, People API가 목록에 있는지 확인합니다.
데이터 스토어 만들기
Google Drive 데이터 스토어를 만듭니다.
- Google Cloud 콘솔에서 AI 애플리케이션으로 이동한 다음 데이터 스토어로 이동합니다.
- + 데이터 스토어 만들기를 클릭합니다.
- 소스의 Google Drive에서 선택을 클릭합니다.

- 데이터에서 모두를 선택하고 계속을 클릭합니다.

- 구성에서 데이터 커넥터 이름을
drive로 설정하고 적용될 수 있는 요금을 검토하고 동의한 후 계속을 클릭합니다.

- 가격에서 원하는 가격 책정 모델을 선택하고 만들기를 클릭합니다. 이 Codelab에서는 일반 가격 책정을 사용하는 것이 좋습니다.
- 새로 추가된 데이터 스토어를 확인할 수 있는 데이터 스토어로 자동 리디렉션됩니다.
Google Calendar 데이터 스토어를 만듭니다.
- + 데이터 스토어 만들기를 클릭합니다.
- 소스에서 Google Calendar를 검색하고 선택을 클릭합니다.
- 작업 섹션에서 건너뛰기를 클릭합니다.
- 구성 섹션에서 데이터 커넥터 이름을
calendar로 설정합니다. - 만들기를 클릭합니다.
- 새로 추가된 데이터 스토어를 확인할 수 있는 데이터 스토어로 자동 리디렉션됩니다.
Google Gmail 데이터 스토어를 만듭니다.
- + 새 데이터 스토어를 클릭합니다.
- 소스에서 Google Gmail을 검색하고 선택을 클릭합니다.
- 작업 섹션에서 건너뛰기를 클릭합니다.
- 구성 섹션에서 데이터 커넥터 이름을
gmail로 설정합니다. - 만들기를 클릭합니다.
- 새로 추가된 데이터 스토어를 확인할 수 있는 데이터 스토어로 자동 리디렉션됩니다.
3. Vertex AI Search 앱
이 에이전트를 사용하면 사용자가 자연어로 Workspace의 데이터를 검색하고 작업을 수행할 수 있습니다. 다음 요소를 사용합니다.
- 모델: Gemini
- 데이터 및 작업: Google Workspace (Calendar, Gmail, Drive)용 Vertex AI 데이터 스토어
- 에이전트 호스트: Vertex AI Search
- UI: Vertex AI Search 웹 위젯
개념 검토
Vertex AI Search 앱
Vertex AI Search 앱은 최종 사용자에게 검색 결과, 작업, 에이전트를 제공합니다. 앱이라는 용어는 API라는 맥락에서 엔진이라는 용어와 서로 바꿔서 사용할 수 있습니다. 앱이 데이터 스토어에 연결되어 있어야 데이터 스토어의 데이터를 사용하여 검색 결과, 답변 또는 작업을 제공할 수 있습니다.
Vertex AI Search 웹 위젯
Vertex AI Search 웹 위젯은 사전 빌드된 맞춤설정 가능한 UI 구성요소로, 개발자가 코딩을 최소화하여 AI 기반 검색창과 결과 인터페이스를 웹사이트에 직접 삽입할 수 있습니다.
Vertex AI Search 미리보기
Vertex AI Search 미리보기는 Google Cloud 콘솔 내에 내장된 테스트 환경으로, 개발자가 검색 구성과 생성형 답변을 검증한 후 프로덕션 준비가 완료된 Vertex AI Search 웹 위젯에 동일한 설정을 원활하게 배포할 수 있습니다.
솔루션 아키텍처 검토

앱 만들기
데이터 스토어를 고정할 새 검색 앱을 만듭니다.
Cloud 콘솔에서 AI 애플리케이션 > 앱을 열고 다음 단계를 따르세요.
- + 앱 만들기를 클릭합니다.
- 유형의 커스텀 검색 (일반)에서 만들기를 클릭합니다.

- 구성에서 가격을 검토하고 동의한 후 Enterprise 버전 기능 및 생성형 대답을 선택합니다.
- 앱 이름을
codelab로 설정합니다. - 이름을 기반으로 ID가 생성되어 필드 아래에 표시되므로 복사합니다.
- 회사 이름을
Codelab로 설정합니다. - 멀티 리전을
global (Global)로 설정합니다. - 계속을 클릭합니다.

- 데이터에서 데이터 스토어 drive, gmail, calendar를 선택한 다음 계속을 클릭합니다.

- 가격에서 원하는 가격 책정 모델을 선택하고 만들기를 클릭합니다. 이 Codelab에서는 일반 가격 책정을 사용하는 것이 좋습니다.
- 앱이 생성되고 AI Applications > Apps > codelab > App overview로 자동 리디렉션됩니다.
- 연결된 데이터 스토어로 이동합니다.
- 몇 분 후 연결된 모든 데이터 스토어 상태가 활성으로 표시됩니다.

웹 위젯 구성
검색 위젯의 시각적 디자인과 동작을 구성합니다.
- 구성으로 이동합니다.
- UI 탭에서 검색 유형을 후속 조치와 함께 검색으로 설정한 다음 저장 및 게시를 클릭합니다.

앱 사용해 보기
Google Cloud 콘솔에서 직접 검색 앱을 테스트합니다.
- 미리보기로 이동하면 웹 위젯이 표시됩니다.
- 채팅에서
Do I have any meetings today?를 입력하고enter를 누릅니다. - 채팅에서
Did I receive an email on March 1st 2026?를 입력하고enter를 누릅니다. - 채팅에서
Give me the title of the latest Drive file I created를 입력하고enter를 누릅니다.

4. 커스텀 에이전트
이 에이전트를 사용하면 사용자가 맞춤 도구와 규칙을 사용하여 자연어로 Workspace의 데이터를 검색하고 작업을 수행할 수 있습니다. 다음 요소를 사용합니다.
- 모델: Gemini
- 데이터 및 작업: Google Workspace (Calendar, Gmail, Drive)용 Vertex AI 데이터 스토어, Google 관리형 Vertex AI Search 모델 컨텍스트 프로토콜 (MCP) 서버, Google Chat 메시지를 전송하는 맞춤 도구 기능 (Google Chat API를 통해)
- 에이전트 빌드 도구: 에이전트 개발 키트 (ADK)
- 에이전트 호스트: Vertex AI Agent Engine
- UI: ADK Web
개념 검토
에이전트 개발 키트(ADK)
에이전트 개발 키트 (ADK)는 추론, 메모리 관리, 도구 통합을 위한 사전 빌드 모듈을 제공하여 자율 AI 에이전트의 생성을 간소화하도록 설계된 전문 도구 및 프레임워크 모음입니다.
모델 컨텍스트 프로토콜(MCP)
모델 컨텍스트 프로토콜 (MCP)은 범용 '플러그 앤 플레이' 인터페이스를 통해 AI 애플리케이션과 다양한 데이터 소스 또는 도구 간의 원활하고 안전한 통합을 지원하기 위해 설계된 개방형 표준입니다.
함수 도구
함수 도구는 AI 모델이 트리거하여 특정 작업을 실행하거나 외부 시스템에서 실시간 데이터를 가져올 수 있는 사전 정의된 실행 가능한 루틴으로, 간단한 텍스트 생성 이상의 기능을 확장합니다.
ADK Web
ADK 웹은 더 쉬운 개발과 디버깅을 위해 ADK SDK와 함께 제공되는 내장 개발 UI입니다.
솔루션 아키텍처 검토

소스 코드 검토
agent.py
다음 코드는 Vertex AI로 인증하고, Vertex AI Search MCP 및 Chat API 도구를 초기화하고, 에이전트의 동작을 정의합니다.
- 인증: 환경 변수에서
ACCESS_TOKEN를 검색하여 MCP 및 API 호출을 인증합니다. - 도구 설정: Vertex AI Search 모델 컨텍스트 프로토콜 (MCP) 서버에 연결되는 도구 세트인
vertexai_mcp와send_direct_message도구를 초기화합니다. 이렇게 하면 에이전트가 연결된 데이터 스토어를 검색하고 Google Chat 메시지를 보낼 수 있습니다. - 에이전트 정의:
gemini-2.5-flash모델을 사용하여root_agent를 정의합니다. 요청 사항은 에이전트에게 정보 검색에는 검색 도구를 사용하고 작업에는send_direct_message도구를 사용하도록 우선순위를 지정하여 에이전트를 기업 데이터에 효과적으로 그라운딩합니다.
...
MODEL = "gemini-2.5-flash"
# Access token for authentication
ACCESS_TOKEN = os.environ.get("ACCESS_TOKEN")
if not ACCESS_TOKEN:
raise ValueError("ACCESS_TOKEN environment variable must be set")
VERTEXAI_SEARCH_TIMEOUT = 15.0
def get_project_id():
"""Fetches the consumer project ID from the environment natively."""
_, project = google.auth.default()
if project:
return project
raise Exception(f"Failed to resolve GCP Project ID from environment.")
def find_serving_config_path():
"""Dynamically finds the default serving config in the engine."""
project_id = get_project_id()
engines = discoveryengine_v1.EngineServiceClient().list_engines(
parent=f"projects/{project_id}/locations/global/collections/default_collection"
)
for engine in engines:
# engine.name natively contains the numeric Project Number
return f"{engine.name}/servingConfigs/default_serving_config"
raise Exception(f"No Discovery Engines found in project {project_id}")
def send_direct_message(email: str, message: str) -> dict:
"""Sends a Google Chat Direct Message (DM) to a specific user by email address."""
chat_client = chat_v1.ChatServiceClient(
credentials=Credentials(token=ACCESS_TOKEN)
)
# 1. Setup the DM space or find existing one
person = chat_v1.User(
name=f"users/{email}",
type_=chat_v1.User.Type.HUMAN
)
membership = chat_v1.Membership(member=person)
space_req = chat_v1.Space(space_type=chat_v1.Space.SpaceType.DIRECT_MESSAGE)
setup_request = chat_v1.SetUpSpaceRequest(
space=space_req,
memberships=[membership]
)
space_response = chat_client.set_up_space(request=setup_request)
space_name = space_response.name
# 2. Send the message
msg = chat_v1.Message(text=message)
message_request = chat_v1.CreateMessageRequest(
parent=space_name,
message=msg
)
message_response = chat_client.create_message(request=message_request)
return {"status": "success", "message_id": message_response.name, "space": space_name}
vertexai_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://discoveryengine.googleapis.com/mcp",
timeout=VERTEXAI_SEARCH_TIMEOUT,
sse_read_timeout=VERTEXAI_SEARCH_TIMEOUT,
headers={"Authorization": f"Bearer {ACCESS_TOKEN}"}
),
tool_filter=['search']
)
# Answer nicely the following user queries:
# - Please find my meetings for today, I need their titles and links
# - What is the latest Drive file I created?
# - What is the latest Gmail message I received?
# - Please send the following message to someone@example.com: Hello, this is a test message.
root_agent = LlmAgent(
model=MODEL,
name='enterprise_ai',
instruction=f"""
You are a helpful assistant that always uses the Vertex AI MCP search tool to answer the user's message, unless the user asks you to send a message to someone.
If the user asks you to send a message to someone, use the send_direct_message tool to send the message.
You MUST unconditionally use the Vertex AI MCP search tool to find answer, even if you believe you already know the answer or believe the Vertex AI MCP search tool does not contain the data.
The Vertex AI MCP search tool accesses the user's data through datastores including Google Drive, Google Calendar, and Gmail.
Only use the Vertex AI MCP search tool with servingConfig and query parameters, do not use any other parameters.
Always use the servingConfig {find_serving_config_path()} while using the Vertex AI MCP search tool.
""",
tools=[vertexai_mcp, FunctionTool(send_direct_message)]
)
소스 코드 다운로드
시작하려면 로컬 환경에 샘플 코드를 다운로드하세요.
- 이 GitHub 저장소를 다운로드합니다.
- 터미널에서
solutions/enterprise-ai-agent-local디렉터리를 엽니다.
API 사용 설정
솔루션에는 추가 API가 사용 설정되어 있어야 합니다.
- Google Cloud 콘솔에서 Vertex AI, Cloud Resource Manager, Google Chat API를 사용 설정합니다.

- 메뉴 ☰ > API 및 서비스 > 사용 설정된 API 및 서비스를 클릭한 다음 Vertex AI API, Cloud Resource Manager API, Google Chat API가 목록에 있는지 확인합니다.
OAuth 동의 화면 구성
이 솔루션에는 동의 화면 구성이 필요합니다.
- Google Cloud 콘솔에서 메뉴 ☰ > Google 인증 플랫폼 > 브랜딩을 클릭합니다.
- 시작하기를 클릭합니다.
- 앱 정보에서 앱 이름을
Codelab로 설정합니다 . - 사용자 지원 이메일에서 사용자가 동의에 대해 문의할 수 있는 지원 이메일 주소를 선택합니다.
- 다음을 클릭합니다.
- 대상에서 내부를 선택합니다.
- 다음을 클릭합니다.
- 연락처 정보에서 프로젝트 변경사항에 대한 알림을 받을 수 있는 이메일 주소를 입력합니다.
- 다음을 클릭합니다.
- 완료에서 Google API 서비스 사용자 데이터 정책을 검토하고 동의하는 경우 Google API 서비스: 사용자 데이터 정책에 동의합니다를 선택합니다.
- 계속을 클릭한 다음 만들기를 클릭합니다.

- 구성이 저장되고 Google 인증 플랫폼 > 개요로 자동 리디렉션됩니다.
자세한 내용은 OAuth 동의 구성 가이드를 참고하세요.
OAuth 클라이언트 사용자 인증 정보 만들기
로컬 환경에서 사용자를 인증할 새 데스크톱 앱 OAuth 클라이언트를 만듭니다.
- Google Cloud 콘솔에서 메뉴 ☰ > Google 인증 플랫폼 > 클라이언트를 클릭합니다.
- + 클라이언트 만들기를 클릭합니다.
- 애플리케이션 유형으로 데스크톱 앱을 선택합니다.
- 이름을
codelab로 설정합니다. - 만들기를 클릭합니다. 새로 생성된 사용자 인증 정보가 표시됩니다.
- JSON 다운로드를 클릭하고 파일을
solutions/enterprise-ai-agent-local디렉터리에 client_secret.json으로 저장합니다.


