참고: 일관되고 높은 성능의 환경을 보장하기 위해 이 실습에서는 일부 모델 요청에 대해 캐시된 응답을 제공할 수 있습니다.

GENAI104

개요

복잡한 에이전트형 애플리케이션을 빌드하려면 여러 전문 모델을 조정하고, 도구 통합을 관리하며, 실행 trace를 디버그해야 하는 경우가 많아 수작업 부담이 크고 확장하기도 어렵습니다.

멀티 에이전트 시스템을 빌드, 테스트, 배포할 수 있는 모듈식 프레임워크를 제공하는 에이전트 개발 키트(ADK)를 사용하면 이러한 문제를 해결할 수 있습니다. 전문 에이전트를 계층 구조로 구성하고, 사전 빌드된 도구나 커스텀 도구를 적용하고, 예측 가능한 파이프라인과 동적인 LLM 기반 라우팅을 모두 활용하여 워크플로를 조정할 수 있습니다.

이 실습에서는 ADK를 사용하여, 요소를 활용해 데이터를 분석하고 구조화된 보고서를 생성하는 조사 어시스턴트를 빌드합니다. 새로운 모델이 출시될 때마다 에이전트형 워크플로를 안정적으로 유지할 수 있도록 이러한 종속 항목을 동적으로 관리하는 방법을 살펴봅니다.

목표

이 실습에서는 다음 작업을 수행하는 방법을 알아봅니다.

• ADK 아키텍처(에이전트, 도구, 세션)를 설명합니다.
• 에이전트형 앱의 로컬 개발 환경을 구성합니다.
• 동적 모델과 커스텀 도구 액세스 권한이 있는 에이전트를 정의합니다.
• ADK 브라우저 UI, Python 코드, CLI 채팅 인터페이스를 사용하여 에이전트를 실행하고 검사합니다.

ADK의 이점

에이전트형 애플리케이션을 빌드하는 개발자는 ADK를 통해 다음과 같은 주요 이점을 누릴 수 있습니다.

• 멀티 에이전트 시스템: 전문 에이전트를 계층 구조로 구성하여 확장 가능한 모듈식 애플리케이션을 빌드
• 다양한 도구 생태계: LangChain과 CrewAI 같은 프레임워크의 사전 빌드된 도구와 커스텀 함수, 통합 기능을 에이전트에 적용
• 유연한 조정: 워크플로 에이전트를 사용하여 예측 가능한 파이프라인을 정의하거나 LLM을 사용해 적응형 동적 라우팅을 구현
• 통합된 개발자 환경: 강력한 CLI와 대화형 UI를 통해 실행을 단계별로 살펴보며 로컬에서 개발 및 디버깅
• 기본 제공되는 평가 기능: 테스트 사례를 기준으로 대답 품질과 실행 궤적을 평가하여 성능을 체계적으로 검증
• 배포 준비 완료: Agent Runtime, Cloud Run 또는 커스텀 Docker 인프라에서 에이전트를 쉽게 컨테이너화하고 확장

다른 SDK를 사용해도 모델을 쿼리할 수는 있지만 ADK는 여러 모델 간의 복잡한 연동을 자동으로 처리하는 더 수준 높은 프레임워크를 제공합니다.

설정 및 요건

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

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

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

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

• 표준 인터넷 브라우저 액세스 권한(Chrome 브라우저 권장)

참고: 이 실습을 실행하려면 시크릿 모드(권장) 또는 시크릿 브라우저 창을 사용하세요. 개인 계정과 학습자 계정 간의 충돌로 개인 계정에 추가 요금이 발생하는 일을 방지해 줍니다.

• 실습을 완료하기에 충분한 시간(실습을 시작하고 나면 일시중지할 수 없음)

참고: 이 실습에는 학습자 계정만 사용하세요. 다른 Google Cloud 계정을 사용하는 경우 해당 계정에 비용이 청구될 수 있습니다.

실습을 시작하고 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 제품 및 서비스에 액세스하려면 탐색 메뉴를 클릭하거나 검색창에 제품 또는 서비스 이름을 입력합니다.

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

이 작업에서는 Cloud Shell 편집기를 구성하고, 프로젝트를 초기화하고, 에이전트 개발 키트(ADK)를 설치하여 에이전트형 애플리케이션을 빌드하고 테스트할 수 있는 환경을 준비합니다.

