멀티 에이전트 시스템 오케스트레이션 🤖🤝🤖

이 노트북에서는 멀티 에이전트 웹 브라우저를 만듭니다. 웹을 이용해 문제를 풀기 위해 여러 에이전트가 협력하는 에이전틱 시스템이죠. 간단한 계층 구조입니다.

              +----------------+
              | Manager agent  |
              +----------------+
                       |
        _______________|______________
       |                              |
Code Interpreter            +------------------+
    tool                    | Web Search agent |
                            +------------------+
                               |            |
                        Web Search tool     |
                                   Visit webpage tool

출처: 공식문서 - Orchestrate a multi-agent system

시스템 설정

필수 의존성을 설치하는 줄을 실행합니다.

!pip install 'smolagents[toolkit]' --upgrade -q

Inference Providers를 호출하려면 HF에 로그인합니다.

from huggingface_hub import login

login()

⚡️ 우리 에이전트는 HF의 Inference API를 쓰는 InferenceClientModel 클래스로 Qwen/Qwen3-Next-80B-A3B-Thinking 모델로 구동됩니다. Inference API는 어떤 오픈소스 모델이든 빠르고 쉽게 실행하게 해줍니다.

[!TIP] Inference Providers는 서버리스 추론 파트너가 구동하는 수백 개 모델에 접근을 제공합니다. 지원 프로바이더 목록은 여기에서 확인하세요.

model_id = "Qwen/Qwen3-Next-80B-A3B-Thinking"

🔍 웹 검색 도구 만들기

웹 브라우징에 네이티브 WebSearchTool을 Google 검색 대용으로 쓸 수 있어요. 하지만 WebSearchTool이 찾은 페이지를 들여다볼 수도 있어야 합니다. 라이브러리의 내장 VisitWebpageTool을 가져올 수도 있지만, 어떻게 만드는지 보기 위해 직접 만들어 보겠습니다. markdownify로 VisitWebpageTool을 처음부터 만듭니다.

import re
import requests
from markdownify import markdownify
from requests.exceptions import RequestException
from smolagents import tool

@tool
def visit_webpage(url: str) -> str:
    """Visits a webpage at the given URL and returns its content as a markdown string.

    Args:
        url: The URL of the webpage to visit.

    Returns:
        The content of the webpage converted to Markdown, or an error message if the request fails.
    """
    try:
        # Send a GET request to the URL
        response = requests.get(url)
        response.raise_for_status()  # Raise an exception for bad status codes

        # Convert the HTML content to Markdown
        markdown_content = markdownify(response.text).strip()

        # Remove multiple line breaks
        markdown_content = re.sub(r"\n{3,}", "\n\n", markdown_content)

        return markdown_content

    except RequestException as e:
        return f"Error fetching the webpage: {str(e)}"
    except Exception as e:
        return f"An unexpected error occurred: {str(e)}"

이제 도구를 초기화하고 테스트합니다!

print(visit_webpage("https://en.wikipedia.org/wiki/Hugging_Face")[:500])

멀티 에이전트 시스템 만들기 🤖🤝🤖

search와 visit_webpage 도구를 모두 갖췄으니 웹 에이전트를 만드는 데 쓸 수 있어요. 어떤 구성을 고를까요?

웹 브라우징은 병렬 도구 호출이 필요 없는 단일 타임라인 작업이므로 JSON 도구 호출이 잘 맞아요. 그래서 ToolCallingAgent를 선택합니다.
웹 검색은 정답을 찾기 전에 여러 페이지를 탐색해야 할 수 있으니 max_steps를 10으로 늘립니다.

from smolagents import (
    CodeAgent,
    ToolCallingAgent,
    InferenceClientModel,
    WebSearchTool,
)

model = InferenceClientModel(model_id=model_id)

web_agent = ToolCallingAgent(
    tools=[WebSearchTool(), visit_webpage],
    model=model,
    max_steps=10,
    name="web_search_agent",
    description="Runs web searches for you.",
)

이 에이전트에 name과 description 속성을 줬습니다. 이 속성은 이 에이전트가 매니저 에이전트에 의해 호출 가능하도록 만드는 필수 속성이에요. 그다음 매니저 에이전트를 만들고, 초기화 시 managed_agents 인자에 관리되는 에이전트를 전달합니다. 이 에이전트가 계획과 사고를 맡으므로 고급 추론이 유리해 CodeAgent가 잘 맞습니다.

💡 이 오케스트레이션은 더 많은 에이전트로 쉽게 확장할 수 있어요. 하나는 코드 실행, 하나는 웹 검색, 하나는 파일 로딩을 맡는 식입니다.

멀티 에이전트 시스템 오케스트레이션 🤖🤝🤖