Deep Agents로 멀티 에이전트 애플리케이션 구축하기

TMT

https://www.blog.langchain.com/building-multi-agent-applications-with-deep-agents/

복잡한 작업을 전문화된 에이전트로 분해하는 것은 강력한 AI 시스템을 구축하는 가장 효과적인 접근 방식 중 하나입니다. 이 글에서는 Deep Agents로 멀티 에이전트 시스템을 구축하는 방법을 보여드립니다.

복잡한 작업을 전문화된 에이전트로 분해하는 것은 강력한 AI 시스템을 구축하는 가장 효과적인 접근 방식 중 하나입니다.

Deep Agents는 다음 두 가지 1급 프리미티브로 이를 손쉽게 지원합니다:

  • subagents: 고립된 에이전트로 위임
  • skills: 점진적 기능 공개

이 글에서는 Deep Agents로 멀티 에이전트 시스템을 구축하는 방법을 보여드립니다.

Subagents: 전문화되고 고립된 작업자

Subagents는 에이전트 엔지니어링의 근본적인 문제인 context bloat를 해결합니다. 이는 에이전트가 작업을 진행하면서 컨텍스트 윈도우가 거의 가득 차는 상황을 말합니다.

왜 중요할까요? 컨텍스트 윈도우가 채워질수록 모델이 작업 완료에 어려움을 겪는다는 Chroma의 컨텍스트 부패(context rot)에 관한 훌륭한 연구가 있습니다. HumanLayer 팀은 이 높은 컨텍스트 영역을 “dumb zone”이라고 부릅니다. Subagents는 메인 에이전트로부터 컨텍스트를 분리함으로써 빠르게 dumb zone에 진입하는 것을 방지합니다.

에이전트가 수십 건의 웹 검색이나 파일 읽기를 수행하면, 중간 결과로 컨텍스트 윈도우가 가득 찹니다. Subagents는 자체 컨텍스트 윈도우로 작업을 분리합니다. 따라서 Subagent가 최종 답을 내기 전 많은 탐색적 작업을 하더라도, 메인 에이전트는 그 결과만 받고, 그 결과를 만드는 데 사용된 20개의 도구 호출은 받지 않습니다.

다음은 기본 Subagents 아키텍처의 개요입니다:

Image

Subagents를 사용하는 경우

  • Context Preservation: 여러 단계가 필요한 작업은 메인 에이전트의 컨텍스트를 어지럽힐 수 있습니다(예: 코드베이스 탐색).
  • Specialization: 도메인 특화 지침이나 도구를 사용합니다. 서로 다른 팀이 개발한 Subagent가 다양한 분야에 특화될 수 있습니다.
  • Multi-Model: Subagent는 메인 에이전트와 다른 모델을 사용할 수 있습니다. 예를 들어, 낮은 지연을 위해 더 작은 모델을 선택합니다.
  • Parallelization: Subagent는 동시에 실행되어 결과를 메인 에이전트로 반환할 수 있습니다. 이는 지연을 줄입니다.

Subagents 만들기

사전을 정의하고 이를 create_deep_agent()⁠에 전달해 Subagent를 생성합니다:

from deepagents import create_deep_agent

research_subagent = {
    "name": "research-agent",
    "description": "Used to research more in depth questions",
    "system_prompt": "You are a great researcher",
    "tools": [internet_search],
    "model": "openai:gpt-4o",  # Optional: override main agent model
}

agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    subagents=[research_subagent]
)

구성 상세는 subagents 문서를 참조하세요.

범용 Subagent

Deep Agents에는 메인 에이전트의 기능을 반영한 기본 제공 general-purpose⁠ Subagent가 포함되어 있습니다. 동일한 시스템 프롬프트, 도구, 모델을 갖습니다. 이는 특수화된 동작 없이 컨텍스트를 분리하기에 적합합니다.

예시: 메인 에이전트가 10번의 웹 검색을 수행하여 컨텍스트를 채우는 대신, task(name="general-purpose", task="Research quantum computing trends")로 general-purpose Subagent에 위임할 수 있습니다. Subagent는 내부적으로 모든 검색을 수행하고 요약만 반환합니다.

Subagents에 대한 모범 사례

명확한 설명을 작성하세요. 메인 에이전트는 어떤 Subagent를 호출할지 결정할 때 설명을 사용합니다:

✅ 좋음: “재무 데이터를 분석하고 신뢰도 점수를 포함한 투자 인사이트를 생성하세요” ❌ 나쁨: “금융 관련 업무를 하세요”

시스템 프롬프트를 상세히 유지하세요. 도구 사용 지침과 출력 형식 요구사항을 포함합니다:

research_subagent = {
    "name": "research-agent",
    "description": "웹 검색을 사용해 심층 연구를 수행하고 발견 내용을 종합합니다",
    "system_prompt": """당신은 꼼꼼한 연구자입니다. 당신의 업무는 다음과 같습니다:

    1. 연구 질문을 검색 가능한 쿼리로 분해합니다
    2. internet_search를 사용해 관련 정보를 찾습니다
    3. 발견한 내용을 포괄적이면서도 간결한 요약으로 종합합니다
    4. 주장을 할 때는 출처를 인용합니다

    출력 형식:
    - 요약 (2-3개 단락)
    - 핵심 발견 사항 (불릿 포인트)
    - 출처 (URL 포함)

    깨끗한 컨텍스트 유지를 위해 응답을 500단어 이내로 유지하세요.""",
    "tools": [internet_search],
}

