Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

ADK 및 MCP로 Google Workspace AI 에이전트 빌드

1. 소개

이 Codelab에서는 공식 Google Workspace MCP 서버에 직접 연결되는 에이전트 개발 키트 (ADK)를 사용하여 프로 코드 AI 에이전트를 빌드하는 방법을 알아봅니다.

모델 컨텍스트 프로토콜 (MCP)은 AI 모델이 원격 서버에서 제공하는 도구를 안전하게 사용할 수 있도록 지원하는 개방형 표준입니다. ADK는 자율 에이전트를 빌드하기 위한 Google의 프로 코드 프레임워크입니다. 이러한 기능을 결합하면 Gmail, Google Drive, Google Calendar, Google Chat, People 데이터에 기반한 고도로 맞춤화된 에이전트를 만들 수 있습니다.

사용 가능한 도구 및 구성에 관한 전체 문서는 Google Workspace MCP 서버 구성을 참고하세요.

실습할 내용

Google Cloud 프로젝트에서 Google Workspace MCP 서비스를 사용 설정합니다.
로컬 테스트와 프로덕션 배포 모두에 대해 OAuth 동의를 구성하고 사용자 인증 정보를 만듭니다.
고정 토큰을 사용하여 5개의 Workspace MCP 서버에 연결되는 로컬 ADK 에이전트를 빌드합니다.
동적 토큰 삽입을 사용하는 프로덕션 지원 ADK 에이전트를 Gemini Enterprise 에이전트 플랫폼 (GEAP) 에이전트 런타임에 빌드하고 배포합니다.
Gemini Enterprise 내에서 기본적으로 커스텀 에이전트를 등록하고 테스트합니다.

필요한 항목

웹브라우저 (예: Chrome)
결제가 사용 설정된 Google Cloud 프로젝트.
Google Workspace 계정 (스마트 기능이 사용 설정됨)
로컬 머신에 Python 3.11 이상이 설치되어 있어야 합니다.
Google Cloud CLI (gcloud)가 설치되고 초기화되었습니다.

2. 시작하기 전에

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

콘솔 옵션

Google Cloud 콘솔에서 Google Cloud 프로젝트를 선택하거나 만듭니다.

CLI 옵션

새 프로젝트를 만들고 활성 상태로 설정합니다.

gcloud projects create YOUR_PROJECT_ID
gcloud config set project YOUR_PROJECT_ID

API 사용 설정

Google Workspace MCP 서버를 사용하려면 표준 Google Workspace API와 전용 MCP 서비스를 모두 사용 설정해야 합니다.

콘솔 옵션

웹브라우저를 사용하여 사용 설정하려면 다음 버튼을 클릭하세요.

CLI 옵션 다음 터미널 명령어를 실행합니다.

# Enable standard GWS APIs
gcloud services enable chat.googleapis.com \
  drive.googleapis.com \
  calendar-json.googleapis.com \
  people.googleapis.com \
  gmail.googleapis.com

# Enable dedicated MCP services
gcloud services enable calendarmcp.googleapis.com \
  chatmcp.googleapis.com \
  drivemcp.googleapis.com \
  gmailmcp.googleapis.com

Chat 앱 구성

Google Chat MCP 서버를 사용하려면 Google Cloud 프로젝트에서 Chat 앱을 구성해야 합니다.

Google Chat API > 관리 > 구성으로 이동합니다.
Chat 앱 설정:
- 앱 이름: ADK Workspace Agent
- 아바타 URL: https://developers.google.com/chat/images/quickstart-app-avatar.png
- 설명: MCP server connection for ADK Agent
- 기능에서 대화형 기능 사용 설정을 사용 중지합니다.
- 로그에서 Logging에 오류 로깅을 선택합니다.
저장을 클릭합니다.

3. OAuth 동의 및 클라이언트 구성

Google Workspace MCP 서버는 보안 인증에 OAuth 2.0을 사용합니다. OAuth 동의 화면을 구성하고 두 개의 별도 클라이언트 ID를 만들어야 합니다. 하나는 로컬 개발용이고 다른 하나는 배포된 에이전트용입니다.

