17. Session/Memory/Artifact [6]- VertexAiSessionService(2/3)

Agentic AI/Google ADK

17. Session/Memory/Artifact [6]- VertexAiSessionService(2/3)

아톨 2026. 10. 25. 17:48

이제 에이전트 엔진 인스턴스를 생성하고, 코드를 실행하여 Google Cloud Resource Name이 표시되는지 확인합니다.

1. STAGING_BUCKET의 버킷명은 어디서 확인할까요?

STAGING_BUCKET = "gs://<버킷명>"은 Google Cloud Storage에 있는 Cloud Storage 버킷의 주소를 지정하는 부분입니다.

여기서 버킷(bucket)은 파일을 담는 최상위 저장 공간이라고 이해하시면 됩니다. 이번 실습에서는 Agent Engine을 생성할 때 필요한 배포 패키지 등의 파일을 임시로 올려 두는 용도로 사용합니다. Google 공식 문서에서도 Agent Engine 생성 설정의 staging_bucket은 gs://로 시작하는 Cloud Storage 버킷이어야 한다고 안내합니다.

방법 A. Google Cloud Console에서 확인하기

① Cloud Storage 버킷 목록 열기

Google Cloud Console에서 현재 프로젝트를 선택한 후 Cloud Storage → Buckets로 이동합니다.

내 프로젝트의 버킷 목록 열기

② 버킷 이름 확인하기

목록에 표시되는 버킷 이름을 확인합니다. 프로젝트 ID가 agent-project-512212라고 해서 버킷 이름도 같은 것은 아닙니다.

예를 들어 실제 버킷 이름이 agent-project-512212-staging이라면 전체 주소는 gs://agent-project-512212-staging입니다.

위 이름은 설명을 위한 예시이며, 실제로 존재하는 버킷이라고 가정한 것은 아닙니다.

방법 B. 터미널에서 확인하기 — 더 간단한 방법

이미 Google Cloud CLI를 설치하셨으므로, Windows PowerShell에서 다음 명령을 실행해 보세요.

gcloud storage buckets list --project=agent-project-512212

현재 프로젝트에 접근 가능한 버킷 목록이 표시됩니다. 예를 들어 다음과 같은 결과가 나온다고 가정하겠습니다.

NAME
gs://agent-project-512212-staging
gs://agent-project-512212-data

이 경우 첫 번째 버킷을 스테이징 용도로 사용하려면 코드를 다음처럼 작성합니다.

STAGING_BUCKET = "gs://agent-project-512212-staging"

중요: 실제로 목록에 표시된 버킷만 사용하세요. 제가 사용자의 Google Cloud 프로젝트에 직접 접근해 현재 버킷 이름을 확인한 것은 아닙니다.

버킷이 하나도 없다면?

새로 생성하면 됩니다. 예를 들어 다음과 같이 실행할 수 있습니다.

gcloud storage buckets create gs://agent-project-512212-staging --project=agent-project-512212 --location=asia-northeast3 --uniform-bucket-level-access

이 명령은 해당 이름의 버킷이 전 세계적으로 고유하고, 해당 리전에서 생성할 수 있으며, 필요한 권한이 있다는 전제하에 동작합니다. 이미 같은 이름의 버킷이 존재하면 다른 이름을 선택해야 합니다.

버킷 이름에는 대문자나 공백을 넣을 수 없으며, 전 세계에서 유일해야 합니다.

또한 버킷을 만들기 전에 asia-northeast3가 이번 Agent Engine 실습에 적합한 리전인지 확인하세요. 버킷의 리전과 Agent Engine의 리전을 맞추면 관리가 편리합니다.

2. 코드 구조 확인

코드가 수행하려는 작업은 다음과 같습니다.

Google Cloud 프로젝트와 리전을 지정합니다.
간단한 Python 에이전트 클래스를 정의합니다.
vertexai.Client를 통해 Vertex AI 클라이언트를 만듭니다.
client.agent_engines.create()로 에이전트를 원격 Agent Engine에 생성합니다.
생성 결과를 출력합니다.

Google의 최신 클라이언트 기반 API에서도 client.agent_engines.create(agent=..., config=...) 형태를 사용합니다.

다만 목표가 무엇인지에 따라 한 가지를 구분해야 합니다.