권장 API 사용 설정

이 실습 환경에서는 Agent Platform API와 Telemetry API가 이미 사용 설정되어 있습니다. 한편, 자체 프로젝트에서는 모델을 쿼리하고 원격 분석 데이터를 Cloud Logging으로 전송할 수 있도록 두 API를 별도로 사용 설정해야 합니다.

Cloud Shell 편집기 탭 준비

1. Google Cloud 콘솔 제목 표시줄에서 Cloud Shell 활성화()를 클릭합니다.

   참고: 또는 콘솔 브라우저 탭을 선택하고 G와 S를 차례로 눌러 Cloud Shell 터미널을 엽니다.

2. 계속을 클릭합니다.

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

4. Cloud Shell 터미널 작업 모음에서 새 창에서 열기()를 클릭합니다.

5. Cloud Shell 편집기 작업 모음에서 편집기 열기()를 클릭하여 파일을 확인합니다.

6. 왼쪽 창에서 탐색기()를 클릭하여 파일 탐색기를 엽니다.

7. 폴더 열기를 클릭합니다.

8. 폴더 열기 대화상자가 열리면 확인을 클릭하여 Google Skills 학습자 계정의 홈 폴더를 선택합니다.

9. 코드 편집기를 위한 공간을 더 확보할 수 있도록 화면 오른쪽에 표시되는 추가 튜토리얼 또는 Gemini 패널을 닫습니다.

이후 실습에서는 이 창을 Cloud Shell 편집기와 Cloud Shell 터미널이 있는 IDE로 사용하여 작업할 수 있습니다.

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

1. 다음 명령어를 Cloud Shell 터미널에 붙여넣어 Cloud Storage 버킷에서 이 실습에 사용할 코드가 포함된 프로젝트 디렉터리를 복사합니다.

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

2. Cloud Shell 터미널에서 다음 명령어를 실행하여 사용자 로컬 환경을 포함하도록 PATH 환경 변수를 업데이트하고, 로깅 및 원격 분석을 위한 OpenTelemetry(OTel) 플러그인을 포함한 ADK와 기타 실습에 필요한 항목을 설치합니다.

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install google-adk[otel-gcp]==1.30.0 -r adk_project/requirements.txt

작업 2. ADK 프로젝트 디렉터리의 핵심 개념과 구조 검토

에이전트, 도구, 조정 패턴 등 ADK의 핵심 개념과 기본 구성요소를 살펴보고, 이를 통해 효과적이고 유연한 멀티 에이전트 시스템을 설계하는 데 적용되는 원리를 이해합니다.

• 에이전트: 특정 작업을 완수하도록 설계된 핵심 구성요소입니다. LLM을 기반으로 추론하고, 계획하고, 도구를 활용하여 목표를 달성할 수 있으며, 복잡한 프로젝트에서의 공동작업도 가능합니다.
• 도구: 에이전트는 도구를 사용하여 대화 기능 외에도 외부 API와 상호작용하고, 정보를 검색하고, 코드를 실행하고, 다른 서비스를 호출할 수 있습니다.
• 세션 서비스: 세션 서비스는 단일 대화(Session)의 컨텍스트, 즉 대화 기록(Events)과 해당 대화를 위한 에이전트 작업 메모리(State) 등을 처리합니다.
• 콜백: 에이전트 프로세스의 특정 시점에 확인, 로깅, 동작 수정을 위해 실행되도록 개발자가 제공하는 커스텀 코드 스니펫입니다.
• 아티팩트 관리: 아티팩트를 사용하면 에이전트는 세션 또는 사용자와 관련된 파일이나 바이너리 데이터(예: 이미지 또는 PDF)를 저장, 로드, 관리할 수 있습니다.
• 실행기: 실행 흐름을 관리하고, 이벤트를 기반으로 에이전트 상호작용을 조정하고, 백엔드 서비스와 함께 조율하는 엔진입니다.

다음으로, ADK 프로젝트의 표준 레이아웃을 살펴보고 이러한 개념이 실제로 어떻게 적용되는지를 확인합니다.