Google Cloud 콘솔의 왼쪽 상단에 있는 탐색 메뉴 (햄버거 아이콘)를 클릭합니다. Google 인증 플랫폼 > 브랜딩을 선택합니다 (또는 Google 인증 플랫폼이 표시되지 않는 경우 API 및 서비스 > OAuth 동의 화면).
앱 정보를 구성합니다.
- 앱 이름: Workspace ADK Agent
- 사용자 지원 이메일: 이메일을 선택합니다.
대상 구성: 내부를 선택합니다.
연락처 정보 구성: 이메일 주소를 입력한 다음 만들기를 클릭합니다.

데이터 액세스 > 범위 추가 또는 삭제로 이동합니다. 직접 범위 추가에서 다음 범위를 추가하여 5개 서비스 모두에 대한 액세스 권한을 부여합니다.

https://www.googleapis.com/auth/calendar.calendarlist.readonly
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/calendar.calendars
https://www.googleapis.com/auth/chat.spaces
https://www.googleapis.com/auth/chat.messages
https://www.googleapis.com/auth/drive.readonly
https://www.googleapis.com/auth/drive.file
https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.compose
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/directory.readonly
https://www.googleapis.com/auth/userinfo.profile
https://www.googleapis.com/auth/contacts.readonly
https://www.googleapis.com/auth/cloud-platform

표에 추가, 업데이트, 저장을 차례로 클릭합니다.

로컬 개발용 클라이언트 ID 만들기 (데스크톱 앱)

Google Cloud 콘솔에서 Google 인증 플랫폼 > 클라이언트 (또는 API 및 서비스 > 사용자 인증 정보)로 이동합니다. 사용자 인증 정보 만들기 (또는 클라이언트 만들기)를 클릭하고 OAuth 클라이언트 ID를 선택합니다.
애플리케이션 유형으로 데스크톱 앱을 선택합니다.
파일 이름을 Workspace Agent Local로 지정합니다.
만들기를 클릭하고 JSON 파일을 다운로드합니다. 파일을 로컬에 client_secret.json로 저장합니다.

4. 에이전트 개발 및 테스트

이 섹션에서는 에이전트 환경을 빌드하는 방법을 설명합니다. 테스트에는 정적 토큰 접근 방식을 사용합니다. 여기서 gcloud를 사용하여 OAuth 토큰을 가져와 ADK의 McpToolset에 전달합니다. 로컬 머신 또는 Google Cloud Shell을 사용하여 다음 단계를 따를 수 있습니다.

로컬 머신 또는 Google Cloud Shell 환경을 선택하여 개발 환경을 설정합니다. 두 방법 모두 인증을 위해 공유 Python 스크립트를 사용하여 플랫폼 간 일관성을 유지합니다.

1. 환경 디렉터리 설정

터미널에서 다음 명령어를 실행하여 프로젝트 디렉터리를 만들고 필요한 패키지를 설치합니다.

Google Cloud Shell: 먼저 Google Cloud 콘솔의 오른쪽 상단 툴바에서 Cloud Shell 활성화 아이콘 (>_)을 클릭합니다.
로컬 머신: 표준 터미널을 엽니다.

mkdir -p gws-adk-agent/workspace_agent
cd gws-adk-agent
python3 -m venv .venv
source .venv/bin/activate
pip install google-adk poetry google-auth-oauthlib

2. 사용자 인증 정보 파일 준비

이전 단계에서 다운로드한 client_secret.json 파일을 gws-adk-agent 디렉터리의 루트에 배치해야 합니다.

로컬 머신: 다운로드한 client_secret.json 파일을 gws-adk-agent 디렉터리로 이동하거나 복사합니다.
Google Cloud Shell: Cloud Shell에서 다음 명령어를 실행하여 파일을 만듭니다 ([PASTE_JSON_HERE]를 실제 JSON 콘텐츠로 대체).

cat << 'EOF' > client_secret.json
[PASTE_JSON_HERE]
EOF

3. 인증 및 .env 생성 (`auth.py`)

