이 페이지는 Cloud Translation API를 통해 번역되었습니다.

ADK로 AI 에이전트 빌드: 도구로 역량 강화

1. 시작하기 전에

'ADK로 AI 에이전트 빌드하기' 시리즈의 두 번째 파트에 오신 것을 환영합니다. 이 실습 Codelab 시리즈에서는 Google의 에이전트 개발 키트 (ADK)를 사용하여 나만의 지능형 AI 에이전트를 만드는 흥미로운 여정을 시작합니다.

이 Codelab은 ADK 기본 Codelab에서 이어집니다. 이 시점에서 필요한 설정을 완료하고 ADK를 사용하여 개인 비서 에이전트를 성공적으로 빌드했다고 가정하므로 여기서는 이러한 설정 단계를 반복하지 않습니다.

이 Codelab을 마치면 개인 비서 에이전트에 다양한 목적의 도구를 제공하여 정교한 멀티 에이전트 시스템 (MAS)으로 변환하는 이 시리즈의 후속 부분에서 확장할 수 있도록 한 단계 더 나아가게 됩니다.

기본 요건

생성형 AI 개념에 대한 이해
Python 프로그래밍에 대한 기본적인 숙련도
ADK 기본사항 Codelab을 완료했습니다.

학습할 내용

맞춤 Python 함수를 도구로 빌드하여 에이전트에게 새로운 기술을 부여하세요.
Google 검색과 같은 기본 제공 도구를 사용하여 에이전트를 실시간 정보에 연결합니다.
복잡한 작업을 위한 전문 하위 에이전트를 만들어 멀티 도구 에이전트를 구성합니다.
LangChain과 같은 인기 AI 프레임워크의 도구를 통합하여 기능을 빠르게 확장하세요.

필요한 항목

작동하는 컴퓨터와 안정적인 Wi-Fi
Google Cloud 콘솔에 액세스하기 위한 브라우저(예: Chrome)
결제가 사용 설정된 Google Cloud 프로젝트
호기심과 학습에 대한 열의

2. 소개

ADK 기본 Codelab에서는 강력한 LLM 브레인이 있는 개인 어시스턴트 에이전트를 빌드했습니다. 하지만 학습 날짜 이후에 생성된 정보에 액세스할 수 없고 외부 서비스와 상호작용할 수 없다는 제한사항이 있습니다. 전화나 인터넷이 없는 도서관에 갇힌 똑똑하고 책에 박식한 비서와 같습니다.

에이전트가 진정으로 유용하려면 도구를 제공해야 합니다.

도구는 유능한 어시스턴트가 외부 세계에 액세스할 수 있도록 지원하는 기능(예: 계산기, 웹브라우저, 특정 회사 데이터베이스에 대한 액세스)이라고 생각하면 됩니다. ADK에서 도구는 에이전트가 실시간 데이터를 조회하거나 외부 API를 호출하는 등의 특정 작업을 실행할 수 있도록 하는 모듈식 코드입니다. 도구를 사용하면 단순한 대화를 넘어 훨씬 다양한 기능을 활용할 수 있습니다.

ADK는 세 가지 카테고리의 도구를 제공합니다.

함수 도구: 사전 정의된 함수 및 에이전트와 같이 애플리케이션의 고유한 요구사항을 충족하기 위해 개발하는 맞춤 도구입니다.
기본 제공 도구: Google 검색, 코드 실행과 같은 일반적인 작업을 위해 프레임워크에서 제공하는 바로 사용할 수 있는 도구입니다.
서드 파티 도구: Serper와 같은 인기 있는 외부 라이브러리와 LangChain 및 CrewAI의 도구

ADK 에이전트와 함께 도구를 사용하는 방법에 대해 자세히 알아보려면 공식 문서를 참고하세요. 이 Codelab에서는 간단한 에이전트를 유능한 개인 여행 어시스턴트로 변환하는 도구를 추가합니다. 지금부터 시작하겠습니다

3. 함수 도구 추가

이전 세션에서 계속 진행하면 웹 인터페이스를 통해 개인 비서 에이전트가 실행됩니다.

다음 달 일본 여행을 준비하면서 현재 환율을 확인해야 한다고 가정해 보겠습니다. 에이전트에게 질문합니다.

What is the exchange rate from Singapore dollars to Japanese yen?