1. Cloud Shell 편집기의 파일 탐색기 창에서 adk_project를 클릭하여 디렉터리를 엽니다.

2. adk_project에 있는 에이전트 디렉터리 4개(adk_utils, app_agent, llm_auditor, my_google_search_agent)를 확인합니다. 각 디렉터리는 하나의 개별 에이전트를 나타냅니다. 프로젝트 디렉터리 내에서 에이전트를 각각의 디렉터리로 분리하면 체계적인 관리가 가능하며, 어떤 에이전트가 있는지 ADK에서 인식할 수 있습니다.

3. my_google_search_agent를 클릭하여 에이전트 디렉터리를 살펴봅니다.

   참고: 현재 adk_project/my_google_search_agent 디렉터리에 있는지 확인하세요.

4. init.py를 클릭하여 콘텐츠를 확인하고 디렉터리에 agent.py 파일도 포함되어 있는지 확인합니다.

5. init.py 파일에는 agent.py 파일에서 가져오는 코드 한 줄이 포함되어 있습니다. ADK는 이 한 줄을 통해 이 디렉터리를 에이전트 패키지로 식별합니다.

   from . import agent

6. agent.py를 클릭하여 Google 검색 도구가 탑재된 간단한 에이전트의 코드를 확인합니다.

   • google.adk에서 가져오는 Agent 클래스와 tools 모듈에서 가져오는 google_search 도구를 확인합니다.
   • 이 간단한 에이전트를 구성하는 파라미터에 관한 코드 주석을 읽습니다.

7. 가져온 google_search 도구를 사용하려면 이 도구를 에이전트에 전달해야 합니다. 다음 줄을 agent.py 파일의 34번 줄 근처에 붙여넣습니다. Agent 객체 생성의 끝부분에 표시된 위치에 붙여넣으면 됩니다.

   tools=[google_search]

8. agent.py 파일을 저장합니다.

도구를 사용하면 에이전트가 텍스트 생성 외에도 다양한 작업을 수행할 수 있습니다. 예를 들어 google_search 도구를 사용하면 에이전트는 학습 데이터에서 얻은 정보보다 더 많은 정보가 필요한 시점을 결정할 수 있습니다. 이후에는 검색어를 작성하고, Google 검색을 사용하여 웹을 검색한 후, 결과를 기반으로 사용자에게 대답할 수 있습니다.

검색한 추가 정보를 기반으로 모델이 대답하는 일을 '그라운딩'이라고 하며, 이 전체 프로세스를 '검색 증강 생성', 즉 'RAG'라고 합니다.

작업 3. ADK 개발 UI를 사용하여 에이전트 실행

ADK에는 로컬에서 실행하도록 설계된 개발 UI가 있어 에이전트를 쉽게 개발하고 테스트할 수 있습니다. 개발 UI를 사용하면 각 에이전트가 어떤 작업을 수행 중이며 여러 에이전트가 서로 어떻게 상호작용하는지를 시각화할 수 있습니다. 이 작업에서는 이 인터페이스를 살펴봅니다.

참고: 에이전트를 실행할 때 ADK는 누가 모델 API 호출을 요청하는지를 알아야 합니다. 이 정보는 다음 두 가지 방법으로 제공할 수 있습니다.

1. Gemini API 키를 제공합니다.
2. Google Cloud 사용자 인증 정보로 환경을 인증하고 모델 API 호출을 Agent Platform 프로젝트 및 위치와 연결합니다.

이 실습에서는 Agent Platform 접근 방식을 사용합니다.

1. Cloud Shell 터미널에서 다음 명령어를 실행하여 에이전트가 프로젝트와 전역 엔드포인트를 사용하도록 환경 변수를 설정하는 .env 파일을 작성합니다.

   cd ~/adk_project cat << EOF > my_google_search_agent/.env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION=global MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} OTEL_SERVICE_NAME=adk-agent OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true EOF

   이러한 변수는 다음 역할을 수행합니다.

   • GOOGLE_GENAI_USE_VERTEXAI=TRUE는 Gemini API 키 인증 대신 Vertex AI를 인증에 사용한다는 사실을 나타냅니다.
   • GOOGLE_CLOUD_PROJECT와 GOOGLE_CLOUD_LOCATION은 모델 호출을 연결할 프로젝트와 위치를 제공합니다.
   • MODEL은 필수 항목은 아니지만 다른 환경 변수로 로드할 수 있도록 여기에 저장됩니다. 다양한 배포 환경에서 다양한 모델을 사용해 볼 수 있는 편리한 방법입니다.
   • OTEL_SERVICE_NAME, OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED와 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT는 에이전트에서 ADK 관련 원격 분석 데이터를 수집하도록 OpenTelemetry(OTel)를 구성하는 데 사용됩니다.

   ADK 개발 UI와 CLI 채팅 인터페이스는 .env 파일에서 구성을 자동으로 로드합니다. 파일이 없으면 이름이 일치하는 시스템 환경 변수를 사용합니다.

