GENAI107

개요

이 실습에서는 에이전트 워크플로를 위한 확장 가능한 완전 관리형 환경을 위해 ADK 에이전트를 Agent Engine에 배포하는 방법을 알아봅니다.

이를 통해 인프라가 할당되고 확장되는 동안 에이전트의 논리에 집중할 수 있습니다.

목표

이 실습에서 학습할 내용은 다음과 같습니다.

• Agent Engine에 에이전트를 배포할 때의 이점
• Reasoning Engine Service Agent에 필요한 역할을 부여하는 방법
• ADK 명령줄 인터페이스를 사용하여 에이전트를 Agent Engine에 배포하는 방법
• Agent Engine에 배포된 에이전트를 쿼리하는 방법
• 배포된 에이전트를 모니터링하는 방법
• 에이전트 삭제 방법

설정 및 요건

실습 시작 버튼을 클릭하기 전에

다음 안내를 확인하세요. 실습에는 시간 제한이 있으며 일시중지할 수 없습니다. 실습 시작을 클릭하면 타이머가 시작됩니다. 이 타이머에는 Cloud 리소스를 사용할 수 있는 시간이 얼마나 남았는지 표시됩니다.

Qwiklabs 실습을 통해 시뮬레이션이나 데모 환경이 아닌 실제 클라우드 환경에서 직접 실습 활동을 진행할 수 있습니다. 실습 시간 동안 Google Cloud Platform에 로그인하고 액세스하는 데 사용할 수 있는 새로운 임시 사용자 인증 정보가 제공됩니다.

준비할 사항

이 실습을 완료하려면 다음을 준비해야 합니다.

• 표준 인터넷 브라우저(Chrome 브라우저 권장)
• 실습을 완료할 시간

참고: 이미 개인용 GCP 계정이나 프로젝트가 있어도 이 실습에서는 사용하지 마세요.

실습을 시작하고 Google Cloud 콘솔에 로그인하는 방법

1. 실습 시작 버튼을 클릭합니다. 실습 비용을 결제해야 하는 경우 결제 수단을 선택할 수 있는 대화상자가 열립니다. 왼쪽에는 다음과 같은 항목이 포함된 실습 세부정보 창이 있습니다.

   • Google Cloud 콘솔 열기 버튼
   • 남은 시간
   • 이 실습에 사용해야 하는 임시 사용자 인증 정보
   • 필요한 경우 실습 진행을 위한 기타 정보

2. Google Cloud 콘솔 열기를 클릭합니다(Chrome 브라우저를 실행 중인 경우 마우스 오른쪽 버튼으로 클릭하고 시크릿 창에서 링크 열기를 선택합니다).

   실습에서 리소스가 가동되면 다른 탭이 열리고 로그인 페이지가 표시됩니다.

   팁: 두 개의 탭을 각각 별도의 창으로 나란히 정렬하세요.

   참고: 계정 선택 대화상자가 표시되면 다른 계정 사용을 클릭합니다.

3. 필요한 경우 아래의 사용자 이름을 복사하여 로그인 대화상자에 붙여넣습니다.

   {{{user_0.username | "Username"}}}

   실습 세부정보 창에서도 사용자 이름을 확인할 수 있습니다.

4. 다음을 클릭합니다.

5. 아래의 비밀번호를 복사하여 시작하기 대화상자에 붙여넣습니다.

   {{{user_0.password | "Password"}}}

   실습 세부정보 창에서도 비밀번호를 확인할 수 있습니다.

6. 다음을 클릭합니다.

   중요: 실습에서 제공하는 사용자 인증 정보를 사용해야 합니다. Google Cloud 계정 사용자 인증 정보를 사용하지 마세요. 참고: 이 실습에 자신의 Google Cloud 계정을 사용하면 추가 요금이 발생할 수 있습니다.

