10. G-ADK Tool 활용[6](3/3) - GCP 샌드박스 에이전트 엔진 기

GCP 샌드박스 에이전트 엔진 인스턴스 생성 및 ADK(Agent Development Kit) 웹 UI 연동 작업에 대한 전체 흐름과, 두 가지 핵심 코드에 대한 상세한 해설입니다.

1. GCP 샌드박스 에이전트 엔진 구축 및 ADK 연동 작업 순서

1. GCP 인증 및 환경 설정

      1) 터미널에서 구글 클라우드 인증을 수행하여 Application Default Credentials(ADC)를 발급받습니다.

         => winget install -e --id Google.CloudSDK

             Google Cloud CLI (gcloud) 설치하기

              Windows 환경에서 신속/깔끔한 설치하는 방법인 PowerShell의 패키지 관리자인 winget 이용

              설치가 완료되면 반드시 현재 열려 있는 PowerShell 창을 완전히 닫는다.

              새로운 PowerShell 창을 관리자 권한 또는 일반 권한으로 다시 오픈 (환경 변수 경로를 시스템이 인식하기)

         => gcloud auth application-default login

             애플리케이션 기본 인증(ADC) 로그인하기

             새로 연 PowerShell 창에서 프로젝트 폴더로 이동한 뒤, 아까 에러가 났던 명령어를 다시 실행해 줍니다.

             이 명령어를 실행하면 브라우저 창이 자동으로 팝업되면서 Google 계정 로그인 화면이 뜹니다.

             클라우드 환경의 AgentEngine을 사용할 수 있도록 권한을 허용(Allow)해 주시면 인증이 완료됩니다.

          => 새로운 Google Cloud 프로젝트 생성: Google Cloud 콘솔 웹페이지를 이용하는 것이 가장 빠르고 간편합니다.

             가.Google Cloud 콘솔 프로젝트 페이지 열기:콘솔 접속.

               웹 브라우저를 열고 Google Cloud Resource Manager 페이지에 접속한 후 로그인합니다.

             나.새 프로젝트 만들기 버튼 클릭:프로젝트 생성.

               페이지 상단에 있는 [프로젝트 만들기 (Create Project)] 버튼을 클릭합니다.

             다.프로젝트 이름 입력하기:정보 입력.

               - 프로젝트 이름: 원하는 이름을 입력합니다 (예: my-agent-project).

               - 조직 또는 위치: 기본값(조직 없음)으로 둡니다.

               - [만들기 (Create)] 버튼을 누릅니다.

 

             라.새로 만든 프로젝트 선택하기:프로젝트 ID 확인.

               - 프로젝트 생성이 완료되면 상단 프로젝트 선택 드롭다운 메뉴에서 방금 만든 프로젝트를 선택하여 활성화

               - 고유한 프로젝트 ID를 확인

    

             마. 정확한 GCP 프로젝트 ID(Project ID)를 확인 or 사용 가능한 프로젝트 목록 확인

                - gcloud projects list

                - 검증: 출력되는 목록의 첫 번째 열(PROJECT_ID)에 나오는 정확한 문자열을 확인합니다.

 

              바. 현재 PowerShell 세션에 환경 변수를 적용

                -  $env:GOOGLE_CLOUD_PROJECT="steve-project-1"

                -  $env:GOOGLE_CLOUD_LOCATION="asia-northeast3"

                -  검증

         2) gcloud config set project [PROJECT_ID] 명령어로 작업할 대상 GCP 프로젝트를 지정합니다.

       

         3) 로컬 인증(ADC) 파일의 할당량 프로젝트(Quota Project) 동기화

             터미널에 아래 명령어를 입력하여 인증 정보의 프로젝트 ID를 방금 만든 프로젝트로 일치시킵니다.

