GENAI106

개요

이 실습에서는 Google 에이전트 개발 키트(Google ADK) 내에서 멀티 에이전트 시스템을 조정하는 방법을 다룹니다.

이 실습에서는 다음 실습에서 다룬 ADK 및 도구 사용에 관한 기본사항을 잘 알고 있다고 가정합니다.

• Google 에이전트 개발 키트(ADK) 시작하기
• 도구로 ADK 에이전트 지원

목표

이 실습에서 학습할 내용은 다음과 같습니다.

• 여러 에이전트를 만들고 상위 에이전트와 하위 에이전트 관계로 서로 연결합니다.
• 세션의 상태 사전에 작성하여 여러 턴의 대화와 여러 에이전트에 걸쳐 콘텐츠를 빌드합니다.
• 에이전트가 세션 상태에서 값을 읽어 대답에 대한 컨텍스트로 사용하도록 지시합니다.
• 워크플로 에이전트를 사용하여 에이전트 간에 대화를 직접 전달합니다.

설정 및 요건

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

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

멀티 에이전트 시스템

에이전트 개발 키트를 사용하면 개발자가 생성 모델에서 더 안정적이고 정교한 다단계 동작을 구현할 수 있습니다. 결과를 안정적으로 제공하지 못할 수 있는 길고 복잡한 프롬프트를 작성하는 대신, 태스크와 책임을 나누어 복잡한 문제에 대해 협업할 수 있는 여러 개의 간단한 에이전트의 흐름을 구성할 수 있습니다.

이 아키텍처 접근 방식은 다음과 같은 몇 가지 주요 이점을 제공합니다.

• 설계 용이성: 특정 작업과 기술을 가진 에이전트의 관점에서 생각할 수 있습니다.
• 더욱 안정적인 성능의 전문화된 기능: 전문 에이전트가 명확한 예를 통해 학습하여 특정 태스크에서 더욱 안정적인 성능을 발휘할 수 있습니다.
• 조직화: 워크플로를 개별 에이전트로 나누면 접근 방식을 더 체계적으로 구성할 수 있어 이해하고 구성하기가 더 쉬워집니다.
• 개선 가능성 및 유지보수 가능성: 하나의 동작을 수정하면 다른 동작에 영향을 미칠 수 있는 복잡한 에이전트를 변경하는 것보다 특화된 구성요소를 개선하거나 수정하는 것이 더 쉽습니다.
• 모듈성: 하나의 워크플로에서 개별 에이전트를 쉽게 복사하여 다른 유사한 워크플로에 포함할 수 있습니다.

계층적 에이전트 트리

에이전트 개발 키트에서는 에이전트를 트리와 같은 구조로 정리합니다. 이렇게 하면 트리의 각 에이전트에 대한 트랜스퍼 옵션이 제한되어 트리를 통해 대화가 진행될 수 있는 가능한 경로를 더 쉽게 제어하고 예측할 수 있습니다. 계층 구조의 이점은 다음과 같습니다.

• 실제 협업 팀에서 영감을 받아 멀티 에이전트 시스템의 동작을 더 쉽게 설계하고 추론할 수 있습니다.
• 일반적인 소프트웨어 개발 패턴을 반영하므로 개발자에게 직관적입니다.
• 시스템 내 정보 흐름과 태스크 위임을 더 정밀하게 제어할 수 있어 가능한 경로를 더 쉽게 이해하고 시스템을 디버그할 수 있습니다. 예를 들어 시스템의 흐름에서 서로 다른 부분에 비슷한 설명을 가진 두 개의 보고서 생성 에이전트가 있는 경우 트리 구조를 사용하면 올바른 에이전트를 더 쉽게 호출할 수 있습니다.

구조는 항상 root_agent 변수에 정의된 에이전트로 시작됩니다(자신을 식별하기 위해 다른 사용자 대상 이름을 가질 수 있음). root_agent는 하나 이상의 하위 에이전트의 상위 역할을 할 수 있습니다. 각 하위 에이전트에는 자체 하위 에이전트가 있을 수 있습니다.

작업 1. ADK 설치 및 환경 설정

이 실습 환경에서는 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. 창 상단에서 편집기 열기 연필 아이콘()을 클릭하여 파일을 표시합니다.
6. 왼쪽 탐색 메뉴 상단에서 탐색기 아이콘()을 클릭하여 파일 탐색기를 엽니다.
7. 폴더 열기 버튼을 클릭합니다.
8. 폴더 열기 대화상자가 열리면 확인을 클릭하여 Qwiklabs 학생 계정의 홈 폴더를 선택합니다.
9. 화면 오른쪽에 표시되는 추가 튜토리얼 또는 Gemini 패널을 닫아 코드 편집기에 더 많은 공간을 확보합니다.
10. 이 실습의 나머지 부분에서는 이 창을 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_multiagent_systems .

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

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

