Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

에이전트 아이덴티티 및 Auth Manager를 사용하여 사용자를 대신하여 행동하는 AI 에이전트 빌드

1. 소개

광범위한 권한이 있는 자체 사용자 인증 정보가 있는 에이전트는 모든 사용자의 데이터를 볼 수 있습니다. 이 Codelab에서는 로그인한 사용자의 사용자 인증 정보를 사용하여 서드 파티 API를 호출하는 에이전트를 빌드합니다. 따라서 에이전트는 해당 사용자가 볼 수 있는 항목만 볼 수 있습니다.

Google 에이전트 개발 키트 (ADK)와 Gemini Enterprise를 사용하여 빌드합니다.

특히 다음을 충족하는 이중 ID 아키텍처를 설계하는 방법을 알아봅니다.

에이전트가 자체적으로 작동 (에이전트 아이덴티티): 에이전트는 SPIFFE 지원 에이전트 아이덴티티를 사용하여 인증 관리자를 호출하고, 원격 분석을 저장하고, Google Cloud API를 호출합니다.
에이전트가 사용자를 대신하여 행동함 (사용자 위임 ID): GitHub와 같은 외부 리소스에 액세스하기 위해 에이전트는 3단계 OAuth (3LO) 동의 흐름을 트리거하여 사용자의 사용자 인증 정보를 사용하여 도구를 안전하게 쿼리합니다.

이중 ID 아키텍처

이를 위해 다음을 수행하는 방법을 알아봅니다.

GitHub의 모델 컨텍스트 프로토콜 (MCP) 서버에 연결되는 ADK 에이전트를 빌드합니다.
Google Cloud Auth Manager를 사용하여 정적 GitHub PAT (개인 액세스 토큰)에서 3레그 OAuth (3LO) 흐름으로 에이전트의 도구를 업데이트합니다.
Agent Runtime에 에이전트를 안전하게 배포하고 에이전트 아이덴티티를 프로비저닝합니다.
사용자를 대신하여 토큰 보관소에 대한 에이전트의 ID 액세스를 제공하도록 IAM 역할을 구성합니다.
Google Cloud의 인증 관리자용 엔드 투 엔드 3LO 흐름을 이해합니다.

기본 요건

시작하기 전에 다음 사항을 확인하세요.

결제가 사용 설정된 Google Cloud 프로젝트
로컬 머신에 설치되고 프로젝트에 인증된 Google Cloud SDK (gcloud CLI) 버전 586.0.0 이상이 필요합니다. gcloud components update를 실행하세요.
Python 3.10~3.13이 로컬로 설치되어 있습니다.
uv 패키지 관리자가 설치되어 있습니다 (pip install uv).
OAuth 애플리케이션을 등록하고 토큰을 생성할 GitHub 계정 GitHub 계정이 없는 경우 3-legged OAuth 2.0을 지원하는 서드 파티 MCP 서버를 대체할 수 있습니다.

2. 프로젝트 설정

1. Google Cloud에 인증

이 실습 중에 환경에 Agent Runtime에 배포하고, 에이전트 아이덴티티를 프로비저닝하고, 인증 관리자를 구성하는 데 필요한 권한이 있는지 확인하려면 로컬 명령줄에서 Google Cloud에 인증하세요.

다음 명령어를 실행하여 Google Cloud 계정에 로그인하고 애플리케이션 기본 사용자 인증 정보 (ADC)를 구성합니다.

gcloud auth login
gcloud auth application-default login

2. 필수 Google Cloud 서비스 사용 설정

이 실습을 실행하려면 Google Cloud 프로젝트에서 필요한 API를 사용 설정하세요. 터미널에서 다음 명령어를 실행합니다.

gcloud services enable \
    agentidentity.googleapis.com \
    agentregistry.googleapis.com \
    aiplatform.googleapis.com \
    apphub.googleapis.com

이 명령어를 실행하는 데 1분 정도 걸릴 수 있습니다. 완료되면 API가 활성화되었음을 확인하는 명령 프롬프트로 돌아갑니다.

