[구글 ADK] 2-3. Workflow Agent ③
Parallel Agent (실습 : 병렬 연구 리서치 에이전트 만들기)
(참고) 유튜브 영상으로 시청하고 싶으신분은 글 맨 하단 [강의 자료 URL]을 확인해주세요^^
이번 시간은 지난 반복적인 하위 에이전트 작업 흐름을 제어하는 LoopAgent 강의에 이어 워크플로우 에이전트 마지막 3번째 유형인 'ParallelAgent' 를 배워보겠습니다.
이번 병렬 에이전트 시간을 끝으로 ADK 워크플로우 에이전트 챕터가 마무리되고 다음 챕터로 넘어가게 됩니다. 워크플로우 에이전트 마지막 장까지 유종의 미를 거두기 위해 달려봅시다!
ParallelAgent 란?
ParallelAgent의 ‘Parallel'이라는 단어는 ‘병렬’이라는 뜻으로
컴퓨터 공학 분야에서는 이를 "여러 프로세스가 동시에 작업을 수행"한다는 의미로 사용됩니다.
Parallel의 뜻에서 힌트를 얻을 수 있듯이 ADK에서의 ParallelAgent는 하위 에이전트를 동시에 실행하는 워크플로 에이전트입니다.
이는 작업이 독립적으로 수행될 수 있는 워크플로의 속도를 극적으로 향상시킵니다.
■ 사용 시기
속도를 우선시하고 독립적이며 리소스 집약적인 작업이 포함된 시나리오의 경우, ParallelAgent는 효율적인 병렬 실행을 용이하게 합니다. 각 하위 에이전트가 의존성 없이 작업이 수행되는경우, 해당 작업은 동시에 수행될 수 있으며, 전체 처리 시간을 크게 단축합니다.
■ 작동 방식
ParallelAgent의 run_async() 메서드가 호출되면:
1. 동시 실행 :
sub_agents 목록에 있는 각 하위 에이전트의 run_async() 메서드를 동시에 시작합니다. 이는 모든 에이전트가 (거의) 동시에 실행되기 시작한다는 의미입니다.
2. 독립적인 분기:
각 하위 에이전트는 자체 실행 분기에서 작동합니다. 실행 중에는 이러한 분기 간에 대화 기록이나 상태가 자동으로 공유되지 않습니다.
3. 결과 수집 :
ParallelAgent는 병렬 실행을 관리하며, 일반적으로 각 하위 에이전트가 완료된 후 결과를 접근할 수 있는 방법을 제공합니다(예: 결과 또는 이벤트 목록을 통해). 결과의 순서는 결정론적이지 않을 수 있습니다.
■ 독립적인 실행 및 상태 관리
ParallelAgent 내의 하위 에이전트는 독립적으로 실행된다는 것을 이해하는 것이 중요합니다. 이러한 에이전트 간의 통신이나 데이터 공유가 필요하다면 명시적으로 구현해야 합니다. 가능한 접근 방식은 다음과 같습니다:
1. 공유 InvocationContext :
각 하위 에이전트에 공유 InvocationContext 객체를 전달할 수 있습니다. 이 객체는 공유 데이터 저장소 역할을 할 수 있습니다. 그러나 경쟁 조건을 피하기 위해 이 공유 컨텍스트에 대한 동시 접근을 신중하게 관리해야 합니다(예: 잠금 사용).
2. 외부 상태 관리 :
외부 데이터베이스, 메시지 큐 또는 기타 메커니즘을 사용하여 공유 상태를 관리하고 에이전트 간의 통신을 용이하게 합니다.
3. 후처리:
각 분기에서 결과를 수집한 다음, 데이터를 조정하기 위한 로직을 구현합니다.
병렬 에이전트 또한 다른 워크플로 에이전트(시퀀셜/루프 에이전트)들과 마찬가지로 LLM 기반으로 구동되지 않으므로 실행 방식이 결정론적입니다.
즉, 병렬 에이전트는 하위 에이전트를 병렬로 작업을 처리하는 실행 방식과 제어 흐름이 이미 결정되어 있다는 의미 입니다.
ParallelAgent 활용 예시 (병렬 연구 리서치 에이전트)
자 그렇다면, 병렬 에이전트를 활용하여 여러 주제를 동시에 연구하고 이를 통합 리포트로 작성하는 에이전트를 개발한다고 상상해봅시다.
연구 주제는 1) 재생가능에너지, 2) 전기자동차기술, 3) 탄소포집 방법 이 3가지로 설정해보겠습니다.
첫번째로 각 주제를 가지고 웹 리서치를 진행하고 리서치 결과를 정리하는 연구 에이전트가 있을 것입니다.
① 연구 에이전트 1 (renewable_energy)
“재생 가능 에너지원"을 연구하는 에이전트입니다.
② 연구 에이전트2 (ev_technology)
“전기 자동차 기술＂을 연구하는 에이전트입니다.
③ 연구 에이전트 3 (carbon_capture)
“탄소 포집 방법＂을 연구하는 에이전트입니다.
④ 리포트 작성 에이전트 (synthesizer)
각 연구 에이전트들이 작업한 리서치 결과를 통합 리포트로 작성하는 에이전트입니다.
이 연구 에이전트들은 병렬 에이전트의 하위 에이전트로 등록되어 동시에 실행됩니다.
그리고 마지막으로 리포트 작성 에이전트가 각 연구 에이전트들이 작업한 리서치 결과를 통합 리포트로 작성하여 반환합니다.
병렬 작업 처리의 효율성
지금은 간단한 예제로 각 연구 에이전트의 작업시간이 몇 초도 안걸리지만 예를들어 연구에이전트 하나의 작업시간이 1시간 걸린다고 가정했을 때, 병렬 에이전트를 사용하지 않는다면, 각 에이전트가 순차적으로 실행되어 총 3시간이 걸렸을 것입니다. 하지만 병렬 에이전트를 사용하여 3가지 연구 에이전트를 동시에 실행한다면 1시간 정도 밖에 안걸릴 겁니다. 3개의 작업을 예시로 해서 속도가 3배 정도 차이난다지만, 이것이 10개 20개가 된다면 속도는 10배, 20배까지 속도차이가 날 수도 있다는 뜻입니다. (단, 컴퓨팅 파워와 성능이 따라준다면..)
이처럼 각 작업이 독립적으로 실행되어도 될 경우 ParallelAgent를 사용하면 순차적으로 실행하는 것과 비교하여 작업 시간을 크게 단축할 수 있습니다.
이제 병렬 웹 리서치 에이전트를 실습을 통해 구현해보도록 하겠습니다.
에이전트 폴더 셋팅
워크플로우 챕터 폴더(02-workflow-agnet/) 아래 루프(Loop) 에이전트에 이어 3번째로 배울 parallel-agent 폴더를 만들어 주겠습니다.
이름은 '3-parallel-agent' 라고 짓겠습니다.
다음으로 방금 전에 [활용 예시[로 들었던 병렬 연구 리서치 에이전트 구현을 위해 에이전트 폴더를 만들어주겠습니다.
에이전트 이름은 글쓰기 에이전트라는 의미로 'research_agent'라는 이름으로 폴더를 생성해주겠습니다.
에이전트 폴더 구조는 이전 시간에 배운 loop agent 구조와 동일하게 생성해주시면 됩니다.
1) __init__.py 파일
2) .env 파일
3) agent.py 파일
4) sub_agents 폴더
__init__.py 파일, .env 파일은 공통 사항이므로, 루프 아이전트에 있는 파일을 그대로 복사하겠습니다.
# research_agent/__init__.py
from . import agent
# research_agent/.env
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=구글 AI 스튜디오에서 받은 API 키
그 다음 root_agent 즉 parallel_agent를 구현할 agent.py 파일을 생성해 주시고, 연구 리서치 작업에 필요한 하위 에이전트들을 구현할 sub_agents 폴더를 만들어줍니다.
에이전트 구현을 위한 기본 프로젝트 셋팅은 끝났습니다.
이제 본격적으로 에이전트 구현을 시작하겠습니다.
하위 에이전트 구현(연구 에이전트 3개 + 리포트 에이전트)
하위 에이전트들의 병렬(동시) 작업 흐름을 조율할 ParallelAgent를 구현하기 이전에 연구 리서치 작업을 진행할 연구 에이전트 3개와 연구 리서치 결과를 정리하는 리포트 에이전트를 먼저 구현하겠습니다.
#1 연구 에이전트 1 (renewable_energy) 구현
첫 번째로 "재생 가능 에너지(renewable_energy)"를 연구하는 에이전트를 정의합니다.
sub_agents 아래 "재생 가능 에너지"라는 뜻의 renewable_energy 폴더를 만들어줍니다.
그리고 에이전트 구현에 필요한 기본 파일 2가지인 __init__.py 파일과 agent.py 파일을 추가합니다.
먼저 enewable_energy/ 폴더 아래 __init__.py을 열고 아래와 같이 작성하겠습니다.
그리고 enewable_energy/ 폴더 아래 agent.py 파일을 열고 "재생가능에너지(renewable_energy)" 연구 에이전트를 아래와 같이 작성합니다.
(agent.py 코드 설명)
Google ADK의 LLMAgent 클래스를 임포트해줍니다.
from google.adk.agents import LlmAgent
에이전트가 구글 검색 기능을 활용할 수 있도록 Google ADK에서 제공하는 내장도구인 google_search 툴을 임포트 해줍니다.
from google.adk.tools import google_search
다음으로 (재생가능에너지) 연구 에이전트1을 간단하게 정의하겠습니다.
변수명은 renewable_energy_agent로 짓고 LlmAgent를 할당합니다.
그리고 LlmAgent의 정체성과 목적을 부여하기 위한 설정값을 입력하겠습니다.
- name은 변수명과 동일한 renewable_energy_agent라고 입력합니다.
- model은 "gemini-2.0-flash" 모델을 사용합니다.
- description은 "재생 가능 에너지 소스 연구"라고 입력하겠습니다.
- instruction은 미리 준비해둔 프롬프트를 복사 붙여넣기 하겠습니다.
인스트럭션을 간단히 설명하자면, 재생 가능 에너지 소스 연구의 최신 발전 동향을 Google 검색 도구를 사용해 조사하고 내용을 간결하게 1~2문장으로 요약하라는 내용입니다.
지난 루프(Loop) 에이전트에서 tools 설정을 배웠던거 기억나시나요?
루트를 종료시키기 위해 직접 종료 함수(exit_loop)를 정의했었는데, 종료 함수의 경우 제가 종료 기능이 있는 파이썬 함수를 구현하고 에이전트가 사용할 수 있도록 tools 설정에 등록했었는데
이번에는 ADK에서 제공하는 내장 도구(툴)를 활용하여 구글 검색을 할 수 있도록 했습니다.
위에서 임포트했던 ADK 내장도구 "google_search"를 tools 설정에 추가합니다.
이렇게 되면 에이전트가 사용자의 요청에 따라 실시간 구글 검색을 할 수 있게 됩니다.
마지막으로 (재생가능에너지) 연구 에이전트1의 연구 결과를 저장할 output_key를 설정합니다.
output_key는 "renewable_energy_result"로 설정합니다.
이것으로 (재생가능에너지) 연구 에이전트1 구현이 완료되었습니다.
# (코드 복사용) research_agent/sub_agents/renewable_energy/agent.py
https://gist.github.com/SoonCoding/dfd39303900b2c6ac3df99d42deaba61
#2 연구 에이전트 2 (ev_technology) 구현
다음으로 "전기 자동차 기술(ev_technology)"를 연구하는 에이전트를 정의합니다.
sub_agents 아래 "전기 자동차 기술"라는 뜻의 ev_technology 폴더를 만들어줍니다.
그리고 에이전트 구현에 필요한 기본 파일 2가지인 __init__.py 파일과 agent.py 파일을 추가합니다.
먼저 ev_technology/ 폴더 아래 __init__.py을 열고 아래와 같이 작성하겠습니다.
그리고 ev_technology/ 폴더 아래 agent.py 파일을 열고 "전기 자동차 기술(ev_technology)" 연구 에이전트를 아래와 같이 작성합니다.
(agent.py 코드 설명)
Google ADK의 LLMAgent 클래스를 임포트해줍니다.
from google.adk.agents import LlmAgent
에이전트가 구글 검색 기능을 활용할 수 있도록 Google ADK에서 제공하는 내장도구인 google_search 툴을 임포트 해줍니다.
from google.adk.tools import google_search
다음으로 (전기 자동차 기술) 연구 에이전트2을 간단하게 정의하겠습니다.
변수명은 ev_technology_agent로 짓고 LlmAgent를 할당합니다.
그리고 LlmAgent의 정체성과 목적을 부여하기 위한 설정값을 입력하겠습니다.
- name은 변수명과 동일한 ev_technology_agent라고 입력합니다.
- model은 "gemini-2.0-flash" 모델을 사용합니다.
- description은 "전기차 기술 연구"라고 입력하겠습니다.
- instruction은 미리 준비해둔 프롬프트를 복사 붙여넣기 하겠습니다.
인스트럭션을 간단히 설명하자면, 전기차 기술 연구의 최신 발전 사항을 Google 검색 도구를 사용해 조사하고 내용을 간결하게 1~2문장으로 요약하라는 내용입니다.
ADK에서 제공하는 내장 도구(툴)를 활용하여 구글 검색을 할 수 있도록 google_search 도구를 에이전트 도구 설정에 추가합니다.
위에서 임포트했던 ADK 내장도구 "google_search"를 tools 설정에 추가합니다.
이렇게 되면 에이전트가 사용자의 요청에 따라 실시간 구글 검색을 할 수 있게 됩니다.
마지막으로 (전기차 기술) 연구 에이전트2의 연구 결과를 저장할 output_key를 설정합니다.
output_key는 "ev_technology_result"로 설정합니다.
이것으로 (전기차 기술) 연구 에이전트2 구현이 완료되었습니다.
# (코드 복사용) research_agent/sub_agents/ev_technology/agent.py
https://gist.github.com/SoonCoding/960da8492741f8670713cf4f247d1ef0
#3 연구 에이전트 3 (carbon_capture) 구현
다음으로 세번째 연구 에이전트인 "탄소 포집 방법(carbon_capture)"를연구하는 에이전트를 정의합니다.
sub_agents 아래 "탄소 포집 방법"라는 뜻의 carbon_capture 폴더를 만들어줍니다.
그리고 에이전트 구현에 필요한 기본 파일 2가지인 __init__.py 파일과 agent.py 파일을 추가합니다.
먼저 carbon_capture/ 폴더 아래 __init__.py을 열고 아래와 같이 작성하겠습니다.
그리고 carbon_capture/ 폴더 아래 agent.py 파일을 열고 "탄소 포집 방법(carbon_capture)" 연구 에이전트를 아래와 같이 작성합니다.
(agent.py 코드 설명)
Google ADK의 LLMAgent 클래스를 임포트해줍니다.
from google.adk.agents import LlmAgent
에이전트가 구글 검색 기능을 활용할 수 있도록 Google ADK에서 제공하는 내장도구인 google_search 툴을 임포트 해줍니다.
from google.adk.tools import google_search
다음으로 (탄소 포집 방법) 연구 에이전트3을 간단하게 정의하겠습니다.
변수명은 carbon_capture_agent로 짓고 LlmAgent를 할당합니다.
그리고 LlmAgent의 정체성과 목적을 부여하기 위한 설정값을 입력하겠습니다.
- name은 변수명과 동일한 carbon_capture_agent라고 입력합니다.
- model은 "gemini-2.0-flash" 모델을 사용합니다.
- description은 "탄소 포집 방법 연구"라고 입력하겠습니다.
- instruction은 미리 준비해둔 프롬프트를 복사 붙여넣기 하겠습니다.
인스트럭션을 간단히 설명하자면, 탄소 포집 방법의 현재 상태를 Google 검색 도구를 사용해 조사하고 내용을 간결하게 1~2문장으로 요약하라는 내용입니다.
ADK에서 제공하는 내장 도구(툴)를 활용하여 구글 검색을 할 수 있도록 google_search 도구를 에이전트 도구 설정에 추가합니다.
위에서 임포트했던 ADK 내장도구 "google_search"를 tools 설정에 추가합니다.
이렇게 되면 에이전트가 사용자의 요청에 따라 실시간 구글 검색을 할 수 있게 됩니다.
마지막으로 (탄소 포집 방법) 연구 에이전트3의 연구 결과를 저장할 output_key를 설정합니다.
output_key는 "carbon_capture_result"로 설정합니다.
이것으로 (탄소 포집 방법) 연구 에이전트3 구현이 완료되었습니다.
# (코드 복사용) research_agent/sub_agents/carbon_capture/agent.py
https://gist.github.com/SoonCoding/cd2b932fcc77be568fa067fa8755f108
#4 리포트 작성 에이전트(synthesizer) 구현
마지막으로 위 3가지 연구 에이전트의 리서치 결과를 종합하여 리포트로 작성하는 에이전트를 정의합니다.
sub_agents 아래 "합성하는 사람"이라는 뜻의 synthesizer 폴더를 만들어줍니다.
그리고 에이전트 구현에 필요한 기본 파일 2가지인 __init__.py 파일과 agent.py 파일을 추가합니다.
먼저 synthesizer/ 폴더 아래 __init__.py을 열고 아래와 같이 작성하겠습니다.
그리고 synthesizer/ 폴더 아래 agent.py 파일을 열고 "리포트 작성 (synthesizer)" 에이전트를 아래와 같이 작성합니다.
(agent.py 코드 설명)
Google ADK의 LLMAgent 클래스를 임포트해줍니다.
from google.adk.agents import LlmAgent
다음으로 연구 리서치 결과를 종합하여 리포트를 작성하는 리포트 작성 에이전트를 간단하게 정의하겠습니다.
변수명은 synthesis_agent 로 짓고 LlmAgent를 할당합니다.
그리고 LlmAgent의 정체성과 목적을 부여하기 위한 설정값을 입력하겠습니다.
- name은 변수명과 동일한 synthesis_agent 라고 입력합니다.
- model은 "gemini-2.0-flash" 모델을 사용합니다.
- description은 "병렬 에이전트 요약을 기반으로 구조화된 리포트 생성"이라고 입력하겠습니다.
- instruction은 미리 준비해둔 프롬프트를 복사 붙여넣기 하겠습니다.
인스트럭션을 간단히 설명하자면, 3가지 연구 에이전트(재생 에너지, 전기차기술, 탄소포집)의 요약된 연구 리서치 결과를 종합하여 구조화된 리포트를 생성하라는 내용입니다. 각 연구 에이전트의 결과는 각 에이전트설정에서 지정한 output_key를 참조하도록 했습니다.
그리고 리포트 작성 에이전트의 경우, 리포트 작성 후, 대화 인터페이스에서 리포트 생성 결과를 곧바로 출력하기 때문에 위 3가지 연구 에이전트들과 달리 따로 output_key를 설정하지 않고, 연구 결과를 종합하고 정리하는 역할만 하기 때문에 따로 검색 기능이 필요하지 않기 때문에 검색 도구를 추가하지 않습니다.
# (코드 복사용) research_agent/sub_agents/synthesizer/agent.py
https://gist.github.com/SoonCoding/125a8899b3c0e8b359b562dabada8eb9
리포트 작성 에이전트 구현을 끝으로 병렬 연구 리서치 에이전트의 하위 에이전트를 모두 구현 하였습니다.
이제 마지막으로 이번 장의 주제인 병렬(parallel) 에이전트를 구현해보겠습니다.
Parallel Agent 구현
병렬(parallel) 에이전트는 앞서 설명드린것 처럼 위 3가지 (재생 에너지, 전기차기술, 탄소포집) 하위 연구 에이전트을 동시에 병렬 작업을 진행할 수 있도록 제어하는 에이전트 입니다.
병렬 연구 리서치 에이전트는 작업이 시작되고 3가지 연구 에이전트들을 병렬 실행하여 리서치 결과를 저장한 이후 -> 리서치 결과를 종합하는 리포트 작성 에이전트에 의해 최종 리포트를 출력합니다.
이말은 3가지 (재생 에너지, 전기차기술, 탄소포집) 연구 에이전트만 병렬 작업 파이프라인에 포함하고 리포트 작성 에이전트는 병렬 작업 이후 작업이 진행되어야 한다는 의미입니다.
그래서 병렬 리서치 파이프라인을 Parallel 에이전트와 Sequential 에이전트와 함께 사용해서 파이프라인을 구성합니다.
에이전트 루트 폴더인 research_agent 폴더 아래 agent.py 파일을 열고 ParallelAgent를 구현해주겠습니다.
(agent.py 코드 설명)
Parallel 에이전트 + Sequential 에이전트 파이프라인을 구성을 위해 ParallelAgent와 SequentialAgent를 임포드해줍니다.
첫번째로 3가지 연구 에이전트들을 병렬로 실행할 병렬 에이전트를 정의해주겠습니다.
Parallel Agent의 핵심은 하위 에이전트를 병렬(동시) 실행하는 것입니다.
그래서 sub_agents=[] 설정값에 병렬(동시) 실행할 하위 에이전트들을 입력해줍니다.
sub_agents 설정에 하위 에이전트를 지정하기 위해서는 구현한 하위 에이전트를 임포트 해야합니다.
참고로 하위 에이전트는 현재 저희가 작업중인 파일을 기준으로 sub_agents 폴더 아래에 위치하고 있습니다.
하위 에이전트(연구 에이전트 3개 + 리포트 작성 에이전트)들을 임포트해주겠습니다
from .sub_agents.renewable_energy import renewable_energy_agent
from .sub_agents.ev_technology import ev_technology_agent
from .sub_agents.carbon_capture import carbon_capture_agent
from .sub_agents.synthesizer import synthesis_agent
병렬 에이전트(parallel_research_agent)의 하위 에이전트는 연구 에이전트 1~3을 추가해줍니다.
sub_agents=[renewable_energy_agent, ev_technology_agent, carbon_capture_agent]
그리고 병렬 에이전트의 이름(name)과 설명(description)을 작성해줍니다.
name="parallel_web_research_agent",
description="여러 연구 에이전트를 병렬로 실행하여 정보 수집"
다음으로 병렬 연구 리서치 에이전트와 리포트 작성 에이전트를 하나의 파이프라인으로 연결하기 위해 Sequential 에이전트를 정의해주겠습니다.
작업 순서가 병렬 연구 리서치 에이전트 실행 -> 연구 리서치 결과 종합 리포트 생성 작업입니다.
sub_agents에 방금전에 구현한 병렬 에이전트(parallel_research_agent)와 하위 에이전트인 리포트 작성 에이전트(synthesis_agent)를 순서대로 추가해줍니다.
sub_agents=[parallel_research_agent, synthesis_agent]
그리고 에이전트 이름(name)과 설명(description)을 작성해주면 끝입니다.
name="research_and_synthesis_pipeline",
description="병렬 연구 실행 후 결과를 통합"
# (코드 복사용) research_agnet/agent.py
https://gist.github.com/SoonCoding/79cb24c7d30890631be6083b8c38a565
이로써 ParallelAgent + SequentialAgent를 활용한 병렬 연구 리서치 에이전트 구현이 완료되었습니다!
이제 adk web ui에 접속해서 병렬 연구 리서치 에이전트가 잘 동작하는지 테스트를 진행하겠습니다.
ADK WEB TEST (ParallelAgent: 병렬 연구 리서치 에이전트)
(참고) 에이전트 테스트는 브런치 글로 작성하지 못했습니다.
병렬 웹 리서치 에이전트 동작을 확인하고 싶으신분들은
아래 유튜브 링크로 확인하시길 바랍니다 ㅠㅠ
강의 자료 (URL)
1. 유튜브 (영상 강의)
2. 브런치 스토리 (블로그 강의)
https://brunch.co.kr/@sooncoding/63/write
3. GitHub (실습 예제 코드)
https://github.com/SoonCoding/adk-tutorials