작업 2. 상위 에이전트, 하위 에이전트, 피어 에이전트 간의 트랜스퍼 살펴보기

대화는 항상 root_agent 변수로 정의된 에이전트로 시작됩니다.

상위 에이전트의 기본 동작은 각 하위 에이전트의 설명을 이해하고 대화에 대한 제어권을 하위 에이전트로 트랜스퍼해야 하는지 여부를 언제든지 결정하는 것입니다.

하위 에이전트의 name 파라미터 값(변수 이름이 아님)을 참조하여 상위 에이전트의 instruction에서 이러한 트랜스퍼를 안내할 수 있습니다. 아래 예시를 수행해 보세요.

1. Cloud Shell 터미널에서 다음을 실행하여 parent_and_subagents 디렉터리에서 에이전트를 인증할 .env 파일을 만듭니다.

   cd ~/adk_multiagent_systems cat << EOF > parent_and_subagents/.env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION=global MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF

2. 다음 명령어를 실행하여 .env 파일을 실습 후반부에서 사용할 workflow_agents 디렉터리에 복사합니다.

   cp parent_and_subagents/.env workflow_agents/.env

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

4. agent.py 파일을 클릭하여 엽니다.

팁: Python 코드에서는 에이전트에 하위 에이전트를 추가하기 전에 하위 에이전트를 정의해야 하므로 대화 흐름 순서대로 agent.py 파일을 읽으려면 하단 에이전트부터 읽기 시작하여 상단으로 거슬러 올라가는 것이 좋습니다.

5. 여기에는 세 가지 에이전트가 있습니다.

   • steering이라는 이름의 root_agent(이름은 ADK의 개발 UI 및 명령줄 인터페이스에서 에이전트를 식별하는 데 사용됨). 이 steering 에이전트는 사용자에게 여행하고 싶은 목적지를 알고 있는지, 아니면 결정하는 데 도움이 필요한지를 물으며, 사용자의 대답에 따라 대화를 어떤 하위 에이전트로 넘길지 결정합니다. 이 에이전트에는 하위 에이전트에 대해서는 언급하지 않는 간단한 instruction만 포함되어 있지만, 하위 에이전트의 설명은 지정되어 있습니다.
   • 사용자가 방문하고 싶은 곳을 모를 경우 목적지를 브레인스토밍하도록 도와주는 travel_brainstormer.
   • 사용자가 방문하고 싶은 국가를 정한 후 할 일 목록을 작성하도록 도와주는 attractions_planner.

6. root_agent를 만들 때 다음 줄을 추가하여 travel_brainstormer와 attractions_planner를 root_agent의 하위 에이전트로 설정합니다.

   sub_agents=[travel_brainstormer, attractions_planner]

7. 파일을 저장합니다.

8. 하위 에이전트에는 해당 parent 파라미터를 추가하지 않습니다. 계층적 트리는 상위 에이전트를 만들 때 sub_agents를 지정하는 방법으로만 정의됩니다.

9. Cloud Shell 터미널에서 다음을 실행하여 ADK 명령줄 인터페이스를 사용하여 에이전트와 채팅합니다.

   cd ~/adk_multiagent_systems adk run parent_and_subagents

10. [user]: 프롬프트가 표시되면 다음을 사용하여 에이전트에게 인사합니다.

    hello

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

    user: hello [steering]: Hi there! Do you already have a country in mind for your trip, or would you like some help deciding where to go?

11. 에이전트에게 다음과 같이 말합니다.

    I could use some help deciding.

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

    user: I could use some help deciding. [travel_brainstormer]: Okay! To give you the best recommendations, I need to understand what you're looking for in a trip. ...

12. 대괄호로 묶인 이름 [travel_brainstormer]에서 이름이 [steering]인 root_agent가 해당 하위 에이전트의 description만을 기반으로 대화를 적절한 하위 에이전트로 트랜스퍼했음을 알 수 있습니다.

13. user: 프롬프트에서 exit를 입력하여 대화를 종료합니다.

14. 또한 에이전트의 instruction의 일부로 하위 에이전트로 트랜스퍼할 시점에 관한 더 자세한 요청 사항을 제공할 수 있습니다. agent.py 파일에서 다음 줄을 root_agent의 instruction에 추가합니다.

    If they need help deciding, send them to 'travel_brainstormer'. If they know what country they'd like to visit, send them to the 'attractions_planner'.

15. 파일을 저장합니다.

16. Cloud Shell 터미널에서 다음을 실행하여 명령줄 인터페이스를 다시 시작합니다.

    adk run parent_and_subagents

17. 다음을 사용하여 에이전트에게 인사합니다.

    hello