3. 에이전트 CLI 설치 및 프로젝트 설정

agents-cli는 ADK 에이전트를 스캐폴딩, 관리, 테스트, Gemini Enterprise에 배포하는 데 사용되는 명령줄 도구입니다. 로컬로 설치합니다.

uvx google-agents-cli setup

설치를 확인합니다.

agents-cli --help

사용 가능한 명령어 (예: deploy, run, status)를 표시하는 CLI의 도움말 메뉴가 표시됩니다.

초기 프로젝트 스캐폴딩을 생성합니다. 로컬 프로토타입으로 시작하여 나중에 Agent Runtime 배포를 위해 개선합니다.

agents-cli create secure-agent-demo --prototype --yes

이렇게 하면 기본 에이전트 코드, 종속 항목, 테스트 파일이 포함된 secure-agent-demo 디렉터리가 생성됩니다.

4. 필수 ADK 추가 기능 추가

생성된 pyproject.toml에는 이 에이전트에 필요한 두 가지 추가 기능이 누락된 google-adk[gcp,otel-gcp]이 포함되어 있습니다. GitHub 도구 모음의 경우 mcp, 실습 후반부의 인증 관리자의 경우 agent-identity입니다. secure-agent-demo/pyproject.toml을 열고 google-adk 줄을 다음과 같이 변경합니다.

"google-adk[agent-identity,gcp,mcp,otel-gcp]>=2.5.0,<3.0.0",

그런 다음 다음을 설치합니다.

cd secure-agent-demo
agents-cli install

3. 에이전트 빌드 및 테스트

1. 에이전트 만들기

프로젝트 내에서 agent.py 파일의 코드를 다음으로 바꿉니다.

# app/agent.py

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types

from app.tools import github_toolset

import os
import google.auth

_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

INSTRUCTION = """You are the DevOps Assistant. You help developers list and triage their GitHub issues and pull requests.
Your capabilities: You have a GitHub MCP toolset that you can use to perform actions that the user requests.

Rules:
- NEVER write, update, or delete. You are only allowed read access.
- Act on behalf of the signed-in user.
- If a tool returns an authentication or authorization error, guide the user to sign in.
- NEVER fabricate information. Only report real issues returned by tools.
"""

root_agent = Agent(
    name="root_agent",
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction=INSTRUCTION,
    tools=[github_toolset()],
)

app = App(
    root_agent=root_agent,
    name="app",
)

이 파일은 에이전트의 세 가지 핵심 구성요소를 정의합니다.

시스템 안내 (INSTRUCTION): 페르소나를 설정하고, 어시스턴트의 범위를 GitHub 트리아지로 지정하고, 엄격한 안전 규칙 (예: 읽기 전용 액세스, 오류 발생 시 사용자 인증 안내)을 적용합니다.
에이전트 구성 (root_agent): gemini-3.8-flash 모델을 사용하여 ADK Agent를 인스턴스화하고, HTTP 재시도 로직을 구성하고, GitHub 도구 모음을 사용하여 에이전트를 장착합니다.
앱 래퍼 (app): 루트 에이전트를 ADK App 컨테이너에 캡슐화하여 Agent Runtime에 배포할 수 있도록 합니다.

2. GitHub MCP 도구 추가

에이전트는 모델 컨텍스트 프로토콜 (MCP)을 통해 GitHub에 연결됩니다. app/ 폴더 아래에 tools.py라는 새 파일을 만들어 MCP 게이트웨이 연결 매개변수를 등록합니다. 다음 코드를 복사하여 붙여넣습니다.

# app/tools.py

from __future__ import annotations
import os
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

GITHUB_MCP_URL = "https://api.githubcopilot.com/mcp/"
GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN", "")

def github_toolset() -> McpToolset:
    """Returns the McpToolset connecting to the public GitHub Copilot MCP gateway."""
    return McpToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=GITHUB_MCP_URL,
            headers={
                "Authorization": f"Bearer {GITHUB_TOKEN}",
                "X-MCP-Toolsets": "all",
                "X-MCP-Readonly": "true",
            },
        )
    )

