GENAI105

개요

이 실습에서는 에이전트 개발 키트 에이전트와 함께 도구를 사용하는 방법을 다룹니다.

Google 검색, Vertex AI Search와 같은 Google에서 제공하는 강력한 도구부터 LangChain 및 CrewAI 생태계에서 사용할 수 있는 다양한 도구에 이르기까지 시작할 수 있는 도구가 많습니다.

또한 함수에서 자체 도구를 만들려면 좋은 docstring을 작성하기만 하면 됩니다.

이 실습에서는 에이전트 개발 키트(ADK) 시작하기 실습에서 다룬 ADK의 기본사항을 잘 알고 있다고 가정합니다.

목표

이 실습에서는 ADK 에이전트가 사용할 수 있는 도구 생태계에 대해 알아봅니다. 또한 에이전트에 함수를 커스텀 도구로 제공하는 방법도 알아봅니다.

이 실습의 목표는 다음과 같습니다.

• 사전 빌드된 Google, LangChain 또는 CrewAI 도구를 에이전트에 제공
• 에이전트 도구용 함수를 작성할 때, 구조화된 docstring과 유형 지정이 중요한 이유 설명
• 에이전트용 자체 도구 함수 작성

설정 및 요건

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

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

에이전트 개발 키트를 활용한 도구 사용

도구를 효과적으로 활용하는 것이야말로 지능형 에이전트와 기본 모델을 진정으로 구별하는 요소입니다. 도구는 함수 또는 메서드와 같은 코드 블록으로, 데이터베이스와 상호작용하거나, API 요청을 하거나, 다른 외부 서비스를 호출하는 등의 특정 작업을 실행합니다.

도구를 사용하면 에이전트가 다른 시스템과 상호작용하고 핵심 추론 및 생성 기능을 넘어선 작업을 수행할 수 있습니다. 이러한 도구는 에이전트의 LLM과 독립적으로 작동하므로 도구가 자체 추론 능력을 자동으로 갖추지는 않습니다.

에이전트 개발 키트는 개발자에게 다양한 도구 옵션을 제공합니다.

• 사전 빌드된 도구: Google 검색, 코드 실행, 검색 증강 생성(RAG) 도구와 같이 바로 사용할 수 있는 기능입니다.
• 서드 파티 도구: LangChain, CrewAI와 같은 외부 라이브러리의 도구와 원활하게 통합됩니다.
• 커스텀 도구: 언어별 구조와 도구로서의 에이전트를 사용하여 특정 요구사항에 맞게 맞춤설정된 커스텀 도구를 만들 수 있습니다. 또한 SDK는 Long Running Function Tools를 통해 비동기 기능도 제공합니다.

이 실습에서는 이러한 카테고리를 살펴보고 각 유형 중 하나를 구현합니다.

Google에서 제공하는 사전 빌드된 도구

Google은 에이전트를 위한 몇 가지 유용한 도구를 제공합니다. 여기에는 다음이 포함됩니다.

Google 검색(google_search): 이 도구를 사용하면 에이전트가 Google 검색을 사용하여 웹 검색을 수행할 수 있습니다. 에이전트의 도구에 google_search를 추가하기만 하면 됩니다.

코드 실행(built_in_code_execution): 이 도구를 사용하면 에이전트가 코드를 실행하여 계산, 데이터 조작을 수행하거나 다른 시스템과 프로그래매틱 방식으로 상호작용할 수 있습니다. 사전 빌드된 VertexCodeInterpreter 또는 BaseCodeExecutor 인터페이스를 구현하는 모든 코드 실행기를 사용할 수 있습니다.

검색(retrieval): 다양한 소스에서 정보를 가져오도록 설계된 도구 패키지입니다.

Vertex AI Search 도구(VertexAiSearchTool): 이 도구는 Google Cloud의 Vertex AI Search 서비스와 통합되어 에이전트가 AI Applications 데이터 스토어를 검색할 수 있도록 합니다.

작업 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 터미널에 붙여넣어 Cloud Storage 버킷에서 이 실습에 사용할 코드를 다운로드합니다.

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

