구글 ADK 입문 : 파이썬으로 시작하는 AI 에이전트 개발 가이드 : zum 뉴스

생성형 AI의 가장 일반적인 사용례는 에이전트 개발이다. 에이전트는 사용자가 자연어로 대화하면서 특정 작업을 완료할 수 있게 해주는 시스템이다. 기존 상용 모델을 활용한다 해도 AI 에이전트 만들기는 고된 작업이다.

구글은 최근 파이썬과 자바를 위한 라이브러리인 ‘에이전트 개발 키트(Agent Development Kit, ADK)’를 출시했다. 이 라이브러리는 AI 에이전트를 만드는 과정에 필요한 번거로운 작업의 상당수를 알아서 처리한다. 구글 에이전트 개발 키트는 간단한 작업 또는 여러 단계로 이뤄진 복잡한 워크플로우를 위한 에이전트 개발을 지원한다. 제미나이와 같은 구글의 자체 AI 모델과는 당연히 잘 호환되고, API를 통해 제공되는 대부분의 AI 모델용으로도 어렵지 않게 개조할 수 있다.

구글 에이전트 개발 키트 설정하기

ADK는 파이썬과 자바, 두 언어를 지원한다. 여기서는 파이썬 버전을 살펴본다.

시작하려면 새 가상 환경을 만들고 pip install google-adk를 사용해 ADK를 설치한다. 참고로 이렇게 하면 많은 수의 종속 항목(이 글을 작성하는 현재 기준으로 84개)이 설치된다. 환경과 종속 항목에만 285MB의 공간이 필요하다.

또한 연결할 AI 서비스에 맞는 API 키를 저장하기 위한 .env 파일을 프로젝트 루트에 생성해야 한다. ADK는 .env 파일을 자동으로 감지해서 사용하므로 이와 관련해서 따로 코드를 작성할 필요는 없다.

기본적인 AI 에이전트 개발

기본적인 에이전트를 만들어 보자. 이 에이전트가 하는 일은 인터넷을 검색해 질문에 대한 답변을 찾는 것이 전부다.

프로젝트 디렉토리에 searchagent라는 하위 디렉토리를 만든다. 이 디렉토리에 __init__.py와 agent.py, 두 파일을 넣을 것이다.

__init__.py의 코드는 다음과 같다

from . import agent

agent.py 파일은 다음과 같다.

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

root_agent = Agent(
    name="search_assistant",
    description="An agent that answers questions augmented with web searches.",
    model="gemini-2.0-flash",
    instruction="Answer questions provided by the user. Compare and contrast information gathered from Google with your own information. If you are given a statement that is not a question, reply, 'Please ask me a question.'",
    tools=[google_search]
)

각 에이전트를 만들 때마다 프로젝트 주 디렉토리 안에 하위 디렉토리를 만들고 이름을 지정한다(이 경우 searchagent). 이렇게 하면 하나의 프로젝트 내에 각각 독립적으로 실행되거나 상호작용할 수 있는 여러 에이전트를 둘 수 있다.

__init__.py 파일은 실제 에이전트 코드를 가져와서 디렉토리를 에이전트로 표시한다. agent.py 파일은 Agent 객체에 설명된 대로 에이전트 자체를 설정한다.

각 Agent는 인터페이스를 위해 모델 API를 사용한다(여기서는 gemini-2.0-flash). 사용자의 각 입력 앞에 붙는 에이전트에 대한 초기 명령은 instructions에 정의된다. 이 같은 instruction은 여기서 제시되는 것보다 훨씬 더 자세할 수 있다. tools 섹션은 에이전트가 사용할 수 있는 부가적인 툴을 제공하는데, 여기서 google_search는 에이전트가 결과를 보완하기 위해 구글 검색을 사용할 수 있도록 한다.

이 예제를 웹 인터페이스를 통해 로컬에서 실행하려면 명령줄을 열고 venv를 활성화한 다음 adk web 명령을 사용한다. 잠시 후 ADK의 웹 인터페이스가 포트 8000에서 실행 중이라는 메시지가 표시된다.