인증을 일관되게 처리하고 환경별 CLI 라우팅 문제를 방지하기 위해 공식 Google 인증 라이브러리로 구동되는 맞춤 Python 스크립트를 사용합니다. 이 스크립트는 OAuth 흐름을 관리하고, 애플리케이션 기본 사용자 인증 정보 (ADC)를 로컬에 저장하고, 필요한 .env 파일을 생성합니다.

gws-adk-agent 디렉터리에 auth.py라는 파일을 만들고 다음 코드를 추가합니다.

import json
import os
from urllib.parse import urlparse, parse_qs
import google.auth
from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_SECRET_FILE = 'client_secret.json'

SCOPES = [
    "https://www.googleapis.com/auth/cloud-platform",
    "https://www.googleapis.com/auth/calendar",
    "https://www.googleapis.com/auth/chat.spaces.readonly",
    "https://www.googleapis.com/auth/chat.messages",
    "https://www.googleapis.com/auth/drive.readonly",
    "https://www.googleapis.com/auth/gmail.readonly",
    "https://www.googleapis.com/auth/gmail.compose",
    "https://www.googleapis.com/auth/directory.readonly",
    "https://www.googleapis.com/auth/contacts.readonly"
]

# Initialize the flow from the client secrets JSON
flow = InstalledAppFlow.from_client_secrets_file(
    CLIENT_SECRET_FILE,
    scopes=SCOPES,
    redirect_uri='http://localhost:8085/'
)

# Generate the Auth URL
auth_url, expected_state = flow.authorization_url(prompt='consent', access_type='offline')

print("\n=== GOOGLE OAUTH OFFICIAL LIBRARY FLOW ===")
print("1. Copy the following link and paste it into your browser (or click it if supported):\n")
print(auth_url)
print("\n2. Authorize the application.")
print("3. Your browser will redirect to a 'localhost' page (it will show a 'Site can't be reached' error, which is EXPECTED and normal).")
print("4. Copy the ENTIRE URL from your browser's address bar (including the http://localhost:8085/ part).\n")

# Get the redirected URL from the user
redirected_url = input("Paste the full localhost URL here: ").strip()

# Exchange the redirect URL for tokens
print("\nExchanging code for tokens...")
try:
    parsed_url = urlparse(redirected_url)
    query_params = parse_qs(parsed_url.query)
    
    returned_state = query_params.get('state', [None])[0]
    code = query_params.get('code', [None])[0]
    
    if not code:
        raise ValueError("No 'code' parameter found in the URL.")
    if returned_state != expected_state:
        raise ValueError("CSRF Warning! State mismatch.")
        
    flow.fetch_token(code=code)
    creds = flow.credentials
except Exception as e:
    print(f"Authentication failed: {e}")
    exit(1)

if not creds.refresh_token:
    print("\nError: No refresh token returned. You may need to revoke access and try again.")
    exit(1)

# Save Application Default Credentials
adc_data = {
    "client_id": creds.client_id,
    "client_secret": creds.client_secret,
    "refresh_token": creds.refresh_token,
    "type": "authorized_user"
}

adc_dir = os.path.expanduser("~/.config/gcloud")
os.makedirs(adc_dir, exist_ok=True)
adc_path = os.path.join(adc_dir, "application_default_credentials.json")

with open(adc_path, "w") as f:
    json.dump(adc_data, f, indent=2)

# Detect Project ID
try:
    _, project_id = google.auth.default()
except Exception:
    project_id = None

project_id = project_id or os.environ.get("GOOGLE_CLOUD_PROJECT", "YOUR_PROJECT_ID")

# Save to .env for local development (relative to project root)
env_dir = "workspace_agent"
os.makedirs(env_dir, exist_ok=True)
env_path = os.path.join(env_dir, ".env")

with open(env_path, "w") as f:
    f.write("GOOGLE_GENAI_USE_VERTEXAI=1\n")
    f.write(f"GOOGLE_CLOUD_PROJECT={project_id}\n")
    f.write("GOOGLE_CLOUD_LOCATION=us-central1\n")

print(f"\nSuccess! Application Default Credentials saved to: {adc_path}")
print(f"Environment variables saved to: {env_path}")
if project_id == "YOUR_PROJECT_ID":
    print("NOTE: Could not automatically detect Project ID. Please update it manually in .env")