2. Cloud Shell 터미널에서 다음 명령어를 실행하여 PATH 환경 변수를 업데이트하고 ADK를 설치하며 이 실습에 필요한 몇 가지 추가 요구사항을 설치합니다.

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

   참고: google-adk[extensions]는 Crew AI 도구에 필요한 추가 종속 항목을 설치하는 데 사용됩니다.

작업 2. 자체 데이터에 대한 응답을 그라운딩하는 데 사용될 검색 앱 만들기

이후 작업에서는 Google에서 제공하는 Vertex AI Search 도구를 사용하여 AI Applications 데이터 스토어의 자체 데이터에 대답을 그라운딩합니다. 앱의 데이터 스토어는 데이터를 수집하는 데 약간의 시간이 필요하므로 지금 설정한 다음 나중에 작업에서 데이터에 대한 대답을 그라운딩하는 데 사용합니다.

1. Cloud 콘솔이 여전히 표시된 브라우저 탭에서 콘솔 상단에서 AI Applications를 검색하여 이동합니다.

2. 이용약관 체크박스를 선택하고 계속 및 API 활성화를 클릭합니다.

3. 왼쪽 탐색 메뉴에서 데이터 스토어를 선택합니다.

4. 데이터 스토어 만들기를 선택합니다.

5. Cloud Storage 카드를 찾고 선택을 클릭합니다.

6. 비정형 문서(PDF, HTML, TXT 등)를 선택합니다.

7. 예시 문서가 Cloud Storage에 업로드되어 있습니다. 이 문서에는 '페르세포네'라는 이름의 새로운 가상 행성 발견과 관련된 내용이 담겨 있습니다. 여기서는 모델이 학습 중에 이 행성에 대해 아무것도 학습하지 못하도록 가상의 행성이 사용됩니다.

   GCS 경로에 -bucket/planet-search-docs를 입력합니다.

8. 계속을 클릭합니다.

9. 위치를 전역으로 유지합니다.

10. 데이터 스토어 이름에 Planet Search를 입력합니다.

11. 만들기를 클릭합니다.

12. 왼쪽 탐색 메뉴에서 앱을 클릭합니다.

13. 새 앱 만들기를 클릭합니다.

14. 커스텀 검색(일반) 앱의 카드를 찾고 만들기를 클릭합니다.

15. 앱 이름을 Planet Search로 지정합니다.

16. 회사 이름으로 Planet Conferences를 입력합니다.

17. 계속을 클릭합니다.

18. Planet Search 데이터 스토어 옆의 체크박스를 선택합니다.

19. 만들기를 선택합니다.

20. 앱이 생성되면 왼쪽 상단에서 AI Applications 로고를 클릭하여 앱 대시보드로 돌아갑니다.

21. 앱 테이블에 표시된 앱의 ID 값을 복사합니다. 나중에 필요하므로 텍스트 문서에 저장합니다.

22. 지금은 데이터 스토어가 관련 데이터를 수집할 때까지 기다려야 합니다. 나중에 에이전트에 이 데이터를 제공하여 대답을 그라운딩합니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. 데이터 스토어 및 검색 앱 만들기

서드 파티 도구

ADK를 사용하면 LangChain, CrewAI와 같은 서드 파티 AI 라이브러리에서 제공되는 도구를 사용할 수 있습니다.

작업 3. LangChain 도구 사용

LangChain 커뮤니티는 다양한 데이터 소스에 액세스하고, 다양한 웹 제품과 통합하고, 여러 작업을 수행할 수 있도록 많은 수의 도구 통합을 만들었습니다. ADK 내에서 커뮤니티 도구를 사용하면 다른 사람이 이미 만든 도구를 다시 작성하는 수고를 덜 수 있습니다.

1. Cloud Shell 편집기가 표시된 브라우저 탭으로 돌아가서 왼쪽의 파일 탐색기를 사용하여 adk_tools/langchain_tool_agent 디렉터리로 이동합니다.