상담사가 실시간 환율을 가져올 수 없다는 메시지가 표시됩니다. 이는 현재 에이전트가 인터넷 액세스 및 외부 시스템 연결이 부족하기 때문입니다. 이 문제를 해결하기 위해 REST API를 통해 환율을 가져오는 Python 함수를 구현하고 에이전트의 함수 도구로 통합합니다.

먼저 키보드 단축키 Ctrl + C (Windows/Linux) 또는 Cmd + C (macOS)를 사용하여 실행 중인 에이전트 프로세스를 종료합니다.

그런 다음 custom_functions.py이라는 Python 파일을 만듭니다. 이 파일에는 외부 API에서 환율 데이터를 가져오는 Python 함수가 포함됩니다.

`custom_functions.py` 생성:

import requests

# define a function to get exchange rate
def get_fx_rate(base: str, target: str):
        """
        Fetches the current exchange rate between two currencies.

        Args:
                base: The base currency (e.g., "SGD").
                target: The target currency (e.g., "JPY").

        Returns:
                The exchange rate information as a json response,
                or None if the rate could not be fetched.
        """
        base_url = "https://hexarate.paikama.co/api/rates/latest"
        api_url = f"{base_url}/{base}?target={target}"

        response = requests.get(api_url)
        if response.status_code == 200:
                return response.json()

이제 agent.py 파일을 수정합니다. get_fx_rate 함수를 가져와 FunctionTool로 할당합니다.

`agent.py` 업데이트:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool

from .custom_functions import get_fx_rate

root_agent = Agent(
    model='gemini-2.0-flash-001',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
    tools=[FunctionTool(get_fx_rate)]
)

변경 후 다음을 입력하여 에이전트를 다시 시작합니다.

uv run adk web

상담사가 응답하면 동일한 질문을 다시 합니다.

What is the exchange rate from Singapore dollars to Japanese yen?

이번에는 get_fx_rate 도구에서 제공한 실제 환율이 표시됩니다.

환전과 관련된 질문이 있으면 언제든지 물어보세요.

4. 기본 제공 도구 추가

이제 에이전트가 환율을 제공할 수 있으므로 다음 작업은 다음 달의 일기 예보를 가져오는 것입니다. 에이전트에게 다음 질문을 합니다.

What is the weather forecast in Tokyo, Japan for next month?

예상하셨겠지만 일기 예보에는 Google 에이전트가 보유하지 않은 실시간 정보가 필요합니다. 필요한 각 실시간 데이터에 대해 새로운 Python 함수를 코딩할 수 있지만, 맞춤 도구를 계속 추가하면 에이전트가 너무 복잡해지고 관리하기 어려워집니다.

다행히 Agent Development Kit (ADK)는 Google 검색을 비롯한 다양한 내장 도구를 제공하여 에이전트가 외부와 상호작용하는 방식을 간소화합니다. 에이전트에 Google 검색 도구를 추가해 보겠습니다. 이렇게 하려면 agent.py 파일을 다음과 같이 수정해야 합니다.

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools import google_search

from .custom_functions import get_fx_rate

root_agent = Agent(
    model='gemini-2.0-flash-001',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
    tools=[
        FunctionTool(get_fx_rate), 
        google_search,
    ]
)

파일을 수정한 후 adk web 인스턴스를 다시 시작합니다. 잊어버릴 수도 있으니

터미널을 클릭하고 Ctrl + C 또는 Cmd + C를 눌러 인스턴스를 중지합니다.
uv run adk web을 클릭하여 인스턴스를 시작합니다.

오류가 발생합니다.

이 오류는 의도적으로 발생하며 ADK의 핵심 아키텍처 원칙을 알려줍니다. 모호성을 방지하고 에이전트 설계를 깔끔하게 유지하기 위해 에이전트는 하나의 기본 검색 기반 도구만 사용하도록 설계되었습니다. google_search를 동일한 에이전트의 다른 복잡한 도구와 함께 나열할 수는 없습니다.

올바른 접근 방식은 다중 에이전트 패턴을 수용하는 것입니다. Google 검색을 수행하는 것만이 유일한 작업인 새로운 전문 에이전트를 만듭니다. 그런 다음 이 검색 에이전트를 기본 personal_assistant에 도구로 제공합니다.