18. 다음을 사용하여 에이전트의 인사말에 답합니다.

    I would like to go to Japan.

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

    user: I would like to go to Japan. [attractions_planner]: Okay, I can help you with that! Here are some popular attractions in Japan: * **Tokyo:** * Senso-ji Temple * Shibuya Crossing * Tokyo Skytree * **Kyoto:** ...

19. 다른 하위 에이전트인 attractions_planner로 트랜스퍼된 것을 확인할 수 있습니다.

20. 다음을 사용하여 답합니다.

    Actually I don't know what country to visit.

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

    user: actually I don't know what country to visit [travel_brainstormer]: Okay! I can help you brainstorm some countries for travel...

21. attractions_planner의 피어 에이전트인 travel_brainstormer 에이전트로 트랜스퍼된 것을 확인할 수 있습니다. 이는 기본적으로 허용됩니다. 피어에 대한 트랜스퍼를 방지하려면 attractions_planner 에이전트에서 disallow_transfer_to_peers 파라미터를 True로 설정하면 됩니다.

22. 사용자 프롬프트에서 exit를 입력하여 세션을 종료합니다.

단계별 패턴: 사용자를 단계별로 안내하는 에이전트에 관심이 있는 경우 첫 번째 단계를 root_agent로 설정하고, 두 번째 단계 에이전트를 그에 대한 유일한 하위 에이전트로 지정한 후, 이어서 각 추가 단계도 이전 단계 에이전트의 유일한 하위 에이전트가 되도록 설정하는 패턴을 사용하면 유용합니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. 상위 에이전트, 하위 에이전트, 피어 에이전트 간의 트랜스퍼 살펴보기

작업 3. 세션 상태를 사용하여 특정 정보 저장 및 검색

ADK의 각 대화는 대화에 참여한 모든 에이전트가 액세스할 수 있는 세션 내에 포함됩니다. 세션에는 대화 기록이 포함되어 있으며, 에이전트는 대답을 생성할 때 사용하는 컨텍스트의 일부로 이 대화 기록을 읽습니다. 세션에는 강조하고 싶은 가장 중요한 정보와 정보에 액세스하는 방법을 더 효과적으로 제어하는 데 사용할 수 있는 세션 상태 사전도 포함되어 있습니다.

이는 에이전트 간에 정보를 전달하거나 사용자와의 대화 과정에서 태스크 목록과 같은 간단한 데이터 구조를 유지하는 데 특히 유용할 수 있습니다.

상태에 값을 추가하고 상태에서 읽는 방법을 살펴보려면 다음 안내를 따르세요.

1. adk_multiagent_systems/parent_and_subagents/agent.py 파일로 돌아갑니다.

2. 다음 함수 정의를 # Tools 헤더 뒤에 붙여넣습니다.

   def save_attractions_to_state( tool_context: ToolContext, attractions: List[str] ) -> dict[str, str]: """Saves the list of attractions to state["attractions"]. Args: attractions [str]: a list of strings to add to the list of attractions Returns: None """ # Load existing attractions from state. If none exist, start an empty list existing_attractions = tool_context.state.get("attractions", []) # Update the 'attractions' key with a combo of old and new lists. # When the tool is run, ADK will create an event and make # corresponding updates in the session's state. tool_context.state["attractions"] = existing_attractions + attractions # A best practice for tools is to return a status message in a return dict return {"status": "success"}

3. 이 코드에서 다음 사항을 살펴봅니다.

   • 세션은 ToolContext로 도구 함수에 전달됩니다. 여기에서 tool_context라는 이름의 파라미터에서 볼 수 있듯이, 이를 수신하려면 파라미터를 하나 할당하기만 하면 됩니다. 그런 다음 tool_context를 사용하여 대화 기록(tool_context.events를 통해) 및 세션 상태 사전(tool_context.state를 통해)과 같은 세션 정보에 액세스할 수 있습니다. 도구 함수에 의해 tool_context.state 사전이 수정되면 도구가 실행을 완료한 후 세션의 상태에 이러한 변경사항이 반영됩니다.
   • docstring은 인수와 반환 값에 대한 명확한 설명과 섹션을 제공합니다.
   • 주석 처리된 함수 코드는 상태 사전을 얼마나 쉽게 업데이트할 수 있는지 보여줍니다.

4. 에이전트를 만들 때 다음과 같이 tools 파라미터를 추가하여 attractions_planner 에이전트에 도구를 추가합니다.

   tools=[save_attractions_to_state]

5. attractions_planner 에이전트의 기존 instruction에 다음 글머리기호 목록을 추가합니다.

   - When they reply, use your tool to save their selected attraction and then provide more possible attractions. - If they ask to view the list, provide a bulleted list of { attractions? } and then suggest some more.