2. Cloud Shell 터미널에서 다음을 실행하여 이 에이전트 디렉터리에 대한 인증 세부정보를 제공하는 .env 파일을 작성합니다.

   cd ~/adk_tools cat << EOF > langchain_tool_agent/.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

3. 다음을 실행하여 .env 파일을 이 실습에서 사용할 다른 에이전트 디렉터리에 복사합니다.

   cp langchain_tool_agent/.env crewai_tool_agent/.env cp langchain_tool_agent/.env function_tool_agent/.env cp langchain_tool_agent/.env vertexai_search_tool_agent/.env

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

5. LangchainTool 클래스를 가져오는 것을 확인합니다. 이것은 에이전트 개발 키트 내에서 LangChain 도구를 사용할 수 있도록 해주는 래퍼 클래스입니다.

6. agent.py 파일에서 표시된 위치에 다음 코드를 추가하여 LangChain Wikipedia 도구를 에이전트에 추가합니다. 이렇게 하면 에이전트가 Wikipedia에서 정보를 검색할 수 있습니다.

   tools = [ # Use the LangchainTool wrapper... LangchainTool( # to pass in a LangChain tool. # In this case, the WikipediaQueryRun tool, # which requires the WikipediaAPIWrapper as # part of the tool. tool=WikipediaQueryRun( api_wrapper=WikipediaAPIWrapper() ) ) ]

7. 파일을 저장합니다.

8. Cloud Shell 터미널의 adk_tools 프로젝트 디렉터리에서 다음 명령어를 사용하여 에이전트 개발 키트 개발 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)

9. 새 탭에서 웹 인터페이스를 보려면 터미널 출력에서 http://127.0.0.1:8000 링크를 클릭합니다.

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

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

12. 다음을 사용해 에이전트를 쿼리합니다.

    Who was Grace Hopper?

    출력:

    

13. 에이전트의 채팅 풍선 옆에 있는 에이전트 아이콘()을 클릭합니다. 이 아이콘은 wikipedia 도구를 사용 중임을 나타냅니다.

14. 콘텐츠에는 Wikipedia에 대한 쿼리가 포함된 functionCall이 포함되어 있습니다.

15. 탭 상단에서 앞으로 버튼을 클릭하여 다음 이벤트로 이동합니다.

16. 이 이벤트를 탐색하면 모델의 대답을 생성하는 데 사용된 Wikipedia에서 검색된 결과를 확인할 수 있습니다.

17. 이 에이전트에 대한 질문을 마치면 개발 UI 브라우저 탭을 닫습니다.

18. Cloud Shell 터미널 패널을 선택하고 Ctrl+C를 눌러 서버를 중지합니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. LangChain 도구 사용

작업 4. CrewAI 도구 사용

마찬가지로, CrewaiTool 래퍼를 사용하여 CrewAI 도구를 사용할 수 있습니다.

1. 이렇게 하려면 Cloud Shell 편집기 파일 탐색기를 사용하여 adk_tools/crewai_tool_agent 디렉터리로 이동합니다.

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

3. ADK에서 CrewaiTool 클래스를 가져오고 crewai_tools에서 ScrapeWebsiteTool을 가져오는 것을 확인합니다.

4. agent.py 파일에서 표시된 위치에 다음 코드를 추가하여 CrewAI Scrape Website 도구를 이름 및 설명과 함께 에이전트에 추가합니다.

   tools = [ CrewaiTool( name="scrape_apnews", description=( """Scrapes the latest news content from the Associated Press (AP) News website.""" ), tool=ScrapeWebsiteTool("https://apnews.com/") ) ]

   ScrapeWebsiteTool은 Associated Press 뉴스 웹사이트 apnews.com에서 콘텐츠를 로드합니다.

5. 파일을 저장합니다.

6. 명령줄 인터페이스를 사용하여 이 에이전트를 실행하여 에이전트를 빠르게 테스트하는 편리한 방법을 익힙니다. Cloud Shell 터미널의 adk_tools 프로젝트 디렉터리에서 아래와 같이 ADK 명령줄 UI를 사용하여 에이전트를 실행합니다.

   adk run crewai_tool_agent

