Agentic AI/Google ADK

16. Session/Memory/Artifact [5]- VertexAiSessionService(1/3)

아톨 2026. 10. 25. 17:27

실습 전 준비 → Google Cloud 설정 → Agent Engine 생성 → ID 확인 → ADK Web 연결 → 서버 재시작 검증 → 최종 정리 순서로 정리하겠습니다.

 

목표는 로컬 PC에서 실행하는 Google ADK 에이전트에 Google Cloud의 관리형 세션 서비스를 연결하여, 웹 서버를 종료하고 다시 실행해도 기존 대화 맥락을 유지할 수 있는지 검증하는 것입니다. 핵심 질문은 다음과 같습니다.

로컬에서 adk web으로 실행하는 에이전트가 대화 세션을 Google Cloud에 저장하면, 서버를 재시작한 뒤에도 이전 대화의 맥락을 이어갈 수 있을까?

이를 확인하기 위해 기존의 InMemorySessionService 대신 VertexAiSessionService를 사용했습니다.

 

1. 먼저 결론부터

실제 실습에 들어가기 전에 몇 가지를 정확하게 구분해야 합니다.

특히 다음 세 가지가 중요합니다.

  • VertexAiSessionService는 대화 세션과 이벤트를 Google Cloud의 관리형 Agent Engine 세션 서비스에 저장하고 관리합니다.

  • 이번 실습에서 생성하려는 Agent Engine은 Memory Bank 전용으로 사용할 수 있는 인스턴스입니다. 에이전트 프로그램 자체를 배포하지 않아도 생성할 수 있습니다.

  • GOOGLE_COULD_LOCATION은 오타입니다. 반드시 GOOGLE_CLOUD_LOCATION으로 설정해야 합니다.

Google의 공식 문서도 프로젝트, Agent Platform API, 로컬 인증, 프로젝트·리전 환경변수, Agent Engine 리소스 생성을 기본 준비 과정으로 안내합니다.

 
 

이번에는 기존에 진행하신 Google ADK와 PostgreSQL 실습의 연장선에서, Windows 로컬 개발 환경을 기준으로 차근차근 설명합니다.

2. 전체 실습의 구조부터 이해하기

 

먼저 두 개념을 구별하겠습니다.

구분 Session Service Memory Bank
핵심 역할 대화 세션과 이벤트 관리 대화에서 유용한 정보를 장기 기억으로 관리
예시 사용자가 첫 번째로 무슨 질문을 했는지 사용자는 Python과 AI Agent 공부를 계속할 계획
주요 용도 대화 이어가기, 세션 상태 관리 과거 대화에서 관련 정보를 찾아 활용
이번 실습 VertexAiSessionService 메모리 전용 Agent Engine 생성 단계에서 기반 마련

따라서 이번에 Agent Engine을 만드는 것과 실제로 세션이 저장되는지 검증하는 것은 별개의 단계입니다. 인스턴스를 만들었다고 해서 로컬 에이전트가 자동으로 그 인스턴스에 연결되는 것은 아닙니다.

3. 사전 준비 항목별 검증 및 상세 해설

① Google Cloud 프로젝트 생성(필수)

실습 전용 프로젝트를 만드는 것은 좋은 방법입니다. 프로젝트는 Google Cloud 리소스를 관리하는 기본 단위입니다.

프로젝트별로 API 활성화, IAM 권한, 결제, 리소스와 사용량을 관리할 수 있습니다.

  • 프로젝트 이름 예시: adk-vertex-session-lab

  • 프로젝트 ID 예시: adk-vertex-session-lab-123456

주의할 점은 프로젝트 이름과 프로젝트 ID는 다르다는 것입니다. 이후 환경변수에 넣어야 하는 값은 프로젝트 ID입니다.

확인 위치: Google Cloud Console → 프로젝트 선택 메뉴

 

② Vertex AI API 활성화(필수)

Google Cloud의 기능을 프로그램에서 사용하려면 해당 API를 활성화해야 합니다. Python 라이브러리를 설치하는 것만으로는 클라우드 서비스에 접근할 수 없습니다.