6. 중괄호로 묶인 섹션 { attractions? }를 살펴봅니다. 이 ADK 기능인 키 템플릿은 상태 사전에서 attractions 키의 값을 로드합니다. attractions 키 뒤의 물음표는 필드가 아직 없는 경우 오류가 발생하는 것을 방지합니다.

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 링크를 클릭합니다.

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

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

11. hello를 사용하여 대화를 시작합니다.

12. 에이전트가 인사하면 다음으로 답합니다.

    I'd like to go to Egypt.

    attractions_planner로 트랜스퍼되고 관광 명소 목록이 제공됩니다.

13. 예를 들어 다음과 같이 관광 명소 한 곳을 선택합니다.

    I'll go to the Sphinx

14. 대답에 다음과 같은 확인 메시지가 표시됩니다. Okay, I've saved The Sphinx to your list. Here are some other attractions...

15. 대답 도구 상자(체크표시로 표시됨)를 클릭하여 도구의 대답으로 생성된 이벤트를 확인합니다. 상태 변경을 설명하는 state_delta가 포함된 actions 필드가 포함되어 있습니다.

16. 에이전트가 더 많은 관광 명소를 선택해 달라는 메시지를 표시합니다. 에이전트가 제시한 옵션 중 하나를 선택하여 에이전트에 답합니다.

17. 왼쪽 탐색 메뉴에서 'X'를 클릭하여 앞서 검사한 이벤트에 대한 포커스를 해제합니다.

18. 이제 사이드바에 이벤트 목록과 몇 가지 탭 옵션이 표시됩니다. 상태 탭을 선택합니다. 여기에서 요청한 두 값이 포함된 attractions 배열을 비롯한 현재 상태를 확인할 수 있습니다.

    

19. 에이전트에게 다음 메시지를 보냅니다.

    What is on my list?

20. instruction에 따라 글머리기호 목록으로 형식이 지정된 목록이 반환됩니다.

21. 에이전트 실험을 마쳤으면 웹브라우저 탭을 닫고 Cloud Shell 터미널에서 Ctrl+C를 눌러 서버를 중지합니다.

    이 실습의 후반부에서는 상태를 사용하여 에이전트 간에 통신하는 방법을 보여줍니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. 세션 상태를 사용하여 특정 정보 저장 및 검색

작은 정보 조각을 저장하는 대신 에이전트의 전체 텍스트 대답을 상태 사전에 저장하려면 에이전트를 정의할 때 output_key 파라미터를 설정하면 됩니다. 그러면 전체 출력이 해당 필드 이름으로 상태 사전에 저장됩니다.

워크플로 에이전트

상위 에이전트에서 하위 에이전트로의 트랜스퍼는 여러 전문 하위 에이전트가 있고 사용자가 각 에이전트와 상호작용하도록 하려는 경우에 적합합니다.

그러나 사용자의 응답을 기다리지 않고 에이전트들이 연속적으로 작동하도록 하려면 워크플로 에이전트를 사용할 수 있습니다. 워크플로 에이전트를 사용할 수 있는 시나리오의 예는 다음과 같습니다.

• 계획 및 실행: 하나의 에이전트가 항목 목록을 준비한 다음 다른 에이전트가 해당 목록을 사용하여 문서의 섹션을 작성하는 등의 후속 태스크를 수행하도록 하려는 경우
• 조사 및 작성: 하나의 에이전트가 함수를 호출하여 Google 검색 또는 다른 데이터 소스에서 컨텍스트 정보를 수집한 다음 다른 에이전트가 해당 정보를 사용하여 출력을 생성하도록 하려는 경우
• 초안 작성 및 수정: 한 에이전트가 문서 초안을 준비한 다음 다른 에이전트가 작업을 확인하고 반복 작업을 수행하도록 하려는 경우

이러한 종류의 태스크를 수행하기 위해 워크플로 에이전트는 하위 에이전트를 보유하고 있으며 각 하위 에이전트가 작동하도록 보장합니다. 에이전트 개발 키트는 3개의 기본 제공 워크플로 에이전트를 제공하며 사용자가 직접 정의할 수도 있습니다.

• SequentialAgent
• LoopAgent
• ParallelAgent

이 실습의 나머지 부분에서는 여러 LLM 에이전트, 워크플로 에이전트, 에이전트의 흐름을 제어하는 데 도움이 되는 도구를 사용하여 멀티 에이전트 시스템을 빌드합니다.

구체적으로 설명하자면 역사적 인물의 삶을 바탕으로 한 전기 영화인 새로운 히트 영화의 피치 문서를 작성하는 에이전트를 빌드합니다. 하위 에이전트가 조사 작업과 시나리오 작가 및 비평가와의 반복적인 글쓰기 루프를 처리하며, 마지막으로 추가 하위 에이전트들이 캐스팅 아이디어를 브레인스토밍하고 과거 박스오피스 데이터를 활용하여 흥행 성적을 예측하는 데 도움을 줍니다.