7. 에이전트가 로드되는 동안 일부 경고가 표시될 수 있습니다. 이러한 경고는 무시해도 됩니다. user: 프롬프트가 표시되면 다음을 입력합니다.

   Get 10 of the latest headlines from AP News.

   출력:

   Using Tool: Read website content [crewai_tool_agent]: Here are the latest headlines from AP News: ...

8. 명령줄 인터페이스는 도구가 사용 중일 때도 알려줍니다.

9. 터미널에서 다음 user: 프롬프트에 exit를 입력하여 명령줄 인터페이스를 종료합니다.

10. 터미널 기록을 뒤로 스크롤하여 adk run crewai_tool_agent를 실행한 위치를 찾고 명령줄 인터페이스에서 추적(tail)할 로그 파일을 제공했는지 확인합니다. 해당 명령어를 복사하여 실행하고 실행에 대한 자세한 내용을 확인합니다.

    tail -F /tmp/agents_log/agent.latest.log

11. Ctrl+C를 눌러 로그 파일 추적을 중지하고 명령 프롬프트로 돌아갑니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. CrewAI 도구 사용

작업 5. 함수를 커스텀 도구로 사용

사전 빌드된 도구가 특정 요구사항을 완전히 충족하지 못하는 경우 자체 도구를 만들 수 있습니다. 이를 통해 독점 데이터베이스에 연결하거나 고유한 알고리즘을 구현하는 등 맞춤형 기능을 사용할 수 있습니다.

새 도구를 만드는 가장 간단한 방법은 표준 형식으로 작성된 docstring이 있는 표준 Python 함수를 작성하고 이를 도구로 모델에 전달하는 것입니다. 이 접근방식은 유연성과 빠른 통합을 제공합니다.

도구로 사용할 함수를 작성할 때는 몇 가지 중요한 사항을 염두에 두어야 합니다.

• 파라미터: 함수는 파라미터를 원하는 만큼 사용할 수 있으며, 각 파라미터는 JSON 직렬화 가능한 모든 유형(예: 문자열, 정수, 목록, 사전)일 수 있습니다. 대규모 언어 모델(LLM)은 현재 파라미터의 기본값 해석을 지원하지 않으므로 기본값을 설정하지 않는 것이 중요합니다.
• 반환 유형: Python 함수 도구의 기본 반환 유형은 사전입니다. 이를 통해 키-값 쌍으로 대답을 구조화하여 LLM에 컨텍스트와 명확성을 제공할 수 있습니다. 예를 들어 숫자 오류 코드를 반환하는 대신 사람이 읽을 수 있는 설명이 포함된 'error_message' 키가 있는 사전을 반환합니다. 반환 사전에 전체 결과를 나타내는 'status' 키를 포함하는 것이 좋습니다(예: 'success', 'error', 'pending'). 그러면 LLM이 작업 상태를 명확히 인식할 수 있습니다.
• Docstring: 함수의 docstring은 도구의 설명 역할을 하며 LLM으로 전송됩니다. 따라서 LLM이 도구를 효과적으로 사용하는 방법을 이해하려면 잘 작성되고 충분한 정보를 담은 docstring이 필수적입니다. 함수의 목적, 파라미터의 의미, 예상되는 반환 값을 명확하게 설명합니다.

다음 단계를 완료하여 함수를 정의하고 도구로 사용합니다.

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

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

3. get_date() 및 write_journal_entry() 함수에는 ADK 에이전트가 언제 어떻게 사용해야 하는지 알 수 있도록 적절하게 서식이 지정된 docstring이 있습니다. 여기에는 다음이 포함됩니다.

   • 각 기능의 역할에 대한 명확한 설명
   • JSON 직렬화 가능 유형으로 함수의 입력 파라미터를 설명하는 Args: 섹션
   • 함수가 반환하는 내용을 설명하는 Returns: 섹션(선호하는 응답 유형은 dict)

4. 함수를 에이전트에 전달하여 도구로 사용하려면 agent.py 파일에서 표시된 위치에 다음 코드를 추가합니다.

   tools=[get_date, write_journal_entry]

