GENAI104

개요: 에이전트 개발 키트의 이점

에이전트형 애플리케이션을 빌드하는 개발자는 에이전트 개발 키트의 여러 주요 이점을 활용할 수 있습니다.

1. 멀티 에이전트 시스템: 계층 구조 내에서 여러 전문 에이전트를 조합하여 확장 가능한 모듈식 애플리케이션을 빌드합니다. 복잡한 조정과 위임도 구현할 수 있습니다.
2. 다양한 도구 생태계: 에이전트에 다양한 기능을 제공합니다. 사전 빌드된 도구(검색, 코드 실행 등)를 사용하거나, 커스텀 함수를 만들거나, 서드 파티 에이전트 프레임워크(LangChain, CrewAI)의 도구를 통합하거나, 심지어 다른 에이전트를 도구로 사용할 수도 있습니다.
3. 유연한 조정: 워크플로 에이전트(SequentialAgent, ParallelAgent, LoopAgent)를 사용하여 예측 가능한 파이프라인을 위한 워크플로를 정의하거나 LLM 기반 동적 라우팅(LlmAgent 전송)을 활용하여 적응형 동작을 구현합니다.
4. 개발자 환경 통합: 강력한 CLI와 대화형 개발 UI를 사용하여 로컬에서 개발, 테스트, 디버그를 수행합니다. 이벤트, 상태, 에이전트 실행을 단계별로 검사합니다.
5. 기본으로 제공되는 평가: 사전 정의된 테스트 사례를 기준으로 최종 대답 품질과 단계별 실행 궤적을 평가하여 에이전트 성능을 체계적으로 판단합니다.
6. 배포 준비 완료: 에이전트를 컨테이너화하고 어디에나 배포합니다. 로컬에서 실행하거나, Vertex AI Agent Engine으로 확장하거나, Cloud Run 또는 Docker를 사용하여 커스텀 인프라에 통합할 수도 있습니다.

다른 생성형 AI SDK나 에이전트 프레임워크를 사용하여 모델을 쿼리하고 도구를 사용하여 모델을 강화할 수도 있지만, 여러 모델을 동적으로 조율하려면 상당한 양의 작업을 수행해야 합니다.

에이전트 개발 키트는 이러한 도구보다 높은 수준의 프레임워크를 제공합니다. 따라서 여러 에이전트를 쉽게 연결하여 복잡하지만 간편하게 유지관리 가능한 워크플로를 구현할 수 있습니다.

또한 복잡한 에이전트 시스템을 Agent Engine의 완전 관리형 엔드포인트에 배포할 수 있으므로, 인프라가 자동으로 할당되고 확장되는 동안 에이전트의 로직에만 집중할 수 있습니다.

목표

이 실습에서는 검색 도구를 사용할 수 있는 단일 에이전트를 만듭니다. 완성한 에이전트는 ADK의 브라우저 UI, CLI 채팅 인터페이스, 스크립트 내부에서 프로그래매틱 방식으로 실행하여 테스트해 봅니다.

다음 사항을 고려합니다.

• 에이전트 개발 키트(ADK)의 주요 기능
• ADK의 핵심 개념
• ADK용 프로젝트 디렉터리를 구성하는 방법
• 모델 이름과 도구를 지정하는 방법을 비롯한 ADK 에이전트의 가장 기본적인 파라미터
• ADK 브라우저 UI의 일부 기능
• 에이전트의 출력 스키마를 제어하는 방법
• 에이전트를 실행하는 세 가지 방법(브라우저 UI, 프로그래매틱 방식, CLI 채팅 인터페이스)

설정 및 요건

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

다음 안내를 확인하세요. 실습에는 시간 제한이 있으며 일시중지할 수 없습니다. 실습 시작을 클릭하면 타이머가 시작됩니다. 이 타이머에는 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 제품 및 서비스에 액세스하려면 탐색 메뉴를 클릭하거나 검색창에 제품 또는 서비스 이름을 입력합니다.

작업 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를 설치합니다. 참고: 설치하는 ADK 버전이 이 실습에서 사용되는 버전과 일치하도록 버전을 지정합니다.

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

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

   gcloud storage cp gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_project.zip ./adk_project.zip unzip adk_project.zip

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

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