지금 작성한 코드는 SimpleAgent라는 실제 Python 객체를 Agent Engine에 배포하는 코드입니다.
메모리 뱅크 전용 인스턴스를 만들기 위한 실습이라면, 이 SimpleAgent가 반드시 필요한지는 참고 자료의 의도를 확인해야 합니다. Agent Engine을 생성하는 방법과 Memory Bank 기능을 설정·활용하는 방법은 동일한 작업이 아닙니다.

따라서 지금 코드를 그대로 사용해도 배포 실습으로는 의미가 있지만, 이것만으로 Memory Bank가 활성화되거나 VertexAiSessionService의 세션 저장이 검증되는 것은 아닙니다.

3. 코드 한 줄씩 상세 해설

먼저 원래 코드의 각 부분을 살펴보겠습니다.

① 라이브러리 가져오기

import vertexai

vertexai는 Google Cloud의 Vertex AI 기능을 Python에서 사용하도록 해 주는 라이브러리입니다.

여기서는 이 라이브러리의 Client 객체를 통해 Agent Engine을 생성하려고 합니다.

이 라이브러리는 로컬 컴퓨터에 설치되어 있어야 합니다. 앞서 설치한 google-cloud-aiplatform[agent_engines] 패키지가 관련 기능을 제공합니다.

② 프로젝트와 리전 지정하기

PROJECT_ID = "agent-project-512212"
LOCATION = "asia-northeast3"
STAGING_BUCKET = "gs://<버킷명>"

각 변수의 역할은 다음과 같습니다.

변수의미예시

PROJECT_ID	리소스를 생성할 Google Cloud 프로젝트	agent-project-512212
LOCATION	Agent Engine이 위치할 리전	asia-northeast3
STAGING_BUCKET	배포에 필요한 파일을 올려 둘 Cloud Storage 버킷	gs://실제-버킷-이름

여기서는 프로젝트 ID를 코드에 직접 입력했습니다. 앞서 환경변수로 설정한 프로젝트 ID와 일치하는지 확인해야 합니다.

또한 STAGING_BUCKET은 실제 버킷 주소로 바꿔야 합니다. 꺾쇠괄호가 포함된 "gs://<버킷명>"을 그대로 사용하면 안 됩니다.

③ SimpleAgent 클래스 정의하기

class SimpleAgent:
    def query(self, input: str, **kwargs):
        return {"message": f"Hello from Agent Engine: {input}"}

이 부분은 이번 코드의 핵심입니다.

class SimpleAgent:는 SimpleAgent라는 클래스를 정의한다는 뜻입니다. 클래스는 객체를 만들기 위한 설계도라고 생각하시면 됩니다.

def query(self, input: str, **kwargs):는 에이전트에 질문을 전달할 때 호출될 메서드를 정의합니다.

self: 현재 객체 자신을 가리킵니다.
input: str: 입력받는 질문이 문자열이라는 의미입니다.
**kwargs: 추가적인 키워드 인자를 받을 수 있게 합니다. 다만 이 코드에서는 추가 인자를 사용하지 않습니다.

다음 줄은 실제 응답을 만듭니다.

return {"message": f"Hello from Agent Engine: {input}"}

예를 들어 입력값이 안녕하세요라면 결과는 다음과 같습니다.

{    "message": "Hello from Agent Engine: 안녕하세요"}

이 에이전트는 LLM을 호출하지 않습니다. 입력받은 문장을 문자열에 붙여서 반환하는 아주 단순한 테스트용 에이전트입니다.

왜 이런 간단한 에이전트를 먼저 만들까요?

복잡한 AI 모델이나 도구를 연결하기 전에, 원격 Agent Engine을 생성하고 Python 객체를 배포하는 기본 흐름부터 확인할 수 있기 때문입니다.

④ Vertex AI 클라이언트 만들기

client = vertexai.Client(
    project=PROJECT_ID,
    location=LOCATION,
)

client는 Google Cloud의 Agent Engine 리소스를 관리하기 위한 클라이언트 객체입니다.

project=PROJECT_ID: 어느 프로젝트에 리소스를 생성할지 지정합니다.
location=LOCATION: 어느 리전에 리소스를 생성할지 지정합니다.

이 코드가 실행되면 로컬 Python 프로그램에서 사용할 클라이언트 객체가 준비됩니다.