결국에 생성되는 멀티 에이전트 시스템은 다음과 같습니다(이미지를 클릭하면 더 크게 볼 수 있음).

하지만 먼저 더 단순한 버전부터 시작합니다.

작업 4. SequentialAgent로 멀티 에이전트 시스템 빌드 시작

SequentialAgent는 하위 에이전트를 선형 시퀀스로 실행합니다. sub_agents 목록에 있는 각 하위 에이전트는 정의된 순서대로 차례로 실행됩니다.

이는 태스크를 특정 순서로 수행해야 하고 한 태스크의 출력이 다음 태스크의 입력으로 사용되는 워크플로에 적합합니다.

이 작업에서는 SequentialAgent를 실행하여 영화 피치 작성 멀티 에이전트 시스템의 첫 번째 버전을 빌드합니다. 에이전트의 첫 번째 초안은 다음과 같은 구조로 작성됩니다.

• 사용자를 환영하고 영화 주제로 역사적 인물을 요청하는 greeter라는 이름의 root_agent

• film_concept_team이라는 SequentialAgent에는 다음이 포함됩니다.

  • researcher: 도구로 ADK 에이전트 지원 실습에서 다룬 LangChain 도구를 사용하여 Wikipedia에서 요청된 역사적 인물에 대해 자세히 알아봅니다. 에이전트는 도구를 연속으로 여러 번 호출하도록 선택할 수 있으므로 researcher는 추가 조사가 필요하다고 판단되면 여러 차례 연속으로 조사를 수행할 수 있습니다.
  • screenwriter: 조사 결과를 바탕으로 줄거리 개요를 작성합니다.
  • file_writer: 결과로 생성된 영화의 제목을 지정하고 시퀀스 결과를 파일에 씁니다.

1. Cloud Shell 편집기에서 adk_multiagent_systems/workflow_agents 디렉터리로 이동합니다.

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

3. 이 에이전트 정의 파일을 읽어 봅니다. 하위 에이전트는 상위 에이전트에 할당되기 전에 정의되어야 하므로 대화 흐름 순서대로 파일을 읽으려면 파일의 하단에서 상단으로 에이전트를 읽으면 됩니다.

4. 또한 append_to_state라는 함수 도구도 있습니다. 이 함수를 사용하면 도구를 갖춘 에이전트가 상태의 사전 값에 콘텐츠를 추가할 수 있습니다. 특히 도구를 여러 번 호출하거나 LoopAgent의 여러 패스에서 작동할 수 있는 에이전트의 경우, 에이전트가 작동할 때마다 출력이 저장되므로 유용합니다.

5. Cloud Shell 터미널에서 웹 인터페이스를 실행하여 현재 버전의 에이전트를 사용해 봅니다. --reload_agents 인수를 사용하여 에이전트 변경사항에 따라 에이전트의 실시간 새로고침을 사용 설정합니다.

   cd ~/adk_multiagent_systems adk web --reload_agents 참고: 이전 adk web 세션을 종료하지 않은 경우 기본 포트(8000)가 차단될 수 있습니다. 이 경우 예를 들어 adk web --port 8001을 사용하여 새 포트로 개발 UI를 실행할 수 있습니다.

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

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

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

9. hello를 사용하여 대화를 시작합니다. 에이전트가 대답하는 데 잠시 시간이 걸릴 수 있지만, 영화 줄거리 생성을 시작할 수 있도록 역사적 인물을 입력하라는 요청이 표시됩니다.

10. 역사적 인물을 입력하라는 메시지가 표시되면 원하는 인물을 입력하거나 다음 예시 중 하나를 사용합니다.

    • 장중경 - 서기 2세기의 유명한 중국 의사
    • 에이다 러브레이스 - 초기 컴퓨터에 관한 연구로 유명한 영국의 수학자이자 작가
    • 마르쿠스 아우렐리우스 - 철학적 저술로 유명한 로마 황제

11. 이제 에이전트가 워크플로를 실행하면서 에이전트를 차례로 호출하고 ~/adk_multiagent_systems/movie_pitches 디렉터리에 줄거리 개요 파일을 작성합니다. 파일을 디스크에 쓰면 알려줍니다.

    에이전트가 파일을 생성했다는 보고가 표시되지 않거나 다른 인물로 시도해 보고 싶다면 오른쪽 상단에서 + 새로운 세션을 클릭하고 다시 시도할 수 있습니다.

12. Cloud Shell 편집기에서 에이전트의 출력을 확인합니다. (가로로 많이 스크롤하지 않고도 전체 텍스트를 보려면 Cloud Shell 편집기의 메뉴에서 보기 > 단어 줄바꿈을 사용 설정하는 것이 좋습니다.)