7. 이후에 표시되는 페이지를 클릭하여 넘깁니다.

   • 이용약관에 동의합니다.
   • 임시 계정이므로 복구 옵션이나 2단계 인증을 추가하지 않습니다.
   • 무료 체험판을 신청하지 않습니다.

잠시 후 Google Cloud 콘솔이 이 탭에서 열립니다.

참고: Google Cloud 제품 및 서비스에 액세스하려면 탐색 메뉴를 클릭하거나 검색창에 제품 또는 서비스 이름을 입력합니다.

Agent Engine

Vertex AI Agent Engine(이전 명칭: Vertex AI 기반 LangChain 또는 Vertex AI Reasoning Engine)은 개발자가 프로덕션에서 AI 에이전트를 배포, 관리, 확장할 수 있는 완전 관리형 Google Cloud 서비스입니다.

이 서비스의 이점은 Vertex AI Agent Engine 문서에서 자세히 알아볼 수 있습니다.

작업 1. ADK 설치 및 환경 설정

참고: 일반적으로 Qwiklabs에서는 Qwiklabs 학습자 계정과 Google Cloud에 로그인된 다른 계정 간에 혼동하지 않도록 시크릿 모드 브라우저 창을 사용하는 것이 좋습니다. Chrome을 사용하는 경우 시크릿 창을 닫은 다음 이 실습 상단의 Google Cloud 콘솔 열기 버튼을 마우스 오른쪽 버튼으로 클릭하고 시크릿 창에서 링크 열기를 선택하면 쉽게 시크릿 모드 브라우저 창을 사용할 수 있습니다.

Vertex AI 권장 API 사용 설정

1. 이 실습 환경에서는 Vertex AI API가 사용 설정되어 있습니다. 자체 프로젝트에서 이러한 단계를 따르려면 Vertex AI로 이동하여 안내에 따라 사용 설정하면 됩니다.

Cloud Shell 편집기 탭 준비

1. Google Cloud 콘솔 창을 선택한 상태에서 키보드의 G 키와 S 키를 차례로 눌러 Cloud Shell을 엽니다. 또는 Cloud 콘솔의 오른쪽 상단에서 Cloud Shell 활성화 버튼()을 클릭해도 됩니다.

2. 계속을 클릭합니다.

3. Cloud Shell을 승인하라는 메시지가 표시되면 승인을 클릭합니다.

4. Cloud Shell 터미널 패널의 오른쪽 상단에서 새 창에서 열기 버튼 을 클릭합니다.

5. Cloud Shell 터미널에서 다음을 입력하여 Cloud Shell 편집기를 홈 디렉터리로 엽니다.

   cloudshell workspace ~

6. 화면 오른쪽에 표시되는 추가 튜토리얼 또는 Gemini 패널을 닫아 코드 편집기 창을 더 많이 확보합니다.
7. 실습의 나머지 부분을 진행하며 이 창을 Cloud Shell 편집기 및 Cloud Shell 터미널이 있는 IDE로 사용할 수 있습니다.

실습에 필요한 ADK 및 코드 샘플 다운로드 및 설치

1. Cloud Shell 터미널에서 다음 명령어를 실행하여 PATH 환경 변수를 업데이트하고 ADK를 설치합니다.

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install google-adk

2. 다음 명령어를 Cloud Shell 터미널에 붙여넣어 Cloud Storage 버킷에서 파일을 복사하고 압축을 해제하면 실습을 위한 코드를 포함한 프로젝트 디렉터리가 생성됩니다.

   gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_to_agent_engine .

3. 다음 명령어를 사용하여 실습에 필요한 추가 항목을 설치합니다.

   python3 -m pip install -r adk_to_agent_engine/requirements.txt

4. 다음 명령어를 실행하여 adk_to_agent_engine 디렉터리에 .env 파일을 만듭니다. (참고: 마침표로 시작하는 숨은 파일을 보려면 Cloud Shell 편집기 메뉴를 사용하여 보기 > 숨은 파일 전환을 사용 설정하면 됩니다.)

   cd ~/adk_to_agent_engine cat << EOF > .env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION={{{project_0.default_region| GCP_LOCATION}}} MODEL=gemini-2.5-flash EOF