이 함수는 GitHub의 MCP 서버를 호출하는 도구를 만듭니다.

MCP 도구 세트 (McpToolset): 호출 가능한 에이전트 도구로 GitHub 기능을 동적으로 검색하고 등록합니다.
연결 매개변수 (StreamableHTTPConnectionParams): 도구 세트를 GitHub의 공개 MCP 게이트웨이로 안내합니다.
인증 헤더: GITHUB_TOKEN를 Bearer 토큰으로 삽입하고 전송 계층에서 직접 읽기 전용 모드 (X-MCP-Readonly: true)를 적용합니다.

3. GitHub PAT (개인 액세스 토큰)로 로컬에서 테스트

정적 사용자 인증 정보로 에이전트를 로컬에서 실행하려면 다음을 실행하세요.

GitHub 개인 액세스 토큰을 만듭니다. 저장소에 대한 읽기 액세스 권한을 부여해야 합니다. 그렇지 않으면 에이전트가 공개 데이터만 볼 수 있으며 아래 프롬프트가 아무것도 반환하지 않습니다.

환경에서 설정합니다.

export GITHUB_TOKEN="your_github_pat_here"

secure-agent-demo 폴더로 이동합니다. 실행:
```
cd secure-agent-demo
agents-cli playground
```
플레이그라운드 인터페이스를 열고 드롭다운에서 'app' 폴더를 선택합니다. 채팅 상자에 "Fetch my contributions across my private repositories over the last 6 months"를 입력하고 에이전트가 GitHub 도구를 호출하고 비공개 저장소에서 데이터를 반환하는지 확인합니다.

4. 인증 관리자 구성

정적 사용자 인증 정보 (예: PAT)를 하드코딩하는 것은 프로토타입 제작에 편리하지만 프로덕션 애플리케이션이 사용자 인증 정보 유출, 수동 토큰 새로고침 다운타임, 클라우드 네이티브 액세스 제어 부족에 노출됩니다.

이를 해결하기 위해 Google Cloud는 에이전트 ID 인증 관리자를 제공합니다. 에이전트 ID 인증 관리자는 사용자 인증 정보를 보호하도록 설계된 사용자 인증 정보 보관소입니다. 이를 통해 상담사는 API 키 또는 OAuth 클라이언트 ID 및 보안 비밀을 사용하여 인증하거나 최종 사용자 액세스 토큰을 사용하는 OAuth 위임을 통해 사용자를 대신하여 인증할 수 있습니다.

인증 관리자 내에서 특정 서드 파티 애플리케이션의 인증 유형과 사용자 인증 정보를 정의하는 인증 제공업체를 구성합니다. 인증 제공자는 리전별이며 리전은 에이전트를 배포하는 리전과 일치해야 합니다. 엔드 투 엔드 인증 관리자 워크플로는 다음과 같이 작동합니다.

인증 관리자 워크플로

동적 동의 가로채기: 에이전트가 사용자를 대신하여 도구를 실행하려고 하면 ADK가 인증 관리자에서 유효한 기존 사용자 인증 정보를 확인합니다. 이러한 토큰이 없으면 인증 관리자는 3단계 OAuth (3LO) 동의 흐름을 시작하기 위한 승인 URL을 반환합니다.
보안 Vault 스토리지: 최종 사용자가 애플리케이션을 승인하면 인증 관리자가 OAuth 콜백을 자동으로 가로채고 결과 사용자 액세스 및 갱신 토큰을 보안 Google 관리 사용자 인증 정보 Vault에 저장합니다.
자동 토큰 수명 주기: 인증 관리자가 백그라운드에서 토큰 만료 및 순환을 완전히 관리하므로 수동 토큰 새로고침 로직이나 다운타임이 필요하지 않습니다.
보안 비밀이 없는 도구 실행: 후속 작업의 경우 에이전트 (SPIFFE 에이전트 아이덴티티를 통해 인증)가 런타임에 인증 관리자로부터 사용자의 위임된 액세스 토큰을 동적으로 요청하여 클라이언트와 에이전트 코드를 모두 보안 비밀이 없는 상태로 유지합니다.