터미널에서 스크립트를 실행합니다.

python3 auth.py

에이전트 코드 만들기

이전 단계에서 선택한 환경과 관계없이 에이전트 코드는 정확히 동일하게 유지됩니다. 미리 생성된 workspace_agent 하위 디렉터리 내에 agent.py 파일을 만들고 다음 코드를 추가합니다. 이 스크립트는 애플리케이션 기본 사용자 인증 정보 (ADC)를 사용하여 승인을 제공하고 동적 헤더 제공자를 통해 메모리에서만 사용자 인증 정보를 자동으로 검증하고 새로고침합니다.

import datetime
import google.auth
from google.auth.transport.requests import Request
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

MODEL = "gemini-2.5-flash"

# Load credentials from Application Default Credentials (ADC) saved by auth.py
creds, _ = google.auth.default()

# 1. STARTUP SAFETY: Ensure valid token at import time for static tool discovery (e.g. adk web UI load)
if not creds.valid:
    creds.refresh(Request())
    print("\n[Agent Startup] Access token refreshed from ADC.")

def auth_header_provider(tool_context=None) -> dict[str, str]:
    """2. RUNTIME SAFETY: Dynamically provides auth headers, refreshing if expired during the session."""
    if not creds.valid:
        creds.refresh(Request())
        print("\n[Agent Runtime] Access token refreshed from ADC.")
    return {"Authorization": f"Bearer {creds.token}"}

# Initialize the 5 GWS MCP servers with combined startup headers and dynamic runtime provider
calendar_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://calendarmcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
chat_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://chatmcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
drive_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://drivemcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
gmail_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://gmailmcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
people_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://people.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)

current_date = datetime.datetime.now().strftime("%Y-%m-%d")

# Define the agent and attach all 5 toolsets
root_agent = LlmAgent(
    model=MODEL,
    name='gws_adk_agent',
    instruction=f"""You are a helpful assistant grounded in the user's Google Workspace data.
    Today's current date is {current_date}. Always calculate relative dates (like 'this week' or 'upcoming meetings') using this reference.
    Use the provided MCP tools to answer questions about their Calendar, Chat, Drive, Gmail, and Contacts.""",
    tools=[calendar_mcp, chat_mcp, drive_mcp, gmail_mcp, people_mcp]
)

에이전트 실행 및 테스트

대화형 웹 UI를 사용하거나 터미널/셸 내에서 직접 에이전트와 상호작용할 수 있습니다.

옵션 1: 대화형 웹 UI

로컬 머신을 사용하는 경우:

gws-adk-agent 프로젝트 루트 디렉터리에서 ADK 웹 인터페이스를 시작합니다.
```
adk web
```
브라우저에서 http://localhost:8000을 열어 에이전트와 채팅합니다.

Google Cloud Shell을 사용하는 경우 다음 단계를 따르세요.

gws-adk-agent 프로젝트 루트 디렉터리에서 포트 8080을 명시적으로 적용하여 ADK 웹 인터페이스를 시작합니다.
```
adk web --port 8080 --allow_origins=*
```
Cloud Shell 툴바의 오른쪽 상단에 있는 웹 미리보기 버튼을 클릭하고 포트 8080에서 미리보기를 선택하여 새 탭에서 인터페이스를 엽니다.

옵션 2: 터미널 CLI 모드 (대체)

터미널에 머무르거나 웹브라우저 미리보기를 설정하지 않으려면 ADK에서 기본 대화형 REPL 채팅 모드를 제공합니다.

gws-adk-agent 프로젝트 루트 디렉터리에서 다음 명령어를 실행합니다 (로컬 머신과 Google Cloud Shell에서 동일하게 작동함).

adk run workspace_agent

셸에서 바로 대화형 채팅 세션이 시작됩니다.

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

에이전트 프롬프트 사용해 보기

선택한 인터페이스와 관계없이 Workspace MCP 도구를 활용하는 질문으로 에이전트를 테스트해 보세요.

What are my upcoming meetings this week?