에이전트 개발 키트의 핵심 개념

Google ADK는 강력하고 유연한 몇 가지 핵심 개념을 기반으로 빌드됩니다.

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

작업 2. 에이전트 개발 키트 프로젝트 디렉터리의 구조 검토

1. Cloud Shell 편집기의 파일 탐색기 창에서 adk_project 폴더를 찾습니다. 클릭하여 전환해 엽니다.

2. 이 디렉터리에는 my_google_search_agent, app_agent, llm_auditor라는 세 가지 디렉터리가 포함되어 있습니다. 각 디렉터리는 별도의 에이전트를 나타냅니다. 프로젝트 디렉터리 내에서 에이전트를 자체 디렉터리로 분리하면 체계적인 관리가 가능하며, 에이전트 개발 키트에서 어떤 에이전트가 있는지를 파악할 수 있습니다.

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

4. 디렉터리에는 __init__.py 파일과 agent.py 파일이 포함되어 있습니다. __init__.py 파일은 주로 다른 Python 코드에서 가져올 수 있는 Python 패키지인 디렉터리를 식별하는 데 사용됩니다. init.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 파일에 붙여 넣어야 합니다. Agent 객체 생성의 끝부분에 표시된 위치에 붙여 넣으면 됩니다.

   tools=[google_search]

8. 파일을 저장합니다.

도구를 사용하면 에이전트는 텍스트 생성 이상의 작업을 수행할 수 있습니다. 예를 들어 google_search 도구를 사용하면 에이전트는 학습 데이터에서 얻은 정보보다 더 많은 정보가 필요한 시점을 결정할 수 있습니다. 이후에는 검색어를 작성하고, Google 검색을 사용하여 웹을 검색한 후, 결과를 기반으로 사용자에게 대답할 수 있습니다. 검색한 추가 정보를 기반으로 모델이 대답하는 일을 '그라운딩'이라고 하며, 이 전체 프로세스를 '검색 증강 생성', 즉 'RAG'라고 합니다.

도구로 ADK 에이전트 지원 실습에서 ADK와 도구를 함께 사용하는 방법을 자세히 알아볼 수 있습니다.

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

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

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

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

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

1. Cloud Shell 편집기 메뉴에서 보기 > 숨은 파일 전환을 선택하여 숨은 파일을 보거나 숨깁니다(파일 이름이 마침표로 시작하는 파일은 대부분의 파일 시스템에서 기본적으로 숨김 처리됨). '숨은 파일 전환' 옵션을 찾으려면 이 메뉴에서 아래로 스크롤해야 할 수도 있습니다.

2. Cloud Shell 편집기 파일 탐색기 창에서 adk_project/my_google_search_agent 디렉터리로 이동합니다.

3. my_google_search_agent 디렉터리에서 .env 파일을 선택합니다.

4. 파일에서 현재 값 대신 이 값을 붙여넣어 프로젝트 ID를 포함하도록 파일을 업데이트합니다.

   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

5. 파일을 저장합니다.

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

• GOOGLE_GENAI_USE_VERTEXAI=TRUE는 Gemini API 키 인증이 아닌 Vertex AI를 인증에 사용한다는 사실을 나타냅니다.
• GOOGLE_CLOUD_PROJECT와 GOOGLE_CLOUD_LOCATION은 모델 호출을 연결할 프로젝트와 위치를 제공합니다.
• MODEL은 필수 항목은 아니지만 다른 환경 변수로 로드할 수 있도록 여기에 저장됩니다. 다양한 배포 환경에서 다양한 모델을 사용해 볼 수 있는 편리한 방법입니다.

ADK의 개발 UI 또는 명령줄 채팅 인터페이스를 사용하여 에이전트를 테스트하는 경우, 에이전트의 `.env` 파일이 있으면 이를 로드하여 사용하고 없으면 여기에 설정된 것과 이름이 같은 환경 변수를 찾습니다.

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

   cd ~/adk_project

7. 다음 명령어를 사용하여 에이전트 개발 키트 개발 UI를 실행합니다.

   adk web

   출력

   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)

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

9. ADK 개발 UI가 표시된 새 브라우저 탭이 열립니다.