A단계: GitHub를 인증 제공업체로 구성

다음 gcloud 명령어를 실행하여 Google Cloud 프로젝트에서 GitHub 인증 제공자를 만듭니다. 클라이언트 ID와 보안 비밀은 나중에 제공합니다. GitHub는 이 제공업체의 콜백 URL을 알 때까지 이를 발급하지 않습니다.

gcloud agent-identity auth-providers create github-oauth-provider \
    --project="${PROJECT_ID}" \
    --location="us-central1" \
    --three-legged-oauth-authorization-url="https://github.com/login/oauth/authorize" \
    --three-legged-oauth-token-url="https://github.com/login/oauth/access_token"

생성된 OAuth 리디렉션 URL을 가져오도록 프로바이더를 설명합니다.

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="${PROJECT_ID}" \
    --location="us-central1"

필드는 authProviderTypeParams.threeLeggedOauth 아래에 중첩된 redirectUrl입니다. 직접 읽으려면 다음 단계를 따르세요.

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="${PROJECT_ID}" --location="us-central1" \
    --format="value(authProviderTypeParams.threeLeggedOauth.redirectUrl)"

https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback과 같이 표시됩니다.

B단계: GitHub에 OAuth 앱 등록

GitHub 개발자 설정 페이지로 이동하여 새 OAuth 앱 등록을 클릭합니다.
홈페이지 URL에 프런트엔드 애플리케이션의 URL을 입력합니다 (예: 로컬 프로토타입의 경우 http://localhost:8501). 나중에 프로덕션에서 배포된 URL로 변경할 수 있습니다.
리디렉션 URI를 이전 단계에서 가져온 redirectUrl로 설정합니다.
애플리케이션 등록을 클릭한 다음 새 클라이언트 보안 비밀번호 생성을 클릭하고 클라이언트 ID와 클라이언트 보안 비밀번호를 모두 저장합니다.

C단계: 인증 제공자에 GitHub 사용자 인증 정보 추가

프로젝트 ID, 클라이언트 ID, 클라이언트 보안 비밀번호를 바꾸고 다음 명령어를 실행합니다.

gcloud agent-identity auth-providers update github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --three-legged-oauth-client-id="YOUR_GITHUB_CLIENT_ID" \
    --three-legged-oauth-client-secret="YOUR_GITHUB_CLIENT_SECRET"

명령어는 clientId가 표시된 프로바이더를 다시 에코합니다. 보안 비밀은 에코되지 않습니다.

👉 이 단계를 완료하면 Google Cloud 인증 관리자가 GitHub OAuth 애플리케이션 사용자 인증 정보로 완전히 구성되어 Google Cloud가 동의 및 토큰 수명 주기를 처리하는 보안 저장소 역할을 하도록 설정됩니다.

5. PAT 토큰을 인증 관리자로 전환

이제 인증 관리자가 완전히 구성되었으므로 다음 단계는 에이전트의 도구 코드를 업데이트하는 것입니다. app/tools.py을 다음 코드로 바꿉니다.

👉 아래 OAUTH_PROVIDER_NAME 변수의 프로젝트 ID와 위치를 바꿉니다.

# app/tools.py

from __future__ import annotations
import os
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# 1. Register the GCP Auth Provider in the global Credential Manager
CredentialManager.register_auth_provider(GcpAuthProvider())

# 2. Replace YOUR_PROJECT_ID with your project ID.
OAUTH_PROVIDER_NAME = "projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider"

# 3. The frontend callback URL where the user is redirected after authorizing GitHub. Resolved from the environment variable.
OAUTH_CONTINUE_URI = os.environ.get(
    "OAUTH_CONTINUE_URI", 
    "http://localhost:8501/validateUserId"
)

def github_toolset() -> McpToolset:
    """Returns the McpToolset using 3LO credentials retrieved via GCP Auth Manager."""
    auth_scheme = GcpAuthProviderScheme(
        name=OAUTH_PROVIDER_NAME,
        # Required to read private repositories. Auth Manager currently supports a
        # single scope for GitHub.
        scopes=["repo"],
        continue_uri=OAUTH_CONTINUE_URI,
    )
    return McpToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://api.githubcopilot.com/mcp/",
            headers={
                "X-MCP-Toolsets": "all",
                "X-MCP-Readonly": "true",
            },
        ),
        auth_scheme=auth_scheme,
    )