브라우저에서 http://localhost:8000으로 이동하면 기본 ADK 웹 인터페이스가 표시될 것이다. 이제 simpleagent 에이전트를 실행할 준비가 됐다. 특정 프로젝트에 여러 개의 에이전트를 구성했다면 페이지 왼쪽 상단의 드롭다운을 통해 원하는 에이전트를 선택할 수 있다.

에이전트가 제대로 실행되고 있는지 확인하려면 웹 페이지 하단의 창에 질문을 입력하고 엔터 키를 누른다. 몇 초 내에 결과가 표시될 것이다.

IDG

웹 UI의 왼쪽에는 에이전트와의 각 대화에 대한 디버깅 정보가 표시된다. 대화 왼쪽의 “봇” 아이콘을 클릭하면 해당 대화의 백엔드 세부 정보가 표시되는데, 이 정보에는 서비스에서 활동에 대해 반환한 메타데이터도 포함된다. 제공되는 세부 정보는 서비스에 따라 다르다.

IDG

채팅 창 상단의 “토큰 스트리밍(Token Streaming)” 옵션을 선택하면 결과가 한 번에 모두 표시되지 않고 한 단어씩 점진적으로 반환된다.

다중 에이전트 아키텍처 개발

ADK의 강점 중 하나는 한 번에 두 개 이상의 에이전트가 관여하는 에이전트 시스템을 만들 수 있다는 점이다. 에이전트 간의 상호작용은 워크플로우 에이전트라는 것을 사용해 구성할 수 있다.

워크플로우 에이전트는 AI 에이전트 작업을 시작한 다음 엄격하게 미리 정해진 방식에 따라 그 실행을 처리한다. 워크플로우 에이전트 자체는 AI 에이전트가 아니라 파이썬 또는 자바로 만들어진 프로그램일 뿐이다. 그러나 이를 통해 에이전트의 작동 범위를 대폭 확장할 수 있다.

워크플로우 에이전트에는 다음과 같은 다양한 형태가 있다.

- 순차적 에이전트 : 순차적 에이전트는 사용자 입력을 특정 LLM 또는 워크플로우에 제공하고 결과를 받아서 다른 LLM 또는 워크플로우에 다시 제공한다. 여기서 에이전트가 입력을 어떻게 처리해야 하는지에 대한 부가적인 프롬프트가 사용될 수도 있다. 이런 방식으로 한 에이전트를 사용해 다른 에이전트의 출력을 변환하거나 다듬을 수 있다. 예를 들어 텍스트를 생성하는 에이전트와 이 텍스트를 특정 작문 스타일로 다시 쓰는 다른 에이전트가 이런 형태에 해당한다.
- 루프 에이전트 : 루프 에이전트는 입력을 받아 LLM 또는 워크플로우에 제공하고, 특정 조건이 충족될 때까지 이 프로세스를 반복 실행한다. 여기서 조건은 단순히 루프를 x번 연속으로 실행하기와 같이 완전히 기계적인 조건일 수도 있지만, 예를 들어 “이 출력이 조건을 충족하는가?”라고 묻는 것과 같이 다른 LLM 에이전트가 기준을 확인하도록 하는 것도 가능하다. 예를 들어 한 에이전트가 긴 텍스트에서 간결한 텍스트를 생성하면 이 간결한 텍스트에 중요한 내용이 누락됐는지 여부를 다른 에이전트가 확인하는 식이다. 중요한 내용이 누락된 경우 새로운 간결한 텍스트가 생성된다. 이론적으로는 이 과정을 무한히 계속할 수도 있지만 보통은 정해진 루프 횟수만큼만 반복된다.
- 병렬 에이전트 : 병렬 에이전트는 두 개 이상의 에이전트 작업을 함께 실행하며, 모든 작업이 완료될 때까지 결과를 반환하지 않는다. 작업이 실행되는 동안 작업 간에 상태는 공유되지 않으므로 모든 작업은 필요한 데이터를 사전에 받아야 한다. 예를 들어 문서의 사실 확인 과정에서 서로 다른 3개의 검색 엔진을 사용하는 에이전트를 생각할 수 있다. 각 사실 확인 단계는 다른 검색 엔진과 나란히 실행되며, 모든 검색이 완료된 후에 결합된 결과가 생성된다.