5. .env 파일을 agent 디렉터리에 복사하여 에이전트가 배포되면 필요한 인증 구성을 제공합니다.

   cp .env transcript_summarization_agent/.env

작업 2. 명령줄 배포 방법을 사용하여 Agent Engine에 배포

ADK의 명령줄 인터페이스는 에이전트를 Agent Engine, Cloud Run, Google Kubernetes Engine(GKE)에 배포하는 단축키를 제공합니다. 다음 기본 명령어를 사용하여 각 서비스에 배포할 수 있습니다.

• adk deploy agent_engine(@deploy.command("agent_engine") 데코레이터 아래에 설명된 명령줄 인수 포함)
• adk deploy cloud_run(@deploy.command("cloud_run") 데코레이터 아래에 설명된 명령줄 인수 포함)
• adk deploy gke(@deploy.command("gke") 데코레이터 아래에 설명된 명령줄 인수 포함)

adk deploy agent_engine 명령어는 에이전트를 reasoning_engines.AdkApp 클래스로 래핑하고 이 앱을 Agent Engine의 관리형 런타임에 배포하여 에이전트 쿼리를 수신할 준비를 합니다.

AdkApp이 Agent Engine에 배포되면 영구적인 관리 세션 상태를 위해 VertexAiSessionService를 자동으로 사용합니다. 이를 통해 추가 구성 없이도 멀티턴 대화형 메모리를 제공할 수 있습니다. 로컬 테스트의 경우 애플리케이션은 기본적으로 임시 InMemorySessionService를 사용합니다.

adk deploy agent_engine을 사용하여 Agent Engine 앱을 배포하려면 다음 단계를 완료합니다.

1. adk_to_agent_engine/transcript_summarization_agent 디렉터리에서 agent.py 파일을 클릭하여 이 간단한 요약 에이전트의 안내를 검토합니다.

2. 에이전트를 배포하려면 요구사항을 제공해야 합니다. Cloud Shell 편집기에서 transcript_summarization_agent 디렉터리를 마우스 오른쪽 버튼으로 클릭합니다. (컨텍스트 메뉴를 사용 설정하려면 허용을 클릭해야 할 수 있습니다.)

3. 새 파일...을 선택합니다.

4. 파일 이름을 표준 Python 요구사항 파일처럼 requirements.txt로 지정합니다.

5. 다음 코드를 파일에 붙여넣습니다.

   google-cloud-aiplatform[adk,agent_engines]==1.110.0

6. 파일을 저장합니다.