도구 집합을 최소화하세요. Subagent에 필요한 도구만 제공하세요:

# ✅ 좋음: 집중된 도구 집합
email_agent = {
    "name": "email-sender",
    # 이메일 관련 도구만
    "tools": [send_email, validate_email],

}

# ❌ 나쁨: 너무 많은 도구
email_agent = {
    "name": "email-sender",
    # 포커스되지 않은
    "tools": [send_email, web_search, database_query, file_upload],
}

스킬 사용: 기능의 점진적 공개

Skills는 다른 패턴, 즉 점진적 공개를 제공합니다. 에이전트에 수십 개의 도구를 한꺼번에 주는 대신, SKILL.md 파일에 전문화된 기능을 정의합니다. 에이전트는 스킬 이름과 설명을 보고, 필요할 때만 전체 지시사항을 읽습니다.

Image

스킬 설명은 컨텍스트 윈도우에 미리 로드됩니다. 스킬 본문은 에이전트가 설명과 이전 컨텍스트를 바탕으로 스킬이 필요하다고 판단할 때에만 로드됩니다.

스킬 설정

Skills는 agentskills.io 사양을 사용합니다. 구조는 다음과 같습니다:

.deepagents/skills/
├── deploy/SKILL.md
└── review-pr/SKILL.md

각 SKILL.md 파일은 메타데이터가 담긴 YAML 프런트매터와 본문을 가집니다:

---
name: deploy
description: 프로덕션에 배포
version: 1.0.0  # 선택 사항
tags: [deployment, production]  # 선택 사항
---

# 프로덕션 배포

사용자가 배포를 요청하면 다음 단계를 따르세요:

1. 테스트 실행: ‎⁠`npm test⁠`
2. 애플리케이션 빌드: ‎⁠`npm run build⁠`
3. 프로덕션 배포: ‎⁠`npm run deploy:prod⁠`
4. 배포 검증: 헬스 엔드포인트 확인

프로덕션에 배포하기 전에 항상 사용자에게 확인을 받으세요.

에이전트에 스킬 추가하기

create_deep_agent⁠의 skills⁠ 인자를 사용해 파일시스템에서 스킬을 로드합니다:

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    backend=FilesystemBackend(root_dir="/"),
    skills=[".deepagents/skills"],
)

이제 에이전트가 스킬을 인식합니다. 상세 지침이 필요할 때, 전체 SKILL.md 파일을 읽습니다.

다른 백엔드(예: StateBackend 또는 StoreBackend)를 사용하고, 이후 files⁠ 명세로 에이전트를 호출할 수도 있습니다:

from deepagents.middleware.filesystem import FileData

# StateBackend가 디폴트
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-20250514",
    skills=["/skills/"],
)

skill_content = """
---
name: deploy
...
"""

# 스킬과 가상 파일을 함께 사용하여 에이전트를 호출
result = agent.invoke({
    "messages": [HumanMessage(content="최신 Python 릴리스를 조사하세요")],
    "files": {
        "/skills/web-research/SKILL.md": FileData(
            content=skill_content.split("\n"),
            created_at="2024-01-01T00:00:00Z",
            modified_at="2024-01-01T00:00:00Z",
        ),
    },
})

올바른 패턴 선택

다음은 안내를 위한 빠른 질문 세트입니다:

다음 상황에 필요할 때…사용하세요…둘 다?
복잡하고 다단계의 작업을 위임컨텍스트 분리를 위한 Subagents
절차나 지침을 재사용점진적 공개를 위한 Skills
특정 작업에 전문화된 도구 제공집중된 도구 세트를 갖춘 Subagents✅
여러 에이전트 간에 기능 공유Skills(단순 파일)✅
큰 도구 세트로 작업토큰 팽창을 피하기 위한 Skills

둘 중 하나를 선택할 필요가 없습니다.
많은 시스템은 둘 다를 사용합니다. Skills는 절차를 정의하고; Subagents는 복잡한 다단계 작업을 실행합니다. Subagents는 컨텍스트 윈도우를 효과적으로 관리하기 위해 Skills를 사용할 수 있습니다!

다음 스텝

Deep Agents의 멀티 에이전트 패턴에 대해 더 알아보려면 다음을 확인하세요:

핵심 인사이트: 멀티 에이전트 패턴은 복잡할 필요가 없습니다. 적절한 추상화(배관을 위한 미들웨어, 호출을 위한 도구 호출)를 사용하면, 강력하고 정교한 시스템으로 구성할 수 있는 단순한 빌딩 블록이 됩니다.

컨텍스트 관리에는 Subagents로 시작하고, 점진적 공개를 위해 Skills를 추가한 뒤, 그 위에 구축하세요.

Edit this page
Index

On this Page

Subagents: 전문화되고 고립된 작업자
Subagents를 사용하는 경우
Subagents 만들기
범용 Subagent
Subagents에 대한 모범 사례
스킬 사용: 기능의 점진적 공개
스킬 설정
에이전트에 스킬 추가하기
올바른 패턴 선택
다음 스텝