2. Cloud Shell 터미널에서 다음 명령어를 실행하여 현재 위치가 에이전트 하위 디렉터리가 있는 adk_project 디렉터리인지 확인합니다.

   cd ~/adk_project

3. 다음 명령어를 유용한 플래그와 함께 사용하여 ADK 개발 UI를 실행합니다. 이 명령어는 다음 작업을 실행합니다.

   • ADK 개발 UI를 사용하여 Fast API 웹 서버 실행
   • Cloud Shell 웹 미리보기에서 에이전트를 쿼리하도록 허용
   • 원격 분석 데이터를 Cloud Logging으로 전송
   • 코드 변경이 감지되면 에이전트를 다시 로드
   adk web \ --allow_origins "regex:https://.*\.cloudshell\.dev" \ --otel_to_cloud \ --reload_agents

   출력

   INFO: Started server process [2434] INFO: Waiting for application startup. +-------------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://localhost:8000. | +-------------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

   현재 개발 UI가 실행 중이므로 ADK 개발 UI URL이 표시됩니다.

4. 새 탭에서 웹 인터페이스를 보려면 터미널 출력에서 http://127.0.0.1:8000 링크를 클릭합니다. 이렇게 하면 Cloud Shell 인스턴스에서 로컬로 실행되는 이 앱에 프록시를 통해 연결됩니다. 그 결과 새 탭에서 개발 UI가 실행됩니다.

5. 왼쪽의 에이전트 선택 메뉴 옵션에서 my_google_search_agent를 선택합니다.

   

6. 다음 질문을 입력해 에이전트가 Google 검색 도구를 사용하게 합니다.

   I know the Summer olympics are happening in 2028, please tell me which countries are participating and what events will be held.

   에이전트가 Google 검색을 사용해 실시간 정보를 검색함으로써 사전 학습된 모델의 지식 단절을 우회하는 것을 확인할 수 있습니다.

   참고: Google 검색을 사용한 그라운딩을 통해 생성한 대답에는 에이전트의 대답 하단에 표시되는 것과 같이 바로 표시할 수 있는 HTML 형식의 '추천 검색어'가 포함됩니다. Google 검색을 사용한 그라운딩 기능을 사용할 때는 모델이 대답에 사용한 정보를 사용자가 더 자세히 확인할 수 있도록 이러한 추천 검색어를 반드시 표시해야 합니다.

7. 왼쪽 창에 Trace 탭이 기본으로 선택되어 있습니다. 마지막 쿼리 텍스트(I know the Summer olympics are happening in 2028, please tell me which countries are participating and what events will be held.)를 클릭하여 쿼리의 서로 다른 부분이 실행되는 데 걸린 시간을 추적합니다.

   이 기능을 사용하면 도구 호출과 관련된 더 복잡한 실행을 디버그하여 다양한 프로세스가 대답의 지연 시간에 어떤 영향을 미치는지를 파악할 수 있습니다.

   

8. 창의 채팅 토론 섹션으로 돌아가서 오른쪽 창에 있는 에이전트의 대답 옆 에이전트 아이콘()을 클릭하여, 에이전트에서 반환한 이벤트를 확인합니다. 이 이벤트에는 사용자에게 반환된 content와 대답의 기반이 된 검색 결과를 자세히 설명하는 groundingMetadata가 포함됩니다.

9. ADK 개발 UI 탐색이 끝나면 이 브라우저 탭을 닫습니다.

10. Cloud Shell 터미널이 있는 브라우저 탭으로 돌아가 터미널 창을 클릭합니다.