다만 이 시점에는 Agent Engine 인스턴스가 생성된 것이 아닙니다. 실제 생성은 다음 메서드에서 수행합니다.

⑤ Agent Engine 생성하기

remote_agent = client.agent_engines.create(
    agent=SimpleAgent(),
    config={
        "display_name": "my-agent-engine",
        "description": "Created with vertexai.Client().agent_engines.create()",
        "staging_bucket": STAGING_BUCKET,
        "requirements": [
            "google-cloud-aiplatform[agent_engines, adk]==1.141.0",
            "cloudpickle==3.0.0",
            "pydantic==2.12.3",
        ],
    },
)

여기서 가장 중요한 부분은 다음입니다.

agent=SimpleAgent()

SimpleAgent라는 클래스의 설계도를 사용하는 데서 끝나는 것이 아니라, SimpleAgent()를 통해 실제 객체를 하나 생성해 배포 대상으로 전달합니다.

다음은 config의 의미입니다.

설정역할

display_name	Google Cloud 콘솔에서 구분하기 위한 이름
description	리소스 설명
staging_bucket	배포 패키지를 준비하는 Cloud Storage 버킷
requirements	원격 실행 환경에 설치할 Python 패키지 목록

특히 requirements를 잘 이해해야 합니다.

로컬 컴퓨터에 패키지를 설치하는 것과 원격 Agent Engine 실행 환경에 패키지를 설치하는 것은 별개의 작업입니다.

예를 들어 다음 항목은 원격 실행 환경에 설치할 패키지를 지정합니다.

"requirements": [
    "google-cloud-aiplatform[agent_engines, adk]==1.141.0",
    "cloudpickle==3.0.0",
    "pydantic==2.12.3",
]

각 패키지는 다음과 같은 목적으로 지정되어 있습니다.

google-cloud-aiplatform: Vertex AI SDK 및 Agent Engine 관련 기능
cloudpickle: Python 객체를 직렬화하고 복원하는 데 사용되는 라이브러리
pydantic: 데이터 모델과 데이터 검증을 지원하는 라이브러리

여기서 ==는 특정 버전을 지정한다는 뜻입니다. 예를 들어 cloudpickle==3.0.0은 원격 환경에서 해당 버전을 사용하도록 요청합니다.

버전을 고정하는 것은 재현성을 높이는 데 유용합니다. 다만 이 버전 조합이 현재 환경과 완전히 호환되는지는 실제 배포 과정에서 확인해야 합니다. 참고 자료가 1.141.0 기준으로 작성되었다면 그 버전을 유지하는 것이 비교 실습에는 유리할 수 있습니다. 반면 설치한 SDK가 다른 버전이라면 로컬 SDK와 원격 런타임의 버전 차이도 점검해야 합니다.

⑥ 생성 결과 출력하기

print(remote_agent)

이 코드는 생성 메서드가 반환한 객체를 출력합니다.

여기서 확인할 것은 단순히 오류가 발생하지 않았는지만이 아닙니다. 출력 결과에서 생성된 리소스의 이름이나 ID를 확인할 수 있는지 살펴봐야 합니다.

다음 단계에서 세션 서비스와 연결하려면 Agent Engine의 리소스 이름 또는 ID가 필요하기 때문입니다.

다만 print(remote_agent)만으로 출력되는 형식은 SDK 버전에 따라 달라질 수 있습니다. 따라서 다음 단계에서는 출력된 객체의 api_resource.name을 확인하는 방법을 사용하는 것이 좋습니다.

4. 실행 코드

원래 코드의 구조는 유지하되, 실제 버킷 이름을 입력하고 생성된 리소스 이름을 확인할 수 있도록 조금 보완한 버전입니다.


import vertexai

# ============================================================
# 1. Google Cloud 프로젝트 설정
# ============================================================

PROJECT_ID = "agent-project-512212"
LOCATION = "asia-northeast3"

# 반드시 실제로 존재하는 버킷 이름으로 변경
STAGING_BUCKET = "gs://여기에-실제-버킷-이름"


# ============================================================
# 2. 테스트용 에이전트 클래스 정의
# ============================================================

class SimpleAgent:
    def query(self, input: str, **kwargs):
        return {
            "message": f"Hello from Agent Engine: {input}"
        }