이제 custom_agents.py라는 Python 파일을 만듭니다. 이 파일에는 전문화된 google_search_agent의 코드가 포함됩니다. 다음 코드를 custom_agents.py 파일에 복사합니다.

`custom_agents.py` 생성 중

from google.adk.agents import Agent
from google.adk.tools import google_search


# Create an agent with google search tool as a search specialist
google_search_agent = Agent(
    model='gemini-2.0-flash-001',
    name='google_search_agent',
    description='A search agent that uses google search to get latest information about current events, weather, or business hours.',
    instruction='Use google search to answer user questions about real-time, logistical information.',
    tools=[google_search],
)

파일이 생성되면 아래와 같이 agent.py 파일을 업데이트합니다.

`agent.py` 업데이트 중

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools import agent_tool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent


root_agent = Agent(
    model='gemini-2.0-flash-001',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        agent_tool.AgentTool(agent=google_search_agent),
    ]
)

코드의 강력한 새 패턴을 분석해 보겠습니다.

새로운 전문가 상담사: 완전히 새로운 상담사 google_search_agent를 정의했습니다. 구체적인 설명과 유일한 도구가 google_search임을 참고하세요. 검색 전문가입니다.
agent_tool.AgentTool: ADK의 특수 래퍼입니다. 전체 에이전트 (google_search_agent)를 가져와 표준 도구처럼 보이도록 패키징합니다.
더 스마트한 **root_agent**: 이제 root_agent에 새로운 도구인 agent_tool.AgentTool(agent=google_search_agent)가 추가되었습니다. 웹 검색 방법을 모르지만 검색 작업을 위임할 수 있는 도구가 있다는 것을 알고 있습니다.

root_agent에서 instruction 필드가 사라진 것을 확인할 수 있습니다. 이제 명령어는 사용 가능한 도구에 의해 암시적으로 정의됩니다. 이제 사용자의 요청을 이해하고 이를 올바른 도구(get_fx_rate 함수 또는 google_search_agent)에 전달하는 것이 주요 작업인 오케스트레이터 또는 라우터가 되었습니다. 이 분산형 설계는 유지관리 가능한 복잡한 에이전트 시스템을 빌드하는 데 중요합니다.

이제 adk web 인스턴스를 다시 시작하고 에이전트에게 이 질문을 다시 합니다.

What is the weather forecast in Tokyo, Japan for next month?

상담사가 이제 google_search_agent를 사용하여 최신 정보를 가져옵니다.

현재 환전 관련 질문을 해 볼 수도 있습니다. 이제 상담사는 각 질문에 적합한 도구를 사용할 수 있습니다.

실시간 정보가 필요한 다른 질문을 에이전트에게 하고 에이전트가 사용할 수 있는 도구를 사용하여 질문을 처리하는 방식을 관찰하세요.

5. 서드 파티 도구 추가

우리 상담사가 훌륭한 여행 어시스턴트가 될 수 있도록 노력하고 있습니다. get_fx_rate 도구로 환전을 처리하고 google_search_agent 도구로 물류를 관리할 수 있습니다. 하지만 멋진 여행은 단순히 물류에 관한 것이 아니라 목적지의 문화와 역사를 이해하는 데 있습니다.

google_search_agent 도구는 검색 결과를 기반으로 문화 및 역사 정보를 제공할 수 있지만, 위키백과와 같은 더 신뢰할 수 있는 출처에서 이러한 정보를 얻는 것이 좋습니다. 마찬가지로 Wikipedia에서 정보를 스크랩하는 자체 Python 함수를 만들 수도 있지만 더 나은 방법이 있어야 합니다.

다행히도 ADK는 확장성이 높게 설계되어 CrewAI, LangChain과 같은 다른 AI 에이전트 프레임워크의 도구를 원활하게 통합할 수 있습니다. 이 상호 운용성은 개발 시간을 단축하고 기존 도구를 재사용할 수 있으므로 매우 중요합니다. 이 사용 사례에서는 LangChain의 Wikipedia 도구를 활용합니다.

먼저 실행 중인 에이전트 프로세스 (Ctrl + C 또는 Cmd + C)를 중지하고 현재 Python 가상 환경에 추가 라이브러리를 설치합니다.

uv add langchain-community
uv add wikipedia