10. 왼쪽의 에이전트 선택 드롭다운에서 my_google_search_agent를 선택합니다.

    

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

    What is some recent global news?

12. 결과를 보면 에이전트가 모델이 학습된 날짜로 정보 습득을 중단하는 대신 Google 검색을 사용하여 최신 정보를 가져온다는 사실을 알 수 있습니다.

    Google 검색으로 그라운딩 기능을 사용한 대답에는 에이전트의 대답 하단에 표시되는 것과 같이 바로 표시할 수 있는 HTML 형식의 '추천 검색어'가 포함됩니다. Google 검색으로 그라운딩 기능을 사용할 때는 이러한 추천 검색어를 표시해야 합니다. 모델이 대답에 사용한 정보를 사용자가 더 알아보는 데 도움이 되기 때문입니다.

13. 왼쪽 사이드바에서 추적 탭이 기본적으로 선택되어 있습니다. 마지막 쿼리 텍스트(What is some recent global news?)를 클릭하여 쿼리의 서로 다른 부분이 실행되는 데 걸린 시간을 추적합니다. 이 기능을 사용하면 도구 호출과 관련된 더 복잡한 실행을 디버그하여 다양한 프로세스가 대답의 지연 시간에 어떤 영향을 미치는지를 파악할 수 있습니다.

    

14. 에이전트의 대답(또는 이벤트 탭의 목록에 있는 이벤트) 옆에 있는 에이전트 아이콘()을 클릭하여 에이전트에서 반환한 이벤트를 검사합니다. 여기에는 사용자에게 반환된 content와 대답의 기반이 된 검색 결과를 자세히 설명하는 groundingMetadata가 포함됩니다.

15. 개발 UI 탐색을 마쳤으면 이 브라우저 탭을 닫고, Cloud Shell 터미널이 있는 브라우저 탭으로 돌아가 터미널 창을 클릭하고 Ctrl+C를 눌러 웹 서버를 중지합니다.

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

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

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

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

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

   export GOOGLE_GENAI_USE_VERTEXAI=TRUE export GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} export GOOGLE_CLOUD_LOCATION={{{project_0.default_region| GCP_LOCATION}}} export MODEL=gemini-2.5-flash

2. Cloud Shell 편집기 파일 브라우저에서 adk_project/app_agent 디렉터리를 선택합니다.

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

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

   구성요소	기능	설명
   InMemoryRunner()	에이전트 실행 감독	러너는 사용자의 쿼리를 수신하고, 이를 적절한 에이전트에 전달하고, 에이전트의 대답 이벤트를 수신하여 호출 애플리케이션이나 UI에 다시 전달한 후, 다음 이벤트를 트리거하는 코드입니다. 자세한 내용은 ADK의 이벤트 루프 관련 문서를 참고하세요.
   runner.session_service.create_session()	대화 기록 및 공유 상태	세션을 사용하면 에이전트는 상태를 유지하여 항목 목록, 작업의 현재 상태 또는 기타 '최신' 정보를 기억할 수 있습니다. 이 클래스는 단순화를 위해 로컬 세션 서비스를 만들지만 프로덕션에서는 데이터베이스에서 이 클래스를 처리할 수 있습니다.
   types.Content() 및 types.Part()	정형 멀티모달 메시지	단순 문자열 대신 여러 부분으로 구성될 수 있는 콘텐츠 객체가 에이전트에 전달됩니다. 따라서 텍스트와 멀티모달 콘텐츠를 포함한 복잡한 메시지를 특정 순서로 에이전트에게 전달할 수 있습니다.

개발 UI에서 에이전트를 실행하면 에이전트에서 세션 서비스, 아티팩트 서비스, 실행기를 자동으로 생성합니다. 프로그래매틱 방식으로 배포하기 위해 자체 에이전트를 작성할 때는 메모리 내 버전을 사용하는 대신 이러한 구성요소를 외부 서비스로 제공하는 것이 좋습니다.

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

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

   python3 app_agent/agent.py

   선택된 출력:

   trivia_agent: The capital of France is Paris.

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

   이제 Pydantic 스키마 클래스인 BaseModel 및 Field의 가져오기를 추가하고 이를 사용하여 단일 필드로 구성된 스키마 클래스를 정의합니다. 이 필드는 'capital' 키 하나와 국가의 수도 이름을 저장하기 위한 문자열 값 하나로 구성됩니다. 이 줄을 app_agent/agent.py 파일의 다른 가져오기 바로 뒤에 붙여 넣어도 됩니다.

   from pydantic import BaseModel, Field class CountryCapital(BaseModel): capital: str = Field(description="A country's capital.") 중요: 출력 스키마를 정의할 때는 도구나 에이전트 전송을 사용할 수 없습니다.

