hdsp-jupyter-extension 2.0.11__py3-none-any.whl → 2.0.13__py3-none-any.whl

agent_server/langchain/MULTI_AGENT_ARCHITECTURE.md

@@ -0,0 +1,1114 @@
+# Multi-Agent Architecture Design
+
+## 목차
+1. [개요](#개요)
+2. [AS-IS vs TO-BE 비교](#as-is-vs-to-be-비교)
+3. [TO-BE 아키텍처](#to-be-아키텍처)
+4. [에이전트 정의](#에이전트-정의)
+5. [구현 전략](#구현-전략)
+6. [개발 계획](#개발-계획)
+7. [참고 자료](#참고-자료)
+
+---
+
+## 개요
+
+### 배경
+현재 HDSP Agent는 단일 에이전트가 모든 도구를 관리하는 모놀리식 구조입니다. 이는 다음과 같은 한계가 있습니다:
+
+- **Context 비대화**: 모든 도구 설명과 대화 기록이 누적되어 context window 압박
+- **프롬프트 복잡도**: 단일 프롬프트에 모든 도구 사용 지침 포함 필요
+- **유지보수 어려움**: 새 기능 추가 시 전체 프롬프트 수정 필요
+- **오류 전파**: 한 작업의 오류가 전체 세션에 영향
+
+### 목표
+LangChain의 **Subagent 패턴**과 **Deep Agents 라이브러리**를 벤치마킹하여 멀티 에이전트 아키텍처로 전환합니다.
+
+> **참고**: Deep Agents 라이브러리는 직접 설치하지 않고, 핵심 패턴을 벤치마킹하여 자체 구현합니다.
+> 이를 통해 프로젝트 의존성을 최소화하고 HDSP 특화 기능을 유연하게 확장할 수 있습니다.
+
+**핵심 원칙**:
+1. **Supervisor Pattern**: Planner가 메인 에이전트로서 서브에이전트들을 도구처럼 호출
+2. **Context Isolation**: 각 서브에이전트는 독립적인 context에서 실행
+3. **Stateless Subagents**: 서브에이전트는 상태를 유지하지 않음 (메인 에이전트가 관리)
+4. **Human-in-the-Loop 유지**: 코드 실행 승인 등 기존 HITL 기능 유지
+5. **Simple Agent Structure**: 최소한의 에이전트로 복잡도 관리 (Planner + 2개 서브에이전트)
+
+---
+
+## AS-IS vs TO-BE 비교
+
+### AS-IS: 단일 에이전트 구조
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Single Agent                             │
+│                                                              │
+│  System Prompt (모든 도구 지침 포함)                          │
+│  ┌─────────────────────────────────────────────────────────┐ │
+│  │ - 데이터 분석 가이드                                      │ │
+│  │ - 파일 작업 지침                                          │ │
+│  │ - 리소스 확인 규칙                                        │ │
+│  │ - Todo 관리 규칙                                          │ │
+│  │ - 출력 형식 지침                                          │ │
+│  └─────────────────────────────────────────────────────────┘ │
+│                                                              │
+│  Tools (모든 도구가 직접 연결)                                │
+│  ┌──────────┬──────────┬──────────┬──────────┬──────────┐   │
+│  │jupyter   │file      │search    │shell     │resource  │   │
+│  │_cell     │_tools    │_tools    │_tools    │_tools    │   │
+│  └──────────┴──────────┴──────────┴──────────┴──────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**문제점**:
+- 프롬프트 크기: ~2000+ tokens
+- 도구 선택 복잡도: 8+ 도구 중 선택
+- Context 누적으로 후반부 성능 저하
+
+### TO-BE: 멀티 에이전트 구조 (간소화)
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        Planner Agent (Supervisor)                    │
+│                                                                      │
+│  System Prompt (계획 및 조율 전문)                                    │
+│  ┌───────────────────────────────────────────────────────────────┐  │
+│  │ - 작업 분해 및 계획 수립                                         │  │
+│  │ - 서브에이전트 선택 및 위임                                       │  │
+│  │ - 리소스 확인 (check_resource_tool 직접 호출)                    │  │
+│  │ - 결과 종합 및 요약                                              │  │
+│  └───────────────────────────────────────────────────────────────┘  │
+│                                                                      │
+│  Tools                                                               │
+│  ┌────────────┬────────────┬───────────────────────────────────┐   │
+│  │write_todos │check_      │      task(agent_name, description) │   │
+│  │            │resource    │                                    │   │
+│  └────────────┴────────────┴───────────────────────────────────┘   │
+│                                    │                                 │
+│                    ┌───────────────┴───────────────┐                │
+│                    ▼                               ▼                │
+│        ┌───────────────────┐           ┌───────────────────┐       │
+│        │ Python Developer  │           │ Researcher Agent  │       │
+│        │                   │           │ (READ-ONLY 검색)   │       │
+│        │ • jupyter_cell    │           │ • search_nb       │       │
+│        │ • markdown        │           │ • diagnostics     │       │
+│        │ • write_file      │           │                   │       │
+│        │ • multiedit_file  │           │ ─────────────────── │       │
+│        │ ─────────────────── │           │ [공통 도구]        │       │
+│        │ [공통 도구]        │           │ • read_file       │       │
+│        │ • read_file       │           │ • exec_cmd        │       │
+│        │ • exec_cmd        │           │ • qdrant_search   │       │
+│        │                   │           └───────────────────┘       │
+│        │ ─────────────────── │                                       │
+│        │ [Nested Subagent] │                                       │
+│        │ • task(athena_    │                                       │
+│        │   query)          │                                       │
+│        └─────────┬─────────┘                                       │
+│                  │                                                  │
+│                  ▼                                                  │
+│        ┌───────────────────┐                                       │
+│        │ Athena Query Agent│                                       │
+│        │ (SQL 생성 전문)    │                                       │
+│        │                   │                                       │
+│        │ • qdrant_search   │                                       │
+│        │   (DB/테이블 메타) │                                       │
+│        │                   │                                       │
+│        │ Returns: SQL query│                                       │
+│        └───────────────────┘                                       │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+**변경사항 (v1.3)**:
+- ❌ Resource Manager 제거: `check_resource_tool`을 Planner가 직접 사용
+- 🔄 FileSystem Agent → **Researcher Agent**: RAG, 웹 검색 등 확장을 위한 범용 이름
+- ➕ **Athena Query Agent** 추가: Qdrant RAG 기반 Athena SQL 생성
+- 🔗 **Nested Subagent 패턴**: Python Developer → Athena Query Agent 호출 가능
+
+**장점**:
+- 프롬프트 크기: Planner ~600 tokens, 각 서브에이전트 ~300 tokens
+- 도구 선택: 각 에이전트는 2-5개 도구만 관리
+- Context 격리로 성능 일관성 유지
+- **자연스러운 워크플로우**: Python Developer가 필요시 Athena Query Agent 직접 호출
+
+---
+
+## TO-BE 아키텍처
+
+### 전체 구조도
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           Client (Jupyter Extension)                     │
+└─────────────────────────────────┬───────────────────────────────────────┘
+                                  │ SSE
+┌─────────────────────────────────▼───────────────────────────────────────┐
+│                           Agent Server (FastAPI)                         │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    Router (langchain_agent.py)                   │    │
+│  │  • stream_agent() / resume_agent()                               │    │
+│  │  • Multi-agent orchestration                                     │    │
+│  └─────────────────────────────────┬───────────────────────────────┘    │
+│                                    │                                     │
+│  ┌─────────────────────────────────▼───────────────────────────────┐    │
+│  │                    Agent Factory (agent_factory.py)              │    │
+│  │  • create_planner_agent()                                        │    │
+│  │  • create_subagent(agent_type)                                   │    │
+│  │  • SubAgentMiddleware (deepagents 패턴 벤치마킹)                  │    │
+│  └─────────────────────────────────┬───────────────────────────────┘    │
+│                                    │                                     │
+│           ┌────────────────────────┼────────────────────────┐           │
+│           │                        │                        │           │
+│  ┌────────▼────────┐    ┌──────────▼──────────┐   ┌────────▼────────┐  │
+│  │  Planner Agent  │    │ Subagent Registry   │   │  State Manager  │  │
+│  │  (Supervisor)   │    │                     │   │                 │  │
+│  │                 │    │ • python_developer  │   │ • Thread state  │  │
+│  │ • Plan creation │    │ • researcher        │   │ • Todos         │  │
+│  │ • Task dispatch │    │ • (extensible)      │   │ • Checkpoints   │  │
+│  │ • Resource check│    │                     │   │                 │  │
+│  │ • Summarization │    │                     │   │                 │  │
+│  └────────┬────────┘    └─────────────────────┘   └─────────────────┘  │
+│           │                                                              │
+│           │ task(agent_name, description)                               │
+│           ▼                                                              │
+│  ┌──────────────────────────────────────────────────────────────────┐   │
+│  │                    Subagent Execution Layer                       │   │
+│  │                                                                   │   │
+│  │  ┌─────────────────────┐           ┌─────────────────────┐       │   │
+│  │  │   Python Developer  │           │   Researcher Agent  │       │   │
+│  │  │                     │           │                     │       │   │
+│  │  │ Tools:              │           │ Tools:              │       │   │
+│  │  │ • jupyter_cell      │           │ • read_file         │       │   │
+│  │  │ • markdown          │           │ • write_file        │       │   │
+│  │  │                     │           │ • search_nb         │       │   │
+│  │  │                     │           │ • exec_cmd          │       │   │
+│  │  │                     │           │ • (future: RAG)     │       │   │
+│  │  └─────────────────────┘           └─────────────────────┘       │   │
+│  └──────────────────────────────────────────────────────────────────┘   │
+│                                                                          │
+│  ┌──────────────────────────────────────────────────────────────────┐   │
+│  │                         Middleware Layer                          │   │
+│  │  • SubAgentMiddleware (서브에이전트 호출 처리)                     │   │
+│  │  • HumanInTheLoopMiddleware (HITL 유지)                          │   │
+│  │  • TodoListMiddleware (Planner에만 적용)                          │   │
+│  │  • SummarizationMiddleware (컨텍스트 관리)                        │   │
+│  └──────────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### 데이터 흐름
+
+```
+User: "타이타닉 데이터를 분석하고 생존율 예측 모델을 만들어줘"
+                │
+                ▼
+┌───────────────────────────────────────────────────────────────────┐
+│ Planner Agent                                                      │
+│                                                                    │
+│ 1. 작업 분해:                                                       │
+│    write_todos([                                                   │
+│      {content: "데이터 로드 및 기본 정보 확인", status: "pending"}, │
+│      {content: "데이터 정제 (결측치 처리)", status: "pending"},     │
+│      {content: "EDA 수행", status: "pending"},                     │
+│      {content: "예측 모델 학습", status: "pending"},               │
+│      {content: "작업 요약 및 다음단계 제시", status: "pending"}     │
+│    ])                                                              │
+│                                                                    │
+│ 2. 리소스 확인 (Planner 직접 호출):                                  │
+│    check_resource_tool(files=["titanic.csv"])                      │
+│    → "titanic.csv: 60KB, 891 rows"                                 │
+│                                                                    │
+│ 3. 서브에이전트 호출:                                               │
+│    task("python_developer",                                        │
+│         "titanic.csv를 로드하고 df.info(), df.head() 출력")        │
+│                     │                                              │
+└─────────────────────┼──────────────────────────────────────────────┘
+                      ▼
+        ┌─────────────────────────┐
+        │   Python Developer      │
+        │                         │
+        │   jupyter_cell_tool(    │
+        │     code="""            │
+        │     import pandas as pd │
+        │     df = pd.read_csv    │
+        │       ('titanic.csv')   │
+        │     print(df.info())    │
+        │     df.head()           │
+        │     """                 │
+        │   )                     │
+        │                         │
+        │   → [HITL: 사용자 승인] │
+        │   → execution_result    │
+        └────────────┬────────────┘
+                     │
+                     ▼
+┌───────────────────────────────────────────────────────────────────┐
+│ Planner Agent                                                      │
+│                                                                    │
+│ 4. 파일 검색 필요 시:                                               │
+│    task("researcher", "workspace에서 CSV 파일 목록 찾기")          │
+│                     │                                              │
+└─────────────────────┼──────────────────────────────────────────────┘
+                      ▼
+        ┌─────────────────────────┐
+        │   Researcher Agent      │
+        │                         │
+        │   execute_command_tool( │
+        │     command="find . -name│
+        │     '*.csv' -type f"    │
+        │   )                     │
+        │                         │
+        │   → "./data/titanic.csv"│
+        │   → "./data/test.csv"   │
+        └────────────┬────────────┘
+                     │
+                     ▼
+┌───────────────────────────────────────────────────────────────────┐
+│ Planner Agent                                                      │
+│                                                                    │
+│ 5. 진행 상황 업데이트:                                              │
+│    write_todos([                                                   │
+│      {content: "데이터 로드...", status: "completed"},             │
+│      {content: "데이터 정제...", status: "in_progress"},           │
+│      ...                                                           │
+│    ])                                                              │
+│                                                                    │
+│ 6. 계속 진행...                                                     │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 에이전트 정의
+
+### 1. Planner Agent (Supervisor)
+
+**역할**: 작업 계획, 리소스 확인, 서브에이전트 조율, 결과 종합
+
+**System Prompt**:
+```
+You are a data science project planner and coordinator. Respond in Korean.
+
+# Your Role
+- Analyze user requests and break them into executable tasks
+- Check resources BEFORE delegating data operations (use check_resource_tool)
+- Delegate tasks to specialized subagents
+- Track progress using write_todos
+- Synthesize results and provide summaries
+
+# Available Subagents
+- python_developer: Python code execution in Jupyter notebooks (analysis, visualization, ML)
+  - Can internally call athena_query for Athena SQL generation
+- researcher: File/workspace search, RAG queries, information gathering
+
+Note: athena_query is NOT directly callable. Use python_developer for Athena data tasks.
+
+# Workflow
+1. Understand the request
+2. Create a todo list with write_todos (always end with "작업 요약 및 다음단계 제시")
+3. Check resources with check_resource_tool (for data loading tasks)
+4. Delegate each task to the appropriate subagent using task()
+5. Update todos as tasks complete
+6. Provide final summary with next_items JSON
+
+# Rules
+- ALWAYS create todos before delegating
+- Check file sizes with check_resource_tool BEFORE python_developer loads data
+- Delegate ONE task at a time
+- Wait for subagent result before next delegation
+- Mark todos complete only after receiving subagent result
+```
+
+**Tools**:
+| Tool | Description |
+|------|-------------|
+| `write_todos` | 작업 목록 관리 (TodoListMiddleware) |
+| `check_resource_tool` | 파일 크기/메모리 확인 (리소스 체크) |
+| `task` | 서브에이전트 호출 (SubAgentMiddleware) |
+
+---
+
+### 2. Python Developer Agent
+
+**역할**: Python 코드 작성, 파일 수정, Jupyter 노트북 실행, **Athena 쿼리 실행**
+
+**System Prompt**:
+```
+You are an expert Python developer specializing in data science and Jupyter notebooks.
+
+# Your Capabilities
+- Write and execute Python code for data analysis
+- Read and modify Python/config files
+- Create visualizations with matplotlib, seaborn, plotly
+- Build machine learning models
+- Add markdown documentation to notebooks
+- Execute Athena queries (via athena_query subagent)
+
+# Athena Query Workflow
+When you need to query AWS Athena data:
+1. Call task("athena_query", "description of what data you need")
+2. Receive the SQL query string from athena_query agent
+3. Execute the query using pyathena/boto3 in jupyter_cell_tool
+
+Example:
+  sql = task("athena_query", "최근 7일간 일별 활성 사용자 수 조회")
+  # Then execute with pyathena:
+  jupyter_cell_tool(code="df = pd.read_sql(sql, athena_conn)")
+
+# Guidelines
+- Use English labels for plots (required for Korean text rendering issues)
+- Handle large datasets efficiently (use chunking, sampling when needed)
+- Always include error handling for file operations
+- Use multiedit_file_tool for multiple changes in a single file
+- For Athena queries, ALWAYS use task("athena_query", ...) first
+
+# Output Format
+Execute code using jupyter_cell_tool, add explanations using markdown_tool.
+Return concise results back to the Planner.
+```
+
+**Tools**:
+| Tool | Description |
+|------|-------------|
+| `jupyter_cell_tool` | Python 코드 실행 (HITL) |
+| `markdown_tool` | 마크다운 셀 추가 |
+| `read_file_tool` | 파일 읽기 (공통) |
+| `write_file_tool` | 파일 쓰기 (HITL) |
+| `multiedit_file_tool` | 다중 편집 (HITL) |
+| `execute_command_tool` | 쉘 명령 실행 (HITL, 공통) |
+| `task` | **Nested subagent 호출** (athena_query만 허용) |
+
+---
+
+### 3. Researcher Agent
+
+**역할**: 정보 검색, 파일 탐색, 코드 분석, 향후 RAG 통합
+
+> **확장성**: 이 에이전트는 현재 읽기 전용 검색/탐색을 담당하며, 향후 RAG (Retrieval-Augmented Generation), 
+> 웹 검색, 문서 검색 등 다양한 검색 기능을 추가할 수 있도록 범용적으로 설계되었습니다.
+
+**System Prompt**:
+```
+You are a research and information specialist for data science workspaces.
+
+# Your Capabilities
+- Read files and analyze content (READ-ONLY)
+- Search notebook cells for code patterns
+- Execute shell commands for file discovery (find, grep, ls)
+- Navigate workspace structure
+- Analyze code for potential issues using LSP diagnostics
+- (Future) RAG-based document search
+- (Future) Web search for documentation
+
+# Guidelines
+- Validate paths to prevent directory traversal
+- Use appropriate encoding for different file types
+- Summarize large file contents instead of full output
+- Use find/grep commands for efficient file search
+- Return concise, actionable results
+
+# Important
+- You are READ-ONLY: Do NOT modify files (use python_developer for that)
+- Focus on gathering and synthesizing information
+```
+
+**Tools**:
+| Tool | Description |
+|------|-------------|
+| `read_file_tool` | 파일 읽기 (공통) |
+| `search_notebook_cells_tool` | 노트북 셀 검색 |
+| `execute_command_tool` | 쉘 명령 실행 (HITL) - 검색용 |
+| `diagnostics_tool` | LSP 진단 (코드 오류 확인) |
+| `qdrant_search_tool` | Qdrant RAG 검색 (공통) |
+| *(Future)* `web_search_tool` | 웹 검색 |
+
+---
+
+### 4. Athena Query Agent
+
+**역할**: Qdrant RAG를 활용한 Athena SQL 쿼리 생성
+
+> **호출 방식**: Planner가 직접 호출하지 않고, **Python Developer가 필요시 호출**합니다.
+> 이는 SQL 생성 → Python 실행이라는 자연스러운 워크플로우를 지원합니다.
+
+**System Prompt**:
+```
+You are an AWS Athena SQL expert. Generate optimized Athena queries based on user requirements.
+
+# Your Capabilities
+- Search database/table metadata using Qdrant RAG
+- Generate Athena-compatible SQL queries (Presto/Trino syntax)
+- Optimize queries for performance (partitioning, predicate pushdown)
+
+# Workflow
+1. Receive query requirement from Python Developer
+2. Search Qdrant for relevant database/table metadata
+3. Generate optimized Athena SQL query
+4. Return ONLY the SQL query string (no explanation needed)
+
+# Guidelines
+- Always use fully qualified table names: database.table
+- Include appropriate WHERE clauses for partitioned columns
+- Use LIMIT for exploratory queries
+- Handle NULL values appropriately
+- Use CAST for type conversions
+
+# Output Format
+Return ONLY the SQL query as a string. Python Developer will execute it.
+Example: "SELECT * FROM my_database.my_table WHERE partition_date = '2024-01-01' LIMIT 100"
+```
+
+**Tools**:
+| Tool | Description |
+|------|-------------|
+| `qdrant_search_tool` | Qdrant에서 DB/테이블 메타데이터 검색 |
+
+**Qdrant RAG 데이터 구조** (예시):
+```json
+{
+  "database": "analytics",
+  "table": "user_events",
+  "columns": [
+    {"name": "user_id", "type": "string", "description": "사용자 고유 ID"},
+    {"name": "event_type", "type": "string", "description": "이벤트 유형"},
+    {"name": "event_time", "type": "timestamp", "description": "이벤트 발생 시간"},
+    {"name": "partition_date", "type": "string", "partition": true, "description": "파티션 날짜 (YYYY-MM-DD)"}
+  ],
+  "description": "사용자 행동 이벤트 로그 테이블",
+  "sample_queries": [
+    "SELECT user_id, COUNT(*) FROM analytics.user_events GROUP BY user_id"
+  ]
+}
+```
+
+---
+
+### Nested Subagent 호출 패턴
+
+Python Developer가 Athena Query Agent를 호출하는 워크플로우:
+
+```
+┌───────────────────────────────────────────────────────────────────┐
+│ Python Developer Agent                                            │
+│                                                                   │
+│ User Task: "최근 7일간 일별 활성 사용자 수를 조회해줘"               │
+│                                                                   │
+│ 1. Athena 쿼리 필요 인식                                           │
+│    task("athena_query",                                           │
+│         "최근 7일간 일별 활성 사용자 수 조회 쿼리 생성")            │
+│                     │                                             │
+└─────────────────────┼─────────────────────────────────────────────┘
+                      ▼
+        ┌─────────────────────────────┐
+        │   Athena Query Agent        │
+        │                             │
+        │   1. qdrant_search_tool(    │
+        │        "사용자 활성 이벤트"   │
+        │      )                      │
+        │      → analytics.user_events│
+        │                             │
+        │   2. Generate SQL:          │
+        │   """                       │
+        │   SELECT                    │
+        │     partition_date,         │
+        │     COUNT(DISTINCT user_id) │
+        │       AS dau                │
+        │   FROM analytics.user_events│
+        │   WHERE partition_date >=   │
+        │     DATE_FORMAT(            │
+        │       DATE_ADD('day', -7,   │
+        │         CURRENT_DATE), '%Y-%m-%d')│
+        │   GROUP BY partition_date   │
+        │   ORDER BY partition_date   │
+        │   """                       │
+        │                             │
+        │   → Return SQL string       │
+        └────────────┬────────────────┘
+                     │
+                     ▼
+┌───────────────────────────────────────────────────────────────────┐
+│ Python Developer Agent                                            │
+│                                                                   │
+│ 2. SQL 수신 후 Python 코드로 실행                                   │
+│    jupyter_cell_tool(code="""                                     │
+│    import boto3                                                   │
+│    import pandas as pd                                            │
+│    from pyathena import connect                                   │
+│                                                                   │
+│    conn = connect(s3_staging_dir='s3://my-bucket/athena-results/',│
+│                   region_name='ap-northeast-2')                   │
+│                                                                   │
+│    query = '''                                                    │
+│    SELECT partition_date, COUNT(DISTINCT user_id) AS dau          │
+│    FROM analytics.user_events                                     │
+│    WHERE partition_date >= DATE_FORMAT(...)                       │
+│    GROUP BY partition_date                                        │
+│    ORDER BY partition_date                                        │
+│    '''                                                            │
+│                                                                   │
+│    df = pd.read_sql(query, conn)                                  │
+│    df                                                             │
+│    """)                                                           │
+│                                                                   │
+│ 3. 결과 반환 to Planner                                            │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 구현 전략
+
+### Phase 1: Deep Agents 패턴 벤치마킹 및 프로토타입
+
+**목표**: Deep Agents의 SubAgentMiddleware 구현 방식을 벤치마킹하여 자체 구현
+
+> **참고**: Deep Agents 라이브러리를 직접 설치하지 않고 핵심 패턴만 차용합니다.
+> GitHub: https://github.com/langchain-ai/deepagents
+
+**Deep Agents 핵심 패턴 (벤치마킹)**:
+```python
+# Deep Agents의 SubAgentMiddleware 핵심 패턴:
+# 1. 서브에이전트를 task(name, description) 도구로 호출
+# 2. 각 서브에이전트는 독립적인 context에서 실행
+# 3. 결과는 문자열로 요약되어 메인 에이전트에 반환
+# 4. HITL interrupt는 메인 에이전트로 bubbling up
+```
+
+**작업**:
+1. Deep Agents GitHub 소스 코드 분석 (SubAgentMiddleware, task tool)
+2. SubAgentMiddleware 핵심 로직을 자체 구현
+3. 프로토타입 구현 (Planner + 2개 서브에이전트)
+
+**핵심 코드 구조** (자체 구현):
+
+```python
+# agent_factory.py (신규)
+
+from typing import Dict, Any, List
+from langchain.agents import create_agent
+from langchain.tools import tool
+
+# 공통 도구 정의 (모듈화)
+SHARED_TOOLS = {
+    "read_file_tool",       # 파일 읽기 - 모든 에이전트 공통
+    "execute_command_tool", # 쉘 명령 - Python Developer, Researcher 공통
+    "qdrant_search_tool",   # Qdrant RAG - Researcher, Athena Query 공통
+}
+
+# 서브에이전트 정의 (3-agent 구조 + Nested 호출)
+SUBAGENT_CONFIGS = {
+    "python_developer": {
+        "name": "python_developer",
+        "description": "Execute Python code, read/write files, run shell commands. Can call athena_query agent.",
+        "system_prompt": PYTHON_DEVELOPER_PROMPT,
+        "tools": ["jupyter_cell_tool", "markdown_tool", 
+                  "read_file_tool", "write_file_tool", "multiedit_file_tool",
+                  "execute_command_tool"],
+        # Nested subagent 호출 허용
+        "can_call_subagents": ["athena_query"],  # Athena Query Agent만 호출 가능
+    },
+    "researcher": {
+        "name": "researcher",
+        "description": "Search files, explore workspace, Qdrant RAG search (READ-ONLY).",
+        "system_prompt": RESEARCHER_PROMPT,
+        "tools": ["read_file_tool", "search_notebook_cells_tool", 
+                  "execute_command_tool", "diagnostics_tool",
+                  "qdrant_search_tool"],  # Qdrant RAG 검색 가능
+    },
+    "athena_query": {
+        "name": "athena_query",
+        "description": "Generate Athena SQL queries using Qdrant RAG for DB/table metadata",
+        "system_prompt": ATHENA_QUERY_PROMPT,
+        "tools": ["qdrant_search_tool"],
+        # Python Developer에 의해서만 호출됨 (Planner 직접 호출 X)
+        "callable_by": ["python_developer"],
+    },
+}
+
+def create_subagent(agent_type: str, llm_config: Dict[str, Any]):
+    """서브에이전트 생성 (deepagents 패턴 벤치마킹)"""
+    config = SUBAGENT_CONFIGS[agent_type]
+    llm = create_llm(llm_config)
+    tools = [get_tool(name) for name in config["tools"]]
+
+    return create_agent(
+        model=llm,
+        tools=tools,
+        prompt=config["system_prompt"],
+        # 서브에이전트는 미들웨어 최소화
+        middleware=[HumanInTheLoopMiddleware(...)],  # HITL 유지
+    )
+
+@tool
+def task(agent_name: str, description: str) -> str:
+    """
+    Delegate a task to a specialized subagent.
+
+    Available agents:
+    - python_developer: Python code execution for data analysis, visualization, ML
+    - researcher: File search, workspace exploration, code pattern search
+
+    Args:
+        agent_name: Name of the subagent to invoke
+        description: Detailed task description for the subagent
+
+    Returns:
+        Result from the subagent execution
+    """
+    if agent_name not in SUBAGENT_CONFIGS:
+        return f"Error: Unknown agent '{agent_name}'. Available: {list(SUBAGENT_CONFIGS.keys())}"
+
+    # 서브에이전트 생성 (또는 캐시에서 가져오기)
+    subagent = create_subagent(agent_name, current_llm_config)
+
+    # 서브에이전트 실행
+    result = subagent.invoke({
+        "messages": [{"role": "user", "content": description}]
+    })
+
+    # 결과 추출 및 반환
+    return result["messages"][-1].content
+
+def create_planner_agent(llm_config: Dict[str, Any], ...):
+    """Planner (Supervisor) 에이전트 생성"""
+    llm = create_llm(llm_config)
+
+    tools = [
+        check_resource_tool,  # 리소스 확인 (Planner 직접 사용)
+        task,  # 서브에이전트 호출 도구
+    ]
+
+    middleware = [
+        TodoListMiddleware(...),  # Todo 관리
+        SubAgentMiddleware(...),  # 서브에이전트 미들웨어
+        SummarizationMiddleware(...),
+        ModelCallLimitMiddleware(run_limit=50),  # 멀티에이전트는 호출 횟수 증가
+    ]
+
+    return create_agent(
+        model=llm,
+        tools=tools,
+        prompt=PLANNER_SYSTEM_PROMPT,
+        middleware=middleware,
+        checkpointer=checkpointer,
+    )
+```
+
+### Phase 2: HITL 통합
+
+**목표**: 서브에이전트의 HITL 도구 호출이 Planner를 통해 클라이언트까지 전파되도록 구현
+
+**과제**:
+- 서브에이전트의 interrupt가 Planner로 bubbling up
+- 클라이언트 UI에서 어떤 서브에이전트의 요청인지 표시
+- resume 시 올바른 서브에이전트로 전달
+
+**구현 방안**:
+
+```python
+# 서브에이전트 실행 시 interrupt 처리
+@tool
+def task(agent_name: str, description: str, runtime: ToolRuntime) -> Command:
+    """서브에이전트 호출 (interrupt 전파 지원)"""
+    subagent = create_subagent(agent_name, current_llm_config)
+
+    try:
+        # 스트리밍 실행으로 interrupt 감지
+        for step in subagent.stream({"messages": [{"role": "user", "content": description}]}):
+            if "__interrupt__" in step:
+                # interrupt를 Planner 레벨로 전파
+                return Command(
+                    interrupt={
+                        "subagent": agent_name,
+                        "original_interrupt": step["__interrupt__"],
+                    }
+                )
+
+        # 정상 완료
+        result = step["messages"][-1].content
+        return result
+
+    except Exception as e:
+        return f"Error in {agent_name}: {str(e)}"
+```
+
+### Phase 3: UI 업데이트
+
+**목표**: 멀티에이전트 상태를 UI에 표시
+
+**변경사항**:
+- 현재 활성 에이전트 표시 (Planner / Python Developer / ...)
+- 서브에이전트 실행 상태 표시
+- HITL 요청 시 서브에이전트 컨텍스트 표시
+
+```typescript
+// AgentPanel.tsx 변경
+interface AgentStatus {
+  activeAgent: 'planner' | 'python_developer' | 'filesystem' | 'resource_manager';
+  currentTask?: string;
+}
+
+// SSE 이벤트 추가
+// event: agent_switch
+// data: { agent: "python_developer", task: "Load titanic.csv" }
+```
+
+### Phase 4: 최적화 및 확장
+
+**목표**: 성능 최적화 및 추가 서브에이전트
+
+**작업**:
+1. 서브에이전트 인스턴스 캐싱
+2. 병렬 서브에이전트 실행 지원 (선택적)
+3. 추가 서브에이전트 (필요 시):
+   - `code_reviewer`: 코드 리뷰 및 리팩토링 제안
+   - `documentation`: 문서화 전문
+
+---
+
+## 개발 계획
+
+### Sprint 1: 기반 구축
+
+| Task | Description | Priority |
+|------|-------------|----------|
+| 1.1 | Deep Agents GitHub 소스 코드 분석 (벤치마킹) | P0 |
+| 1.2 | SubAgentMiddleware 핵심 패턴 추출 | P0 |
+| 1.3 | `agent_factory.py` 모듈 생성 | P0 |
+| 1.4 | `task` 도구 기본 구현 | P0 |
+| 1.5 | Planner 에이전트 프롬프트 작성 | P1 |
+
+**산출물**:
+- `agent_factory.py` with `create_planner_agent()`, `create_subagent()`
+- Basic `task` tool implementation
+- Deep Agents 패턴 분석 문서
+
+### Sprint 2: 서브에이전트 구현
+
+| Task | Description | Priority |
+|------|-------------|----------|
+| 2.1 | Python Developer 서브에이전트 구현 | P0 |
+| 2.2 | Researcher 서브에이전트 구현 | P0 |
+| 2.3 | 서브에이전트 프롬프트 최적화 | P1 |
+| 2.4 | 단위 테스트 작성 | P1 |
+
+**산출물**:
+- 2개 서브에이전트 구현 완료
+- 각 서브에이전트 테스트 케이스
+
+### Sprint 3: HITL 통합 (1주)
+
+| Task | Description | Priority |
+|------|-------------|----------|
+| 3.1 | 서브에이전트 interrupt 전파 구현 | P0 |
+| 3.2 | Router 수정 (멀티에이전트 지원) | P0 |
+| 3.3 | resume_agent 멀티에이전트 처리 | P0 |
+| 3.4 | 기존 HITL 테스트 케이스 통과 확인 | P1 |
+
+**산출물**:
+- HITL이 서브에이전트에서도 정상 작동
+- 기존 기능 회귀 테스트 통과
+
+### Sprint 4: UI 및 최적화 (1주)
+
+| Task | Description | Priority |
+|------|-------------|----------|
+| 4.1 | UI에 활성 에이전트 표시 | P1 |
+| 4.2 | SSE 이벤트 추가 (agent_switch) | P1 |
+| 4.3 | 서브에이전트 캐싱 구현 | P2 |
+| 4.4 | 성능 벤치마크 | P2 |
+| 4.5 | 문서화 업데이트 | P1 |
+
+**산출물**:
+- 멀티에이전트 UI 완성
+- 성능 비교 리포트
+- 업데이트된 ARCHITECTURE.md
+
+---
+
+## 파일 구조 (TO-BE)
+
+```
+agent_server/langchain/
+├── __init__.py
+├── agent.py                    # 기존 (deprecated, 호환성 유지)
+├── agent_factory.py            # [NEW] 에이전트 팩토리
+├── subagents/                  # [NEW] 서브에이전트 정의
+│   ├── __init__.py
+│   ├── base.py                 # 서브에이전트 기본 클래스
+│   ├── python_developer.py     # Python/Jupyter 코드 실행 (can call athena_query)
+│   ├── researcher.py           # 검색/탐색 (READ-ONLY)
+│   └── athena_query.py         # [NEW] Athena SQL 생성 (Qdrant RAG)
+├── middleware/                 # [NEW] 미들웨어 리팩토링
+│   ├── __init__.py
+│   ├── subagent_middleware.py  # SubAgentMiddleware (deepagents 벤치마킹)
+│   ├── hitl_middleware.py
+│   ├── todo_middleware.py
+│   └── custom_middleware.py    # 기존 커스텀 미들웨어
+├── prompts/                    # [NEW] 프롬프트 분리
+│   ├── __init__.py
+│   ├── planner_prompt.py       # Planner (Supervisor) 프롬프트
+│   ├── python_developer_prompt.py
+│   ├── researcher_prompt.py    # Researcher 에이전트 프롬프트
+│   └── athena_query_prompt.py  # [NEW] Athena Query 에이전트 프롬프트
+├── tools/                      # [REFACTOR] 도구 모듈화
+│   ├── __init__.py
+│   ├── shared/                 # [NEW] 공통 도구 (여러 에이전트가 공유)
+│   │   ├── __init__.py
+│   │   ├── read_file.py        # read_file_tool
+│   │   ├── execute_command.py  # execute_command_tool
+│   │   └── qdrant_search.py    # qdrant_search_tool (Researcher, Athena Query 공통)
+│   ├── planner/                # [NEW] Planner 전용 도구
+│   │   ├── __init__.py
+│   │   └── check_resource.py   # check_resource_tool
+│   ├── python_developer/       # [NEW] Python Developer 전용 도구
+│   │   ├── __init__.py
+│   │   ├── jupyter_cell.py     # jupyter_cell_tool
+│   │   ├── markdown.py         # markdown_tool
+│   │   ├── write_file.py       # write_file_tool
+│   │   └── multiedit_file.py   # multiedit_file_tool
+│   └── researcher/             # [NEW] Researcher 전용 도구
+│       ├── __init__.py
+│       ├── search_notebook.py  # search_notebook_cells_tool
+│       └── diagnostics.py      # diagnostics_tool
+├── llm_factory.py              # 기존 유지
+├── state.py                    # 기존 유지
+└── logging_utils.py            # 기존 유지
+```
+
+### 도구 모듈화 설계
+
+```python
+# tools/shared/__init__.py
+"""공통 도구 - 여러 에이전트가 공유"""
+from .read_file import read_file_tool
+from .execute_command import execute_command_tool
+
+SHARED_TOOLS = [read_file_tool, execute_command_tool]
+
+# tools/__init__.py
+"""에이전트별 도구 조합"""
+from .shared import SHARED_TOOLS
+from .planner import check_resource_tool
+from .python_developer import jupyter_cell_tool, markdown_tool, write_file_tool, multiedit_file_tool
+from .researcher import search_notebook_cells_tool, diagnostics_tool
+
+def get_tools_for_agent(agent_type: str, include_nested_task: bool = False) -> list:
+    """에이전트 타입별 도구 목록 반환"""
+    base_tools = list(SHARED_TOOLS)  # 공통 도구 복사
+    
+    if agent_type == "planner":
+        return [check_resource_tool]  # Planner는 task tool만 사용 (agent_factory에서 추가)
+    elif agent_type == "python_developer":
+        tools = base_tools + [jupyter_cell_tool, markdown_tool, write_file_tool, multiedit_file_tool]
+        if include_nested_task:
+            # Python Developer는 athena_query만 호출 가능한 제한된 task tool 추가
+            tools.append(create_limited_task_tool(allowed_agents=["athena_query"]))
+        return tools
+    elif agent_type == "researcher":
+        return base_tools + [search_notebook_cells_tool, diagnostics_tool, qdrant_search_tool]
+    elif agent_type == "athena_query":
+        return [qdrant_search_tool]  # Athena Query는 Qdrant 검색만 사용 (공통 도구에서 가져옴)
+    else:
+        raise ValueError(f"Unknown agent type: {agent_type}")
+
+def create_limited_task_tool(allowed_agents: list):
+    """특정 에이전트만 호출할 수 있는 제한된 task tool 생성"""
+    @tool
+    def task(agent_name: str, description: str) -> str:
+        """Delegate a task to a specialized subagent (limited)."""
+        if agent_name not in allowed_agents:
+            return f"Error: Cannot call '{agent_name}'. Allowed: {allowed_agents}"
+        # ... 기존 task 로직
+    return task
+```
+
+---
+
+## Deep Agents 벤치마킹 상세
+
+### 핵심 패턴 분석
+
+Deep Agents 라이브러리(https://github.com/langchain-ai/deepagents)의 SubAgentMiddleware를 분석하여 다음 패턴을 벤치마킹합니다:
+
+#### 1. Subagent 정의 구조
+```python
+# deepagents의 SubAgent TypedDict 패턴
+SubAgent = TypedDict("SubAgent", {
+    "name": str,                  # 필수: 에이전트 식별자
+    "description": str,           # 필수: task tool에 표시될 설명
+    "system_prompt": str,         # 필수: 에이전트 프롬프트
+    "tools": List[BaseTool],      # 필수: 사용 가능한 도구 목록
+    "model": Optional[str],       # 선택: 커스텀 LLM 모델
+    "middleware": Optional[List], # 선택: 추가 미들웨어
+})
+```
+
+#### 2. Task Tool 동작 방식
+```python
+# deepagents의 task tool 핵심 로직
+@tool
+def task(task_description: str, subagent_type: str = "general") -> str:
+    """
+    1. subagent_type 유효성 검사
+    2. 격리된 상태 준비 (messages, todos 등 제외)
+    3. task_description을 HumanMessage로 변환하여 서브에이전트에 전달
+    4. 서브에이전트 실행
+    5. 최종 메시지를 ToolMessage로 반환
+    """
+```
+
+#### 3. Context Isolation (핵심!)
+```python
+# deepagents 패턴: 서브에이전트 호출 시 상태 격리
+def _prepare_isolated_state(parent_state: dict) -> dict:
+    """메인 에이전트 컨텍스트를 오염시키지 않도록 격리"""
+    excluded_keys = {"messages", "todos", "structured_response"}
+    isolated = {k: v for k, v in parent_state.items() if k not in excluded_keys}
+    return isolated
+```
+
+#### 4. HITL Interrupt Bubbling
+```python
+# deepagents 패턴: 서브에이전트의 HITL interrupt를 메인 에이전트로 전파
+def _handle_subagent_interrupt(interrupt_info: dict) -> Command:
+    """
+    서브에이전트가 HITL interrupt 발생 시:
+    1. interrupt 정보를 메인 에이전트로 bubbling up
+    2. 클라이언트에서 승인 후 resume_agent 호출 시
+    3. 올바른 서브에이전트 context로 라우팅
+    """
+    return Command(interrupt={
+        "subagent": interrupt_info["agent_name"],
+        "tool_call": interrupt_info["tool_call"],
+        "checkpoint": interrupt_info["checkpoint_id"],
+    })
+```
+
+### HDSP 적용 계획
+
+| Deep Agents 패턴 | HDSP 적용 |
+|-----------------|----------|
+| `SubAgent` TypedDict | `SUBAGENT_CONFIGS` dict |
+| `task(description, subagent_type)` | `task(agent_name, description)` |
+| Context Isolation | 서브에이전트 호출 시 messages 제외 |
+| HITL Bubbling | 기존 `interrupt_on_approval` 패턴 확장 |
+| `general` default subagent | 제외 (명시적 호출만 허용) |
+
+---
+
+## 참고 자료
+
+### LangChain Documentation
+- [Subagents Architecture](https://docs.langchain.com/oss/python/langchain/multi-agent/subagents)
+- [Personal Assistant Tutorial](https://docs.langchain.com/oss/python/langchain/multi-agent/subagents-personal-assistant)
+- [Router vs Subagents](https://docs.langchain.com/oss/python/langchain/multi-agent/router-knowledge-base)
+
+### Deep Agents Library (벤치마킹 대상)
+- [Overview](https://docs.langchain.com/oss/python/deepagents/overview)
+- [Middleware](https://docs.langchain.com/oss/python/deepagents/middleware)
+- [Subagents](https://docs.langchain.com/oss/python/deepagents/subagents)
+- [Task Delegation (Harness)](https://docs.langchain.com/oss/python/deepagents/harness)
+- [GitHub Repository](https://github.com/langchain-ai/deepagents)
+
+### 핵심 개념
+1. **Supervisor Pattern**: 중앙 에이전트가 전문 에이전트들을 도구처럼 호출
+2. **Context Isolation**: 각 서브에이전트는 깨끗한 context window에서 실행
+3. **Stateless Subagents**: 서브에이전트는 상태를 유지하지 않음
+4. **Tool-based Invocation**: 서브에이전트를 `task()` 도구를 통해 호출
+5. **HITL Bubbling**: 서브에이전트의 human-in-the-loop interrupt가 메인 에이전트로 전파
+
+---
+
+## 변경 이력
+
+| Date | Version | Description |
+|------|---------|-------------|
+| 2026-01-22 | 1.0 | 초안 작성 |
+| 2026-01-22 | 1.1 | 아키텍처 간소화: Resource Manager 제거, FileSystem → Researcher 변경, Deep Agents 벤치마킹 방식으로 전환 |
+| 2026-01-22 | 1.2 | 도구 재배치: Python Developer에 file tools, execute_command 추가. Researcher는 READ-ONLY로 변경. 공통 도구 모듈화 설계 추가 |
+| 2026-01-22 | 1.3 | **Athena Query Agent 추가**: Qdrant RAG 기반 SQL 생성. **Nested Subagent 패턴** 도입 (Python Developer → Athena Query 호출 가능) |
+| 2026-01-22 | 1.4 | **구현 완료**: 디렉토리 구조, 프롬프트, 도구 레지스트리, 서브에이전트 기반, 미들웨어, 라우터 업데이트, 단위 테스트 (22개 통과) |
+
+---
+
+## 구현 상태 (Implementation Status)
+
+### ✅ 완료된 항목
+
+#### 1. 디렉토리 구조
+```
+agent_server/langchain/
+├── agent_prompts/              # ✅ 에이전트별 프롬프트
+│   ├── __init__.py
+│   ├── planner_prompt.py
+│   ├── python_developer_prompt.py
+│   ├── researcher_prompt.py
+│   └── athena_query_prompt.py
+├── subagents/                  # ✅ 서브에이전트 설정
+│   ├── __init__.py
+│   └── base.py                 # SubAgentConfig 정의
+├── middleware/                 # ✅ 서브에이전트 미들웨어
+│   ├── __init__.py
+│   └── subagent_middleware.py  # task tool, SubAgentMiddleware
+├── tools/
+│   ├── shared/                 # ✅ 공통 도구
+│   │   ├── __init__.py
+│   │   └── qdrant_search.py    # Qdrant RAG 검색
+│   └── tool_registry.py        # ✅ 에이전트별 도구 매핑
+├── agent.py                    # ✅ create_agent_system 추가
+└── agent_factory.py            # ✅ 멀티에이전트 팩토리
+```
+
+#### 2. 핵심 모듈
+| 모듈 | 상태 | 설명 |
+|------|------|------|
+| `agent_factory.py` | ✅ | `create_multi_agent_system`, `create_planner_agent`, `create_subagent` |
+| `tool_registry.py` | ✅ | 에이전트별 도구 매핑 (`AGENT_TOOLS_CONFIG`, `get_tools_for_agent`) |
+| `subagent_middleware.py` | ✅ | `task` 도구, `SubAgentMiddleware`, `create_task_tool` |
+| `subagents/base.py` | ✅ | `SubAgentConfig`, `SUBAGENT_CONFIGS`, `get_subagent_config` |
+
+#### 3. 라우터 업데이트
+- ✅ `AgentRequest.agentMode` 필드 추가 ("single" | "multi")
+- ✅ `ResumeRequest.agentMode` 필드 추가
+- ✅ `create_agent_system()` 사용으로 전환
+- ✅ 캐시 키에 `agent_mode` 포함
+
+#### 4. 단위 테스트
+- ✅ `tests/test_multi_agent_architecture.py` (22개 테스트 모두 통과)
+  - Tool Registry 테스트 (5개)
+  - SubAgent Config 테스트 (4개)
+  - Agent Prompts 테스트 (3개)
+  - SubAgent Middleware 테스트 (2개)
+  - Agent Factory 테스트 (1개)
+  - Agent System Wrapper 테스트 (2개)
+  - Router Agent Mode 테스트 (3개)
+  - Qdrant Search Tool 테스트 (2개)
+
+### 🔄 사용 방법
+
+#### Single Agent Mode (기존 방식)
+```python
+# 기본값: agentMode="single"
+response = await client.post("/langchain/stream", json={
+    "request": "분석해줘",
+    "threadId": "...",
+})
+```
+
+#### Multi-Agent Mode (Planner + Subagents)
+```python
+# 멀티에이전트 모드 활성화
+response = await client.post("/langchain/stream", json={
+    "request": "분석해줘",
+    "threadId": "...",
+    "agentMode": "multi",  # ← 멀티에이전트 모드
+})
+```
+
+### 📝 향후 작업 (TODO)
+
+1. **HITL Interrupt Bubbling**: 서브에이전트의 HITL interrupt가 Planner로 전파되도록 구현
+2. **UI 업데이트**: 활성 에이전트 표시, agent_switch SSE 이벤트
+3. **Qdrant 연동 테스트**: 실제 Qdrant 서버와 연동 테스트
+4. **성능 벤치마크**: 단일 에이전트 vs 멀티에이전트 비교