일반적으로 활성화할 API의 서비스 이름은 다음과 같습니다.

aiplatform.googleapis.com

확인 위치: Vertex AI API 페이지

프로젝트에서 결제가 활성화되어 있어야 할 수 있으며, 실제 서비스 사용에는 요금이 발생할 수 있습니다. API 활성화와 과금은 별개의 사항입니다.

 

③ Google Cloud 인증(필수)

로컬 Python 프로그램이 Google Cloud에 요청을 보낼 때, 어떤 사용자 또는 서비스 계정의 권한으로 요청하는지 확인하는 절차입니다.

이번 실습에서는 로컬 개발용으로 다음 명령을 사용합니다.

gcloud auth application-default login

이 명령은 브라우저를 열어 Google 계정으로 로그인하고, Application Default Credentials(ADC) 를 구성합니다.

여기에는 중요한 차이가 있습니다.

  • gcloud auth login: 주로 gcloud CLI 명령을 실행할 사용자를 인증합니다.

  • gcloud auth application-default login: Python 등의 애플리케이션이 Google Cloud API를 호출할 때 사용할 기본 인증 정보를 구성합니다.

두 인증은 서로 다른 용도입니다. 이번처럼 Python SDK를 사용하는 실습에서는 ADC 인증이 중요합니다.

또한 로그인했다고 모든 작업이 허용되는 것은 아닙니다. 로그인한 계정에 프로젝트의 적절한 IAM 권한이 있어야 합니다.

 

④ 환경변수 설정(필수)

환경변수는 프로그램이 실행될 때 참조하는 설정값입니다. 코드에 프로젝트 ID와 리전을 매번 직접 적지 않아도 되도록 해 줍니다.

필요한 변수는 다음 두 가지입니다.

  • GOOGLE_CLOUD_PROJECT: Google Cloud 프로젝트 ID

  • GOOGLE_CLOUD_LOCATION: 리전(region), 즉 리소스가 위치할 지역

제시하신 GOOGLE_COULD_LOCATION은 철자가 잘못되었습니다. CLOUD로 수정해야 합니다.

리전으로 제시하신 asia-northeast3는 서울 리전을 가리킵니다. 다만 Agent Engine과 Memory Bank가 해당 리전에서 지원되는지 확인한 뒤 사용해야 합니다. 지원되지 않는다면 두 서비스가 지원하는 공통 리전을 선택해야 합니다.

 

⑤ Python 라이브러리 설치(필수)

VertexAiSessionService를 사용하는 ADK Python 실습이라면 ADK의 GCP 관련 추가 의존성도 명시하는 편이 좋습니다.

권장 명령은 다음과 같습니다.

pip install -U "google-adk[gcp]" "google-cloud-aiplatform[agent_engines]"

각 패키지의 역할은 다음과 같습니다.

패키지 역할
google-adk[gcp] ADK 본체와 Google Cloud 연동에 필요한 추가 의존성
google-cloud-aiplatform[agent_engines] Vertex AI SDK와 Agent Engine 관련 기능

-U는 패키지를 설치하거나 사용 가능한 최신 버전으로 업데이트하라는 옵션입니다.

두 패키지를 함께 최신화하면 기존 프로젝트의 다른 의존성과 충돌할 수 있으므로, 기존 ADK 실습 환경과 분리한 가상환경에서 진행하는 것을 권합니다.

참고로 최신 SDK 설치 여부와 실제 서비스 지원 리전은 별도로 확인해야 합니다. 패키지 버전이 최신이라고 해서 모든 리전과 모든 API 기능이 자동으로 지원되는 것은 아닙니다.

 
 

4. Windows에서 그대로 따라 하기

기존 개발 환경이 Windows이고 ADK 실습을 진행해 오셨으므로, 우선 Anaconda Prompt 또는 터미널에서 활성화한 Python 가상환경을 기준으로 설명하겠습니다.