8. root_agent의 Agent 정의 내에서 다음 파라미터를 추가하여 출력 스키마를 사용하는 경우 필수 작업인 전송을 사용 중지하고, 위에서 정의한 CountryCapital 스키마에 따라 생성될 출력을 설정합니다.

   disallow_transfer_to_parent=True, disallow_transfer_to_peers=True, output_schema=CountryCapital,

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

   python3 app_agent/agent.py

   선택된 출력:

   ** User says: {'parts': [{'text': 'What is the capital of France?'}], 'role': 'user'} ** 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 new movies that have been released in the past month in India?

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

   [google_search_agent]: Here are some movies that have been released in India in the past month (August-September 2025): * **Param Sundari** Released on 29 August 2025. * **Ek Chatur Naar** Released on 12 September 2025. * **Jolly LLB 3** Released on 19 September 2025. * **Ajey: The Untold Story of a Yogi** Released on 19 September 2025. * **Antha 7 Naatkal** Released on Sep 25 2025.

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 파일이 표시됩니다. 또한 체계적이고 완전한 프롬프트를 agent.py 파일로 가져오기 전에 저장하고 수정할 수 있는 전용 공간을 제공하는 prompt.py 파일도 표시됩니다.

4. Cloud Shell 터미널에서 다음을 실행하여 이 에이전트의 .env 파일을 만들고 개발 UI를 다시 실행합니다.

   cd ~/adk_project cat << EOF > llm_auditor/.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 adk web 참고: 이전 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.

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

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

9. 각 대답 옆에 있는 에이전트 아이콘()을 클릭하여 해당 대답의 이벤트 패널을 엽니다. 또는 이벤트 패널에서 해당 번호의 이벤트를 찾아 선택합니다. 이벤트 보기 상단에는 이 멀티 에이전트 시스템 내 에이전트와 도구 간의 관계를 시각화하는 그래프가 표시됩니다. 이 대답을 담당한 에이전트가 강조 표시됩니다.

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

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

11. 대화를 재설정하려면 ADK 개발 UI의 오른쪽 상단에 있는 + 새 세션 링크를 사용하여 대화를 다시 시작합니다.

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

인간 참여형(Human-In-The-Loop) 패턴

이 예시에서는 SequentialAgent 워크플로 에이전트를 사용하지만 이 패턴을 인간 참여형(Human-In-The-Loop) 패턴으로 간주할 수도 있습니다. SequentialAgent에서 시퀀스를 종료하면 대화는 상위 요소(이 예시에서는 llm_auditor)로 돌아가 사용자의 새로운 입력 차례를 기다린 다음 대화를 다른 에이전트에게 다시 전달합니다.

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

수고하셨습니다

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

• 에이전트 개발 키트(ADK)의 주요 기능
• ADK의 핵심 개념
• ADK용 프로젝트 디렉터리를 구성하는 방법
• 모델 이름과 도구를 지정하는 방법을 비롯한 ADK 에이전트의 가장 기본적인 파라미터
• ADK 브라우저 UI의 일부 기능
• 에이전트의 출력 스키마를 제어하는 방법
• 에이전트를 실행하는 세 가지 방법(브라우저 UI, 프로그래매틱 방식, CLI 채팅 인터페이스)

다음 단계

에이전트 개발 키트를 사용하여 에이전트를 빌드하고 배포하는 방법을 자세히 알아보려면 다음 실습을 확인하세요.

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

문서 및 GitHub 저장소에서 ADK에 대해 자세히 알아보세요.

• 에이전트 개발 키트 문서 에이전트 개발 키트
• adk-docs GitHub 저장소 adk-docs

Google Cloud 교육 및 자격증

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

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

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

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