Summarize the last 3 unread emails in my Gmail.

5. 프로덕션 배포

에이전트를 프로덕션에 배포하려면 하드코딩된 로컬 토큰을 사용할 수 없습니다. 대신 사용자가 에이전트와 상호작용할 때 Gemini Enterprise 플랫폼에서 삽입한 OAuth 액세스 토큰을 동적으로 추출하기 위해 ADK의 header_provider를 사용합니다.

프로덕션 에이전트 코드 만들기

enterprise_ai라는 디렉터리 패키지를 만들고 그 안에 agent.py 파일을 만듭니다.

mkdir -p enterprise_ai

enterprise_ai/agent.py에 다음 콘텐츠를 작성합니다.

import datetime
import os
import re
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.tool_context import ToolContext

MODEL = "gemini-2.5-flash"
# This name MUST match the Authorization Name used during Gemini Enterprise registration
CLIENT_AUTH_NAME = "workspace-adk-auth"

def _get_access_token_from_context(tool_context: ToolContext) -> str:
    """Dynamically parses the user bearer token injected into the ToolContext state."""
    escaped_name = re.escape(CLIENT_AUTH_NAME)
    pattern = re.compile(fr"^{escaped_name}_\d+$")
    state_dict = tool_context.state.to_dict() if hasattr(tool_context.state, 'to_dict') else tool_context.state
    matching_keys = [k for k in state_dict.keys() if pattern.match(k)]
    if matching_keys:
        return state_dict.get(matching_keys[0])
    raise Exception(f"No bearer token found in ToolContext state matching pattern {pattern.pattern}")

def auth_header_provider(tool_context: ToolContext) -> dict[str, str]:
    """Provides the dynamic Authorization header for MCP requests."""
    token = _get_access_token_from_context(tool_context)
    return {"Authorization": f"Bearer {token}"}

# Initialize toolsets using the dynamic header_provider
calendar_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://calendarmcp.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)
chat_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://chatmcp.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)
drive_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://drivemcp.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)
gmail_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://gmailmcp.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)
people_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://people.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)

current_date = datetime.datetime.now().strftime("%Y-%m-%d")

root_agent = LlmAgent(
    model=MODEL,
    name='enterprise_ai',
    instruction=f"""You are an enterprise assistant grounded securely in the user's Workspace data.
    Today's current date is {current_date}. Always calculate relative dates (like 'this week' or 'upcoming meetings') using this reference.
    Always use the provided MCP tools to fetch context from Calendar, Chat, Drive, Gmail, and People.""",
    tools=[calendar_mcp, chat_mcp, drive_mcp, gmail_mcp, people_mcp]
)

GEAP Agent Runtime에 배포

ADK CLI를 사용하여 프로 코드 에이전트를 배포합니다.

adk deploy agent_engine \
  --project=$(gcloud config get-value project) \
  --region=us-central1 \
  --display_name="Workspace ADK Agent" \
  enterprise_ai

배포가 완료될 때까지 기다린 후 터미널 출력에서 생성된 Reasoning Engine 리소스 이름 (예: projects/PROJECT_ID/locations/us-central1/reasoningEngines/ENGINE_ID)을 복사합니다.

6. Gemini Enterprise에 등록

이제 사용자가 기본적으로 채팅할 수 있도록 맞춤 ADK 에이전트를 Gemini Enterprise로 가져옵니다.

프로덕션용 클라이언트 ID 만들기 (웹 애플리케이션)

에이전트를 프로덕션에 배포하려면 웹 애플리케이션 클라이언트 ID를 만들어야 합니다. 로컬 테스트에 사용되는 데스크톱 클라이언트와 달리 웹 애플리케이션 클라이언트는 보안 서버 측 OAuth 흐름을 지원합니다. 이를 통해 GEAP 에이전트 런타임의 호스팅 에이전트는 지정된 리디렉션 URI를 사용하여 Gemini Enterprise에서 전달한 사용자의 인증 토큰을 안전하게 수신할 수 있습니다. 이 설정은 상담사가 프로덕션 환경에서 사용자를 대신하여 Google Workspace 데이터에 안전하게 액세스하는 데 필요합니다.