7. Cloud Shell 터미널에서 다음 명령어를 실행합니다.

   adk deploy agent_engine transcript_summarization_agent \ --display_name "Transcript Summarizer" \ --staging_bucket gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket

   명령어 출력에서 연결되는 로그 파일에서 상태를 추적할 수 있습니다. 배포 중에 다음 단계가 발생합니다.

   1. 다음과 같이 구성된 아티팩트 번들이 로컬로 생성됩니다.
      • *.pkl: local_agent에 해당하는 피클 파일입니다.
      • requirements.txt: 에이전트 폴더에서 패키지 요구사항을 정의하는 파일입니다.
      • dependencies.tar.gz: 추가 패키지가 포함된 tar 파일입니다.
   2. 아티팩트를 스테이징하기 위해 번들이 Cloud Storage에 업로드됩니다(지정된 경우 정의된 디렉터리 사용).
   3. 해당 아티팩트의 Cloud Storage URI는 PackageSpec에 지정됩니다.
   4. Vertex AI Agent Engine 서비스가 요청을 수신하고 컨테이너를 빌드하며 백엔드에서 HTTP 서버를 가동합니다.

   참고: 배포에는 약 10분이 소요되지만 배포가 진행되는 동안 이 실습을 계속 진행할 수 있습니다.

   에이전트 배포 중 퀴즈

   각 adk deploy ... 명령어에는 특정 인수를 설정해야 합니다. 최신 인수를 확인하려면 이 작업의 상단에 있는 목록에서 연결된 명령어를 클릭하고 '필수'라고 표시된 인수를 찾습니다.

   adk deploy agent_engine 배포의 --project 및 --region과 같은 일부 필수 인수는 존재하는 경우 에이전트의 .env 파일에서 값을 로드할 수 있습니다.

   adk deploy agent_engine의 인수를 바탕으로 다음 질문에 답하세요.

   예상 출력의 하이라이트:

   에이전트 소스 코드 복사 중... 에이전트 소스 코드 복사가 완료되었습니다. Vertex AI 초기화 중... [...] Creating AgentEngine Create AgentEngine backing LRO: projects/430282503153/locations/us-central1/reasoningEngines/2902138951282196480/operations/2777364189918789632 View progress and logs at https://console.cloud.google.com/logs/query?project=qwiklabs-gcp-04-f71a2270bd79 AgentEngine created. 리소스 이름: projects/430282503153/locations/us-central1/reasoningEngines/2902138951282196480 다른 세션에서 이 AgentEngine을 사용하려면 다음을 실행합니다. agent_engine = vertexai.agent_engines.get('projects/430282503153/locations/us-central1/reasoningEngines/2902138951282196480') 임시 폴더 정리: /tmp/agent_engine_deploy_src/20250813_175223

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. 에이전트 배포

작업 3. Agent Engine에 배포된 에이전트 가져오기 및 쿼리하기

에이전트를 쿼리하려면 먼저 Vertex AI를 통해 모델을 호출할 수 있는 권한을 에이전트에 부여해야 합니다.

1. 서비스 에이전트와 할당된 역할을 보려면 콘솔에서 IAM으로 이동합니다.

2. Google 제공 역할 부여 포함 체크박스를 선택합니다.

3. AI Platform Reasoning Engine 서비스 에이전트(service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com)를 찾고 이 서비스 에이전트의 행에서 수정 연필 아이콘을 클릭합니다.

4. + 다른 역할 추가를 클릭합니다.

5. 역할 선택 필드에 Vertex AI 사용자를 입력합니다. 도구를 사용하여 다른 데이터에 액세스하는 에이전트를 배포하는 경우 이 서비스 에이전트에도 해당 시스템에 대한 액세스 권한을 부여하게 됩니다.

6. 변경사항을 저장합니다.

7. Cloud Shell 편집기에서 adk_to_agent_engine 디렉터리 내에 있는 query_agent_engine.py 파일을 엽니다.

8. 코드와 주석을 검토하여 코드가 수행하는 작업을 파악합니다.

9. 에이전트에게 전달된 스크립트를 검토하여 적절한 요약을 생성하는지 평가합니다.

10. Cloud Shell 터미널에서 adk_to_agent_engine 디렉터리의 파일을 다음 명령어로 실행합니다.

    cd ~/adk_to_agent_engine/transcript_summarization_agent python3 query_agent_engine.py

    출력 예시(결과는 약간 다를 수 있음):

    [원격 응답] 사용자가 보트를 구매하고 싶어 하며, 크기에 대한 질문을 받은 후 50,000달러로 어떤 보트를 구매할 수 있는지 묻습니다. 가상 에이전트는 50,000달러면 '아주 멋진 보트'를 살 수 있다고 응답하고, 사용자는 이에 동의하여 계속 진행합니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. 에이전트 쿼리

작업 4. Agent Engine에 배포된 에이전트 보기 및 삭제하기

1. 에이전트 배포가 완료되면 Cloud 콘솔이 표시된 브라우저 탭으로 돌아가 콘솔 상단에서 Agent Engine을 검색하고 선택하여 이동합니다.

