🌟 개요
최근 팀 스터디에서 진행 중인 프로젝트를 Deep Agent 기반으로 전환하기로 했다.
프로젝트는 광고 컨셉과 아이템, 광고주 정보를 입력하면 AI가 최적의 인플루언서를 추천해주는 서비스인데, 지금까지는 하나의 AI 에이전트가 모든 걸 처리하는 구조로 만들어져 있었다. 이걸 여러 개의 전문 에이전트로 나누고, 인플루언서 탐색 → 추천 근거 생성 → 사용자 확인 → 리포트 생성까지 단계별로 처리하는 구조로 바꾸자는 것이었다.
Deep Agent에 대한 개념을 잘 몰라서, 프로젝트를 Deep Agent로 전환하기 전에 이 개념을 제대로 이해하고자 글을 쓰게 되었다.
🌟 현재 프로젝트 구조: ReAct Agent
Deep Agent를 이해하려면, 지금 구조가 어떤 방식인지부터 알아야 한다.
현재 프로젝트는 ReAct Agent 방식으로 만들어져 있다.
✨ ReAct란?
Reasoning(추론) + Acting(행동)의 약자이다.
말 그대로 에이전트가 생각하고 → 행동하고 → 결과를 보고 → 다시 생각하는 과정을 반복한다.
구조 자체는 단순하다. 하나의 LLM이 루프를 돌면서 스스로 판단하고, 도구를 선택해서 호출하고, 결과를 보고 다음 행동을 결정한다.
💥 문제: 도구가 너무 많다
현재 프로젝트에는 도구가 20개나 된다.
| 분류 | 도구 이름 | 설명 |
|---|---|---|
| DB 검색 (3개) | search_by_category | 카테고리로 검색 |
search_by_platform | 플랫폼으로 검색 | |
search_by_followers | 팔로워 범위로 검색 | |
| 상세 조회 (1개) | get_influencer_details | 인플루언서 전체 프로필 조회 |
| 분석 (1개) | calculate_match_score | 매칭 점수 계산 |
| 지식 그래프 (7개) | find_similar_influcners | 유사 인플루언서 탐색 |
get_influencer_ad_history | 광고 이력 조회 | |
find_best_match_for_ad | 광고에 최적 인플루언서 탐색 | |
analyze_advertiser_pattern | 광고주 선호 패턴 분석 | |
get_all_advertisers | 광고주 목록 | |
get_active_advertisements | 진행 중인 광고 목록 | |
query_knowledge_graph | 직접 Cypher 쿼리 | |
| 의미 검색 (5개) | semantic_search_influencers | 자연어로 인플루언서 검색 |
query_kg_natural_language | 자연어로 지식 그래프 질의 | |
analyze_match_history | 과거 매칭 성공 사례 분석 | |
search_similar_campaigns | 유사 캠페인 검색 | |
search_collected_ad_data | 스크래핑된 광고 데이터 검색 | |
| 평판 조사 (1개) | search_influencer_reputation | 웹 검색으로 논란/이슈 확인 |
| 광고 이력 (2개) | get_ad_history | 인플루언서 광고 게시물 이력 |
get_ad_brand_summary | 브랜드별 광고 횟수 요약 |
이 20개를 하나의 LLM이 전부 파악하고, 어떤 걸 언제 써야 할지 스스로 판단해야 한다.
도구가 2~3개일 때는 괜찮지만, 20개가 되면 LLM이 헷갈리기 시작한다. 비슷한 도구 중 어떤 걸 써야 할지 잘못 고르거나, 불필요한 도구까지 호출하거나, 중요한 도구를 아예 빠뜨리기도 한다.
⚠️ ReAct의 한계
결국 ReAct의 핵심 문제는 하나의 에이전트가 판단, 검색, 분석, 평판 조사까지 혼자 다 한다는 것이다.
작업이 복잡해질수록 판단 실수가 늘어나고, 결과 품질이 들쭉날쭉해진다. 검색 결과가 별로여도 스스로 재시도하지 않고 그냥 넘어가버리기도 한다.
이게 Deep Agent로 전환을 고려하게 된 직접적인 이유이다.
🌟 Deep Agent란?
공식적으로 정해진 정의는 없지만, 현업에서 Deep Agent라고 하면 보통 이런 특성을 가진 에이전트 시스템을 의미한다.
하나의 에이전트가 혼자 다 하지 않고, 여러 전문 에이전트가 역할을 나눠서 협업하는 구조
✨ ReAct와의 차이
"Deep"이라는 단어에는 두 가지 의미가 담겨 있다.
-
넓이(Width) - 여러 전문 에이전트로 역할 분리
-
깊이(Depth) - 하나의 작업을 여러 단계로 깊게 처리
실제 Deep Agent는 이 두 가지를 동시에 가진다.
✨ 한눈에 비교
| ReAct (현재) | Deep Agent | |
|---|---|---|
| 에이전트 수 | 1개 | 오케스트레이터 + 여러 서브 에이전트 |
| 계획 수립 | 즉흥적 (프롬프트로 강제) | 계획 에이전트가 먼저 전략 수립 |
| 자기 검토 | 도구 호출 수준 (얕음) | 전략 수준 (깊음) |
| 메모리 | 세션 내 단기 기억만 | 장기 기억, 과거 결과 학습 가능 |
| 실패 대응 | 그냥 다음 단계로 넘어감 | 실패 감지 후 전략 수정 |
✨ 회사 조직으로 비유하면
ReAct는 만능 아르바이트생 한 명이 혼자 다 하는 구조이다.
검색도 하고, 분석도 하고, 평판 조사도 하고, 최종 추천까지 전부 혼자 처리한다.
Deep Agent는 팀장 + 전문 팀원들이 협업하는 구조이다.
팀장(오케스트레이터)이 전체 작업을 보고 "너는 검색, 너는 분석, 너는 평판 조사"라고 지시하고, 각 팀원(서브 에이전트)은 자기 전문 영역에만 집중한다.
도구가 20개로 늘어난 지금 프로젝트에서는, 만능 아르바이트생 한 명에게 맡기는 것보다 팀을 꾸리는 게 훨씬 안정적이다.
🌟 오케스트레이터란?
Deep Agent의 구조를 이해하려면 오케스트레이터가 뭔지 먼저 알아야 한다.
✨ 오케스트라 비유
오케스트라를 떠올려 보자.
에이전트에서 오케스트레이터는 정확히 이 지휘자 역할이다.
✨ 오케스트레이터가 하는 일 vs. 하지 않는 일
- 하는 일: 머리 쓰는 일
- 작업 분해 (예: "이걸 3단계로 나눠야겠다")
- 우선순위 결정 (예: "검색을 먼저 해야 분석이 가능하다")
- 결과 평가 (예: "점수가 낮네, 재검색 지시해야겠다")
- 결과 취합 (예: "3개 결과 합쳐서 최종 답변 만들기")
- 예외 처리 (예: "검색 에이전트가 실패했으니, 플랜 B로")
- 하지 않는 일: 손발 쓰는 일
- DB 직접 검색
- 점수 계산
- 웹 크롤링
- 파일 읽기/쓰기
✨ 오케스트레이터가 없는 구조도 있다
오케스트레이터가 반드시 있어야 하는 건 아니다. 작업 순서가 항상 고정되어 있다면, 에이전트들이 컨베이어 벨트처럼 순서대로 결과를 넘기는 방식도 가능하다.
다만 이 방식은 예상치 못한 상황이 생겼을 때 유연하게 대응하기 어렵다.
오케스트레이터가 있으면 "결과가 별로니까 전략을 바꾸자"는 판단을 할 수 있는데, 없으면 그 판단을 누가 하는지 애매해진다.
✨ 오케스트레이터 = 플래너?
거의 같다. 같은 역할을 하는 에이전트를 부르는 방식이 다를 뿐이다.
- 계획 수립 측면을 강조할 때: "플래너 에이전트"
- 전체 지휘 측면을 강조할 때: "오케스트레이터"
현업에서도 두 용어를 혼용해서 쓴다.
🌟 서브 에이전트란?
오케스트레이터가 지휘자라면, 서브 에이전트는 각 파트를 연주하는 연주자이다.
✨ 서브 에이전트는 자동으로 생기지 않는다
중요한 점이 있다. 서브 에이전트는 개발자가 직접 정의해야 생긴다. Deep Agent 구조를 선택한다고 해서 자동으로 만들어지는 게 아니다.
개발자가 각 서브 에이전트마다 직접 정의해야 하는 것들은 다음과 같다.
- 역할: "너는 인플루언서 검색만 담당해"
- 사용할 도구:
search_by_category,semantic_search_influencers만 접근 가능 - 시스템 프롬프트: "검색 결과는 반드시 JSON 형식으로 반환해"
- 입출력 형식: 광고 컨셉 받아서 → 인플루언서 목록 반환
🤔 도구를 제한하는 이유
서브 에이전트마다 쓸 수 있는 도구를 의도적으로 제한한다. 전체 도구를 다 주지 않는 것이다.
이유는 단순하다.
사람도 마찬가지다. 한 명한테 모든 업무를 몰아주면 실수가 늘어나지만, 담당 업무를 나눠주면 훨씬 잘한다.
🪄 이 프로젝트에 적용하면
현재 도구 20개를 서브 에이전트별로 나누면 이렇게 된다.
오케스트레이터는 도구 없이 지시만 한다.
🌟 프롬프트가 전부다
구조를 아무리 잘 잡아도 결국 에이전트는 LLM이다. LLM은 프롬프트대로 행동한다.
오케스트레이터를 만들든, 서브 에이전트를 만들든, 각 에이전트에게 반드시 지침을 줘야 한다.
"너는 어떤 역할을 하는 에이전트야"
"어떤 상황에서 어떻게 행동해야 해"
"결과는 항상 이런 형식으로 반환해"이게 바로 시스템 프롬프트이다.
🚨 프롬프트가 애매하면 생기는 일
- 나쁜 예시
에이전트 입장에서 이 지침은 너무 애매하다. "계획을 세운다"는 게 구체적으로 뭘 해야 하는 건지 알 수 없다."너는 계획을 세우는 에이전트야"
결국 에이전트는 이렇게 행동한다.
필요하지 않은 서브 에이전트까지 전부 호출하다 보니, 단순한 요청인데도 응답이 한참 걸린다. 구조만 복잡해지고 결과는 오히려 ReAct보다 나빠지는 상황이 된다."계획이 뭔지 모르겠으니 일단 다 해보자" → 검색 에이전트 호출 → 분석 에이전트 호출 → 평판 에이전트 호출 → 지식 그래프 에이전트 호출
-
좋은 예시
"""너는 인플루언서 매칭 작업을 지휘하는 오케스트레이터야. 1. 광고 입력을 받으면 먼저 카테고리를 추론해. 2. 검색이 필요한지, 평판 조사가 필요한지 판단해. 3. 검색 결과가 3개 미만이면 반드시 재검색을 지시해. 4. 모든 결과가 모이면 취합해서 최종 추천을 생성해. """프롬프트에 역할, 판단 기준, 예외 상황까지 구체적으로 적어두면 오케스트레이터가 흔들리지 않는다.
광고 입력 수신 → "뷰티 카테고리겠네, 검색 에이전트 호출하자." → 검색 결과 5명 반환됨 → "충분하니까 평판 조사로 넘어가자" → 평판 에이전트 호출 → 결과 취합 → 최종 추천 출력필요한 서브 에이전트만 골라서 호출하고, 결과가 부족하면 재검색을 지시하는 등 상황에 맞게 판단한다. 프롬프트가 명확할수록 오케스트레이터가 예측 가능하게 움직인다.
🚨 역효과가 실제로 난다
Deep Agent 구조를 도입했는데 오히려 성능이 나빠지는 경우가 있다. 대부분 프롬프트 문제이다.
흔한 실패 케이스는 다음과 같다.
- 오케스트레이터가 모든 서브 에이전트를 무조건 다 호출
- 필요 없는 평판 조사까지 실행
- ReAct보다 응답이 훨씬 느려짐
- 오케스트레이터가 서브 에이전트 결과를 무시하고 혼자 결론냄
- 검색 결과가 반영 안 된 추천 출력
- 검색 결과가 0개인데 다음 단계로 그냥 넘어감
- 아무도 없는 TOP 3 추천
🧐 그래서 현업에서는
"에이전트 개발의 70%는 프롬프트 엔지니어링"이라는 말이 있을 정도다.
코드 구조보다 각 에이전트에게 무엇을, 어떻게, 어떤 조건에서 해야 하는지를 명확하게 지시하는 것이 시스템 전체 성능을 결정한다.
Deep Agent로 전환할 때 가장 공들여야 할 부분이 바로 여기이다.
🌟 우리 프로젝트에 적용하면?
🧐 현재 흐름
지금은 하나의 에이전트가 입력을 받아서 모든 걸 처리한다.
🧐 Deep Agent 적용 후 흐름
스터디에서 논의된 방향은 작업을 4단계로 나누는 것이다.
🛠️ 도구 배분
각 서브 에이전트는 자기 역할에 필요한 도구만 가진다.오케스트레이터는 도구 없이 지시와 취합만 담당한다.
🧐 달라지는 점
- 현재
- 에이전트 1개가 도구 20개를 혼자 판단함
- 중간 결과를 사용자가 확인할 방법 없음
- 결과 품질이 들쭉날쭉함
- 전환 후
- 각 에이전트가 도구 5~7개에만 집중함
- 중간 결과를 사용자가 확인하고 승인함
- 단계별로 검증이 가능해짐
🌟 전환하려면 뭐가 필요한가?
✨ 라이브러리
현재 프로젝트는 LangChain 기반이다. Deep Agent 구조로 전환하려면 LangGraph를 추가해야 한다.
uv pip install langgraph
uv pip install langgraph-supervisor-
langgraph
멀티 에이전트 구조를 공식 지원하는 라이브러리이다. 서브 에이전트 생성, 에이전트 간 흐름 정의, 조건부 분기(결과가 나쁘면 재시도 등)가 가능하다. -
langgraph-supervisor
오케스트레이터 패턴을 쉽게 구현할 수 있도록 LangGraph가 공식으로 제공하는 패키지이다. 오케스트레이터를 직접 처음부터 만들면 복잡하기 때문에 이걸 쓰면 훨씬 간단하다.
LangGraph는 LangChain 위에서 동작하기 때문에 기존 코드 대부분은 그대로 재활용할 수 있다.
🧐 바꿔야 하는 것 vs. 건드릴 필요 없는 것
- 바꿔야 하는 것
agent_factory.py: 단일 에이전트 → 여러 서브 에이전트로 분리agent_service.py: LangGraph 그래프 실행 방식으로 변경
- 건드릴 필요 없는 것
tools/: 도구 파일들 자체는 그대로 재사용domain/: Influencer 등 도메인 엔티티adapters/persistence/: DB 관련 코드adapters/inbound/: Streamlit UI
구조 변경이 주된 작업이고, 비즈니스 로직은 손댈 필요가 없다.
✨ Langfuse
에이전트가 1개일 때는 어디서 문제가 생겼는지 대략 파악이 쉽다.
그런데 에이전트가 여러 개로 늘어나면 내부에서 무슨 일이 벌어졌는지 보기가 훨씬 어려워진다.
- 오케스트레이터가 어떤 판단을 내렸는지?
- 어떤 서브 에이전트를 호출했는지?
- 어디서 시간이 오래 걸렸는지?
- 어느 단계에서 실패했는지?
- 토큰을 얼마나 썼는지?
이걸 눈으로 볼 수 있게 해주는 도구가 Langfuse이다. 에이전트 실행 흐름을 대시보드로 시각화해주고, 각 단계의 프롬프트 전문과 응답, 소요 시간, 비용까지 기록해준다.
Deep Agent로 전환하면 구조가 복잡해지는 만큼, Langfuse 같은 모니터링 도구는 사실상 필수가 된다.
🌟 마치며
처음에 Deep Agent로 프로젝트 구조를 바꾼다고 했을 때, 현재 프로젝트 구조는 어떻게 구성되어 있고, Deep Agent 구조로 바꾼다는 게 무슨 의미인지 잘 몰랐다. 에이전트는 들어봤어도 Deep Agent는 생소한 개념이었다.
그래서 코드를 건드리기 전에 먼저 개념을 정리해 봤다.
핵심만 추리면 이렇다.
아직 실제 전환은 시작 전이다. 개념을 알고 들어가는 것과 모르고 들어가는 건 다르다고 생각해서 먼저 정리해 봤는데, 막상 구현하다 보면 또 새로 배우는 것들이 생길 것 같다.
