[Deep Agents] 3. SubAgent (서브에이전트)

[Deep Agents] 3. SubAgent (서브에이전트)

 

이번에는 DeepAgents에서 꽤 중요한 개념인 SubAgent를 알아봅니다.

에이전트를 만들다 보면 금방 이런 생각이 들게되는데

• 하나의 에이전트가 모든 일을 다 하게 해도 될까?
• 검색 전용, 분석 전용, 요약 전용처럼 역할을 나눌 수 없을까?
• 복잡한 작업을 분리해서 더 체계적으로 처리할 수 없을까?

바로 이런 문제를 해결하기 위해 등장하는 것이 SubAgent 입니다.

SubAgent란 무엇인가

SubAgent는 말 그대로 메인 에이전트가 필요할 때 호출해서 특정 역할을 맡기는 하위 에이전트다.

쉽게 말하면 이런 구조입니다.

• 메인 에이전트: 전체 흐름을 조정하는 관리자
• 서브 에이전트: 특정 전문 역할을 맡는 담당자

즉, 하나의 거대한 에이전트가 모든 걸 직접 처리하는 대신, 필요한 작업을 더 잘할 수 있는 작은 에이전트에게 맡기는 방식입니다.

 

왜 SubAgent가 필요한가

그냥 Tool만 여러 개 붙이면 되는 거 아닌가 라는 생각을 했습니다. 그런데 작업이 복잡해 질수록 Tool 로는 한계가 생깁니다.

예를 들어 메인 에이전트가 아래를 전부 직접 처리한다고 생각해보면

• 질문 이해
• 검색 여부 판단
• 검색어 생성
• 검색 결과 해석
• 정리 및 보고서 작성

이렇게 되면 에이전트 하나에 너무 많은 역할이 몰리게 됩니다.

그래서 더 나은 구조는

• 메인 에이전트는 전체 흐름을 조정
• 리서치 전용 SubAgent는 깊이 있는 조사 담당
• 필요하다면 다른 SubAgent는 분석, 요약, 코드 생성 담당

즉, SubAgent는 복잡한 작업을 역할별로 분리해서 더 안정적이고 명확하게 처리하기 위한 구조입니다.

 

예제코드

주석은 AI 가 달아주었습니다.

# 필요한 라이브러리 설치
# pip install deepagents tavily-python
# pip install langchain-openai
# pip install python-dotenv

import os  # 환경변수 접근용
from typing import Literal  # 타입 힌트에서 허용 문자열 범위를 제한할 때 사용
from tavily import TavilyClient  # Tavily 검색 API 클라이언트
from deepagents import create_deep_agent  # Deep Agent 생성 함수
from dotenv import load_dotenv  # .env 파일의 환경변수를 불러오는 함수
from langchain.chat_models import init_chat_model  # LangChain 채팅 모델 초기화 함수

# .env 파일에 저장된 환경변수 로드
load_dotenv()

# 환경변수에 저장된 TAVILY_API_KEY를 사용해 Tavily 클라이언트 생성
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])


def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """웹 검색을 수행하는 함수"""
    
    # Tavily 검색 API 호출
    return tavily_client.search(
        query,  # 검색어
        max_results=max_results,  # 최대 검색 결과 개수
        include_raw_content=include_raw_content,  # 원문 포함 여부
        topic=topic,  # 검색 주제: general / news / finance
    )


# 에이전트가 "전문 리서처"처럼 동작하도록 지시하는 시스템 프롬프트
research_instructions = """You are an expert researcher. Your job is to conduct thorough research and then write a polished report.

You have access to an internet search tool as your primary means of gathering information.

## `internet_search`

Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
"""

# 서브 에이전트 설정
research_subagent = {
    "name": "research-agent",  # 서브 에이전트 이름
    "description": "Used to research more in depth questions",  # 역할 설명
    "system_prompt": research_instructions,  # 이 서브 에이전트가 따를 시스템 프롬프트
    "tools": [internet_search],  # 사용할 수 있는 도구 목록
    "model": "openai:gpt-5.2",  # 이 서브 에이전트 전용 모델 (생략 시 메인 모델 사용)
}

# 서브 에이전트들을 리스트로 묶음
subagents = [research_subagent]

# 메인 에이전트 생성
agent = create_deep_agent(
    model=init_chat_model(
        model="openai:gpt-5.4",  # 메인 에이전트가 사용할 LLM
        max_retries=2,  # 네트워크 실패 시 재시도 횟수
        timeout=120,    # 요청 타임아웃(초)
    ),
    subagents=subagents  # 위에서 만든 서브 에이전트 연결
)

# 사용자 질문을 에이전트에 전달하여 실행
result = agent.invoke({
    "messages": [
        {"role": "user", "content": "What is n8n?"}  # 사용자 질문
    ]
})

# 마지막 응답 메시지의 내용을 출력
print(result["messages"][-1].content)

코드에서 보듯이 deepagent 정의시 subagents 를 연결하게되고 subagent 는 tool, skill 을 연결할 수 있게됩니다.

하나의 독립적인 역할을 가진 서브 에이전트를 정의하여 연결하게되어 여러 전문가를 고용하여 쓰는것과 동일합니다.

subagent 정의시 모델을 다르게 매핑이 가능해 역할에 대해 양질의 응답을 받을수 있는 모델을 사용할 수있습니다.

또한 메인 에이전트는 더 강한 추론 모델 사용하고 서브 에이전트는 비용이 낮거나 특정 작업에 적합한 모델 사용하게 할 수 있게됩니다.

 

실제 동작 흐름

1. 사용자 질문 입력
2. 메인 에이전트가 질문을 해석
3. 이 질문이 리서치가 필요한지 판단
4. 필요하면 research-agent 서브 에이전트 호출
5. research-agent가 internet_search 도구를 사용해 조사
6. 조사 결과를 바탕으로 응답 생성
7. 최종 결과를 사용자에게 반환

 

메인 에이전트가 모든 걸 직접 하는 것이 아니라 필요할 때 전문 역할을 가진 서브 에이전트에게 일을 위임하는 구조입니다.