gcloud auth application-default set-quota-project steve-project-1-511300

 

         4) GCP 프로젝트(steve-project-1-511300)에 결제 계정(Billing Account)이 연결

           가.Google Cloud 결제 페이지 접속하기:웹 브라우저.

             - Google Cloud Billing Console에 접속한 후, 상단 프로젝트 선택 드롭다운에서 방금 만든 프로젝트(steve-project-1-511300)를 선택합니다.

             - 확인 방법: 결제 상태가 '사용 중지됨(Disabled)'으로 표시되어 있는지 확인합니다.

          나.결제 계정 연결하기:결제 프로필 선택.

             - 페이지 내에서 [결제 계정 연결 (Link a billing account)]을 클릭하고, 기존에 등록된 결제 계정을 선택하거나 새 결제 계정을 등록하여 연결합니다.

            - 확인 방법: 결제 대시보드 상태가 **'활성(Active)'**으로 변경되는지 확인합니다.

 

         5) GCS 버킷(Staging Bucket) 생성 및 지정 방법

           - 버킷이란 무엇인가요? Vertex AI Agent Engine은 코드를 클라우드에 배포할 때 소스 파일을 임시로 담아둘 클라우드 저장소(Google Cloud Storage)가 반드시 필요합니다.

           - 버킷명 작성 규칙: 전 세계에서 고유한 이름이어야 하므로, 보통 프로젝트명-staging-bucket 형태로 만듭니다. (예: steve-project-1-staging-bucket)

           - 생성 방법 (터미널에서 실행):