도구 코드 이해하기

주요 변경사항은 auth_scheme입니다. 툴셋에 연결하면 상담사가 GitHub를 호출할 때마다 ADK가 먼저 인증 관리자에게 해당 사용자의 토큰을 요청하고, 아직 토큰이 없는 경우 실패하는 대신 사용자에게 로그인하라는 메시지를 표시합니다. 하드코딩된 GITHUB_TOKEN가 완전히 사라졌습니다.

6. Agent Runtime에 에이전트 배포

이제 GitHub MCP 도구가 인증 관리자를 사용하도록 업데이트되었으므로 다음 단계는 Agent Runtime에 에이전트를 배포하는 것입니다. 에이전트 아이덴티티를 사용 설정하여 배포하면 에이전트에 고유한 SPIFFE ID가 프로비저닝됩니다.

먼저 프로젝트의 배포 구성을 초기화해 보겠습니다. 터미널에서 실행:

agents-cli scaffold enhance . --deployment-target agent_runtime --prototype --yes

이 명령어는 프로젝트 구조에서 ADK 호환성을 검사하고, 기본 컨테이너 패키징 구성을 준비하고, 기본 배포 설정이 미리 채워진 agents-cli-manifest.yaml 파일을 프로젝트 루트에 생성합니다.

👉 새로 만든 agents-cli-manifest.yaml 파일을 열고 region 필드를 us-central1로 확인하거나 업데이트하여 에이전트가 인증 제공업체와 동일한 리전에 배포되도록 합니다.

region: "us-central1"

에이전트 아이덴티티로 에이전트 배포

adk deploy agent_engine으로 배포합니다. 이렇게 하면 에이전트에 자체 에이전트 아이덴티티가 프로비저닝됩니다. 에이전트 아이덴티티는 이 배포에 속하는 고유한 SPIFFE 지원 암호화 ID이며, 에이전트는 이를 사용하여 인증 관리자 및 기타 Google Cloud 서비스에 인증합니다.

👉 다음 명령어를 실행하기 전에 YOUR_PROJECT_ID를 바꿉니다.

# Request a SPIFFE-backed Agent Identity for this deployment
echo '{ "identity_type": "AGENT_IDENTITY" }' > app/.agent_engine_config.json

# Generate the dependency list the build will install
uv export --no-emit-workspace --no-hashes --format requirements.txt \
    --output-file app/requirements.txt

uv run adk deploy agent_engine app \
    --project="YOUR_PROJECT_ID" \
    --region="us-central1"

배포에서 컨테이너를 빌드하고 업로드하는 데 몇 분 정도 걸립니다. 완료되면 CLI에서 배포된 리소스 이름을 출력합니다. reasoningEngines/ENGINE_ID 값에 유의하세요. 상담사를 승인하고 UI 클라이언트를 가리키는 데 필요합니다.

에이전트 아이덴티티 승인

이제 에이전트가 클라우드에서 실행되므로 Auth Manager에 저장된 사용자 인증 정보에 액세스할 권한이 필요합니다. 기본적으로 에이전트의 SPIFFE ID는 외부 클라우드 리소스에 액세스할 수 없습니다.

다음 gcloud 명령어를 실행하여 인증 제공업체 리소스에서 에이전트의 ID에 roles/agentidentity.user 역할을 부여합니다. 이렇게 하면 에이전트가 보관소에서 사용자 토큰을 요청하는 데 필요한 정확한 권한만 부여되며 그 이상은 부여되지 않습니다.

👉 YOUR_PROJECT_ID, YOUR_ORG_ID, YOUR_PROJECT_NUMBER, YOUR_ENGINE_ID를 바꿉니다 (엔진 ID는 위의 배포 출력에 있음).