13. ADK 개발 UI에서 대화의 차례를 나타내는 에이전트 아이콘() 중 하나를 클릭하여 이벤트 뷰를 엽니다.

14. 이벤트 뷰는 이 세션에서 사용된 에이전트와 도구의 트리를 시각적으로 표현합니다. 전체 그래프를 보려면 이벤트 패널에서 스크롤해야 할 수 있습니다.

15. 그래프 뷰 외에도 이벤트의 요청 탭을 클릭하여 대화 기록을 포함해 이 에이전트가 요청의 일부로 수신한 정보를 확인할 수 있습니다.
16. 이벤트의 대답 탭을 클릭하여 에이전트가 반환한 내용을 확인할 수도 있습니다.

참고: 이 시스템은 흥미로운 결과를 생성할 수 있지만, 요청 사항이 이렇게 짧아도 된다거나 예를 추가하는 단계를 건너뛰어도 된다는 의미는 아닙니다. 각 에이전트에 더 엄격한 요청 사항과 예를 추가하는 추가 단계를 통해 시스템의 안정성을 크게 높일 수 있습니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. SequentialAgent로 멀티 에이전트 시스템 빌드 시작

작업 5. 반복 작업을 위한 LoopAgent 추가

LoopAgent는 정의된 순서로 하위 에이전트를 실행한 다음 사용자 입력을 위해 중단하지 않고 순서의 시작 부분에서 다시 시작합니다. 반복 횟수에 도달하거나 하위 에이전트 중 하나가 (일반적으로 기본 제공 exit_loop 도구를 호출하여) 루프 종료 호출을 수행할 때까지 루프를 반복합니다.

이 에이전트는 지속적인 개선, 모니터링 또는 순환 워크플로가 필요한 태스크에 유용합니다. 예를 들면 다음과 같습니다.

• 반복적인 개선: 에이전트 주기를 반복하여 문서 또는 계획을 지속적으로 개선합니다.
• 지속적인 모니터링: 에이전트 시퀀스를 사용하여 데이터 소스 또는 조건을 주기적으로 확인합니다.
• 토론 또는 협상: 에이전트 간의 반복적 논의를 시뮬레이션하여 더 나은 결과를 도출합니다.

스토리를 작성하는 동안 여러 차례의 조사와 반복을 허용하기 위해 영화 피치 에이전트에 LoopAgent를 추가합니다. 스크립트를 다듬는 것 외에도 사용자가 덜 구체적인 입력으로 시작할 수 있습니다. 예를 들어 특정 역사적 인물을 제안하는 대신 고대 의사에 관한 이야기를 원한다는 것만 알아도 됩니다. 이 경우 조사 및 작성 반복 루프를 통해 에이전트가 적합한 후보를 찾아내어 스토리를 작성할 수 있습니다.

수정된 에이전트는 다음과 같은 흐름으로 작동합니다.

• root_agent greeter는 동일하게 유지됩니다.
• film_concept_team SequentialAgent는 이제 다음과 같이 구성됩니다.
  • 시퀀스를 시작하는 writers_room LoopAgent. 다음과 같이 구성됩니다.
    • researcher: 이전과 동일합니다.
    • screenwriter: 이전과 유사합니다.
    • critic: 현재 초안에 대한 비판적인 의견을 제공하여 루프에서 다음 조사 및 개선 단계로 넘어가도록 동기를 부여합니다.
  • 루프가 종료되면 대화에 대한 제어권이 film_concept_team SequentialAgent로 다시 에스컬레이션되고, 이 에이전트는 제어권을 시퀀스의 다음 에이전트인 file_writer에게 넘깁니다. 이 에이전트는 이전과 마찬가지로 영화 제목을 지정하고 시퀀스 결과를 파일에 기록합니다.

변경하려면 다음 단계를 따르세요.

1. adk_multiagent_systems/workflow_agents/agent.py 파일에 아래의 도구 가져오기를 추가하여 에이전트가 원하는 경우 루프를 종료할 수 있도록 합니다.

   from google.adk.tools import exit_loop