gcloud storage buckets create gs://steve-project-1-staging-bucket --location=asia-northeast3

              (위 명령어로 버킷을 생성한 뒤, 코드의 STAGING_BUCKET 변수에 gs://steve-project-1-staging-bucket을 넣어주시면 됩니다.)

 

      2. 원격 에이전트 엔진 생성 (코드 1)

            - 최신 agentplatform SDK와 AdkApp을 사용하여 GCP 환경(asia-northeast3)에 원격 샌드박스 에이전트 엔진(Reasoning Engine)을 배포합니다.

            - 배포 완료 후 발급되는 고유한 리소스 이름(resource_name)을 확보합니다.

 

      3. ADK 코딩 에이전트 구성 (코드 2)

            - VertexAiCodeExecutor를 활용해 앞서 생성한 GCP 원격 엔진 리소스 경로를 에이전트의 코드 실행 환경으로 지정.

            - 모델(gemini-3.5-flash)과 에이전트 인스턴스(Agent)를 결합하고, 실행 결과를 명확히 출력하도록 인스트럭션을 부여. 

 

      4. 로컬 개발 서버 구동 및 테스트

            - adk web --port 8080 명령어로 로컬 웹 서버를 띄운 뒤, 웹 UI([http://127.0.0.1:8080](http://127.0.0.1:8080))에서 에이전트와 대화하며 코딩/연산 작업을 테스트합니다.

            - 예) 1부터 100까지의 소수(prime number)를 모두 찾고, 그 합계를 구하세요.
            - 예) 파이썬 코드로 피보나치 수열 10번째까지 구해줘

 

2. 코드별 상세 해설

[코드 1] GCP 원격 에이전트 엔진 생성 코드

이 코드는 최신 GCP SDK 규격에 맞춰 클라우드상에 독립적인 에이전트 런타임(Reasoning Engine) 인스턴스를 생성하는 역할을 합니다.

• 라이브러리 및 SDK 버전 전환
  • 과거의 vertexai.Client 대신 최신 표준인 import agentplatform(agentplatform.Client)을 사용하여 클라이언트를 초기화합니다.
• 프로젝트 및 스토리지 설정
  • PROJECT_ID, 리소스가 위치할 LOCATION, 그리고 패키지 및 상태 저장을 위한 GCS 버킷(STAGING_BUCKET)을 명시합니다.
• 에이전트 정의 및 래핑
  • SimpleAgent 클래스 내부에 표준 query 메서드를 구현하여 기본 입출력 구조를 갖추고, 이를 Vertex AI ADK 앱 규격인 AdkApp으로 감쌉니다.
• 원격 런타임 생성 (client.runtimes.create)
  • config 인자에 staging_bucket, 디스플레이 이름, 그리고 원격 샌드박스 환경에서 구동될 필수 패키지 목록(requirements)을 전달하여 배포를 수행합니다.
  • 실행 결과: 배포가 성공하면 projects/465544953779/locations/asia-northeast3/reasoningEngines/5781619166939185152와 같은 고유 리소스 이름(Resource Name)이 발급됩니다.

 

    import agentplatform #최신 agentplatform 라이브러리 사용

    from vertexai.agent_engines import AdkApp

    # 1. 프로젝트 정보 및 GCS 버킷 설정

    PROJECT_ID = "steve-project-1-511300"

    LOCATION = "asia-northeast3"

    STAGING_BUCKET = "gs://steve-project-1-511300-staging-bucket"

    # 2. SimpleAgent 클래스 정의 (표준 query 메서드 구현)

    class SimpleAgent:

        def query(self, input:str, **kwargs):

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

    # 3. 최신 agentplatform 클라이언트 초기화

    client = agentplatform.Client(

        project=PROJECT_ID,

        location=LOCATION,

    )

    # 4. ADK 에이전트를 AdkApp으로 래핑

    app = AdkApp(agent=SimpleAgent())

    # 5. Agent Engine 생성 (staging_bucket을 최상위 인자로 전달)

    # (client.runtimes.create 사용 및 config 내 staging_bucket 지정)

    remote_agent = client.runtimes.create(

        agent=app,

        config={

            "display_name": "my-agent-engine",

            "description": "Created with agentplatform.Client().runtimes.create()",

            "staging_bucket":STAGING_BUCKET, # 최신 SDK 규격에 맞춘 스테이징 버킷 지정

            # 최신 규격에서는 config 내부에 포함됩니다.

            "requirements":["google-adk","google-cloud-aiplatform","pydantic","cloudpickle",],

        }    

    )

    print("성공적으로 생성된 원격 에이전트: ", remote_agent)

 

[코드 2] ADK 기반 코딩 에이전트 연동 코드

코드 1에서 생성한 GCP 원격 샌드박스 엔진을 ADK 에이전트가 코드 실행 도구(Code Executor)로 사용할 수 있도록 연결하는 코드입니다.

• VertexAiCodeExecutor 설정
  • 코드 1에서 발급받은 고유 resource_name과 GCP 프로젝트/리전 정보를 정확히 입력하여, 에이전트가 요청하는 파이썬 코드 실행 작업을 GCP 클라우드 샌드박스로 안전하게 위임합니다.
• 에이전트 정의 (Agent)
  • gemini-3.5-flash 모델을 기반으로 하는 coding_agent를 생성합니다.
  • code_executor에 앞서 설정한 vertexai_code_executor를 장착하여, 에이전트가 복잡한 수학 계산이나 데이터 분석이 필요할 때 직접 코드를 짜서 실행할 수 있는 능력을 부여합니다.
• 인스트럭션(Instruction) 최적화
  • 에이전트가 백엔드에서 코드를 실행한 후, 그 결과와 정답을 사용자에게 자연어로 친절하게 요약·설명하도록 명시적인 지시문을 추가하여 응답 누락 가능성을 방지합니다.
• 루트 에이전트 지정 (root_agent)
  • ADK 웹 서버가 로드할 수 있도록 최종 에이전트를 root_agent 변수에 할당합니다.

 

    import os

    from google.adk import Agent

    from google.adk.code_executors import VertexAiCodeExecutor

    vertexai_code_executor = VertexAiCodeExecutor(

        project="steve-project-1-511300",

        location="asia-northeast3",

        resource_name="projects/4655****3779/locations/asia-northeast3/reasoningEngines/5781****6693918****"

    )

    coding_agent = Agent(

        model=os.getenv("GOOGLE_MODEL","gemini-3.5-flash"),

        name="coding_agent",

        code_executor=vertexai_code_executor,

        instruction=(

            "당신은 수학 및 데이터 분석 전문가입니다. "

            "복잡한 계산이나 로직이 필요한 경우 직접 파이썬 코드를 작성하고 실행하세요. "

            "**중요: 코드 실행이 완료되면, 반드시 그 실행 결과와 최종 도출된 정답을 사용자가 읽기 쉽도록 친절하게 설명하여 답변하세요.**"

        )

    )