YOUR_ORG_ID를 가져오려면 아래 명령어를 실행하세요.

gcloud projects get-ancestors $(gcloud config get-value project) \
  --filter="type=organization" \
  --format="value(id)"

gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --role="roles/agentidentity.user" \
    --member="principal://agents.global.org-YOUR_ORG_ID.system.id.goog/resources/aiplatform/projects/YOUR_PROJECT_NUMBER/locations/us-central1/reasoningEngines/YOUR_ENGINE_ID"

이제 제공업체에서 내 계정에 동일한 역할을 부여합니다. 다음 단계에서 실행하는 UI 클라이언트는 애플리케이션 기본 사용자 인증 정보로 사용자 인증 정보 완료 API를 호출하므로 이 API가 없으면 동의 흐름이 agentidentity.authProviders.retrieveCredentials에서 403으로 실패합니다.

gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --role="roles/agentidentity.user" \
    --member="user:YOUR_EMAIL_ADDRESS"

7. 서드 파티 동의 절차 이해하기

이제 에이전트가 보안 에이전트 ID와 함께 Agent Runtime에 배포되었으므로 다음 단계는 사용자가 에이전트와 채팅할 수 있는 맞춤 프런트엔드 인터페이스를 제공하는 것입니다. 더 중요한 점은 Google Cloud 인증 관리자가 인증 루프를 완료하려면 클라이언트 애플리케이션 콜백 핸들러가 필요하다는 점입니다.

Google Cloud Auth Manager는 보관소 내에서 사용자 인증 정보를 안전하게 관리하지만 자체적으로 OAuth 토큰 교환을 완료할 수는 없습니다. 3LO 핸드셰이크는 클라이언트 애플리케이션이 격차를 해소하는 데 의존합니다.

사용자가 GitHub 앱을 승인하면 GitHub에서 사용자를 에이전트 아이덴티티 인증 제공업체 redirectUrl로 다시 리디렉션합니다.
그런 다음 인증 관리자가 사용자의 브라우저 팝업을 클라이언트 측 콜백 URL (continue_uri)로 다시 리디렉션합니다.
이 리디렉션을 가로채고, 브라우저의 쿠키에서 nonce를 읽고, Google Cloud의 credentials:finalize 엔드포인트를 호출하여 핸드셰이크를 완료하는 것은 클라이언트 애플리케이션의 책임입니다.
클라이언트가 교환을 완료하면 Google Cloud는 인증 제공업체의 보관소에 토큰을 안전하게 저장하여 에이전트가 GitHub 도구를 호출할 수 있도록 합니다.

콜백 엔드포인트를 호스팅하는 맞춤 클라이언트가 없으면 핸드셰이크가 완료되지 않으며 Vault에서 사용자 인증 정보를 저장할 수 없습니다.

대화형 OAuth 3LO 흐름은 여러 레이어에 걸쳐 있습니다. 다음은 도구 요청의 전체 실행 수명 주기입니다. 아래 설명과 다음 단계에서 자세히 살펴보겠습니다.

👉 이미지를 클릭하여 확대합니다.

핸드셰이크에서 클라이언트의 핵심 책임

동의 챌린지 전달 (5~6단계): 에이전트가 동의 URL과 일회성 nonce를 전달하는 adk_request_credential를 내보냅니다. 클라이언트가 팝업을 열고 nonce를 쿠키로 저장합니다.
리디렉션 콜백 호스팅 (10~11단계): /validateUserId, 여기서 인증 관리자는 동의 후 팝업을 전송합니다.
토큰 완료 (12~14단계): 리디렉션의 유효성 검사 상태를 캐시된 nonce와 결합하고 credentials:finalize를 호출하여 토큰을 보관소에 저장합니다.

자체 클라이언트 빌드

실습을 위해 이 클라이언트를 작성할 필요는 없습니다. 다음 단계에서 사전 빌드된 클라이언트를 실행합니다. 자체 애플리케이션에서 이를 구현할 때는 다음 두 가지 참조를 사용하세요.