Google Cloud 콘솔의 왼쪽 상단에 있는 탐색 메뉴 (햄버거 아이콘)를 클릭합니다. Google 인증 플랫폼 > 클라이언트를 선택합니다 (또는 Google 인증 플랫폼이 표시되지 않는 경우 API 및 서비스 > 사용자 인증 정보). 사용자 인증 정보 만들기 (또는 클라이언트 만들기)를 클릭하고 OAuth 클라이언트 ID를 선택합니다.
애플리케이션 유형으로 웹 애플리케이션을 선택합니다.
파일 이름을 Workspace Agent Production로 지정합니다.
승인된 리디렉션 URI 섹션에 다음 URI를 추가합니다.
- URI 추가를 클릭하고 https://vertexaisearch.cloud.google.com/oauth-redirect을 입력합니다.
- URI 추가를 다시 클릭하고 https://vertexaisearch.cloud.google.com/static/oauth/oauth.html를 입력합니다.
만들기를 클릭합니다. 'OAuth 클라이언트 생성됨' 팝업 (또는 클라이언트 목록)에서 클라이언트 ID와 클라이언트 보안 비밀을 복사합니다. Gemini Enterprise에 에이전트를 등록할 때 이러한 정보가 필요합니다.

Gemini Enterprise 앱 만들기

Google Cloud 콘솔에서 Gemini Enterprise 페이지로 이동합니다.

Gemini Enterprise 카드에서 관리를 클릭합니다.
앱 만들기를 클릭합니다.
Gemini Enterprise 섹션에서 만들기를 클릭합니다.
앱 이름 필드에 앱 이름을 입력합니다. 앱 이름 아래에 앱 ID가 표시됩니다.
회사 또는 조직의 외부 이름 필드에 회사 또는 조직 이름을 입력합니다. 이 튜토리얼에서는 Cymbal Bank를 사용할 수 있습니다.
앱 위치로 전역(전 세계)을 선택합니다.
계속을 클릭합니다.

커스텀 에이전트 등록

Gemini Enterprise 콘솔을 엽니다.

활성 앱을 선택하고 에이전트로 이동한 다음 + 에이전트 추가 > Agent Runtime을 통한 맞춤 에이전트 추가를 클릭합니다.

승인 섹션에서 승인 추가를 클릭합니다.

승인 이름: workspace-adk-auth (Python 코드의 CLIENT_AUTH_NAME과 정확히 일치해야 함)
클라이언트 ID: 위에 만든 프로덕션 웹 애플리케이션 클라이언트 ID를 붙여넣습니다.
클라이언트 보안 비밀번호: 위에서 생성한 프로덕션 웹 애플리케이션 클라이언트 보안 비밀번호를 붙여넣습니다.
토큰 URI: https://oauth2.googleapis.com/token

승인 URI: YOUR_CLIENT_ID를 위의 5단계에서 복사한 클라이언트 ID로 대체하여 URI를 구성합니다.

https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.calendars%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.events%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.send%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fchat.spaces%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fchat.messages%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.file%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdirectory.readonly&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

완료를 클릭한 후 다음을 클릭합니다.

구성 섹션에서 다음을 수행합니다.

상담사 이름: Workspace Pro Agent

설명:

Use this agent to answer questions about your Google Workspace data, including Gmail, Google Drive, Google Calendar, Google Chat, and Contacts. It can find files, summarize emails, check your schedule, and look up contact information.

Agent Runtime 추론 엔진: adk deploy 출력에서 복사한 엔진 리소스 이름을 붙여넣습니다.

만들기를 클릭합니다.

Gemini Enterprise에서 에이전트 사용해 보기

Google Cloud 콘솔 미리보기 (개발자에게 가장 빠름) 또는 Gemini Enterprise 웹 앱 (최종 사용자 환경)을 사용하여 에이전트와 상호작용할 수 있습니다.

옵션 1: Google Cloud 콘솔 미리보기

Google Cloud 콘솔에서 Gemini Enterprise 페이지로 이동합니다.