# ============================================================
# 3. Vertex AI 클라이언트 생성
# ============================================================

client = vertexai.Client(
    project=PROJECT_ID,
    location=LOCATION,
)


# ============================================================
# 4. Agent Engine 생성 및 배포
# ============================================================

remote_agent = client.agent_engines.create(
    agent=SimpleAgent(),
    config={
        "display_name": "my-agent-engine",
        "description": (
            "Created with vertexai.Client().agent_engines.create()"
        ),
        "staging_bucket": STAGING_BUCKET,
        "requirements": [
            "google-cloud-aiplatform[agent_engines,adk]==1.141.0",
            "cloudpickle==3.0.0",
            "pydantic==2.12.3",
        ],
    },
)


# ============================================================
# 5. 생성 결과 확인
# ============================================================

print("Agent Engine 생성 요청 완료")
print(remote_agent)

# 리소스 이름 확인
if hasattr(remote_agent, "api_resource"):
    print("Resource name:", remote_agent.api_resource.name)

이 코드는 원래 예제의 버전 고정을 유지했습니다. 다만 다음 두 가지는 기억해 주세요.

STAGING_BUCKET에는 실제 버킷 이름을 넣어야 합니다.
create()가 성공적으로 반환되더라도 실제 배포 상태와 런타임 준비 여부는 별도로 확인해야 할 수 있습니다.

그리고 위 코드의 마지막 부분은 리소스 이름을 확인하기 위한 것입니다. 설치한 SDK에서 api_resource가 제공되지 않는다면 우선 print(remote_agent) 결과를 확인한 후 해당 버전에 맞는 속성을 사용하면 됩니다.

5. 실행 전에 확인할 것

실행 전에 PowerShell에서 다음 세 가지를 확인하면 좋습니다.

gcloud config get-value project
gcloud storage buckets list --project=agent-project-512212
python -m pip show google-cloud-aiplatform

첫 번째 명령은 CLI의 기본 프로젝트를 확인합니다.
두 번째 명령은 실제 버킷 이름을 확인합니다.
세 번째 명령은 현재 Python 환경에 설치된 Vertex AI SDK 버전을 확인합니다.

버킷이 실제로 존재하고, 프로젝트와 리전이 올바르며, 필요한 권한이 있다면 코드를 실행할 준비가 된 것입니다.

공식 문서도 Agent Engine 생성 시 staging_bucket을 지정하고 생성 결과를 통해 관리형 리소스를 확인하는 방식을 안내합니다.

6. 마지막으로 꼭 구분할 점

이번 코드는 SimpleAgent를 원격 Agent Engine에 배포하는 실습입니다. 따라서 이 코드가 성공하면 Agent Engine 생성·배포의 기본 흐름을 확인한 것입니다.

하지만 아직 다음 작업은 수행하지 않았습니다.

Memory Bank 기능을 실제로 사용하도록 설정하거나 연결하기
VertexAiSessionService로 세션 생성하기
사용자와 에이전트의 대화 이벤트 저장하기
프로그램을 다시 실행하거나 세션을 재조회해 영속성 확인하기

다음 단계에서는 생성 결과의 리소스 이름을 확인하고, 그 ID를 이용해 VertexAiSessionService를 연결하면 됩니다.

추가로, Agent Engine은 관리형 클라우드 리소스이므로 실습이 끝난 뒤에는 더 이상 필요하지 않은 리소스를 정리하는 것도 잊지 마세요. 생성 및 사용에 따른 비용은 프로젝트와 서비스 구성에 따라 발생할 수 있습니다.

7. 실제 실행 순서: Windows 기준

이제 실제로 실행해 보겠습니다. 가장 쉬운 방법은 Python 파일로 저장한 후 터미널에서 실행하는 것입니다.

1단계. 가상환경 활성화

Anaconda Prompt에서 기존 ADK 실습용 가상환경을 사용한다면, 예를 들어 다음과 같이 실행합니다.

conda activate i_py310_64

본인이 실제 사용 중인 가상환경 이름이 다르다면 그 이름을 사용하세요.

설치된 Python과 SDK 버전을 확인합니다.

python --version
python -m pip show google-cloud-aiplatform

2단계. 버킷 확인

gcloud storage buckets list --project=agent-project-512212