5. 파일을 저장합니다.

6. 개발 UI를 사용하여 이 에이전트를 실행하고 도구를 통해 도구 요청과 응답을 쉽게 시각화할 수 있는 방법을 확인합니다. Cloud Shell 터미널의 adk_tools 프로젝트 디렉터리에서 다음 명령어를 사용하여 개발 UI를 다시 실행합니다(서버가 여전히 실행 중인 경우 먼저 Ctrl+C를 사용하여 실행 중인 서버를 중지한 후 다음 명령어를 실행하여 다시 시작합니다).

   adk web

7. 터미널 출력에서 http://127.0.0.1:8000 링크를 클릭합니다.

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

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

10. 다음 명령어를 실행하여 에이전트와 대화를 시작합니다.

    hello

11. 에이전트가 오늘 하루가 어땠는지 물어봅니다. 오늘 하루가 어땠는지 한 문장으로 답하면(예: It's been a good day. I did a cool ADK lab.) 에이전트가 일기를 작성해 줍니다.

    출력 예시:

    

12. 에이전트가 커스텀 도구의 요청과 대답에 대한 버튼을 표시하는 것을 확인합니다. 각 이벤트를 클릭하면 자세한 정보를 확인할 수 있습니다.

13. 개발 UI 탭을 닫습니다.

14. Cloud Shell 편집기의 adk_tools 디렉터리에서 날짜가 지정된 일기 파일을 찾을 수 있습니다. (가로로 많이 스크롤하지 않고도 전체 텍스트를 보려면 Cloud Shell 편집기의 메뉴에서 보기 > 단어 줄바꿈을 사용 설정하는 것이 좋습니다.)

15. Cloud Shell 터미널 패널을 클릭하고 Ctrl+C를 눌러 서버를 중지합니다.

도구로 사용될 함수를 작성할 때 권장사항은 다음과 같습니다.

• 파라미터 수는 적을수록 좋음: 복잡성을 줄이려면 파라미터 수를 최소화하세요.
• 단순 데이터 유형 사용: 가능하면 커스텀 클래스보다 str, int와 같은 기본 데이터 유형을 사용하세요.
• 의미 있는 이름 사용: 함수의 이름과 파라미터 이름은 LLM이 도구를 해석하고 활용하는 방식에 큰 영향을 미칩니다. 함수의 목적과 입력의 의미를 명확하게 반영하는 이름을 선택하세요.
• 복잡한 함수 세분화: 단일 update_profile(profile: Profile) 함수 대신 update_name(name: str), update_age(age: int) 등 별도의 함수를 만드세요.
• 반환 상태: 반환 사전에 전체 결과를 나타내는 'status' 키를 포함하세요(예: 'success', 'error', 'pending'). 그러면 LLM이 작업 상태를 명확히 인식할 수 있습니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. 함수를 커스텀 도구로 사용

작업 6. Vertex AI Search를 자체 데이터에 그라운딩하는 도구로 사용

이 작업에서는 Google의 기본 제공 Vertex AI Search 도구와 이전에 만든 AI Applications 데이터 스토어를 사용하여 에이전트 개발 키트 에이전트로 RAG 애플리케이션을 얼마나 쉽게 배포할 수 있는지 알아봅니다.

1. Cloud Shell 편집기 탭으로 돌아가서 adk_tools/vertexai_search_tool_agent 디렉터리를 선택합니다.

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

3. 가져오기 하단에 표시된 위치에 VertexAiSearchTool 클래스의 가져오기를 추가합니다.

   from google.adk.tools import VertexAiSearchTool

4. VertexAiSearchTool이 인스턴스화되는 코드를 업데이트합니다. data_store_id에 전달되는 경로에서 YOUR_PROJECT_ID를 (으)로 업데이트하고 YOUR_SEARCH_APP_ID를 이전 작업에서 복사한 검색 앱 ID로 업데이트합니다.

5. 에이전트 정의에서 표시된 위치에 다음 줄을 추가하여 에이전트에 도구를 제공합니다.

tools=[vertexai_search_tool]

5. agents.py 파일을 저장합니다.

콘솔의 AI Applications > 데이터 스토어 페이지에서 데이터 스토어의 이름을 선택하여 데이터 스토어가 사용할 준비가 되었는지 확인할 수 있습니다.

활동 및 문서 탭에는 문서의 가져오기 및 색인 생성 상태가 표시됩니다. 활동 탭에 '가져오기 완료'가 표시되면 데이터 스토어가 쿼리할 준비가 된 것입니다.

6. Cloud Shell 터미널의 adk_tools 프로젝트 디렉터리에서 다음 명령어를 사용하여 명령줄 인터페이스를 실행합니다. 변경사항을 적용할 때마다 개발 UI가 에이전트를 다시 로드하도록 --reload_agents 플래그를 포함합니다.

   adk web --reload_agents 참고: 이전 adk web 세션을 종료하지 않은 경우 실행 중인 Cloud Shell 터미널 패널을 선택하고 Ctrl+C를 누릅니다. 이전에 사용한 Cloud Shell 터미널 탭을 찾을 수 없는 경우 기본 포트(8000)가 차단될 수 있습니다. 이 경우 adk web --port 8001을 사용하여 새 포트로 개발 UI를 실행할 수 있습니다.

7. http://127.0.0.1:8000을 클릭하여 ADK 개발 UI를 엽니다.

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

9. Cloud Storage 문서에 설명된 가상의 행성에 관해 에이전트에 다음을 사용하여 쿼리합니다.

   Is the new planet Persephone suitable for habitation?

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

   Based on the "Persephone Survey: What we Know So Far" document, Persephone exhibits several characteristics that suggest it could be habitable: - Location: It orbits within the habitable zone of its star. - Temperature: The average surface temperature is estimated to be around 18°C (64°F). ...

AgentTool을 사용하여 검색 도구를 다른 도구와 통합

검색 도구에는 동일한 에이전트에서 검색 도구와 비검색 도구를 혼합할 수 없다는 구현 제한이 있습니다. 이 문제를 해결하려면 AgentTool을 사용하여 에이전트를 검색 도구로 래핑한 다음, 해당 에이전트를 도구로 사용하여 다른 도구와 함께 검색을 수행할 수 있습니다.

실제로 어떻게 작동하는지 확인하려면 다음을 수행합니다.

1. adk_tools/vertexai_search_tool_agent/agent.py 파일이 열려 있는지 확인합니다.

2. get_date 함수 도구를 포함하도록 root_agent의 tools 파라미터를 업데이트합니다.

   tools=[vertexai_search_tool, get_date]

3. 파일을 저장합니다.

4. ADK 개발 UI에서 에이전트에게 다음을 묻습니다.

   What is today's date?

   예상 출력:

   

5. adk_tools/vertexai_search_tool_agent/agent.py 파일로 돌아가서 root_agent 위에 다음 코드를 붙여넣습니다. 이 에이전트는 검색 도구 사용에 특화되어 있으며, 검색 도구와 이를 사용하는 방법에 대한 안내를 모두 포함합니다.

   vertexai_search_agent = Agent( name="vertexai_search_agent", model=os.getenv("MODEL"), instruction="Use your search tool to look up facts.", tools=[vertexai_search_tool] )

6. 그런 다음 root_agent의 tools 파라미터를 다음 코드로 바꿔 이전 단계에서 만든 에이전트를 AgentTool로 래핑합니다.

   tools=[ AgentTool(vertexai_search_agent, skip_summarization=False), get_date ]

7. 이제 에이전트를 쿼리하여 검색 결과를 받고 get_date() 함수를 사용할 수 있습니다.

   ADK 개발 UI 브라우저 탭으로 돌아가서 + 새로운 세션을 클릭합니다.

8. 다시 질문합니다.

   What is today's date?

   에이전트가 올바른 날짜를 대답할 것입니다.

9. 다음과 같이 질문하여 검색 도구를 호출합니다.

   When is the PlanetCon conference?

   예상 출력:

   The PlanetCon: Persephone conference is scheduled for October 26th - 28th, 2028.

10. 이 새로운 행성과 행성의 발견 사실이 발표될 학회에 관해 에이전트에 더 많은 질문을 해 봅니다. 만족스러우면 개발 UI 탭을 닫습니다.

11. 이 에이전트에 대한 질문을 마치면 브라우저 탭을 닫고 서버가 실행 중인 Cloud Shell 터미널 창을 선택한 다음 Ctrl+C를 눌러 서버를 중지합니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. Google에서 제공하는 도구 사용

더 다양한 유형의 도구

다음 도구 유형은 알아두면 좋지만 이 실습에서는 구현하지 않습니다.

LongRunningFunctionTool 클래스

이 도구는 FunctionTool의 서브클래스입니다. 에이전트의 실행을 차단하지 않고 호출해야 하며 상당한 처리 시간이 필요한 작업에 맞게 설계되었습니다.

LongRunningFunctionTool을 사용할 때 Python 함수는 장기 실행 작업을 시작하고 선택적으로 중간 결과를 반환하여 모델과 사용자에게 진행 상황(예: 상태 업데이트 또는 예상 완료 시간)을 알릴 수 있습니다. 그러면 에이전트는 다른 작업을 계속 진행할 수 있습니다.

예를 들어 에이전트가 작업을 진행하기 전에 사람의 승인을 받아야 하는 인간 참여형(Human-In-The-Loop) 시나리오가 있습니다.

Application Integration 워크플로를 도구로 사용

Application Integration을 사용하면 Google Cloud 콘솔의 드래그 앤 드롭 인터페이스를 통해 Google Cloud 제품과 Salesforce, ServiceNow, JIRA, SAP 등의 서드 파티 시스템을 위한 Integration Connector의 100개 이상의 사전 빌드된 커넥터를 활용해 도구, 데이터 연결, 데이터 변환을 빌드할 수 있습니다. 그런 다음 ADK ApplicationIntegrationToolset를 사용하여 에이전트가 이러한 소스에 연결하거나 워크플로를 호출하도록 허용할 수 있습니다.

모델 컨텍스트 프로토콜(MCP) 도구

모델 컨텍스트 프로토콜(MCP)은 Gemini 및 Claude와 같은 대규모 언어 모델(LLM)이 외부 애플리케이션, 데이터 소스, 도구와 통신하는 방식을 표준화하기 위해 설계된 개방형 표준입니다. ADK는 MCP 서비스를 호출하는 도구를 빌드하든, 다른 개발자나 에이전트가 도구와 상호작용할 수 있도록 MCP 서버를 노출하든, 에이전트에서 MCP 도구를 사용하고 소비하는 데 도움이 됩니다.

MCP 도구 문서에서 다음을 비롯해 ADK를 MCP 서버와 함께 사용하는 데 도움이 되는 코드 샘플과 설계 패턴을 참조하세요.

• ADK 내 기존 MCP 서버 사용: ADK 에이전트는 MCP 클라이언트 역할을 하며 외부 MCP 서버에서 제공하는 도구를 사용할 수 있습니다.
• MCP 서버를 통한 ADK 도구 노출: ADK 도구를 래핑하여 모든 MCP 클라이언트가 액세스할 수 있도록 하는 MCP 서버를 빌드하는 방법

ADK 에이전트와 함께 MCP를 사용하는 방법에 대한 자세한 내용은 모델 컨텍스트 프로토콜(MCP) 도구를 ADK 에이전트와 함께 사용 실습을 참조하세요.

수고하셨습니다

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

• 사전 빌드된 Google, LangChain 또는 CrewAI 도구를 에이전트에 제공
• 에이전트용 자체 도구 함수 작성
• 에이전트 도구용 함수를 작성할 때 구조화된 docstring과 유형 지정이 중요한 이유 설명

다음 단계

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

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

Google Cloud 교육 및 자격증

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

설명서 최종 업데이트: 2025년 9월 22일

실습 최종 테스트: 2025년 9월 22일

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