기억해야 할 중요한 점은 이런 에이전트가 실제로는 파이썬 또는 자바 프로그램에 불과하다는 것이다. 따라서 전통적인 프로그램 동작의 제한 사항이 에이전트에도 그대로 적용된다. 예를 들어 병렬 에이전트는 병렬로 수행하려는 작업에 따라 제한된다. 즉, API 키에서 한 번에 하나의 작업만 수락하는 원격 서비스에서 여러 작업을 실행하기 위해 병렬 에이전트를 사용한다면 이 에이전트는 병렬 에이전트로 작동하지 않는다.

에이전트 개발 키트에 포함된 툴

ADK의 에이전트는 툴을 사용해 작업 방식을 보강할 수 있다. 여기서 말하는 “툴“은 파이썬 또는 자바 코드로 작성된 기능을 의미하며, 비LLM 구성요소와 접촉하는 역할을 한다(예를 들어 URL 엔드포인트에서 특정 요소를 가져오기, 데이터베이스에서 정보를 검색하기 또는 LLM이 없어도 되는 기타 작업). 다만 이 경우에도 LLM이 생성한 데이터를 사용할 수는 있다.

ADK 툴은 다음과 같은 세 가지 범주로 분류할 수 있다.

- 함수 툴은 프로그래머가 작성한 언어의 기존 함수를 래핑한다. 이 함수들은 JSON을 반환하므로 반환 값으로 사용되는 모든 데이터 타입은 기본적으로 JSON 직렬화가 가능해야 한다. 함수는 다른 동작을 차단하지 않으면서 실행되도록 설정할 수 있으며, 에이전트로도 작동할 수 있다. 즉, 에이전트를 툴처럼 호출하고 그 응답을 툴의 응답으로 사용하면 된다.
- 기본 제공 툴은 구글 검색과 같은 일반적인 기본 기능을 제공해서 처음부터 새로 구현할 필요가 없도록 한다. 또한 기본 제공 툴을 통해 임의의 코드를 실행하거나 구글 버텍스 AI 검색을 실행할 수도 있다.
- 서드파티 툴은 예를 들어 랭체인과 같이 내 워크플로우에서 사용 가능한 툴을 다른 개발자가 제공할 수 있도록 한다.

기존 비즈니스 로직을 ADK 기반 에이전트에 연결하려는 경우 최선의 방법은 에이전트 코드에 로직을 복사하는 대신 툴을 사용하는 것이다. 단순히 실험을 원한다면 에이전트에 직접 로직을 작성해 넣을 수 있지만 프로덕션급에서는 툴 인터페이스를 통해서 해야 한다.

ADK의 예제 프로젝트

ADK를 처음 시작하기 위한 좋은 방법은 기존의 다양한 예제 프로젝트를 살펴보고 그 중 하나를 내 요구사항에 맞게 수정하는 방법이다. 예제는 다양한 사용례와 동작을 포괄하므로 복제하고자 하는 패턴이 이미 있을 가능성이 높다.

- LLM 감사자 : 두 에이전트로 구성된 자동화된 사실 확인 시스템이다. 한 에이전트는 주장을 검증하고, 다른 에이전트는 검증된 사실에 부합하는 그 주장의 재작성된 버전을 생성한다. 이 예제는 순차적 에이전트 아키텍처를 사용하므로 순차적 에이전트 시스템을 원한다면 참고해서 따라하면 된다.
- 고객 서비스 : 다양한 백엔드 서비스와 연결돼 다양한 고객 서비스 작업을 수행하는 고객 서비스 에이전트다. 많은 툴이 이 예제를 통해 목업으로 구현돼 있으므로(예를 들어 영상 통화, 또는 세일즈포스와 같은 서비스와의 연동 등) 필요에 따라 이 예제를 실제 백엔드 서비스에 연결할 수 있다.
- 이미지 채점 에이전트 : 이미지를 생성하고, 생성된 이미지를 평가하는 다른 에이전트에 제공된 기준에 따라 결과를 검증한다. 이 예제에서는 루프 에이전트를 사용하므로 입력을 지속적으로 개선해야 하는 프로젝트에서 기본 구조로 사용할 수 있다.

dl-itworldkorea@foundryco.com

이 기사의 카테고리는 언론사의 분류를 따릅니다.