11. Ctrl+C를 눌러 웹 서버를 중단합니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. ADK 웹 UI를 사용하여 에이전트 실행

작업 4. 프로그래매틱 방식으로 에이전트 실행

ADK 개발 UI는 테스트와 디버깅에 적합하지만 프로덕션에서 여러 사용자에게 에이전트를 제공하는 데는 적합하지 않습니다.

더 큰 애플리케이션의 일부로 에이전트를 실행하려면 이전 작업에서 웹 앱이 처리한 agent.py 스크립트에 몇 가지 추가 구성요소를 포함해야 합니다. 다음 단계를 진행하여 이러한 구성요소가 포함된 스크립트를 열고 검토하세요.

1. 디렉터리에 .env 파일이 없는 경우 모든 에이전트에서 사용할 환경 변수를 설정할 수 있습니다. Cloud Shell 터미널에서 다음 명령어를 실행하여 환경 변수를 내보냅니다.

   export GOOGLE_GENAI_USE_VERTEXAI=TRUE export GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} export GOOGLE_CLOUD_LOCATION=global export MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}}

2. Cloud Shell 편집기 파일 브라우저에서 adk_project/app_agent를 클릭합니다.

3. 이 디렉터리에서 agent.py 파일을 클릭합니다.

4. 이 에이전트는 애플리케이션의 일부로 실행되도록 설계되었습니다. agent.py에서 주석 처리된 코드를 읽습니다. 코드의 다음 구성요소에 특히 주목하세요.

   • 에이전트 실행 기능을 감시하는 역할을 하는 (68번째 줄 근처에 있는) InMemoryRunner(): Runner는 사용자의 쿼리를 수신하여 적절한 에이전트에 전달하고, 에이전트의 대답 이벤트를 수신하여 호출 애플리케이션이나 UI로 다시 전달한 후 다음 이벤트를 트리거하는 코드입니다. 자세한 내용은 ADK의 이벤트 루프 관련 문서를 참고하세요.
   • (71번째 줄 근처에 있는) runner.session_service.create_session(): 대화 기록 및 공유 상태를 관리하는 기능입니다. Session을 사용하면 에이전트가 상태를 유지하도록 하여 항목 목록, 작업의 현재 상태 또는 기타 '최신' 정보를 기억할 수 있습니다. 이 클래스는 단순화를 위해 로컬 세션 서비스를 생성하지만, 프로덕션 환경에서는 데이터베이스를 통해 이 클래스를 처리할 수도 있습니다.
   • (78번째와 79번째 줄 근처에 있는) types.Content() 및 types.Part(): 정형 멀티모달 메시지 기능입니다. 단순 문자열 대신 여러 Part로 구성될 수 있는 Content 객체가 에이전트에 전달됩니다. 이를 통해 텍스트와 멀티모달 콘텐츠를 포함한 복잡한 메시지를 특정 순서로 에이전트에게 전달할 수 있습니다.
   참고: ADK 개발 UI에서 에이전트를 실행했을 때는 세션 서비스, 아티팩트 서비스, 실행기가 자동으로 생성되었습니다. 하지만 프로그래매틱 방식으로 배포하기 위해 자체 에이전트를 작성할 때는 메모리 내 버전을 사용하는 대신 이러한 구성요소를 외부 서비스로 제공하는 것이 좋습니다.

   스크립트에는 에이전트에게 "What is the capital of France?"라고 묻는 하드코딩된 쿼리가 (93번째 줄 근처에) 포함되어 있습니다.

5. Cloud Shell 터미널에서 다음 명령어를 실행하여 에이전트를 프로그래매틱 방식으로 실행합니다.

   python3 app_agent/agent.py

   선택된 출력:

   ** User says: What is the capital of France? ... ** trivia_agent: The capital of France is Paris.

Pydantic 스키마 클래스 추가

다음과 같이 에이전트의 특정 입력 또는 출력 스키마를 정의할 수도 있습니다.

1. 28번째 줄 근처에 Pydantic 스키마 클래스인 BaseModel과 Field를 가져오는 다음 문을 추가하여 스키마 클래스를 정의합니다.

   from pydantic import BaseModel, Field class CountryCapital(BaseModel): capital: str = Field(description="A country's capital.")