인증 관리자 문서의 클라이언트 측 애플리케이션 업데이트를 참고하세요. 여기에서는 동의 챌린지 처리 및 credentials:finalize 호출을 다룹니다.
adk-python 저장소의 실행 가능한 샘플 클라이언트 위의 세 가지 책임의 완전하고 작동하는 구현은 main.py에서 확인할 수 있습니다.

8. UI 클라이언트를 로컬로 실행

3LO 동의 흐름 시퀀스 다이어그램에서 추적한 대로 인증 관리자는 브라우저 팝업을 클라이언트 측 콜백 엔드포인트로 다시 리디렉션해야 합니다. 샘플 클라이언트는 /validateUserId에서 해당 엔드포인트를 호스팅합니다. 로컬에서 실행해 보겠습니다.

클라이언트 파일을 로컬에 복사

adk-python GitHub 저장소에서 gcp_auth/client 폴더로 이동합니다. 이 폴더에는 채팅 클라이언트 컨테이너를 빌드하는 데 필요한 애셋이 포함되어 있습니다.

👉 gcp_auth/client 아래의 모든 파일을 로컬 환경에 복사합니다.

main.py: 이전 섹션에서 설명한 토큰 완료 콜백 (/validateUserId)이 포함된 FastAPI 애플리케이션 스크립트입니다.
static/: HTML 페이지가 포함되어 있습니다.

또는 폴더의 스파스 체크아웃을 실행할 수도 있습니다.

git clone --filter=blob:none --no-checkout https://github.com/google/adk-python.git
cd adk-python
git sparse-checkout init --cone
git sparse-checkout set contributing/samples/integrations/gcp_auth/client
git checkout

클라이언트 실행

방금 복사한 client 폴더로 이동합니다.

cd adk-python/contributing/samples/integrations/gcp_auth/client

가상 환경을 만들고 클라이언트의 종속 항목을 설치합니다. 폴더에는 requirements.txt가 제공되고 pyproject.toml는 제공되지 않으므로 uv run uvicorn ... 자체는 Failed to spawn: uvicorn로 인해 실패합니다.
```
uv venv --python 3.13 .venv
source .venv/bin/activate
uv pip install --python .venv/bin/python -r requirements.txt
```

배포한 에이전트를 클라이언트로 지정한 다음 포트 8501에서 시작합니다.

export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1
export AGENT_ID=YOUR_ENGINE_ID

.venv/bin/uvicorn main:app --port 8501

서버가 성공적으로 시작되었고 http://localhost:8501에서 수신 대기 중인지 확인합니다.

9. OAuth 흐름 테스트

이제 모든 서비스가 배포되고, IAM 바인딩이 구성되고, 환경 변수가 설정되었으므로 보안 엔드 투 엔드 사용자 위임 승인 흐름을 테스트할 수 있습니다.

A단계: 도구 실행 시작