2. 리전 드롭다운에서 이 실습의 위치()가 선택되어 있는지 확인합니다.

3. 배포된 에이전트의 표시 이름이 표시됩니다. 클릭하여 모니터링 대시보드로 이동합니다.

4. 측정항목 탭과 세션 탭을 모두 확인하세요. 각 탭에서 에이전트가 어떻게 사용되고 있는지에 대한 통계를 확인할 수 있습니다.

5. 에이전트를 삭제할 준비가 되면 모니터링 대시보드 상단에서 배포 세부정보를 선택합니다.

6. Cloud Shell 터미널을 실행 중인 브라우저 탭으로 돌아가서 다음 명령어를 붙여넣되 아직 실행하지는 마세요.

   cd ~/adk_to_agent_engine python3 agent_engine_utils.py delete REPLACE_WITH_AE_ID

7. Agent Engine 배포 정보 패널에서 이름 필드를 복사합니다. 이 필드는 projects/qwiklabs-gcp-02-76ce2eed15a5/locations/us-central1/reasoningEngines/1467742469964693504와 같은 형식을 갖습니다.

8. Cloud Shell 터미널로 돌아가서 명령어의 끝에 있는 REPLACE_WITH_AE_ID를 복사한 리소스 이름으로 바꿉니다.

9. 돌아가기를 눌러 삭제 명령어를 실행합니다.

   출력 예시:

   AgentEngine 리소스 삭제: projects/1029886909158/locations/us-central1/reasoningEngines/1456078850617245696 AgentEngine 지원 LRO 삭제: projects/1029886909158/locations/us-central1/operations/2884525977596067840 AgentEngine 리소스 삭제됨: projects/1029886909158/locations/us-central1/reasoningEngines/1456078850617245696

10. Cloud 콘솔에서 Agent Engine 대시보드로 돌아가 에이전트가 삭제되었는지 확인합니다.

11. 에이전트를 나열하고 삭제하는 간단한 Python SDK 코드를 보려면 adk_to_agent_engine/agent_engine_utils.py 파일의 내용을 확인합니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. 에이전트 나열 및 삭제

수고하셨습니다

이 실습에서는 다음 내용을 배웠습니다.

• Agent Engine에 에이전트를 배포할 때의 이점
• Reasoning Engine Service Agent에 필요한 역할을 부여하는 방법
• ADK 명령줄 인터페이스를 사용하여 에이전트를 Agent Engine에 배포하는 방법
• Agent Engine에 배포된 에이전트를 쿼리하는 방법
• 배포된 에이전트를 모니터링하는 방법
• 에이전트 삭제 방법

다음 단계

이 시리즈의 다른 실습에서 에이전트 개발 키트(ADK)를 사용해 에이전트를 빌드하는 방법을 자세히 알아볼 수 있습니다.

• 도구로 ADK 에이전트 지원
• ADK로 멀티 에이전트 시스템 빌드
• ADK 에이전트를 Agent Engine에 배포

Google Cloud 교육 및 자격증

Google Cloud 기술을 최대한 활용하는 데 도움이 됩니다. Google 강의에는 빠른 습득과 지속적인 학습을 지원하는 기술적인 지식과 권장사항이 포함되어 있습니다. 기초에서 고급까지 수준별 학습을 제공하며 바쁜 일정에 알맞은 주문형, 실시간, 가상 옵션이 포함되어 있습니다. 인증은 Google Cloud 기술에 대한 역량과 전문성을 검증하고 입증하는 데 도움이 됩니다.

설명서 최종 업데이트: 2025년 8월 19일

실습 최종 테스트: 2025년 8월 19일

Copyright 2020 Google LLC All rights reserved. Google 및 Google 로고는 Google LLC의 상표입니다. 기타 모든 회사명 및 제품명은 해당 업체의 상표일 수 있습니다.