2. root_agent의 Agent 정의에서 62번째 줄 근처에 output_schema 파라미터를 설정하여 위에서 정의한 CountryCapital 스키마를 사용합니다.

   output_schema=CountryCapital

3. 에이전트 스크립트를 다시 실행하여 output_schema에 따른 대답을 확인합니다.

   python3 app_agent/agent.py

   선택된 출력:

   ** User says: What is the capital of France? ... ** trivia_agent: {"capital": "Paris"}

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. 프로그래매틱 방식으로 에이전트 실행

작업 5. 명령줄 인터페이스를 통해 에이전트와 채팅

명령줄 인터페이스를 사용하여 로컬 개발 환경에서 에이전트와 채팅할 수도 있습니다. 에이전트를 개발할 때 빠르게 디버깅하고 테스트하는 데 매우 유용합니다.

웹 인터페이스와 마찬가지로 명령줄 인터페이스도 에이전트를 위한 세션 서비스, 아티팩트 서비스, 실행기 생성을 처리합니다.

명령줄 인터페이스를 사용하여 대화형 세션을 실행하려면 다음 단계를 따르세요.

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

   adk run my_google_search_agent

   출력:

   Log setup complete: /tmp/agents_log/agent.20250322_010300.log To access latest log: tail -F /tmp/agents_log/agent.latest.log Running agent basic_search_agent, type exit to exit. user:

2. 다음 메시지를 입력합니다.

   What are some popular movies that have been released in India this year?

   출력 예시(사용자마다 다를 수 있음):

   [google_search_agent]: Here are some of the movies that have been released in India in the past month (January 2026 to early February 2026): * **January 16, 2026**: *Bihu Attack*, *Happy Patel: Khatarnak Jasoos*. * **January 23, 2026**: *Border 2*. * **January 30, 2026**: *Mardaani 3*, *Mayasabha - The Hall of Illusion*. * **February 5, 2026**: *Vadh 2*, *Haunted 3D: Ghosts Of The Past*. * **February 13, 2026**: *Tu Yaa Main*, *O'Romeo*, *Swayambhu*,. * **February 19, 2026**: *Veer Murarbaji*, *Do Deewane Seher Mein*. * **February 20, 2026**: *Epic: Elvis Presley In Concert*, *Hamnet*. * **February 26, 2026**: *The Kerala Story 2 Goes Beyond*.

3. 명령줄 인터페이스와의 채팅이 끝나면 다음 사용자 프롬프트에 exit를 입력하여 채팅을 종료합니다.

작업 6. 멀티 에이전트 예시 미리보기

이 작업에서는 멀티 에이전트 시스템을 살펴보고 핵심 ADK 기능을 이해합니다.

이 에이전트형 시스템은 LLM에서 사실에 그라운딩하여 생성한 대답을 평가하고 개선합니다. 다음이 포함됩니다.

• 자동화된 사실 확인 도구 역할을 하는 critic_agent
• 확인된 결과를 기반으로 부정확한 부분을 수정하기 위해 필요한 경우 대답을 다시 작성하는 reviser_agent

이 에이전트를 살펴보려면 다음 단계를 따르세요.

1. Cloud Shell 편집기 파일 탐색기를 사용하여 adk_project/llm_auditor 디렉터리로 이동합니다.

2. llm_auditor 디렉터리에서 agent.py를 클릭합니다.

3. 이 멀티 에이전트 예시에서는 다음과 같은 사항을 확인할 수 있습니다.

   • SequentialAgent는 사용자 입력 없이도 에이전트 간에 대화 제어를 순차적으로 전달하는 워크플로 클래스입니다. 실행되면 critic_agent와 reviser_agent가 순서대로 자동으로 대답합니다.
   • 이러한 하위 에이전트는 각각 sub_agents 디렉터리 내의 자체 디렉터리에서 가져옵니다.
   • 하위 에이전트 디렉터리에는 init.py, agent.py, prompt.py가 포함되어 있습니다. prompt.py를 사용하여 복잡한 프롬프트를 독립적으로 관리한 후 agent.py로 가져옵니다.