설치가 완료되면 third_party_tools.py라는 파일을 만듭니다. 이 파일에는 LangChain Wikipedia 도구의 구현이 포함됩니다.

`third_party_tools.py` 생성 중

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

# Configure the Wikipedia LangChain tool to act as our cultural guide
langchain_wikipedia_tool = WikipediaQueryRun(
    api_wrapper=WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=3000)
)

# Give the tool a more specific description for our agent
langchain_wikipedia_tool.description = (
    "Provides deep historical and cultural information on landmarks, concepts, and places."
    "Use this for 'tell me about' or 'what is the history of' type questions."
)

이제 agent.py 파일을 업데이트합니다.

`agent.py` 업데이트 중

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools import agent_tool
from google.adk.tools import langchain_tool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent
from .third_party_tools import langchain_wikipedia_tool


root_agent = Agent(
    model='gemini-2.0-flash-001',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        agent_tool.AgentTool(agent=google_search_agent),
        langchain_tool.LangchainTool(langchain_wikipedia_tool),
    ]
)

이제 adk web 인스턴스를 다시 시작하고 에이전트에게 이 질문을 다시 합니다.

Tell me about the history of Kyoto

상담사는 이를 과거에 관한 질문으로 올바르게 식별하고 새로운 Wikipedia 도구를 사용합니다. 서드 파티 도구를 통합하고 특정 역할을 부여하면 여행 계획 목적으로 에이전트를 훨씬 더 지능적이고 유용하게 만들 수 있습니다.

에이전트가 이 선택을 한 정확한 방법을 확인하려면 adk web UI의 이벤트 검사기를 사용하면 됩니다. 이벤트 탭을 클릭한 다음 가장 최근의 functionCall 이벤트를 클릭합니다.

인스펙터에는 사용 가능한 모든 도구 목록이 표시되고 에이전트가 실행한 도구의 tool_code가 강조 표시됩니다.

6. 삭제

이 Codelab에는 장기 실행 제품이 포함되지 않으므로 터미널에서 Ctrl + C를 눌러 활성 에이전트 세션 (예: 터미널의 adk web 인스턴스)을 중지하면 됩니다.

상담사 프로젝트 폴더 및 파일 삭제

Cloud Shell 환경에서만 코드를 삭제하려면 다음 명령어를 사용하세요.

cd ~
rm -rf ai-agents-adk

Vertex AI API 사용 중지

이전에 사용 설정한 Vertex AI API를 사용 중지하려면 다음 명령어를 실행하세요.

gcloud services disable aiplatform.googleapis.com

전체 Google Cloud 프로젝트 종료

Google Cloud 프로젝트를 완전히 종료하려면 공식 가이드에서 자세한 안내를 참고하세요.

7. 결론

축하합니다. 맞춤 함수와 실시간 Google 검색 액세스를 통해 개인 어시스턴트 에이전트를 강화했습니다.

무엇보다도, 유능한 에이전트를 빌드하기 위한 기본적인 아키텍처 패턴인 전문 에이전트를 도구로 사용하는 방법을 배웠습니다. 전용 google_search_agent를 만들어 root_agent에 제공함으로써 단일 에이전트를 빌드하는 것에서 간단하면서도 강력한 멀티 에이전트 시스템을 오케스트레이션하는 것으로 첫 단계를 밟았습니다.

이제 여러 에이전트와 워크플로를 오케스트레이션하는 방법을 자세히 알아볼 다음 Codelab을 완벽하게 준비했습니다. 다음 Codelab에서 뵙겠습니다!

ADK로 AI 에이전트 빌드: 도구로 역량 강화

1. 시작하기 전에

기본 요건

학습할 내용

필요한 항목

2. 소개

3. 함수 도구 추가

custom_functions.py 생성:

agent.py 업데이트:

4. 기본 제공 도구 추가

custom_agents.py 생성 중

agent.py 업데이트 중

5. 서드 파티 도구 추가

third_party_tools.py 생성 중

agent.py 업데이트 중

6. 삭제

상담사 프로젝트 폴더 및 파일 삭제

Vertex AI API 사용 중지

전체 Google Cloud 프로젝트 종료

7. 결론

`custom_functions.py` 생성:

`agent.py` 업데이트:

`custom_agents.py` 생성 중

`agent.py` 업데이트 중

`third_party_tools.py` 생성 중

`agent.py` 업데이트 중