2. 루프를 종료할 시점을 결정하려면 줄거리 개요가 준비되었는지 결정하는 critic 에이전트를 추가합니다. 다음 새 에이전트를 agent.py 파일의 # Agents 섹션 헤더 아래에 붙여넣습니다(기존 에이전트를 덮어쓰지 않음). 이 에이전트에는 exit_loop 도구가 포함되어 있으며, 이를 언제 사용하는지에 대한 요청 사항도 포함되어 있습니다.

   critic = Agent( name="critic", model=model_name, description="Reviews the outline so that it can be improved.", instruction=""" INSTRUCTIONS: Consider these questions about the PLOT_OUTLINE: - Does it meet a satisfying three-act cinematic structure? - Do the characters' struggles seem engaging? - Does it feel grounded in a real time period in history? - Does it sufficiently incorporate historical details from the RESEARCH? If the PLOT_OUTLINE does a good job with these questions, exit the writing loop with your 'exit_loop' tool. If significant improvements can be made, use the 'append_to_state' tool to add your feedback to the field 'CRITICAL_FEEDBACK'. Explain your decision and briefly summarize the feedback you have provided. PLOT_OUTLINE: { PLOT_OUTLINE? } RESEARCH: { research? } """, before_model_callback=log_query_to_model, after_model_callback=log_model_response, tools=[append_to_state, exit_loop] )

3. researcher, screenwriter, critic의 반복적인 루프를 만드는 writers_room이라는 새로운 LoopAgent를 만듭니다. 루프를 거칠 때마다 지금까지의 작업에 대한 비판적 검토로 끝나며, 이는 다음 단계 개선을 촉진합니다. 기존 film_concept_team SequentialAgent 위에 다음을 붙여넣습니다.

   writers_room = LoopAgent( name="writers_room", description="Iterates through research and writing to improve a movie plot outline.", sub_agents=[ researcher, screenwriter, critic ], max_iterations=5, )

4. LoopAgent 생성에는 max_iterations 파라미터가 포함되어 있습니다. 이 파라미터는 루프가 종료되기 전에 실행되는 횟수를 정의합니다. 다른 방법을 통해 루프를 중단할 계획이더라도 총 반복 횟수에 제한을 두는 것이 좋습니다.

5. film_concept_team SequentialAgent를 업데이트하여 researcher와 screenwriter를 방금 만든 writers_room LoopAgent로 바꿉니다. file_writer 에이전트는 시퀀스의 끝에 남아 있어야 합니다. 이제 film_concept_team은 다음과 같이 표시됩니다.

   film_concept_team = SequentialAgent( name="film_concept_team", description="Write a film plot outline and save it as a text file.", sub_agents=[ writers_room, file_writer ], )

6. ADK 개발 UI 탭으로 돌아가서 오른쪽 상단에 있는 + 새로운 세션 버튼을 클릭하여 새 세션을 시작합니다.

7. hello를 사용하여 새 대화를 시작합니다.

8. 역사적 인물을 선택하라는 메시지가 표시되면 관심 있는 인물을 선택합니다. 예를 들어 다음과 같습니다.

   • 대중을 위한 제품을 만든 산업 디자이너
   • 지도 제작자
   • 작물 수확량을 늘린 사람

9. 인물 유형을 선택하면 에이전트가 루프를 반복하여 영화 제목을 정하고 줄거리를 파일에 작성합니다.

10. Cloud Shell 편집기를 사용하여 생성된 파일을 검토합니다. 이 파일은 adk_multiagent_systems/movie_pitches 디렉터리에 저장되어 있습니다. (다시 한번 설명하자면, 가로로 많이 스크롤하지 않고도 전체 텍스트를 보려면 편집기의 메뉴에서 보기 > 단어 줄바꿈을 사용 설정하는 것이 좋습니다.)

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. 반복 작업을 위한 LoopAgent 추가

작업 6. ParallelAgent를 사용한 보고서 생성 시 '팬아웃 및 수집' 패턴 사용

ParallelAgent는 하위 에이전트의 동시 실행을 지원합니다. 각 하위 에이전트는 자체 브랜치에서 작동하며, 기본적으로 병렬 실행 중에 대화 기록이나 상태를 서로 직접 공유하지 않습니다.

이는 동시에 처리할 수 있는 독립적인 하위 태스크로 나눌 수 있는 태스크에 유용합니다. ParallelAgent를 사용하면 이러한 태스크의 전체 실행 시간을 크게 줄일 수 있습니다.

이 실습에서는 잠재적인 흥행 성적에 대한 조사와 캐스팅에 대한 초기 아이디어를 담은 보충 보고서를 추가하여 새 영화의 피치를 강화합니다.

수정된 에이전트는 다음과 같은 흐름으로 작동합니다.

• greeter는 동일합니다.
• film_concept_team SequentialAgent는 이제 다음과 같이 구성됩니다.
  • writers_room LoopAgent: 동일하게 유지되며 다음을 포함합니다.
    • researcher 에이전트
    • screenwriter 에이전트
    • critic 에이전트
  • 새로운 preproduction_team ParallelAgent: 다음과 같이 구성되어 동작합니다.
    • box_office_researcher 에이전트: 이전 박스오피스 데이터를 활용하여 이 영화의 잠재적인 흥행 성적에 대한 보고서를 생성합니다.
    • casting_agent 에이전트: 유사한 영화에 출연한 배우를 바탕으로 캐스팅에 대한 몇 가지 초기 아이디어를 생성합니다.
  • file_writer: 이전과 동일하게 유지되며, 시퀀스 결과를 파일에 기록합니다.

