Overview
supervisor 패턴은 중앙 supervisor agent가 전문화된 worker agent들을 조정하는 multi-agent 아키텍처입니다. 이 접근 방식은 작업에 다양한 유형의 전문 지식이 필요할 때 탁월합니다. 도메인 전반에 걸쳐 tool 선택을 관리하는 하나의 agent를 구축하는 대신, supervisor가 전체 워크플로우를 이해하고 조정하는 집중된 전문가들을 만듭니다. 이 튜토리얼에서는 현실적인 워크플로우를 통해 이러한 이점을 보여주는 개인 비서 시스템을 구축합니다. 시스템은 근본적으로 다른 책임을 가진 두 명의 전문가를 조정합니다:- 일정 관리, 가용성 확인 및 이벤트 관리를 처리하는 calendar agent.
- 커뮤니케이션 관리, 메시지 초안 작성 및 알림 전송을 관리하는 email agent.
supervisor를 사용하는 이유는?
Multi-agent 아키텍처를 사용하면 tools를 worker들에게 분할할 수 있으며, 각각 고유한 prompt나 지침을 가집니다. 모든 calendar 및 email API에 직접 액세스할 수 있는 agent를 고려해보세요: 많은 유사한 tool 중에서 선택하고, 각 API의 정확한 형식을 이해하며, 여러 도메인을 동시에 처리해야 합니다. 성능이 저하되면 관련 tool과 관련 prompt를 논리적 그룹으로 분리하는 것이 도움이 될 수 있습니다(부분적으로 반복적인 개선을 관리하기 위해).개념
다음 개념을 다룹니다:Setup
Installation
이 튜토리얼은langchain 패키지가 필요합니다:
LangSmith
agent 내부에서 무슨 일이 일어나는지 검사하려면 LangSmith를 설정하세요. 그런 다음 다음 환경 변수를 설정합니다:Components
LangChain의 통합 제품군에서 chat model을 선택해야 합니다:- OpenAI
- Anthropic
- Azure
- Google Gemini
- AWS Bedrock
1. Define tools
구조화된 입력이 필요한 tool을 정의하는 것부터 시작합니다. 실제 애플리케이션에서는 실제 API(Google Calendar, SendGrid 등)를 호출합니다. 이 튜토리얼에서는 패턴을 시연하기 위해 stub을 사용합니다.2. Create specialized sub-agents
다음으로 각 도메인을 처리하는 전문화된 sub-agent를 만듭니다.Create a calendar agent
calendar agent는 자연어 일정 요청을 이해하고 정확한 API 호출로 변환합니다. 날짜 파싱, 가용성 확인 및 이벤트 생성을 처리합니다.create_calendar_event를 호출하고, 자연어 확인을 반환합니다.
Create an email agent
email agent는 메시지 작성 및 전송을 처리합니다. 수신자 정보 추출, 적절한 제목 및 본문 텍스트 작성, 이메일 커뮤니케이션 관리에 중점을 둡니다.send_email을 호출하고, 확인을 반환합니다. 각 sub-agent는 도메인별 tool과 prompt를 사용하여 좁은 초점을 가지므로 특정 작업에서 탁월할 수 있습니다.
3. Wrap sub-agents as tools
이제 각 sub-agent를 supervisor가 호출할 수 있는 tool로 래핑합니다. 이것은 계층화된 시스템을 만드는 핵심 아키텍처 단계입니다. supervisor는 “create_calendar_event”와 같은 저수준 tool이 아닌 “schedule_event”와 같은 고수준 tool을 보게 됩니다.4. Create the supervisor agent
이제 sub-agent를 조정하는 supervisor를 만듭니다. supervisor는 고수준 tool만 보고 개별 API 수준이 아닌 도메인 수준에서 라우팅 결정을 내립니다.5. Use the supervisor
이제 여러 도메인에 걸친 조정이 필요한 복잡한 요청으로 전체 시스템을 테스트하세요:Example 1: Simple single-domain request
schedule_event를 호출하며, calendar agent가 날짜 파싱 및 이벤트 생성을 처리합니다.
각 chat model 호출에 대한 prompt 및 응답을 포함한 정보 흐름에 대한 완전한 투명성을 위해 위 실행에 대한 LangSmith trace를 확인하세요.
Example 2: Complex multi-domain request
schedule_event를 호출한 다음 알림을 위해 manage_email을 호출합니다. 각 sub-agent는 작업을 완료하고, supervisor는 두 결과를 일관된 응답으로 합성합니다.
개별 chat model prompt 및 응답을 포함한 위 실행에 대한 자세한 정보 흐름을 보려면 LangSmith trace를 참조하세요.
Complete working example
다음은 실행 가능한 스크립트로 모든 것을 함께 모은 것입니다:Understanding the architecture
시스템에는 세 개의 계층이 있습니다. 하단 계층에는 정확한 형식이 필요한 엄격한 API tool이 포함되어 있습니다. 중간 계층에는 자연어를 받아들이고, 구조화된 API 호출로 변환하고, 자연어 확인을 반환하는 sub-agent가 포함되어 있습니다. 상단 계층에는 고수준 기능으로 라우팅하고 결과를 합성하는 supervisor가 포함되어 있습니다. 이러한 관심사의 분리는 여러 가지 이점을 제공합니다: 각 계층은 집중된 책임을 가지며, 기존 도메인에 영향을 주지 않고 새 도메인을 추가할 수 있으며, 각 계층을 독립적으로 테스트하고 반복할 수 있습니다.6. Add human-in-the-loop review
민감한 작업에 대한 human-in-the-loop review를 통합하는 것이 신중할 수 있습니다. LangChain에는 tool 호출을 검토하기 위한 built-in middleware가 포함되어 있으며, 이 경우 sub-agent가 호출하는 tool입니다. 두 sub-agent 모두에 human-in-the-loop review를 추가해 보겠습니다:create_calendar_event및send_emailtool을 중단하도록 구성하여 모든 response types(approve,edit,reject)를 허용합니다- 최상위 agent에만 checkpointer를 추가합니다. 이는 실행을 일시 중지하고 재개하는 데 필요합니다.
Command를 사용하여 ID를 참조하여 각 interrupt에 대한 결정을 지정할 수 있습니다. 자세한 내용은 human-in-the-loop guide를 참조하세요. 시연 목적으로 여기서는 calendar 이벤트를 수락하지만 발신 이메일의 제목을 편집합니다:
7. Advanced: Control information flow
기본적으로 sub-agent는 supervisor로부터 요청 문자열만 받습니다. 대화 기록이나 사용자 기본 설정과 같은 추가 컨텍스트를 전달하고 싶을 수 있습니다.Pass additional conversational context to sub-agents
LangSmith trace의 chat model call에서 sub agent가 받은 전체 컨텍스트를 볼 수 있습니다.
Control what supervisor receives
supervisor로 다시 흐르는 정보를 사용자 정의할 수도 있습니다:8. Key takeaways
supervisor 패턴은 각 계층이 명확한 책임을 가진 추상화 계층을 만듭니다. supervisor 시스템을 설계할 때 명확한 도메인 경계로 시작하고 각 sub-agent에 집중된 tool과 prompt를 제공하세요. supervisor를 위한 명확한 tool 설명을 작성하고, 통합 전에 각 계층을 독립적으로 테스트하며, 특정 요구 사항에 따라 정보 흐름을 제어하세요.supervisor 패턴을 사용해야 하는 경우여러 개의 뚜렷한 도메인(calendar, email, CRM, database)이 있고, 각 도메인에 여러 tool이나 복잡한 로직이 있으며, 중앙 집중식 워크플로우 제어를 원하고, sub-agent가 사용자와 직접 대화할 필요가 없을 때 supervisor 패턴을 사용하세요.몇 개의 tool만 있는 간단한 경우에는 단일 agent를 사용하세요. agent가 사용자와 대화해야 하는 경우 대신 handoffs를 사용하세요. agent 간의 peer-to-peer 협업의 경우 다른 multi-agent 패턴을 고려하세요.
Next steps
agent 간 대화를 위한 handoffs에 대해 알아보고, 정보 흐름을 미세 조정하기 위한 context engineering을 탐색하고, 다양한 패턴을 비교하기 위해 multi-agent overview를 읽고, multi-agent 시스템을 디버그하고 모니터링하기 위해 LangSmith를 사용하세요.Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.