4-1. Google Cloud CLI 설치 여부 확인

먼저 gcloud 명령을 사용할 수 있는지 확인합니다.

gcloud --version

정상적으로 버전 정보가 나오면 다음 단계로 진행합니다. 명령을 찾을 수 없다는 오류가 발생하면 Google Cloud CLI 설치 안내를 참고해 설치한 후 터미널을 다시 엽니다.

4-2. Google Cloud 프로젝트 선택

먼저 현재 CLI 설정을 확인합니다.

gcloud config list

실습 프로젝트가 선택되어 있지 않거나 다른 프로젝트가 선택되어 있다면 다음과 같이 설정합니다.

gcloud config set project YOUR_PROJECT_ID

YOUR_PROJECT_ID를 실제 프로젝트 ID로 바꿔야 합니다. 예를 들어 프로젝트 ID가 adk-vertex-session-lab-123456이라면 다음과 같습니다.

gcloud config set project adk-vertex-session-lab-123456

이 설정은 CLI의 기본 프로젝트를 지정합니다. Python SDK가 사용할 프로젝트를 확실하게 지정하려면 다음 환경변수 설정도 별도로 해야 합니다.

4-3. Vertex AI API 활성화

gcloud services enable aiplatform.googleapis.com

명령이 성공하면 해당 프로젝트에서 Vertex AI API를 사용할 수 있도록 활성화한 것입니다.

확인하려면 다음 명령을 실행합니다.

gcloud services list --enabled

출력에 aiplatform.googleapis.com이 있는지 확인합니다.

4-4. ADC 인증

gcloud auth application-default login

브라우저가 열리면 사용할 Google 계정으로 로그인하고 권한 요청을 승인합니다.

인증이 완료되면 다음 명령으로 인증 계정을 확인할 수 있습니다.

gcloud auth list

다만 이 명령은 CLI 계정 목록을 보여주는 것이므로, ADC 인증까지 확실하게 확인하려면 다음 명령도 실행해 보세요.

gcloud auth application-default print-access-token

정상적으로 토큰이 출력되면 ADC 인증 정보로 액세스 토큰을 얻을 수 있는 상태입니다. 토큰은 비밀번호처럼 취급하고 다른 사람에게 공유하지 마세요.

4-5. 환경변수 설정

여기서 중요한 점은 Windows PowerShell과 Linux/macOS 터미널의 명령어가 다르다는 것입니다.

사용하시는 Windows 환경에서는 PowerShell을 기준으로 다음처럼 설정할 수 있습니다.

$env:GOOGLE_CLOUD_PROJECT = "YOUR_PROJECT_ID"
$env:GOOGLE_CLOUD_LOCATION = "asia-northeast3"

실제 프로젝트 ID를 입력한 뒤, 설정값이 올바른지 확인합니다.

echo $env:GOOGLE_CLOUD_PROJECT
echo $env:GOOGLE_CLOUD_LOCATION

각 명령의 의미는 다음과 같습니다.

  • 첫 번째 줄: Python 프로그램이 사용할 Google Cloud 프로젝트를 지정합니다.

  • 두 번째 줄: Agent Engine 리소스를 만들거나 호출할 때 사용할 리전을 지정합니다.

이 방식은 현재 PowerShell 창에만 적용됩니다. 터미널을 새로 열면 다시 설정해야 합니다. 우선 실습을 단순하게 진행하기 위해 이 방법을 추천합니다.

참고로 원래 자료에 있는 export 명령은 Linux, macOS 또는 Git Bash에서 사용하는 문법입니다.

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="asia-northeast3"

두 가지 방법 중 현재 사용하는 터미널에 맞는 방법 하나만 사용하면 됩니다.

4-6. Python 가상환경 확인 및 라이브러리 설치

가상환경이 활성화된 상태에서 다음 명령을 실행합니다.

python --version
python -m pip --version

그다음 권장 패키지를 설치합니다.

python -m pip install -U "google-adk[gcp]" "google-cloud-aiplatform[agent_engines]"