이 예시의 대부분은 인간 팀이 수행하는 창의적인 작업을 보여주지만, 이 워크플로는 복잡한 태스크 체인을 여러 하위 에이전트에 분산하여 복잡한 문서의 초안을 생성하는 방법을 나타냅니다. 이후 인간 팀원들이 이 초안을 편집하고 개선할 수 있습니다.

1. 다음 새 에이전트와 ParallelAgent를 workflow_agents/agent.py 파일의 # Agents 헤더 아래에 붙여넣습니다.

   box_office_researcher = Agent( name="box_office_researcher", model=model_name, description="Considers the box office potential of this film", instruction=""" PLOT_OUTLINE: { PLOT_OUTLINE? } INSTRUCTIONS: Write a report on the box office potential of a movie like that described in PLOT_OUTLINE based on the reported box office performance of other recent films. """, output_key="box_office_report" ) casting_agent = Agent( name="casting_agent", model=model_name, description="Generates casting ideas for this film", instruction=""" PLOT_OUTLINE: { PLOT_OUTLINE? } INSTRUCTIONS: Generate ideas for casting for the characters described in PLOT_OUTLINE by suggesting actors who have received positive feedback from critics and/or fans when they have played similar roles. """, output_key="casting_report" ) preproduction_team = ParallelAgent( name="preproduction_team", sub_agents=[ box_office_researcher, casting_agent ] )

2. 기존 film_concept_team 에이전트의 sub_agents 목록을 업데이트하여 writers_room과 file_writer 사이에 preproduction_team을 포함합니다.

   film_concept_team = SequentialAgent( name="film_concept_team", description="Write a film plot outline and save it as a text file.", sub_agents=[ writers_room, preproduction_team, file_writer ], )

3. file_writer의 instruction을 다음으로 업데이트합니다.

   INSTRUCTIONS: - Create a marketable, contemporary movie title suggestion for the movie described in the PLOT_OUTLINE. If a title has been suggested in PLOT_OUTLINE, you can use it, or replace it with a better one. - Use your 'write_file' tool to create a new txt file with the following arguments: - for a filename, use the movie title - Write to the 'movie_pitches' directory. - For the 'content' to write, include: - The PLOT_OUTLINE - The BOX_OFFICE_REPORT - The CASTING_REPORT PLOT_OUTLINE: { PLOT_OUTLINE? } BOX_OFFICE_REPORT: { box_office_report? } CASTING_REPORT: { casting_report? }

4. 파일을 저장합니다.

5. ADK 개발 UI의 오른쪽 상단에서 + 새로운 세션을 클릭합니다.

6. hello를 입력하여 대화를 시작합니다.

7. 메시지가 표시되면 관심 있는 새로운 인물 아이디어를 입력합니다. 예를 들어 다음과 같습니다.

   • Wi-Fi 기술을 발명한 여배우
   • 흥미로운 셰프
   • 세계 박람회 전시회의 핵심 인물들

8. 에이전트가 스토리 작성 및 보고서 생성을 완료하면 adk_multiagent_systems/movie_pitches 디렉터리에서 생성된 파일을 검사합니다. 프로세스의 일부가 실패하면 오른쪽 상단에서 + 새로운 세션을 클릭하고 다시 시도합니다.

커스텀 워크플로 에이전트

SequentialAgent, LoopAgent, ParallelAgent의 사전 정의된 워크플로 에이전트가 요구사항을 충족하기에 부족한 경우 CustomAgent를 사용하면 유연하게 새로운 워크플로 로직을 구현할 수 있습니다. 흐름 제어, 조건부 실행 또는 하위 에이전트 간 상태 관리를 위한 패턴을 정의할 수 있습니다. 이는 복잡한 워크플로, 스테이트풀(Stateful) 조정 또는 커스텀 비즈니스 로직을 프레임워크의 조정 레이어에 통합하는 데 유용합니다.

CustomAgent 생성은 이 실습의 범위를 벗어나지만 필요할 경우 사용할 수 있다는 점을 알아두면 좋습니다.

수고하셨습니다

이 실습에서는 여러 에이전트를 만들어 상위 에이전트와 하위 에이전트 관계로 서로 연결하고, 세션 상태에 추가하고, 에이전트 요청 사항에서 읽고, 워크플로 에이전트를 사용하여 에이전트 간에 대화를 직접 전달하는 방법을 알아보았습니다.

Google Cloud 교육 및 자격증

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

설명서 최종 업데이트: 2026년 2월 3일

실습 최종 테스트: 2026년 2월 3일

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