탐색 메뉴에서 앱을 클릭하고 방금 만든 앱을 선택합니다.
오른쪽 상단에서 미리보기를 클릭하거나 미리보기 열기를 클릭합니다.

검색창에 다음 쿼리를 입력합니다.

Search for files in Drive related to 'Project Milestone', summarize them, and tell me if I have any meetings with the project owner today.

Enter 키를 눌러 쿼리를 제출하고 콘솔에서 결과를 직접 확인합니다.

옵션 2: Gemini Enterprise 웹 앱

Gemini Enterprise 웹 앱 인터페이스를 엽니다.
메뉴 ☰ > 에이전트로 이동하여 조직에서 Workspace Pro 에이전트를 선택합니다.
Google Cloud 콘솔 미리보기 옵션과 동일한 쿼리를 입력합니다.
OAuth 사용자 동의 흐름을 진행하라는 메시지가 표시되면 승인을 클릭합니다.
에이전트는 MCP 프로토콜을 사용하여 여러 서비스에서 원활하게 작업을 실행합니다.

7. 삭제

불필요한 요금이 청구되지 않도록 리소스를 정리하세요.

콘솔 옵션

API 및 서비스 대시보드로 이동하여 사용 설정한 MCP 서비스 (예: Calendar MCP, Gmail MCP)를 선택하고 API 사용 중지를 클릭합니다. Google 인증 플랫폼 > 클라이언트에서 OAuth 클라이언트 ID를 삭제하고 Gemini Enterprise 콘솔에서 Reasoning Engine 배포를 삭제합니다.

CLI 옵션

다음 터미널 명령어를 실행하여 MCP 서비스를 사용 중지합니다.

# Disable Workspace MCP services
gcloud services disable calendarmcp.googleapis.com \
  chatmcp.googleapis.com \
  drivemcp.googleapis.com \
  gmailmcp.googleapis.com

8. 축하합니다

축하합니다. 공식 Google Workspace MCP 서버에 직접 연결된 프로 코드 ADK AI 에이전트를 빌드, 테스트, 배포했습니다.

학습한 내용

Google Cloud에서 Google Workspace MCP 서비스를 사용 설정하는 방법
정적 헤더를 사용하여 로컬 ADK 테스트의 OAuth 사용자 인증 정보를 처리하는 방법
프로덕션 에이전트에서 header_provider를 사용하여 동적 토큰 삽입을 구현하는 방법
GEAP 에이전트 런타임에 ADK 에이전트를 배포하고 Gemini Enterprise에 등록하는 방법

ADK 및 MCP로 Google Workspace AI 에이전트 빌드

1. 소개

실습할 내용

필요한 항목

2. 시작하기 전에

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

콘솔 옵션

CLI 옵션

API 사용 설정

콘솔 옵션

CLI 옵션 다음 터미널 명령어를 실행합니다.

Chat 앱 구성

3. OAuth 동의 및 클라이언트 구성

OAuth 동의 화면 설정

로컬 개발용 클라이언트 ID 만들기 (데스크톱 앱)

4. 에이전트 개발 및 테스트

1. 환경 디렉터리 설정

2. 사용자 인증 정보 파일 준비

3. 인증 및 .env 생성 (auth.py)

에이전트 코드 만들기

에이전트 실행 및 테스트

옵션 1: 대화형 웹 UI

로컬 머신을 사용하는 경우:

Google Cloud Shell을 사용하는 경우 다음 단계를 따르세요.

옵션 2: 터미널 CLI 모드 (대체)

에이전트 프롬프트 사용해 보기

5. 프로덕션 배포

프로덕션 에이전트 코드 만들기

GEAP Agent Runtime에 배포

6. Gemini Enterprise에 등록

프로덕션용 클라이언트 ID 만들기 (웹 애플리케이션)

Gemini Enterprise 앱 만들기

커스텀 에이전트 등록

Gemini Enterprise에서 에이전트 사용해 보기

옵션 1: Google Cloud 콘솔 미리보기

옵션 2: Gemini Enterprise 웹 앱

7. 삭제

콘솔 옵션

CLI 옵션

8. 축하합니다

학습한 내용

참조 문서

3. 인증 및 .env 생성 (`auth.py`)