설치가 끝나면 의존성 상태를 확인합니다.

python -m pip check

오류가 없다면 현재 환경에서 설치된 패키지의 의존성 관계가 정상이라는 의미입니다. 다만 이것만으로 Google Cloud API 호출까지 정상임을 보장하지는 않습니다.

5. 빠진 준비 사항은 없는가?

추가로 확인할 사항이 있습니다.

항목 필요 여부 설명
Google Cloud CLI 사실상 필요 ADC 인증과 프로젝트 설정에 사용
결제 계정 연결 프로젝트 및 기능에 따라 필요 Agent Engine 생성과 실제 서비스 사용에 과금이 발생할 수 있음
IAM 권한 필수 API 활성화, Agent Engine 생성 및 세션 접근에 필요한 권한
Agent Platform API 필수 Vertex AI 및 Agent Engine 기능에 사용
리전 지원 여부 필수 확인 선택한 리전에서 대상 기능을 사용할 수 있어야 함
Cloud Storage 버킷 작업에 따라 필요 에이전트 배포용 스테이징 버킷 등이 필요한 경우
Agent Engine 인스턴스 ID 다음 단계에서 필요 세션 서비스를 특정 인스턴스와 연결하는 데 사용

특히 IAM 권한은 중요합니다. 프로젝트를 생성했거나 API를 활성화할 수 있다는 사실만으로 Agent Engine을 생성하고 세션 데이터를 읽고 쓸 수 있는 권한까지 모두 보장되지는 않습니다.

Cloud Storage 버킷도 모든 경우에 무조건 만들어야 하는 것은 아닙니다. 이번처럼 먼저 세션 및 메모리용 Agent Engine을 생성하는 것과, 에이전트 프로그램을 실제 런타임에 배포하는 것은 구분해야 합니다. 배포할 계획이 있다면 스테이징 버킷과 관련 권한을 추가로 준비하는 것이 좋습니다.

6. 사전 준비 완료 여부를 확인하는 체크리스트

아래 항목을 하나씩 확인해 보세요.

사전 준비 진행 상황

- Google Cloud 전용 프로젝트 생성 및 프로젝트 ID 확인

-  Vertex AI API 활성화
-  gcloud CLI 설치 및 실행 확인
-  ADC 인증 완료
-  GOOGLE_CLOUD_PROJECT 설정 확인
-  GOOGLE_CLOUD_LOCATION 설정 확인 및 리전 지원 확인
-  google-adk[gcp] 설치
-  google-cloud-aiplatform[agent_engines] 설치
-  필요한 IAM 권한 및 결제 설정 확인

7. 다음 단계는 어떻게 진행할 것인가?

사전 준비가 끝나면 다음 순서로 진행하면 됩니다.

  1. 1단계 — 메모리 뱅크 전용 Agent Engine 생성: Vertex AI SDK의 vertexai.Client를 사용하여 에이전트 코드를 배포하지 않고 인스턴스를 생성합니다.

  2. 2단계 — Agent Engine ID 확인 및 추출: 생성 결과의 agent_engine.api_resource.name에서 전체 리소스 이름과 숫자형 ID를 확인합니다.

  3. 3단계 — 세션 영속성 검증: VertexAiSessionService를 통해 세션을 만들고 대화 이벤트를 저장한 뒤, 다시 조회하여 세션 데이터가 유지되는지 확인합니다.

여기서 한 가지 더 주의할 점이 있습니다. Memory Bank 기능을 위한 Agent Engine 생성 예제와 세션 서비스에서 요구하는 agent_engine_id의 사용법은 SDK 버전에 따라 세부 사항이 달라질 수 있습니다. 따라서 다음 단계에서는 설치된 SDK의 실제 API에 맞춰 코드를 작성하는 것이 안전합니다. 공식 Memory Bank 문서에는 client.agent_engines.create()와 agent_engine.api_resource.name을 이용하는 생성 및 ID 확인 절차가 소개되어 있습니다.

 

저작자표시 비영리 변경금지 (새창열림)