브라우저 탭을 열고 클라이언트 URL(http://localhost:8501)로 이동합니다.
왼쪽 창에서 에이전트 유형을 Remote Agent Engine로 설정합니다.
Google Cloud 프로젝트와 위치를 입력합니다. Load Remote Agents를 클릭합니다. 이렇게 하면 프로젝트에 배포된 모든 에이전트가 로드됩니다.
드롭다운에서 올바른 에이전트를 선택하고 설정을 저장합니다.
채팅 상자에 다음을 입력합니다.
```
Fetch my contributions across my private repositories over the last 6 months
```
를 입력하고 Enter 키를 누릅니다.
채팅 UI를 확인합니다. 에이전트에는 아직 사용자 세션의 사용자 인증 정보가 없으므로 인증 챌린지를 수신하고 대화 스레드에 인증 필요 카드를 표시합니다.

별도의 브라우저 팝업 창이 열리고 Google Cloud의 인증 관리자를 통해 GitHub OAuth 승인 페이지로 리디렉션됩니다.
요청된 권한을 검토하고 승인을 클릭합니다.
GitHub에서 Google Cloud로 다시 리디렉션되고, Google Cloud에서 팝업을 localhost 콜백 URL /validateUserId로 리디렉션합니다.
콜백 서비스는 사용자 인증 정보 핸드셰이크를 처리하고 완료합니다.

C단계: 이력서

팝업 창이 닫히면 상위 채팅 탭에서 자동으로 닫힘을 감지합니다.
프런트엔드는 재개 페이로드를 에이전트에게 다시 보냅니다.
에이전트는 Google Cloud Auth Manager에서 새로 교환된 토큰을 안전하게 가져오고, 사용자를 대신하여 GitHub MCP 도구를 호출하고, 에이전트가 자체적으로는 도달할 수 없는 데이터를 비공개 저장소에서 채팅 창으로 직접 스트리밍합니다.

D단계: Cloud 로그 검사

토큰 교환 및 완료가 안전하게 처리되었는지 확인하려면 다음 단계를 따르세요.

Google Cloud 콘솔 로그 탐색기로 이동합니다.

nonce 추출 및 유효성 검사가 성공했음을 확인하는 서버 로그를 찾습니다.

INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx
INFO:secure-agent-client:Successfully finalized auth provider credentials.

Agent Runtime 로그 검사: 또는 Agent Platform 콘솔 내에서 직접 실행 로그를 볼 수 있습니다.
- Agent Runtime 콘솔로 이동합니다.
- 목록에서 배포된 에이전트를 클릭합니다.
- Playground 탭으로 전환합니다. 그러면 하단 창에 실시간 에이전트 로그가 표시되어 에이전트의 추론 루프, 도구 실행 세부정보, 토큰 검색 수명 주기가 실시간으로 표시됩니다.

10. 삭제

Google Cloud에서 지속적으로 비용이 청구되지 않도록 배포된 리소스를 정리합니다.

# Follow the instructions here to delete the deployed Agent Runtime resource
# https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/manage-deployed-agents#console_3

# Delete the auth provider
gcloud agent-identity auth-providers delete github-oauth-provider \
    --project=YOUR_PROJECT_ID --location=us-central1

# Note: deleted providers sit in soft-delete for 30 days, and the name is not
# reusable until roughly a day after that. Pick a fresh name if you repeat this lab.

# Optionally, you could also delete your Google Cloud Project
gcloud projects delete YOUR_PROJECT_ID

# Optionally, delete the GitHub PAT Token and the OAuth app: 
# https://github.com/settings/personal-access-tokens

로컬 파일 정리

선택적으로 로컬 환경을 완전히 정리하려면 다음 단계를 따르세요.

실행 중인 터미널에서 Ctrl+C를 눌러 로컬 uvicorn 서버를 중지합니다.
이 실습 중에 만든 프로젝트 디렉터리를 삭제합니다.

# cd to the correct folder
rm -rf secure-agent-demo client adk-python

11. 수고하셨습니다

로그인한 사용자를 대신하여 작동하는 에이전트를 성공적으로 빌드하고 보호했습니다.

학습한 내용:

에이전트 시스템 ID: 에이전트가 자체 계정 ID로 작동하여 GCP 인프라와 안전하게 인터페이스하고, 원격 분석 로그를 관리하고, 사용자 인증 정보 완료 API를 호출하는 방법입니다.
사용자 위임 ID: 에이전트가 3단계 OAuth(3LO) 동의 흐름을 트리거하여 GitHub와 같은 외부 플랫폼에서 사용자를 대신하여 작업을 수행할 권한을 요청하는 방법입니다.
안전한 도구 통합: 하드코딩된 보안 비밀을 사용하는 대신 Google Cloud 인증 관리자를 사용하여 ADK 에이전트를 모델 컨텍스트 프로토콜 (MCP) 서버에 연결하여 사용자 토큰을 동적으로 가져오는 방법
IAM 정책 구성: 인증 제공자에서 에이전트 런타임 ID와 자체 계정을 모두 승인하도록 세분화된 권한 바인딩을 설정하는 방법

추가 자료

에이전트 ID 인증 관리자를 참고하여 인증 흐름 구성 및 범위를 파악하세요.
Agent Runtime 개요
ADK 문서
모델 컨텍스트 프로토콜