결과에 실제 버킷이 있는지 확인하고, 그 이름을 코드의 STAGING_BUCKET에 입력합니다.

3단계. 코드 파일 저장

예를 들어 다음 경로에 파일을 저장합니다.

C:\Dev\book_agentic_ai\create_memory_engine.py

코드를 저장하기 전에 STAGING_BUCKET을 실제 버킷 주소로 바꿔 주세요.

4단계. 실행

cd C:\Dev\book_agentic_ai
python create_memory_engine.py

실행이 시작되면 Google Cloud로 리소스 생성 요청이 전송됩니다. 패키지 설치, 배포 패키징, 원격 리소스 생성 때문에 시간이 걸릴 수 있습니다.

중간에 오류가 발생하면 오류 메시지를 확인하기 전까지 같은 코드를 반복 실행하지 않는 것이 좋습니다. 생성 요청이 일부 진행된 뒤 실패했거나, 이미 리소스가 생성되었을 가능성도 있기 때문입니다.

8. 성공 여부를 확실하게 확인하는 방법

실행 결과는 다음 세 가지 방법으로 확인하세요.

방법 1. Python 출력 결과 확인

코드 실행이 정상적으로 끝나고 remote_agent 객체가 출력되면 첫 번째 확인 단계입니다.

특히 다음과 비슷한 리소스 이름이 표시되는지 확인합니다.

projects/agent-project-512212/locations/asia-northeast3/reasoningEngines/1234567890123456789

위 숫자는 예시입니다. 실제 출력되는 값은 다릅니다.

이 리소스 이름의 마지막 부분이 다음 단계에서 사용할 Agent Engine ID입니다. 공식 SDK 문서에서도 Agent Engine의 리소스 이름에 projects/.../locations/.../reasoningEngines/... 형식을 사용합니다.

Google Cloud Documentation

방법 2. Google Cloud Console에서 확인

Agent Engine 리소스가 생성되었는지 웹 콘솔에서도 확인할 수 있습니다.

Google Cloud Console에서 Agent Engine 확인

프로젝트가 agent-project-512212로 선택되어 있는지 확인하고, Agent Engine 목록에서 my-agent-engine이라는 이름을 찾으세요. 콘솔 메뉴 구성은 업데이트에 따라 달라질 수 있습니다.

방법 3. Python으로 생성된 리소스 목록 조회

다음 코드를 별도의 파일 check_engines.py로 저장해서 실행하면 현재 프로젝트와 리전에 등록된 Agent Engine 목록을 확인할 수 있습니다.

import vertexaiPROJECT_ID = "agent-project-512212"LOCATION = "asia-northeast3"client = vertexai.Client(    project=PROJECT_ID,    location=LOCATION,)engines = client.agent_engines.list()for engine in engines:    print("이름:", engine.api_resource.display_name)    print("리소스 ID:", engine.api_resource.name)    print("-" * 50)

목록에 my-agent-engine이 표시되면 해당 이름으로 등록된 리소스를 찾은 것입니다. 최신 SDK의 client.agent_engines.list()는 Agent Engine 목록 조회를 지원합니다.

Google Cloud Documentation

9. 성공 판정 체크리스트

Python 프로그램이 예외 없이 종료되었다.
remote_agent 출력에서 리소스 이름 또는 ID를 확인했다.
Google Cloud Console 또는 목록 조회 코드에서 my-agent-engine을 확인했다.
리소스 이름의 프로젝트 ID와 리전이 내가 지정한 값과 일치한다.

이 네 가지를 확인하면 Agent Engine 생성 성공 여부를 상당히 확실하게 검증할 수 있습니다.

다만 여기까지는 인스턴스 생성과 배포 확인입니다. SimpleAgent가 실제 원격 환경에서 응답하는지 확인하려면 별도의 원격 호출 테스트가 필요하며, Memory Bank 및 VertexAiSessionService의 영속성 검증은 그다음 단계입니다.

* 중요한 확인 1 : 지금 만든 것은 Memory Bank 전용 인스턴스일까요?

Google의 공식 문서에서는 Memory Bank 또는 세션 저장소만 필요할 때 다음과 같이 에이전트 코드를 전달하지 않고 Agent Engine을 생성하도록 안내합니다.

import vertexai

client = vertexai.Client(
    project="agent-project-512212",
    location="asia-northeast3",
)