4. 앞에서 만든 .env 파일을 이 에이전트에서도 사용할 수 있도록 복사한 다음 Cloud Shell 터미널에서 다음 명령어를 실행하여 ADK 개발 UI를 다시 실행합니다.

   cd ~/adk_project cp my_google_search_agent/.env llm_auditor/.env adk web \ --allow_origins "regex:https://.*\.cloudshell\.dev" \ --otel_to_cloud \ --reload_agents 참고: 이전 adk web 세션을 종료하지 않은 경우 기본 포트(8000)가 차단될 수 있습니다. 이 경우 adk web --port 8001 등을 사용하여 새 포트로 개발 UI를 실행할 수 있습니다.

5. 터미널 출력에 표시되는 http://127.0.0.1:8000 링크를 클릭합니다. ADK 개발 UI가 표시된 새 브라우저 탭이 열립니다.

6. 왼쪽의 에이전트 선택 메뉴 옵션에서 llm_auditor를 선택합니다.

7. 다음과 같은 거짓 문으로 대화를 시작합니다.

   Double check this: Earth is further away from the Sun than Mars.

채팅 영역에 에이전트의 대답 두 개가 표시됩니다.

• 첫 번째 대답은 critic_agent에서 제공하는 상세한 대답으로 Google 검색을 통한 사실확인을 기반으로 문장의 진실성을 확인합니다.
• 두 번째 대답은 reviser_agent에서 제공하는 수정된 짧은 문장으로 사용자의 거짓 입력 문장을 수정한 버전입니다(예: "Earth is closer to the Sun than Mars.").

8. 각 대답 옆에 있는 에이전트 아이콘()을 클릭하여 해당 대답의 이벤트 패널을 엽니다. 또는 이벤트 패널에서 해당 번호의 이벤트를 찾아 선택합니다.

이벤트 뷰 상단에는 이 멀티 에이전트 시스템 내 에이전트와 도구 간의 관계를 시각화하는 그래프가 표시되며, 이 대답을 생성한 에이전트가 강조 표시됩니다.

9. 코드를 더 자세히 살펴보거나 개발 UI에서 다른 사실 확인 예시를 요청해 보세요. 다음과 같은 예시도 시도해 볼 수 있습니다.

   Q: Why is the sky blue? A: Because the sky reflects the color of the ocean.

10. 대화를 재설정하려면 세션 제목 표시줄에서 새 세션을 클릭하여 대화를 다시 시작합니다.

11. 이 에이전트에 대한 질문을 마치면 브라우저 탭을 닫고 터미널에서 Ctrl+C를 눌러 서버를 중지합니다.

참고: 이 예시에서는 SequentialAgent 워크플로 에이전트를 사용하지만, 이 패턴을 인간 참여형(Human-In-The-Loop) 패턴으로 간주할 수도 있습니다.

SequentialAgent에서 시퀀스를 종료하면 대화는 상위 요소(이 예시에서는 llm_auditor)로 돌아가 사용자의 새로운 입력을 받은 다음 대화를 다른 에이전트에 다시 전달합니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. 멀티 에이전트 예시 미리 보기

수고하셨습니다

에이전트 개발 키트(ADK)의 기본 실습을 성공적으로 완료했습니다. 에이전트와 도구의 핵심 아키텍처를 분석하고, 표준화된 개발 환경을 초기화하고, 요소를 동적 모델 종속 항목으로 구성했습니다. 커스텀 도구와 정형 출력 스키마를 구현하여 브라우저 UI, Python 스크립트, CLI 전반에서 에이전트 동작을 제어하고 워크플로를 실행했습니다. 이러한 기능은 강력하며 프로덕션에 즉시 사용 가능한 에이전트형 애플리케이션을 빌드하고 확장하기 위한 기반을 마련하는 데 사용됩니다.

다음 단계/더 학습하기

ADK에 관한 자세한 내용은 다음 리소스를 참고하세요.

• ADK 문서 에이전트 개발 키트
• adk-docs GitHub 저장소 adk-docs
• AI 에이전트를 보호하는 방법: 기술 심층 분석
• ADK를 사용하여 37줄의 코드로 멀티모달 멀티 에이전트 빌드

Google Cloud 교육 및 자격증

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

설명서 최종 업데이트: 2026년 5월 20일

실습 최종 테스트: 2026년 5월 20일

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