agent_engine = client.agent_engines.create(
    config={
        "display_name": "my-session-store",
    }
)

print(agent_engine.api_resource.name)

반면 지금 실행하신 코드에는 다음 항목이 있습니다.

agent=SimpleAgent()

그리고 출력 결과에도 다음이 나타납니다.

agent_framework='custom'
class_methods=[ ... 'name': 'query' ... ]

따라서 현재 리소스는 SimpleAgent를 배포한 Agent Engine입니다. 세션 저장소로 활용할 수 있지만, 처음 계획하신 'Memory Bank 전용 인스턴스'를 만드는 예제와는 다릅니다.

이미 생성한 리소스를 바로 삭제할 필요는 없습니다. 세션 영속성 실습을 위해 그대로 활용할 수도 있습니다. 다만 실습 목적을 명확히 구분하려면 아래 두 선택지 중 하나를 택하면 됩니다.

기존 리소스 활용: 지금 생성한 my-agent-engine을 대상으로 세션 영속성을 검증합니다.
목표에 맞게 별도 생성: 위 코드로 에이전트가 없는 my-session-store를 생성하고, 그 리소스를 세션 저장소로 사용합니다.

저라면 학습 목적이 Memory Bank와 세션 저장의 구조를 이해하는 것이라면 두 번째 방법을 추천합니다. 단, 새 리소스를 생성하면 별도의 클라우드 리소스가 추가되므로 중복 생성에 유의하세요.

* 중요한 확인 2 : 다음 단계에 필요한 Agent Engine ID 추출하기

출력에서 확인된 전체 리소스 이름은 다음 형식입니다.

projects/****%%%%$$$$/locations/asia-northeast3/reasoningEngines/2528612$$$$%%%%^^^^

각 부분의 의미는 다음과 같습니다.

부분의미

projects/921865052026	프로젝트 번호
locations/asia-northeast3	서울 리전
reasoningEngines/2528612861094133760	Agent Engine 리소스 ID

여기서 921865052026은 프로젝트 ID인 agent-project-512212와 다른 프로젝트 번호입니다. Google Cloud에서는 둘 다 동일한 프로젝트를 식별하는 데 사용됩니다.

ADK의 VertexAiSessionService를 사용할 때는 다음과 같이 숫자형 ID를 전달할 수 있습니다.

from google.adk.sessions import VertexAiSessionService

session_service = VertexAiSessionService(
    project="agent-project-512212",
    location="asia-northeast3",
    agent_engine_id="2528612861094133760",
)

실제 ID를 코드에 복사해 넣는 대신, 생성 결과에서 자동 추출하려면 다음과 같이 작성할 수도 있습니다.

resource_name = remote_agent.api_resource.name
agent_engine_id = resource_name.split("/")[-1]

print("전체 리소스 이름:", resource_name)
print("Agent Engine ID:", agent_engine_id)

split("/")은 /를 기준으로 문자열을 나누고, [-1]은 마지막 항목을 가져옵니다. 따라서 전체 리소스 이름에서 숫자형 ID만 추출할 수 있습니다.

공식 ADK 문서에서도 이와 같은 방식으로 ID를 추출해 세션 서비스에 전달합니다.

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

'Agentic AI > Google ADK' 카테고리의 다른 글

19. Session/Memory/Artifact [8]- InMemoryMemoryService (0)	2026.10.25
18. Session/Memory/Artifact [7]- VertexAiSessionService(3/3) (0)	2026.10.25
16. Session/Memory/Artifact [5]- VertexAiSessionService(1/3) (0)	2026.10.25
15. Session/Memory/Artifact [4] - DatabaseSessionService 활용Google ADK + PostgreSQL 정리(2/2) (0)	2026.10.18
14. Session/Memory/Artifact [3] - DatabaseSessionService 활용Google ADK + PostgreSQL 정리(1/2) (0)	2026.10.18

현재글17. Session/Memory/Artifact [6]- VertexAiSessionService(2/3)

아톨러브

사회생활, 회사생활, 비즈니스에 대해, 실생황/영화/기술자료/보도 등 다양한 사례를 기반으로, 심리적/심리학적 분석과 이해를 통해, 더 나은 삶을 함께 살아가기

Today :
Yesterday :

아톨러브