andre/crewAI
1
0
Fork 0
mirror of https://github.com/crewAIInc/crewAI.git synced 2026-01-20 13:28:13 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Add Korean translations (#3307)
Some checks failed
Notify Downstream / notify-downstream (push) Has been cancelled
Details
Mark stale issues and pull requests / stale (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Daniel Barreto
2025-08-12 19:58:12 -03:00
committed by GitHub
parent 251ae00b8b
commit a0eadf783b
185 changed files with 36306 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

109
docs/ko/tools/web-scraping/brightdata-tools.mdx Normal file
View File

@@ -0,0 +1,109 @@
---
title: Bright Data 도구
description: SERP 검색, Web Unlocker 스크래핑 및 Dataset API를 위한 Bright Data 통합.
icon: spider
---
# Bright Data 도구
이 도구 세트는 웹 추출을 위한 Bright Data 서비스를 통합합니다.
## 설치
```shell
uv add crewai-tools requests aiohttp
```
## 환경 변수
- `BRIGHT_DATA_API_KEY` (필수)
- `BRIGHT_DATA_ZONE` (SERP/Web Unlocker용)
https://brightdata.com/ 에서 자격 증명을 생성하세요 (회원가입 후 API 토큰과 zone을 만드세요).
문서는 여기를 참고하세요: https://developers.brightdata.com/
## 포함된 도구
- `BrightDataSearchTool`: 지역/언어/디바이스 옵션과 함께 SERP 검색(Google/Bing/Yandex).
- `BrightDataWebUnlockerTool`: 안티봇 우회 및 렌더링을 통한 페이지 스크랩.
- `BrightDataDatasetTool`: Dataset API 작업 실행 및 결과 가져오기.
## 예시
### SERP 검색
```python Code
from crewai_tools import BrightDataSearchTool
tool = BrightDataSearchTool(
query="CrewAI",
country="us",
)
print(tool.run())
```
### 웹 언로커
```python Code
from crewai_tools import BrightDataWebUnlockerTool
tool = BrightDataWebUnlockerTool(
url="https://example.com",
format="markdown",
)
print(tool.run(url="https://example.com"))
```
### 데이터셋 API
```python Code
from crewai_tools import BrightDataDatasetTool
tool = BrightDataDatasetTool(
dataset_type="ecommerce",
url="https://example.com/product",
)
print(tool.run())
```
## 문제 해결
- 401/403: `BRIGHT_DATA_API_KEY`와 `BRIGHT_DATA_ZONE`을 확인하세요.
- 빈 내용/차단된 콘텐츠: 렌더링을 활성화하거나 다른 존을 시도해 보세요.
## 예시
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import BrightDataSearchTool
tool = BrightDataSearchTool(
query="CrewAI",
country="us",
)
agent = Agent(
role="Web Researcher",
goal="Search with Bright Data",
backstory="Finds reliable results",
tools=[tool],
verbose=True,
)
task = Task(
description="Search for CrewAI and summarize top results",
expected_output="Short summary with links",
agent=agent,
)
crew = Crew(
agents=[agent],
tasks=[task],
verbose=True,
)
result = crew.kickoff()
```

50
docs/ko/tools/web-scraping/browserbaseloadtool.mdx Normal file
View File

@@ -0,0 +1,50 @@
---
title: Browserbase 웹 로더
description: Browserbase는 헤드리스 브라우저를 신뢰성 있게 실행, 관리 및 모니터링할 수 있는 개발자 플랫폼입니다.
icon: browser
---
# `BrowserbaseLoadTool`
## 설명
[Browserbase](https://browserbase.com)는 헤드리스 브라우저를 안정적으로 실행, 관리, 모니터링할 수 있는 개발자 플랫폼입니다.
AI 데이터 수집을 다음과 같이 강화하세요:
- [서버리스 인프라스트럭처](https://docs.browserbase.com/under-the-hood)를 통해 복잡한 UI에서 데이터를 추출할 수 있는 신뢰할 수 있는 브라우저 제공
- [스텔스 모드](https://docs.browserbase.com/features/stealth-mode)에서는 지문 인식 회피 기법과 자동 캡차 솔루션이 포함되어 있습니다
- [세션 디버거](https://docs.browserbase.com/features/sessions)를 통해 네트워크 타임라인과 로그로 Browser Session을 점검
- [라이브 디버그](https://docs.browserbase.com/guides/session-debug-connection/browser-remote-control)로 자동화 작업을 신속하게 디버깅
## 설치
- [browserbase.com](https://browserbase.com)에서 API 키와 Project ID를 받아 환경 변수(`BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID`)에 설정하세요.
- [Browserbase SDK](http://github.com/browserbase/python-sdk)와 `crewai[tools]` 패키지를 설치하세요:
```shell
pip install browserbase 'crewai[tools]'
```
## 예시
아래와 같이 BrowserbaseLoadTool을 활용하여 에이전트가 웹사이트를 로드할 수 있도록 합니다:
```python Code
from crewai_tools import BrowserbaseLoadTool
# Initialize the tool with the Browserbase API key and Project ID
tool = BrowserbaseLoadTool()
```
## 인수
다음 매개변수를 사용하여 `BrowserbaseLoadTool`의 동작을 맞춤 설정할 수 있습니다:
| 인수 | 타입 | 설명 |
|:----------------|:-----------|:---------------------------------------------------------------------------------------------------------------------------------|
| **api_key** | `string` | _선택 사항_. Browserbase API 키. 기본값은 `BROWSERBASE_API_KEY` 환경 변수입니다. |
| **project_id** | `string` | _선택 사항_. Browserbase 프로젝트 ID. 기본값은 `BROWSERBASE_PROJECT_ID` 환경 변수입니다. |
| **text_content**| `bool` | _선택 사항_. 텍스트 콘텐츠만 가져옵니다. 기본값은 `False`입니다. |
| **session_id** | `string` | _선택 사항_. 기존 세션 ID를 제공합니다. |
| **proxy** | `bool` | _선택 사항_. 프록시 활성화/비활성화 옵션입니다. 기본값은 `False`입니다. |

47
docs/ko/tools/web-scraping/firecrawlcrawlwebsitetool.mdx Normal file
View File

@@ -0,0 +1,47 @@
---
title: Firecrawl 웹사이트 크롤링
description: FirecrawlCrawlWebsiteTool은(는) 웹사이트를 크롤링하여 깔끔한 마크다운이나 구조화된 데이터로 변환하도록 설계되었습니다.
icon: fire-flame
---
# `FirecrawlCrawlWebsiteTool`
## 설명
[Firecrawl](https://firecrawl.dev)은(는) 모든 웹사이트를 크롤링하여 깔끔한 마크다운이나 구조화된 데이터로 변환할 수 있는 플랫폼입니다.
## 설치
- [firecrawl.dev](https://firecrawl.dev)에서 API 키를 받아 환경 변수(`FIRECRAWL_API_KEY`)에 설정합니다.
- [Firecrawl SDK](https://github.com/mendableai/firecrawl)와 `crewai[tools]` 패키지를 설치합니다:
```shell
pip install firecrawl-py 'crewai[tools]'
```
## 예시
다음과 같이 FirecrawlScrapeFromWebsiteTool을 활용하여 에이전트가 웹사이트를 불러올 수 있습니다:
```python Code
from crewai_tools import FirecrawlCrawlWebsiteTool
tool = FirecrawlCrawlWebsiteTool(url='firecrawl.dev')
```
## 인자
- `api_key`: 선택 사항. Firecrawl API 키를 명시합니다. 기본값은 `FIRECRAWL_API_KEY` 환경 변수입니다.
- `url`: 크롤링을 시작할 기본 URL입니다.
- `page_options`: 선택 사항.
- `onlyMainContent`: 선택 사항. 헤더, 내비게이션, 푸터 등을 제외한 페이지의 주요 콘텐츠만 반환합니다.
- `includeHtml`: 선택 사항. 페이지의 원시 HTML 내용을 포함합니다. 응답에 html 키가 추가됩니다.
- `crawler_options`: 선택 사항. 크롤링 동작을 제어하는 옵션입니다.
- `includes`: 선택 사항. 크롤링에 포함할 URL 패턴입니다.
- `exclude`: 선택 사항. 크롤링에서 제외할 URL 패턴입니다.
- `generateImgAltText`: 선택 사항. LLM을 사용하여 이미지의 대체 텍스트를 생성합니다(유료 플랜 필요).
- `returnOnlyUrls`: 선택 사항. true로 설정하면 크롤 상태에서 URL 목록만 반환합니다. 참고: 응답은 문서 목록이 아니라, data 내부의 URL 목록이 됩니다.
- `maxDepth`: 선택 사항. 크롤링할 최대 깊이입니다. 깊이 1은 기본 URL, 깊이 2는 기본 URL과 그 직접 자식까지 포함합니다.
- `mode`: 선택 사항. 사용할 크롤링 모드입니다. Fast 모드는 사이트맵이 없는 웹사이트에서 4배 빠르게 크롤링하지만 정확도가 떨어질 수 있으며, 자바스크립트로 렌더링이 많은 사이트에는 사용하지 않는 것이 좋습니다.
- `limit`: 선택 사항. 크롤링할 최대 페이지 수입니다.
- `timeout`: 선택 사항. 크롤링 작업의 타임아웃(밀리초 단위)입니다.

43
docs/ko/tools/web-scraping/firecrawlscrapewebsitetool.mdx Normal file
View File

@@ -0,0 +1,43 @@
---
title: Firecrawl 웹사이트 스크랩
description: FirecrawlScrapeWebsiteTool은 웹사이트를 스크랩하여 깔끔한 마크다운이나 구조화된 데이터로 변환하도록 설계되었습니다.
icon: fire-flame
---
# `FirecrawlScrapeWebsiteTool`
## 설명
[Firecrawl](https://firecrawl.dev)은(는) 모든 웹사이트를 크롤링하고, 이를 깨끗한 마크다운이나 구조화된 데이터로 변환해주는 플랫폼입니다.
## 설치
- [firecrawl.dev](https://firecrawl.dev)에서 API 키를 받아 환경 변수(`FIRECRAWL_API_KEY`)에 설정합니다.
- [Firecrawl SDK](https://github.com/mendableai/firecrawl)와 `crewai[tools]` 패키지를 설치합니다:
```shell
pip install firecrawl-py 'crewai[tools]'
```
## 예시
FirecrawlScrapeWebsiteTool을 다음과 같이 활용하여 에이전트가 웹사이트를 불러올 수 있도록 합니다:
```python Code
from crewai_tools import FirecrawlScrapeWebsiteTool
tool = FirecrawlScrapeWebsiteTool(url='firecrawl.dev')
```
## 인자
- `api_key`: 선택 사항입니다. Firecrawl API 키를 지정합니다. 기본값은 `FIRECRAWL_API_KEY` 환경 변수입니다.
- `url`: 스크래핑할 URL입니다.
- `page_options`: 선택 사항입니다.
- `onlyMainContent`: 선택 사항입니다. 헤더, 내브, 푸터 등을 제외한 페이지의 주요 콘텐츠만 반환합니다.
- `includeHtml`: 선택 사항입니다. 페이지의 원시 HTML 콘텐츠를 포함합니다. 응답에 html 키가 추가됩니다.
- `extractor_options`: 선택 사항입니다. 페이지 콘텐츠에서 구조화된 정보를 LLM 기반으로 추출하기 위한 옵션입니다.
- `mode`: 사용할 추출 모드로, 현재는 'llm-extraction'을 지원합니다.
- `extractionPrompt`: 선택 사항입니다. 페이지에서 어떤 정보를 추출할지 설명하는 프롬프트입니다.
- `extractionSchema`: 선택 사항입니다. 추출할 데이터의 스키마입니다.
- `timeout`: 선택 사항입니다. 요청에 대한 타임아웃(ms)입니다.

41
docs/ko/tools/web-scraping/firecrawlsearchtool.mdx Normal file
View File

@@ -0,0 +1,41 @@
---
title: Firecrawl 검색
description: FirecrawlSearchTool은 웹사이트를 검색하고 이를 깔끔한 마크다운 또는 구조화된 데이터로 변환하도록 설계되었습니다.
icon: fire-flame
---
# `FirecrawlSearchTool`
## 설명
[Firecrawl](https://firecrawl.dev)은(는) 어떤 웹사이트도 크롤링하여 깔끔한 마크다운 또는 구조화된 데이터로 변환할 수 있는 플랫폼입니다.
## 설치
- [firecrawl.dev](https://firecrawl.dev)에서 API 키를 발급받아 환경 변수(`FIRECRAWL_API_KEY`)에 설정하세요.
- [Firecrawl SDK](https://github.com/mendableai/firecrawl)와 함께 `crewai[tools]` 패키지를 설치하세요:
```shell
pip install firecrawl-py 'crewai[tools]'
```
## 예시
에이전트가 웹사이트를 로드할 수 있도록 FirecrawlSearchTool을 다음과 같이 활용합니다:
```python Code
from crewai_tools import FirecrawlSearchTool
tool = FirecrawlSearchTool(query='what is firecrawl?')
```
## 인자
- `api_key`: 선택 사항입니다. Firecrawl API 키를 지정합니다. 기본값은 `FIRECRAWL_API_KEY` 환경 변수입니다.
- `query`: 검색에 사용될 검색 쿼리 문자열입니다.
- `page_options`: 선택 사항입니다. 결과 형식 지정 옵션입니다.
- `onlyMainContent`: 선택 사항입니다. 헤더, 내브, 푸터 등을 제외한 페이지의 주요 내용만 반환합니다.
- `includeHtml`: 선택 사항입니다. 페이지의 원시 HTML 콘텐츠를 포함합니다. 응답에 html 키가 출력됩니다.
- `fetchPageContent`: 선택 사항입니다. 페이지의 전체 콘텐츠를 가져옵니다.
- `search_options`: 선택 사항입니다. 크롤링 동작 제어 옵션입니다.
- `limit`: 선택 사항입니다. 크롤링할 페이지의 최대 개수입니다.

86
docs/ko/tools/web-scraping/hyperbrowserloadtool.mdx Normal file
View File

@@ -0,0 +1,86 @@
---
title: Hyperbrowser 로드 도구
description: HyperbrowserLoadTool은 Hyperbrowser를 사용하여 웹 스크래핑과 크롤링을 가능하게 합니다.
icon: globe
---
# `HyperbrowserLoadTool`
## 설명
`HyperbrowserLoadTool`은 [Hyperbrowser](https://hyperbrowser.ai)를 이용한 웹 스크래핑과 크롤링을 가능하게 해주는 도구입니다. Hyperbrowser는 헤드리스 브라우저를 실행하고 확장할 수 있는 플랫폼입니다. 이 도구를 통해 단일 페이지를 스크랩하거나 전체 사이트를 크롤링할 수 있으며, 적절하게 포맷된 마크다운 또는 HTML로 콘텐츠를 반환합니다.
주요 특징:
- 즉각적인 확장성 – 인프라 고민 없이 수백 개의 브라우저 세션을 몇 초 만에 실행
- 간편한 통합 – Puppeteer, Playwright 등 인기 툴과 완벽하게 연동
- 강력한 API – 어떤 사이트든 쉽게 스크래핑/크롤링할 수 있는 API 제공
- 안티-봇 우회 – 내장 스텔스 모드, 광고 차단, 자동 CAPTCHA 해결, 프록시 자동 회전
## 설치
이 도구를 사용하려면 Hyperbrowser SDK를 설치해야 합니다:
```shell
uv add hyperbrowser
```
## 시작 단계
`HyperbrowserLoadTool`을 효과적으로 사용하려면 다음 단계를 따르세요:
1. **회원가입**: [Hyperbrowser](https://app.hyperbrowser.ai/)에 방문하여 회원가입을 하고 API 키를 생성하세요.
2. **API 키**: `HYPERBROWSER_API_KEY` 환경 변수를 설정하거나 도구 생성자에 직접 전달하세요.
3. **SDK 설치**: 위 명령어를 사용하여 Hyperbrowser SDK를 설치하세요.
## 예시
다음 예시는 도구를 초기화하고 웹사이트를 스크래핑하는 방법을 보여줍니다:
```python Code
from crewai_tools import HyperbrowserLoadTool
from crewai import Agent
# Initialize the tool with your API key
tool = HyperbrowserLoadTool(api_key="your_api_key") # Or use environment variable
# Define an agent that uses the tool
@agent
def web_researcher(self) -> Agent:
'''
This agent uses the HyperbrowserLoadTool to scrape websites
and extract information.
'''
return Agent(
config=self.agents_config["web_researcher"],
tools=[tool]
)
```
## 매개변수
`HyperbrowserLoadTool`은(는) 다음과 같은 매개변수를 허용합니다:
### 생성자 매개변수
- **api_key**: 선택 사항입니다. Hyperbrowser API 키입니다. 제공하지 않으면 `HYPERBROWSER_API_KEY` 환경 변수에서 읽어옵니다.
### 실행 매개변수
- **url**: 필수입니다. 스크랩 또는 크롤링할 웹사이트의 URL입니다.
- **operation**: 선택 사항입니다. 웹사이트에서 수행할 작업입니다. 'scrape' 또는 'crawl' 중 하나입니다. 기본값은 'scrape'입니다.
- **params**: 선택 사항입니다. 스크랩 또는 크롤 작업을 위한 추가 매개변수입니다.
## 지원되는 파라미터
지원되는 모든 파라미터에 대한 자세한 정보는 다음을 방문하세요:
- [스크래핑 파라미터](https://docs.hyperbrowser.ai/reference/sdks/python/scrape#start-scrape-job-and-wait)
- [크롤링 파라미터](https://docs.hyperbrowser.ai/reference/sdks/python/crawl#start-crawl-job-and-wait)
## 반환 형식
도구는 다음과 같은 형식으로 콘텐츠를 반환합니다:
- **스크래핑** 작업의 경우: 페이지의 내용을 마크다운 또는 HTML 형식으로 반환합니다.
- **크롤링** 작업의 경우: 각 페이지의 콘텐츠를 구분선으로 구분하여 반환하며, 각 페이지의 URL도 포함됩니다.
## 결론
`HyperbrowserLoadTool`은 웹사이트를 스크랩하고 크롤링할 수 있는 강력한 방식을 제공하며, 봇 방지 기술, CAPTCHA 등과 같은 복잡한 상황도 처리할 수 있습니다. Hyperbrowser의 플랫폼을 활용하여 이 도구는 에이전트가 웹 콘텐츠에 효율적으로 접근하고 추출할 수 있도록 지원합니다.

111
docs/ko/tools/web-scraping/overview.mdx Normal file
View File

@@ -0,0 +1,111 @@
---
title: "개요"
description: "강력한 스크래핑 도구로 웹사이트에서 데이터를 추출하고 브라우저 상호작용을 자동화하세요"
icon: "face-smile"
---
이러한 도구들은 에이전트가 웹과 상호작용하고, 웹사이트에서 데이터를 추출하며, 브라우저 기반 작업을 자동화할 수 있도록 해줍니다. 간단한 웹 스크래핑부터 복잡한 브라우저 자동화까지, 이러한 도구들은 모든 웹 상호작용 요구를 충족합니다.
## **사용 가능한 도구**
<CardGroup cols={2}>
<Card title="웹사이트 스크래핑 도구" icon="globe" href="/ko/tools/web-scraping/scrapewebsitetool">
모든 웹사이트의 콘텐츠를 추출할 수 있는 범용 웹 스크래핑 도구입니다.
</Card>
<Card title="요소 스크래핑 도구" icon="crosshairs" href="/ko/tools/web-scraping/scrapeelementfromwebsitetool">
웹 페이지의 특정 요소를 정밀하게 스크래핑할 수 있습니다.
</Card>
<Card title="Firecrawl 크롤 도구" icon="spider" href="/ko/tools/web-scraping/firecrawlcrawlwebsitetool">
Firecrawl의 강력한 엔진으로 전체 웹사이트를 체계적으로 크롤링합니다.
</Card>
<Card title="Firecrawl 스크래핑 도구" icon="fire" href="/ko/tools/web-scraping/firecrawlscrapewebsitetool">
Firecrawl의 고급 기능을 통한 고성능 웹 스크래핑을 제공합니다.
</Card>
<Card title="Firecrawl 검색 도구" icon="magnifying-glass" href="/ko/tools/web-scraping/firecrawlsearchtool">
Firecrawl의 검색 기능을 사용하여 특정 콘텐츠를 찾아 추출합니다.
</Card>
<Card title="Selenium 스크래핑 도구" icon="robot" href="/ko/tools/web-scraping/seleniumscrapingtool">
Selenium WebDriver의 기능으로 브라우저 자동화 및 스크래핑을 지원합니다.
</Card>
<Card title="ScrapFly 도구" icon="plane" href="/ko/tools/web-scraping/scrapflyscrapetool">
ScrapFly의 프리미엄 스크래핑 서비스를 활용한 전문 웹 스크래핑 도구입니다.
</Card>
<Card title="ScrapGraph 도구" icon="network-wired" href="/ko/tools/web-scraping/scrapegraphscrapetool">
복잡한 데이터 관계를 위한 그래프 기반 웹 스크래핑 도구입니다.
</Card>
<Card title="Spider 도구" icon="spider" href="/ko/tools/web-scraping/spidertool">
종합적인 웹 크롤링 및 데이터 추출 기능을 제공합니다.
</Card>
<Card title="BrowserBase 도구" icon="browser" href="/ko/tools/web-scraping/browserbaseloadtool">
BrowserBase 인프라를 활용한 클라우드 기반 브라우저 자동화 도구입니다.
</Card>
<Card title="HyperBrowser 도구" icon="window-maximize" href="/ko/tools/web-scraping/hyperbrowserloadtool">
HyperBrowser의 최적화된 엔진으로 빠른 브라우저 상호작용을 제공합니다.
</Card>
<Card title="Stagehand 도구" icon="hand" href="/ko/tools/web-scraping/stagehandtool">
자연어 명령어 기반의 지능형 브라우저 자동화 도구입니다.
</Card>
<Card title="Oxylabs 스크래퍼 도구" icon="globe" href="/ko/tools/web-scraping/oxylabsscraperstool">
대규모 웹 데이터에 Oxylabs를 통해 접근합니다.
</Card>
<Card title="Bright Data 도구" icon="spider" href="/ko/tools/web-scraping/brightdata-tools">
SERP 검색, 웹 언락커, 데이터셋 API 통합 기능을 지원합니다.
</Card>
</CardGroup>
## **일반적인 사용 사례**
- **데이터 추출**: 제품 정보, 가격, 리뷰 스크래핑
- **컨텐츠 모니터링**: 웹사이트 및 뉴스 소스의 변경 사항 추적
- **리드 생성**: 연락처 정보 및 비즈니스 데이터 추출
- **시장 조사**: 경쟁 정보 및 시장 데이터 수집
- **테스트 & QA**: 브라우저 테스트 및 검증 워크플로우 자동화
- **소셜 미디어**: 게시물, 댓글, 소셜 미디어 분석 데이터 추출
## **빠른 시작 예제**
```python
from crewai_tools import ScrapeWebsiteTool, FirecrawlScrapeWebsiteTool, SeleniumScrapingTool
# Create scraping tools
simple_scraper = ScrapeWebsiteTool()
advanced_scraper = FirecrawlScrapeWebsiteTool()
browser_automation = SeleniumScrapingTool()
# Add to your agent
agent = Agent(
role="Web Research Specialist",
tools=[simple_scraper, advanced_scraper, browser_automation],
goal="Extract and analyze web data efficiently"
)
```
## **스크래핑 모범 사례**
- **robots.txt 준수**: 항상 웹사이트의 스크래핑 정책을 확인하고 따라야 합니다.
- **요청 속도 제한**: 서버에 과부하를 주지 않도록 요청 간 지연을 구현하세요.
- **User Agent**: 봇을 식별할 수 있도록 적절한 user agent 문자열을 사용하세요.
- **법률 준수**: 스크래핑 활동이 서비스 약관을 준수하는지 확인하세요.
- **오류 처리**: 네트워크 문제 및 차단된 요청에 대해 견고한 오류 처리를 구현하세요.
- **데이터 품질**: 처리 전에 추출한 데이터를 검증하고 정제하세요.
## **도구 선택 가이드**
- **간단한 작업**: 기본 콘텐츠 추출에는 `ScrapeWebsiteTool`을 사용하세요
- **JavaScript 기반 사이트**: 동적 콘텐츠에는 `SeleniumScrapingTool`을 사용하세요
- **확장성 및 성능**: 대량 스크래핑에는 `FirecrawlScrapeWebsiteTool`을 사용하세요
- **클라우드 인프라**: 확장 가능한 브라우저 자동화에는 `BrowserBaseLoadTool`을 사용하세요
- **복잡한 워크플로우**: 지능형 브라우저 상호작용에는 `StagehandTool`을 사용하세요

235
docs/ko/tools/web-scraping/oxylabsscraperstool.mdx Normal file
View File

@@ -0,0 +1,235 @@
---
title: Oxylabs 스크래퍼
description: >
Oxylabs 스크래퍼를 사용하면 해당 소스에서 정보를 쉽게 접근할 수 있습니다. 아래에서 사용 가능한 소스 목록을 확인하세요:
- `Amazon Product`
- `Amazon Search`
- `Google Seach`
- `Universal`
icon: globe
---
## 설치
[여기](https://oxylabs.io)에서 Oxylabs 계정을 생성하여 자격 증명을 받으세요.
```shell
pip install 'crewai[tools]' oxylabs
```
API 매개변수에 대한 자세한 정보는 [Oxylabs 문서](https://developers.oxylabs.io/scraping-solutions/web-scraper-api/targets)를 참고하세요.
# `OxylabsAmazonProductScraperTool`
### 예시
```python
from crewai_tools import OxylabsAmazonProductScraperTool
# make sure OXYLABS_USERNAME and OXYLABS_PASSWORD variables are set
tool = OxylabsAmazonProductScraperTool()
result = tool.run(query="AAAAABBBBCC")
print(result)
```
### 매개변수
- `query` - 10자리 ASIN 코드.
- `domain` - Amazon의 도메인 로컬라이제이션.
- `geo_location` - _배송지_ 위치.
- `user_agent_type` - 디바이스 유형 및 브라우저.
- `render` - `html`로 설정 시 JavaScript 렌더링을 활성화합니다.
- `callback_url` - 콜백 엔드포인트의 URL.
- `context` - 특수 요구 사항을 위한 추가 고급 설정 및 제어 옵션.
- `parse` - true로 설정하면 파싱된 데이터를 반환합니다.
- `parsing_instructions` - HTML 스크래핑 결과에 대해 실행할 자체 파싱 및 데이터 변환 로직을 정의합니다.
### 고급 예제
```python
from crewai_tools import OxylabsAmazonProductScraperTool
# make sure OXYLABS_USERNAME and OXYLABS_PASSWORD variables are set
tool = OxylabsAmazonProductScraperTool(
config={
"domain": "com",
"parse": True,
"context": [
{
"key": "autoselect_variant",
"value": True
}
]
}
)
result = tool.run(query="AAAAABBBBCC")
print(result)
```
# `OxylabsAmazonSearchScraperTool`
### 예시
```python
from crewai_tools import OxylabsAmazonSearchScraperTool
# make sure OXYLABS_USERNAME and OXYLABS_PASSWORD variables are set
tool = OxylabsAmazonSearchScraperTool()
result = tool.run(query="headsets")
print(result)
```
### 파라미터
- `query` - Amazon 검색어.
- `domain` - Bestbuy의 도메인 로컬라이제이션.
- `start_page` - 시작 페이지 번호.
- `pages` - 가져올 페이지 수.
- `geo_location` - _배송지_ 위치.
- `user_agent_type` - 디바이스 종류와 브라우저.
- `render` - `html`로 설정 시 JavaScript 렌더링 활성화.
- `callback_url` - 콜백 엔드포인트의 URL.
- `context` - 고급 설정 및 특별한 요구사항을 위한 제어.
- `parse` - true로 설정 시 파싱된 데이터 반환.
- `parsing_instructions` - HTML 스크레이핑 결과에서 실행될 사용자 정의 파싱 및 데이터 변환 로직을 정의합니다.
### 고급 예제
```python
from crewai_tools import OxylabsAmazonSearchScraperTool
# make sure OXYLABS_USERNAME and OXYLABS_PASSWORD variables are set
tool = OxylabsAmazonSearchScraperTool(
config={
"domain": 'nl',
"start_page": 2,
"pages": 2,
"parse": True,
"context": [
{'key': 'category_id', 'value': 16391693031}
],
}
)
result = tool.run(query='nirvana tshirt')
print(result)
```
# `OxylabsGoogleSearchScraperTool`
### 예시
```python
from crewai_tools import OxylabsGoogleSearchScraperTool
# make sure OXYLABS_USERNAME and OXYLABS_PASSWORD variables are set
tool = OxylabsGoogleSearchScraperTool()
result = tool.run(query="iPhone 16")
print(result)
```
### 파라미터
- `query` - 검색 키워드.
- `domain` - Google의 도메인 현지화.
- `start_page` - 시작 페이지 번호.
- `pages` - 가져올 페이지 수.
- `limit` - 각 페이지에서 가져올 결과 수.
- `locale` - Google 검색 페이지 웹 인터페이스 언어를 변경하는 `Accept-Language` 헤더 값.
- `geo_location` - 결과가 적응해야 하는 지리적 위치. 이 파라미터를 올바르게 사용하는 것이 올바른 데이터를 얻기 위해 매우 중요합니다.
- `user_agent_type` - 디바이스 유형과 브라우저.
- `render` - `html`로 설정 시 JavaScript 렌더링을 활성화합니다.
- `callback_url` - 콜백 엔드포인트의 URL.
- `context` - 특수 요구를 위한 추가 고급 설정 및 제어.
- `parse` - true로 설정 시 파싱된 데이터를 반환합니다.
- `parsing_instructions` - HTML 스크래핑 결과에 대해 실행될 사용자 지정 파싱 및 데이터 변환 로직을 정의합니다.
### 고급 예시
```python
from crewai_tools import OxylabsGoogleSearchScraperTool
# make sure OXYLABS_USERNAME and OXYLABS_PASSWORD variables are set
tool = OxylabsGoogleSearchScraperTool(
config={
"parse": True,
"geo_location": "Paris, France",
"user_agent_type": "tablet",
}
)
result = tool.run(query="iPhone 16")
print(result)
```
# `OxylabsUniversalScraperTool`
### 예시
```python
from crewai_tools import OxylabsUniversalScraperTool
# make sure OXYLABS_USERNAME and OXYLABS_PASSWORD variables are set
tool = OxylabsUniversalScraperTool()
result = tool.run(url="https://ip.oxylabs.io")
print(result)
```
### 매개변수
- `url` - 스크래핑할 웹사이트 URL입니다.
- `user_agent_type` - 디바이스 유형 및 브라우저입니다.
- `geo_location` - 데이터를 가져올 프록시의 지리적 위치를 설정합니다.
- `render` - `html`로 설정할 경우 JavaScript 렌더링을 활성화합니다.
- `callback_url` - 콜백 엔드포인트의 URL입니다.
- `context` - 특수 요구 사항을 위한 추가 고급 설정 및 제어 옵션입니다.
- `parse` - 제출된 URL의 페이지 유형에 대한 전용 파서가 존재할 경우 `true`로 설정하면 파싱된 데이터를 반환합니다.
- `parsing_instructions` - HTML 스크래핑 결과에서 실행될 자체 파싱 및 데이터 변환 로직을 정의합니다.
### 고급 예제
```python
from crewai_tools import OxylabsUniversalScraperTool
# make sure OXYLABS_USERNAME and OXYLABS_PASSWORD variables are set
tool = OxylabsUniversalScraperTool(
config={
"render": "html",
"user_agent_type": "mobile",
"context": [
{"key": "force_headers", "value": True},
{"key": "force_cookies", "value": True},
{
"key": "headers",
"value": {
"Custom-Header-Name": "custom header content",
},
},
{
"key": "cookies",
"value": [
{"key": "NID", "value": "1234567890"},
{"key": "1P JAR", "value": "0987654321"},
],
},
{"key": "http_method", "value": "get"},
{"key": "follow_redirects", "value": True},
{"key": "successful_status_codes", "value": [808, 909]},
],
}
)
result = tool.run(url="https://ip.oxylabs.io")
print(result)
```

139
docs/ko/tools/web-scraping/scrapeelementfromwebsitetool.mdx Normal file
View File

@@ -0,0 +1,139 @@
---
title: 웹사이트 요소 스크랩 도구
description: ScrapeElementFromWebsiteTool은 CrewAI 에이전트가 CSS 셀렉터를 사용하여 웹사이트에서 특정 요소를 추출할 수 있도록 합니다.
icon: code
---
# `ScrapeElementFromWebsiteTool`
## 설명
`ScrapeElementFromWebsiteTool`은 CSS 선택자를 사용하여 웹사이트에서 특정 요소를 추출하도록 설계되었습니다. 이 도구는 CrewAI 에이전트가 웹 페이지에서 타겟이 되는 콘텐츠를 스크래핑할 수 있게 하여, 웹페이지의 특정 부분만이 필요한 데이터 추출 작업에 유용합니다.
## 설치
이 도구를 사용하려면 필요한 종속성을 설치해야 합니다:
```shell
uv add requests beautifulsoup4
```
## 시작 단계
`ScrapeElementFromWebsiteTool`을 효과적으로 사용하려면 다음 단계를 따르십시오:
1. **필수 종속성 설치**: 위의 명령어를 사용하여 필요한 패키지를 설치합니다.
2. **CSS 선택자 식별**: 웹사이트에서 추출하려는 요소의 CSS 선택자를 결정합니다.
3. **도구 초기화**: 필요한 매개변수로 도구 인스턴스를 생성합니다.
## 예시
다음 예시는 `ScrapeElementFromWebsiteTool`을 사용하여 웹사이트에서 특정 요소를 추출하는 방법을 보여줍니다:
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import ScrapeElementFromWebsiteTool
# Initialize the tool
scrape_tool = ScrapeElementFromWebsiteTool()
# Define an agent that uses the tool
web_scraper_agent = Agent(
role="Web Scraper",
goal="Extract specific information from websites",
backstory="An expert in web scraping who can extract targeted content from web pages.",
tools=[scrape_tool],
verbose=True,
)
# Example task to extract headlines from a news website
scrape_task = Task(
description="Extract the main headlines from the CNN homepage. Use the CSS selector '.headline' to target the headline elements.",
expected_output="A list of the main headlines from CNN.",
agent=web_scraper_agent,
)
# Create and run the crew
crew = Crew(agents=[web_scraper_agent], tasks=[scrape_task])
result = crew.kickoff()
```
도구를 미리 정의된 매개변수와 함께 초기화할 수도 있습니다:
```python Code
# Initialize the tool with predefined parameters
scrape_tool = ScrapeElementFromWebsiteTool(
website_url="https://www.example.com",
css_element=".main-content"
)
```
## 매개변수
`ScrapeElementFromWebsiteTool`은(는) 초기화 시 다음과 같은 매개변수를 허용합니다:
- **website_url**: 선택 사항. 스크래핑할 웹사이트의 URL입니다. 초기화 시 제공되면, 도구를 사용할 때 에이전트가 이를 지정할 필요가 없습니다.
- **css_element**: 선택 사항. 추출할 요소들의 CSS 선택자입니다. 초기화 시 제공되면, 도구를 사용할 때 에이전트가 이를 지정할 필요가 없습니다.
- **cookies**: 선택 사항. 요청과 함께 전송할 쿠키가 담긴 딕셔너리입니다. 인증이 필요한 웹사이트의 경우 유용하게 사용할 수 있습니다.
## 사용법
`ScrapeElementFromWebsiteTool`을 에이전트와 함께 사용할 때, 초기화 시 지정되지 않은 경우 에이전트는 다음 매개변수를 제공해야 합니다:
- **website_url**: 스크레이핑할 웹사이트의 URL
- **css_element**: 추출할 요소의 CSS 선택자
이 도구는 CSS 선택자와 일치하는 모든 요소의 텍스트 콘텐츠를 줄바꿈으로 연결하여 반환합니다.
```python Code
# Example of using the tool with an agent
web_scraper_agent = Agent(
role="Web Scraper",
goal="Extract specific elements from websites",
backstory="An expert in web scraping who can extract targeted content using CSS selectors.",
tools=[scrape_tool],
verbose=True,
)
# Create a task for the agent to extract specific elements
extract_task = Task(
description="""
Extract all product titles from the featured products section on example.com.
Use the CSS selector '.product-title' to target the title elements.
""",
expected_output="A list of product titles from the website",
agent=web_scraper_agent,
)
# Run the task through a crew
crew = Crew(agents=[web_scraper_agent], tasks=[extract_task])
result = crew.kickoff()
```
## 구현 세부사항
`ScrapeElementFromWebsiteTool`은 웹 페이지를 가져오기 위해 `requests` 라이브러리를 사용하고, HTML을 파싱하고 지정된 요소를 추출하기 위해 `BeautifulSoup`을 사용합니다:
```python Code
class ScrapeElementFromWebsiteTool(BaseTool):
name: str = "Read a website content"
description: str = "A tool that can be used to read a website content."
# Implementation details...
def _run(self, **kwargs: Any) -> Any:
website_url = kwargs.get("website_url", self.website_url)
css_element = kwargs.get("css_element", self.css_element)
page = requests.get(
website_url,
headers=self.headers,
cookies=self.cookies if self.cookies else {},
)
parsed = BeautifulSoup(page.content, "html.parser")
elements = parsed.select(css_element)
return "\n".join([element.get_text() for element in elements])
```
## 결론
`ScrapeElementFromWebsiteTool`은 CSS 셀렉터를 사용하여 웹사이트에서 특정 요소를 추출할 수 있는 강력한 방법을 제공합니다. 이 도구를 통해 에이전트는 필요한 콘텐츠만 선택적으로 수집할 수 있어 웹 스크래핑 작업을 더욱 효율적이고 집중적으로 수행할 수 있습니다. 이 도구는 데이터 추출, 콘텐츠 모니터링, 연구 등 웹 페이지에서 특정 정보를 추출해야 하는 작업에 특히 유용합니다.

196
docs/ko/tools/web-scraping/scrapegraphscrapetool.mdx Normal file
View File

@@ -0,0 +1,196 @@
---
title: Scrapegraph 스크레이프 도구
description: ScrapegraphScrapeTool은 Scrapegraph AI의 SmartScraper API를 활용하여 웹사이트에서 콘텐츠를 지능적으로 추출합니다.
icon: chart-area
---
# `ScrapegraphScrapeTool`
## 설명
`ScrapegraphScrapeTool`은 Scrapegraph AI의 SmartScraper API를 활용하여 웹사이트에서 콘텐츠를 지능적으로 추출하도록 설계되었습니다. 이 도구는 AI 기반 콘텐츠 추출을 통한 고급 웹 스크래핑 기능을 제공하여, 타깃 데이터 수집 및 콘텐츠 분석 작업에 이상적입니다. 기존의 웹 스크래퍼와 달리, 자연어 프롬프트를 기반으로 웹 페이지의 맥락과 구조를 이해하여 가장 관련성 높은 정보를 추출할 수 있습니다.
## 설치
이 도구를 사용하려면 Scrapegraph Python 클라이언트를 설치해야 합니다:
```shell
uv add scrapegraph-py
```
또한 Scrapegraph API 키를 환경 변수로 설정해야 합니다:
```shell
export SCRAPEGRAPH_API_KEY="your_api_key"
```
API 키는 [Scrapegraph AI](https://scrapegraphai.com)에서 발급받을 수 있습니다.
## 시작하는 단계
`ScrapegraphScrapeTool`을 효과적으로 사용하려면 다음 단계를 따라주세요:
1. **의존성 설치**: 위 명령어를 사용하여 필요한 패키지를 설치합니다.
2. **API 키 설정**: Scrapegraph API 키를 환경 변수로 설정하거나 초기화 시에 제공합니다.
3. **도구 초기화**: 필요한 매개변수로 도구의 인스턴스를 생성합니다.
4. **추출 프롬프트 정의**: 특정 콘텐츠 추출을 안내할 자연어 프롬프트를 작성합니다.
## 예시
다음 예시는 `ScrapegraphScrapeTool`을 사용하여 웹사이트에서 콘텐츠를 추출하는 방법을 보여줍니다:
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import ScrapegraphScrapeTool
# Initialize the tool
scrape_tool = ScrapegraphScrapeTool(api_key="your_api_key")
# Define an agent that uses the tool
web_scraper_agent = Agent(
role="Web Scraper",
goal="Extract specific information from websites",
backstory="An expert in web scraping who can extract targeted content from web pages.",
tools=[scrape_tool],
verbose=True,
)
# Example task to extract product information from an e-commerce site
scrape_task = Task(
description="Extract product names, prices, and descriptions from the featured products section of example.com.",
expected_output="A structured list of product information including names, prices, and descriptions.",
agent=web_scraper_agent,
)
# Create and run the crew
crew = Crew(agents=[web_scraper_agent], tasks=[scrape_task])
result = crew.kickoff()
```
도구를 미리 정의된 파라미터로 초기화할 수도 있습니다:
```python Code
# Initialize the tool with predefined parameters
scrape_tool = ScrapegraphScrapeTool(
website_url="https://www.example.com",
user_prompt="Extract all product prices and descriptions",
api_key="your_api_key"
)
```
## 매개변수
`ScrapegraphScrapeTool`은 초기화 시 다음 매개변수를 허용합니다:
- **api_key**: 선택 사항. 귀하의 Scrapegraph API 키입니다. 제공하지 않으면 `SCRAPEGRAPH_API_KEY` 환경 변수를 찾습니다.
- **website_url**: 선택 사항. 스크랩할 웹사이트의 URL입니다. 초기화 시 제공하면 에이전트가 도구를 사용할 때 별도로 지정할 필요가 없습니다.
- **user_prompt**: 선택 사항. 콘텐츠 추출을 위한 맞춤 지침입니다. 초기화 시 제공하면 에이전트가 도구를 사용할 때 별도로 지정할 필요가 없습니다.
- **enable_logging**: 선택 사항. Scrapegraph 클라이언트에 대한 로깅 활성화여부입니다. 기본값은 `False`입니다.
## 사용법
`ScrapegraphScrapeTool`을 agent와 함께 사용할 때, agent는 다음 파라미터들을 제공해야 합니다(초기화 시 지정하지 않았다면):
- **website_url**: 스크래핑할 웹사이트의 URL.
- **user_prompt**: 선택 사항. 콘텐츠 추출을 위한 사용자 정의 지침. 기본값은 "웹페이지의 주요 콘텐츠를 추출하세요"입니다.
툴은 제공된 prompt에 따라 추출된 콘텐츠를 반환합니다.
```python Code
# Example of using the tool with an agent
web_scraper_agent = Agent(
role="Web Scraper",
goal="Extract specific information from websites",
backstory="An expert in web scraping who can extract targeted content from web pages.",
tools=[scrape_tool],
verbose=True,
)
# Create a task for the agent to extract specific content
extract_task = Task(
description="Extract the main heading and summary from example.com",
expected_output="The main heading and summary from the website",
agent=web_scraper_agent,
)
# Run the task
crew = Crew(agents=[web_scraper_agent], tasks=[extract_task])
result = crew.kickoff()
```
## 오류 처리
`ScrapegraphScrapeTool`은 다음과 같은 예외를 발생시킬 수 있습니다:
- **ValueError**: API 키가 누락되었거나 URL 형식이 잘못된 경우 발생합니다.
- **RateLimitError**: API 사용 제한이 초과된 경우 발생합니다.
- **RuntimeError**: 스크래핑 작업이 실패했을 때(네트워크 문제, API 오류 등) 발생합니다.
에이전트에게 잠재적인 오류를 우아하게 처리하도록 권장합니다:
```python Code
# Create a task that includes error handling instructions
robust_extract_task = Task(
description="""
Extract the main heading from example.com.
Be aware that you might encounter errors such as:
- Invalid URL format
- Missing API key
- Rate limit exceeded
- Network or API errors
If you encounter any errors, provide a clear explanation of what went wrong
and suggest possible solutions.
""",
expected_output="Either the extracted heading or a clear error explanation",
agent=web_scraper_agent,
)
```
## 요청 제한
Scrapegraph API는 구독 플랜에 따라 다양한 요청 제한이 있습니다. 다음 모범 사례를 참고하세요:
- 여러 URL을 처리할 때 요청 간에 적절한 지연 시간을 구현하세요.
- 애플리케이션에서 요청 제한 오류를 원활하게 처리하세요.
- Scrapegraph 대시보드에서 자신의 API 플랜 제한을 확인하세요.
## 구현 세부 정보
`ScrapegraphScrapeTool`은 Scrapegraph Python 클라이언트를 사용하여 SmartScraper API와 상호 작용합니다:
```python Code
class ScrapegraphScrapeTool(BaseTool):
"""
A tool that uses Scrapegraph AI to intelligently scrape website content.
"""
# Implementation details...
def _run(self, **kwargs: Any) -> Any:
website_url = kwargs.get("website_url", self.website_url)
user_prompt = (
kwargs.get("user_prompt", self.user_prompt)
or "Extract the main content of the webpage"
)
if not website_url:
raise ValueError("website_url is required")
# Validate URL format
self._validate_url(website_url)
try:
# Make the SmartScraper request
response = self._client.smartscraper(
website_url=website_url,
user_prompt=user_prompt,
)
return response
# Error handling...
```
## 결론
`ScrapegraphScrapeTool`은 AI 기반의 웹 페이지 구조 이해를 활용하여 웹사이트에서 콘텐츠를 추출할 수 있는 강력한 방법을 제공합니다. 에이전트가 자연어 프롬프트를 사용하여 특정 정보를 타겟팅할 수 있도록 함으로써, 웹 스크래핑 작업을 더욱 효율적이고 집중적으로 수행할 수 있게 해줍니다. 이 도구는 데이터 추출, 콘텐츠 모니터링, 그리고 웹 페이지에서 특정 정보를 추출해야 하는 연구 과제에 특히 유용합니다.

47
docs/ko/tools/web-scraping/scrapewebsitetool.mdx Normal file
View File

@@ -0,0 +1,47 @@
---
title: 웹사이트 스크랩
description: ScrapeWebsiteTool은 지정된 웹사이트의 내용을 추출하고 읽도록 설계되었습니다.
icon: magnifying-glass-location
---
# `ScrapeWebsiteTool`
<Note>
저희는 여전히 도구를 개선하고 있으므로, 예기치 않은 동작이나 변경 사항이 발생할 수 있습니다.
</Note>
## 설명
지정된 웹사이트의 내용을 추출하고 읽을 수 있도록 설계된 도구입니다. 이 도구는 HTTP 요청을 보내고 수신된 HTML 콘텐츠를 파싱함으로써 다양한 유형의 웹 페이지를 처리할 수 있습니다.
이 도구는 웹 스크래핑 작업, 데이터 수집 또는 웹사이트에서 특정 정보를 추출하는 데 특히 유용할 수 있습니다.
## 설치
crewai_tools 패키지를 설치하세요
```shell
pip install 'crewai[tools]'
```
## 예시
```python
from crewai_tools import ScrapeWebsiteTool
# 실행 중에 찾은 모든 웹사이트를 스크랩할 수 있도록 활성화
tool = ScrapeWebsiteTool()
# 웹사이트 URL로 도구를 초기화하여,
# 에이전트가 지정된 웹사이트의 콘텐츠만 스크랩할 수 있도록 합니다
tool = ScrapeWebsiteTool(website_url='https://www.example.com')
# 사이트에서 텍스트 추출
text = tool.run()
print(text)
```
## 인자
| 인자 | 타입 | 설명 |
|:---------------|:---------|:--------------------------------------------------------------------------------------------------------------------------------|
| **website_url** | `string` | **필수** 웹사이트 URL로, 파일을 읽기 위한 주소입니다. 이 값은 도구의 주요 입력값으로, 어떤 웹사이트의 콘텐츠를 수집하고 읽을지 지정합니다. |

220
docs/ko/tools/web-scraping/scrapflyscrapetool.mdx Normal file
View File

@@ -0,0 +1,220 @@
---
title: Scrapfly 웹사이트 스크레이핑 도구
description: ScrapflyScrapeWebsiteTool은 Scrapfly의 웹 스크레이핑 API를 활용하여 다양한 형식으로 웹사이트의 콘텐츠를 추출합니다.
icon: spider
---
# `ScrapflyScrapeWebsiteTool`
## 설명
`ScrapflyScrapeWebsiteTool`은 [Scrapfly](https://scrapfly.io/)의 웹 스크래핑 API를 활용하여 웹사이트에서 콘텐츠를 추출하도록 설계되었습니다. 이 도구는 헤드리스 브라우저 지원, 프록시, 안티-봇 우회 기능 등 고급 웹 스크래핑 기능을 제공합니다. 원시 HTML, 마크다운, 일반 텍스트 등 다양한 형식으로 웹 페이지 데이터를 추출할 수 있어, 광범위한 웹 스크래핑 작업에 이상적입니다.
## 설치
이 도구를 사용하려면 Scrapfly SDK를 설치해야 합니다:
```shell
uv add scrapfly-sdk
```
또한 [scrapfly.io/register](https://www.scrapfly.io/register/)에서 회원가입하여 Scrapfly API 키를 발급받아야 합니다.
## 시작 단계
`ScrapflyScrapeWebsiteTool`을(를) 효과적으로 사용하려면 다음 단계를 따르세요:
1. **의존성 설치**: 위의 명령어를 사용하여 Scrapfly SDK를 설치하세요.
2. **API 키 받기**: Scrapfly에 등록하여 API 키를 받으세요.
3. **도구 초기화**: API 키로 도구 인스턴스를 생성하세요.
4. **스크래핑 매개변수 구성**: 필요에 따라 스크래핑 매개변수를 맞춤 설정하세요.
## 예제
다음 예제는 `ScrapflyScrapeWebsiteTool`을 사용하여 웹사이트에서 콘텐츠를 추출하는 방법을 보여줍니다:
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import ScrapflyScrapeWebsiteTool
# Initialize the tool
scrape_tool = ScrapflyScrapeWebsiteTool(api_key="your_scrapfly_api_key")
# Define an agent that uses the tool
web_scraper_agent = Agent(
role="Web Scraper",
goal="Extract information from websites",
backstory="An expert in web scraping who can extract content from any website.",
tools=[scrape_tool],
verbose=True,
)
# Example task to extract content from a website
scrape_task = Task(
description="Extract the main content from the product page at https://web-scraping.dev/products and summarize the available products.",
expected_output="A summary of the products available on the website.",
agent=web_scraper_agent,
)
# Create and run the crew
crew = Crew(agents=[web_scraper_agent], tasks=[scrape_task])
result = crew.kickoff()
```
스크래핑 파라미터를 사용자 정의할 수도 있습니다:
```python Code
# Example with custom scraping parameters
web_scraper_agent = Agent(
role="Web Scraper",
goal="Extract information from websites with custom parameters",
backstory="An expert in web scraping who can extract content from any website.",
tools=[scrape_tool],
verbose=True,
)
# The agent will use the tool with parameters like:
# url="https://web-scraping.dev/products"
# scrape_format="markdown"
# ignore_scrape_failures=True
# scrape_config={
# "asp": True, # Bypass scraping blocking solutions, like Cloudflare
# "render_js": True, # Enable JavaScript rendering with a cloud headless browser
# "proxy_pool": "public_residential_pool", # Select a proxy pool
# "country": "us", # Select a proxy location
# "auto_scroll": True, # Auto scroll the page
# }
scrape_task = Task(
description="Extract the main content from the product page at https://web-scraping.dev/products using advanced scraping options including JavaScript rendering and proxy settings.",
expected_output="A detailed summary of the products with all available information.",
agent=web_scraper_agent,
)
```
## 매개변수
`ScrapflyScrapeWebsiteTool`은(는) 다음과 같은 매개변수를 받습니다:
### 초기화 매개변수
- **api_key**: 필수. 귀하의 Scrapfly API 키입니다.
### 실행 매개변수
- **url**: 필수. 스크랩할 웹사이트의 URL입니다.
- **scrape_format**: 선택 사항. 웹 페이지 콘텐츠를 추출할 형식입니다. 옵션으로는 "raw"(HTML), "markdown", "text"가 있습니다. 기본값은 "markdown"입니다.
- **scrape_config**: 선택 사항. 추가 Scrapfly 스크래핑 구성 옵션이 포함된 딕셔너리입니다.
- **ignore_scrape_failures**: 선택 사항. 스크래핑 실패 시 실패를 무시할지 여부입니다. `True`로 설정하면, 스크래핑에 실패했을 때 예외를 발생시키는 대신에 도구가 `None`을 반환합니다.
## Scrapfly 구성 옵션
`scrape_config` 매개변수를 사용하면 다음과 같은 옵션으로 스크래핑 동작을 사용자 지정할 수 있습니다:
- **asp**: 안티 스크래핑 보호 우회 활성화.
- **render_js**: 클라우드 헤드리스 브라우저로 JavaScript 렌더링 활성화.
- **proxy_pool**: 프록시 풀 선택 (예: "public_residential_pool", "datacenter").
- **country**: 프록시 위치 선택 (예: "us", "uk").
- **auto_scroll**: 페이지를 자동으로 스크롤하여 지연 로딩된 콘텐츠를 불러옵니다.
- **js**: 헤드리스 브라우저에서 커스텀 JavaScript 코드 실행.
전체 구성 옵션 목록은 [Scrapfly API 문서](https://scrapfly.io/docs/scrape-api/getting-started)를 참조하세요.
## 사용법
`ScrapflyScrapeWebsiteTool`을 에이전트와 함께 사용할 때, 에이전트는 크롤링할 웹사이트의 URL을 제공해야 하며, 선택적으로 포맷과 추가 구성 옵션을 지정할 수 있습니다.
```python Code
# Example of using the tool with an agent
web_scraper_agent = Agent(
role="Web Scraper",
goal="Extract information from websites",
backstory="An expert in web scraping who can extract content from any website.",
tools=[scrape_tool],
verbose=True,
)
# Create a task for the agent
scrape_task = Task(
description="Extract the main content from example.com in markdown format.",
expected_output="The main content of example.com in markdown format.",
agent=web_scraper_agent,
)
# Run the task
crew = Crew(agents=[web_scraper_agent], tasks=[scrape_task])
result = crew.kickoff()
```
더 고급 사용자 지정 구성을 위한 사용법:
```python Code
# Create a task with more specific instructions
advanced_scrape_task = Task(
description="""
Extract content from example.com with the following requirements:
- Convert the content to plain text format
- Enable JavaScript rendering
- Use a US-based proxy
- Handle any scraping failures gracefully
""",
expected_output="The extracted content from example.com",
agent=web_scraper_agent,
)
```
## 오류 처리
기본적으로 `ScrapflyScrapeWebsiteTool`은 스크래핑에 실패하면 예외를 발생시킵니다. 에이전트는 `ignore_scrape_failures` 매개변수를 지정하여 실패를 우아하게 처리하도록 지시할 수 있습니다.
```python Code
# Create a task that instructs the agent to handle errors
error_handling_task = Task(
description="""
Extract content from a potentially problematic website and make sure to handle any
scraping failures gracefully by setting ignore_scrape_failures to True.
""",
expected_output="Either the extracted content or a graceful error message",
agent=web_scraper_agent,
)
```
## 구현 세부사항
`ScrapflyScrapeWebsiteTool`은 Scrapfly SDK를 사용하여 Scrapfly API와 상호작용합니다:
```python Code
class ScrapflyScrapeWebsiteTool(BaseTool):
name: str = "Scrapfly web scraping API tool"
description: str = (
"Scrape a webpage url using Scrapfly and return its content as markdown or text"
)
# Implementation details...
def _run(
self,
url: str,
scrape_format: str = "markdown",
scrape_config: Optional[Dict[str, Any]] = None,
ignore_scrape_failures: Optional[bool] = None,
):
from scrapfly import ScrapeApiResponse, ScrapeConfig
scrape_config = scrape_config if scrape_config is not None else {}
try:
response: ScrapeApiResponse = self.scrapfly.scrape(
ScrapeConfig(url, format=scrape_format, **scrape_config)
)
return response.scrape_result["content"]
except Exception as e:
if ignore_scrape_failures:
logger.error(f"Error fetching data from {url}, exception: {e}")
return None
else:
raise e
```
## 결론
`ScrapflyScrapeWebsiteTool`은 Scrapfly의 고급 웹 스크래핑 기능을 활용하여 웹사이트에서 콘텐츠를 추출할 수 있는 강력한 방법을 제공합니다. 헤드리스 브라우저 지원, 프록시, 안티-봇 우회와 같은 기능을 통해 복잡한 웹사이트도 처리할 수 있으며, 다양한 형식의 콘텐츠를 추출할 수 있습니다. 이 도구는 신뢰할 수 있는 웹 스크래핑이 필요한 데이터 추출, 콘텐츠 모니터링, 연구 작업에 특히 유용합니다.

195
docs/ko/tools/web-scraping/seleniumscrapingtool.mdx Normal file
View File

@@ -0,0 +1,195 @@
---
title: Selenium 스크래퍼
description: SeleniumScrapingTool은 Selenium을 사용하여 지정된 웹사이트의 콘텐츠를 추출하고 읽도록 설계되었습니다.
icon: clipboard-user
---
# `SeleniumScrapingTool`
<Note>
이 도구는 현재 개발 중입니다. 기능을 개선하는 과정에서 사용자께서 예기치 않은 동작을 경험하실 수 있습니다.
개선을 위한 소중한 피드백을 부탁드립니다.
</Note>
## 설명
`SeleniumScrapingTool`은 고효율 웹 스크래핑 작업을 위해 제작되었습니다.
이 도구는 CSS 선택자를 사용하여 웹 페이지에서 특정 요소를 정확하게 추출할 수 있습니다.
다양한 스크래핑 요구에 맞게 설계되어, 제공된 모든 웹사이트 URL과 함께 유연하게 작업할 수 있습니다.
## 설치
이 도구를 사용하려면 CrewAI tools 패키지와 Selenium을 설치해야 합니다:
```shell
pip install 'crewai[tools]'
uv add selenium webdriver-manager
```
또한 이 도구는 Chrome WebDriver를 사용하여 브라우저 자동화를 수행하므로, 시스템에 Chrome이 설치되어 있어야 합니다.
## 예시
다음 예시는 `SeleniumScrapingTool`을 CrewAI agent와 함께 사용하는 방법을 보여줍니다:
```python Code
from crewai import Agent, Task, Crew, Process
from crewai_tools import SeleniumScrapingTool
# Initialize the tool
selenium_tool = SeleniumScrapingTool()
# Define an agent that uses the tool
web_scraper_agent = Agent(
role="Web Scraper",
goal="Extract information from websites using Selenium",
backstory="An expert web scraper who can extract content from dynamic websites.",
tools=[selenium_tool],
verbose=True,
)
# Example task to scrape content from a website
scrape_task = Task(
description="Extract the main content from the homepage of example.com. Use the CSS selector 'main' to target the main content area.",
expected_output="The main content from example.com's homepage.",
agent=web_scraper_agent,
)
# Create and run the crew
crew = Crew(
agents=[web_scraper_agent],
tasks=[scrape_task],
verbose=True,
process=Process.sequential,
)
result = crew.kickoff()
```
도구를 미리 정의된 파라미터로 초기화할 수도 있습니다:
```python Code
# Initialize the tool with predefined parameters
selenium_tool = SeleniumScrapingTool(
website_url='https://example.com',
css_element='.main-content',
wait_time=5
)
# Define an agent that uses the tool
web_scraper_agent = Agent(
role="Web Scraper",
goal="Extract information from websites using Selenium",
backstory="An expert web scraper who can extract content from dynamic websites.",
tools=[selenium_tool],
verbose=True,
)
```
## 파라미터
`SeleniumScrapingTool`은(는) 초기화 시 다음과 같은 파라미터를 받습니다:
- **website_url**: 선택 사항. 스크래핑할 웹사이트의 URL입니다. 초기화 시 지정하면, 에이전트가 도구 사용 시 따로 지정할 필요가 없습니다.
- **css_element**: 선택 사항. 추출할 요소의 CSS 셀렉터입니다. 초기화 시 지정하면, 에이전트가 도구 사용 시 따로 지정할 필요가 없습니다.
- **cookie**: 선택 사항. 쿠키 정보가 담긴 딕셔너리로, 제한된 콘텐츠에 접근하기 위한 로그인 세션을 시뮬레이션하는 데 유용합니다.
- **wait_time**: 선택 사항. 스크래핑 전 대기 시간(초 단위)을 지정하며, 웹사이트와 모든 동적 콘텐츠가 완전히 로드되도록 합니다. 기본값은 `3`초입니다.
- **return_html**: 선택 사항. 단순 텍스트 대신 HTML 콘텐츠를 반환할지 여부를 지정합니다. 기본값은 `False`입니다.
에이전트와 함께 도구를 사용할 때, 다음 파라미터를 제공해야 합니다(초기화 시 이미 지정된 경우 제외):
- **website_url**: 필수. 스크래핑할 웹사이트의 URL입니다.
- **css_element**: 필수. 추출할 요소의 CSS 셀렉터입니다.
## 에이전트 통합 예시
여기서는 `SeleniumScrapingTool`을 CrewAI 에이전트와 통합하는 방법에 대해 더 자세히 설명합니다.
```python Code
from crewai import Agent, Task, Crew, Process
from crewai_tools import SeleniumScrapingTool
# Initialize the tool
selenium_tool = SeleniumScrapingTool()
# Define an agent that uses the tool
web_scraper_agent = Agent(
role="Web Scraper",
goal="Extract and analyze information from dynamic websites",
backstory="""You are an expert web scraper who specializes in extracting
content from dynamic websites that require browser automation. You have
extensive knowledge of CSS selectors and can identify the right selectors
to target specific content on any website.""",
tools=[selenium_tool],
verbose=True,
)
# Create a task for the agent
scrape_task = Task(
description="""
Extract the following information from the news website at {website_url}:
1. The headlines of all featured articles (CSS selector: '.headline')
2. The publication dates of these articles (CSS selector: '.pub-date')
3. The author names where available (CSS selector: '.author')
Compile this information into a structured format with each article's details grouped together.
""",
expected_output="A structured list of articles with their headlines, publication dates, and authors.",
agent=web_scraper_agent,
)
# Run the task
crew = Crew(
agents=[web_scraper_agent],
tasks=[scrape_task],
verbose=True,
process=Process.sequential,
)
result = crew.kickoff(inputs={"website_url": "https://news-example.com"})
```
## 구현 세부 사항
`SeleniumScrapingTool`은 Selenium WebDriver를 사용하여 브라우저 상호작용을 자동화합니다:
```python Code
class SeleniumScrapingTool(BaseTool):
name: str = "Read a website content"
description: str = "A tool that can be used to read a website content."
args_schema: Type[BaseModel] = SeleniumScrapingToolSchema
def _run(self, **kwargs: Any) -> Any:
website_url = kwargs.get("website_url", self.website_url)
css_element = kwargs.get("css_element", self.css_element)
return_html = kwargs.get("return_html", self.return_html)
driver = self._create_driver(website_url, self.cookie, self.wait_time)
content = self._get_content(driver, css_element, return_html)
driver.close()
return "\n".join(content)
```
이 도구는 다음과 같은 단계를 수행합니다:
1. Headless Chrome 브라우저 인스턴스를 생성합니다.
2. 지정된 URL로 이동합니다.
3. 페이지가 로드될 수 있도록 지정된 시간만큼 대기합니다.
4. 제공된 쿠키가 있다면 추가합니다.
5. CSS 선택자에 따라 콘텐츠를 추출합니다.
6. 추출된 콘텐츠를 텍스트 또는 HTML로 반환합니다.
7. 브라우저 인스턴스를 닫습니다.
## 동적 콘텐츠 처리
`SeleniumScrapingTool`은 JavaScript를 통해 로드되는 동적 콘텐츠가 있는 웹사이트를 스크래핑할 때 특히 유용합니다. 실제 브라우저 인스턴스를 사용함으로써 다음을 수행할 수 있습니다:
1. 페이지에서 JavaScript 실행
2. 동적 콘텐츠가 로드될 때까지 대기
3. 필요하다면 요소와 상호작용
4. 단순 HTTP 요청으로는 얻을 수 없는 콘텐츠 추출
모든 동적 콘텐츠가 추출 전에 로드되었는지 확인하기 위해 `wait_time` 파라미터를 조정할 수 있습니다.
## 결론
`SeleniumScrapingTool`은 브라우저 자동화를 활용하여 웹사이트에서 콘텐츠를 추출하는 강력한 방법을 제공합니다. 이 도구는 에이전트가 실제 사용자처럼 웹사이트와 상호작용할 수 있게 해주어, 간단한 방법으로는 추출이 어렵거나 불가능한 동적 콘텐츠의 스크래핑을 가능하게 합니다. 특히, JavaScript로 렌더링되는 현대적인 웹 애플리케이션을 대상으로 연구, 데이터 수집 및 모니터링 작업에 매우 유용합니다.

100
docs/ko/tools/web-scraping/serperscrapewebsitetool.mdx Normal file
View File

@@ -0,0 +1,100 @@
---
title: Serper 웹사이트 스크랩
description: SerperScrapeWebsiteTool은 Serper의 스크래핑 API를 사용하여 웹사이트를 스크랩하고 깔끔하고 읽기 쉬운 콘텐츠를 추출하도록 설계되었습니다.
icon: globe
---
# `SerperScrapeWebsiteTool`
## 설명
이 도구는 웹사이트의 콘텐츠를 스크랩하여 모든 웹사이트 URL에서 깔끔하고 읽기 쉬운 텍스트를 추출하도록 설계되었습니다. [serper.dev](https://serper.dev) 스크래핑 API를 활용하여 웹 페이지를 가져오고 처리하며, 선택적으로 더 나은 구조와 가독성을 위해 마크다운 형식을 포함할 수 있습니다.
## 설치
`SerperScrapeWebsiteTool`을 효과적으로 사용하려면 다음 단계를 따르세요:
1. **패키지 설치**: Python 환경에 `crewai[tools]` 패키지가 설치되어 있는지 확인합니다.
2. **API 키 획득**: `serper.dev`에 계정을 등록하여 `serper.dev` API 키를 획득합니다.
3. **환경 구성**: 획득한 API 키를 `SERPER_API_KEY`라는 환경 변수에 저장하여 도구에서 사용할 수 있도록 합니다.
이 도구를 프로젝트에 포함시키려면 아래 설치 안내를 따르세요:
```shell
pip install 'crewai[tools]'
```
## 예시
다음 예시는 도구를 초기화하고 웹사이트를 스크랩하는 방법을 보여줍니다:
```python Code
from crewai_tools import SerperScrapeWebsiteTool
# Initialize the tool for website scraping capabilities
tool = SerperScrapeWebsiteTool()
# Scrape a website with markdown formatting
result = tool.run(url="https://example.com", include_markdown=True)
```
## 인수
`SerperScrapeWebsiteTool`은 다음 인수를 허용합니다:
- **url**: 필수. 스크랩할 웹사이트의 URL입니다.
- **include_markdown**: 선택 사항. 스크랩된 콘텐츠에 마크다운 서식을 포함할지 여부입니다. 기본값은 `True`입니다.
## 매개변수와 함께 사용하는 예시
여기 다양한 매개변수와 함께 도구를 사용하는 방법을 보여주는 예시가 있습니다:
```python Code
from crewai_tools import SerperScrapeWebsiteTool
tool = SerperScrapeWebsiteTool()
# 마크다운 형식으로 스크레이프 (기본값)
markdown_result = tool.run(
url="https://docs.crewai.com",
include_markdown=True
)
# 일반 텍스트용 마크다운 미포함 스크레이프
plain_result = tool.run(
url="https://docs.crewai.com",
include_markdown=False
)
print("마크다운 형식의 콘텐츠:")
print(markdown_result)
print("\n일반 텍스트 콘텐츠:")
print(plain_result)
```
## 사용 사례
`SerperScrapeWebsiteTool`은 특히 다음과 같은 경우에 유용합니다:
- **콘텐츠 분석**: 연구 목적을 위해 웹사이트 콘텐츠를 추출하고 분석할 때
- **데이터 수집**: 웹 페이지에서 구조화된 정보를 수집할 때
- **문서 처리**: 웹 기반 문서를 읽기 쉬운 형식으로 변환할 때
- **경쟁사 분석**: 시장 조사를 위해 경쟁사 웹사이트를 스크래핑할 때
- **콘텐츠 마이그레이션**: 기존 웹사이트의 콘텐츠를 마이그레이션 목적으로 추출할 때
## 오류 처리
이 도구는 다음에 대한 포괄적인 오류 처리를 포함합니다:
- **네트워크 문제**: 연결 시간 초과 및 네트워크 오류를 원활하게 처리
- **API 오류**: API 관련 문제에 대한 자세한 오류 메시지 제공
- **잘못된 URL**: 잘못된 형식의 URL 문제를 검증 및 보고
- **인증**: 누락되었거나 잘못된 API 키에 대해 명확한 오류 메시지 제공
## 보안 고려사항
- `SERPER_API_KEY`는 항상 환경 변수에 저장하고, 소스 코드에 하드코딩하지 마세요.
- Serper API에서 부과하는 속도 제한을 유의하세요.
- 콘텐츠를 스크래핑할 때 robots.txt와 웹사이트 서비스 약관을 준수하세요.
- 대규모 스크래핑 작업 시 요청 간에 지연을 구현하는 것을 고려하세요.

91
docs/ko/tools/web-scraping/spidertool.mdx Normal file
View File

@@ -0,0 +1,91 @@
---
title: Spider 스크레이퍼
description: SpiderTool은 Spider를 사용하여 지정된 웹사이트의 콘텐츠를 추출하고 읽도록 설계되었습니다.
icon: spider-web
---
# `SpiderTool`
## 설명
[Spider](https://spider.cloud/?ref=crewai)는 [가장 빠른](https://github.com/spider-rs/spider/blob/main/benches/BENCHMARKS.md#benchmark-results) 오픈 소스 스크래퍼이자 크롤러로, LLM에 바로 사용할 수 있는 데이터를 제공합니다.
어떤 웹사이트든 순수 HTML, 마크다운, 메타데이터 또는 텍스트로 변환하며, AI를 활용해 사용자 정의 작업을 수행하며 크롤링할 수 있습니다.
## 설치
`SpiderTool`을 사용하려면 [Spider SDK](https://pypi.org/project/spider-client/)와 `crewai[tools]` SDK도 다운로드해야 합니다:
```shell
pip install spider-client 'crewai[tools]'
```
## 예제
이 예제는 에이전트가 `SpiderTool`을 사용하여 웹사이트를 스크래핑하고 크롤링할 수 있는 방법을 보여줍니다.
Spider API로부터 반환되는 데이터는 이미 LLM-적합 포맷이므로, 추가로 정제할 필요가 없습니다.
```python Code
from crewai_tools import SpiderTool
def main():
spider_tool = SpiderTool()
searcher = Agent(
role="Web Research Expert",
goal="Find related information from specific URL's",
backstory="An expert web researcher that uses the web extremely well",
tools=[spider_tool],
verbose=True,
)
return_metadata = Task(
description="Scrape https://spider.cloud with a limit of 1 and enable metadata",
expected_output="Metadata and 10 word summary of spider.cloud",
agent=searcher
)
crew = Crew(
agents=[searcher],
tasks=[
return_metadata,
],
verbose=2
)
crew.kickoff()
if __name__ == "__main__":
main()
```
## 인수
| 인수 | 타입 | 설명 |
|:---------------------|:----------|:------------------------------------------------------------------------------------------------------------------------------------------------------|
| **api_key** | `string` | Spider API 키를 지정합니다. 지정하지 않으면 환경 변수에서 `SPIDER_API_KEY`를 찾습니다. |
| **params** | `object` | 요청에 대한 선택적 매개변수입니다. 기본값은 `{"return_format": "markdown"}`로, LLM에 최적화되어 있습니다. |
| **request** | `string` | 수행할 요청 유형 (`http`, `chrome`, `smart`). `smart`는 기본적으로 HTTP를 사용하며, 필요시 JavaScript 렌더링으로 전환합니다. |
| **limit** | `int` | 웹사이트별로 크롤링할 최대 페이지 수입니다. `0` 또는 생략 시 무제한입니다. |
| **depth** | `int` | 최대 크롤링 깊이입니다. `0`으로 설정하면 제한이 없습니다. |
| **cache** | `bool` | 반복 실행 속도를 높이기 위한 HTTP 캐싱을 활성화합니다. 기본값은 `true`입니다. |
| **budget** | `object` | 크롤된 페이지의 경로 기반 제한을 설정합니다. 예: `{"*":1}` (루트 페이지만 크롤). |
| **locale** | `string` | 요청에 사용할 로케일입니다 (예: `en-US`). |
| **cookies** | `string` | 요청에 사용할 HTTP 쿠키입니다. |
| **stealth** | `bool` | Chrome 요청 시 감지 우회를 위한 스텔스 모드를 활성화합니다. 기본값은 `true`입니다. |
| **headers** | `object` | 모든 요청에 적용할 key-value 쌍의 HTTP 헤더입니다. |
| **metadata** | `bool` | 페이지 및 콘텐츠에 대한 메타데이터를 저장하여 AI 상호운용성을 지원합니다. 기본값은 `false`입니다. |
| **viewport** | `object` | Chrome 뷰포트 크기를 설정합니다. 기본값은 `800x600`입니다. |
| **encoding** | `string` | 인코딩 타입을 지정합니다. 예: `UTF-8`, `SHIFT_JIS`. |
| **subdomains** | `bool` | 크롤 시 서브도메인을 포함합니다. 기본값은 `false`입니다. |
| **user_agent** | `string` | 사용자 정의 HTTP user agent입니다. 기본값은 랜덤 agent입니다. |
| **store_data** | `bool` | 요청에 대한 데이터 저장을 활성화합니다. 설정 시 `storageless`를 무시합니다. 기본값은 `false`입니다. |
| **gpt_config** | `object` | AI가 크롤 액션을 생성할 수 있도록 하며, `"prompt"`에서 배열을 통한 단계적 체이닝도 지원합니다. |
| **fingerprint** | `bool` | Chrome을 위한 고급 지문 인식 기능을 활성화합니다. |
| **storageless** | `bool` | 모든 데이터 저장(예: AI 임베딩 포함)을 방지합니다. 기본값은 `false`입니다. |
| **readability** | `bool` | [Mozilla’s readability](https://github.com/mozilla/readability)를 통해 읽기 전용으로 콘텐츠를 전처리합니다. LLM에 알맞게 콘텐츠를 개선합니다. |
| **return_format** | `string` | 반환 데이터 포맷: `markdown`, `raw`, `text`, `html2text`. 페이지의 기본 형식을 원할 경우 `raw` 사용. |
| **proxy_enabled** | `bool` | 네트워크 레벨 차단을 피하기 위해 고성능 프록시를 활성화합니다. |
| **query_selector** | `string` | 마크업에서 콘텐츠 추출을 위한 CSS 쿼리 셀렉터입니다. |
| **full_resources** | `bool` | 웹사이트에 연결된 모든 자원을 다운로드합니다. |
| **request_timeout** | `int` | 요청의 타임아웃(초 단위, 5-60). 기본값은 `30`입니다. |
| **run_in_background** | `bool` | 요청을 백그라운드에서 실행하며, 데이터 저장 및 대시보드 크롤 트리거에 유용합니다. `storageless`가 설정된 경우 동작하지 않습니다. |

241
docs/ko/tools/web-scraping/stagehandtool.mdx Normal file
View File

@@ -0,0 +1,241 @@
---
title: Stagehand 도구
description: Stagehand를 CrewAI와 통합하여 브라우저 상호작용 및 자동화를 수행하는 웹 자동화 도구
icon: hand
---
# 개요
`StagehandTool`은 [Stagehand](https://docs.stagehand.dev/get_started/introduction) 프레임워크를 CrewAI와 통합하여 에이전트가 자연어 지시를 사용해 웹사이트와 상호작용하고 브라우저 작업을 자동화할 수 있도록 합니다.
## 개요
Stagehand는 Browserbase에서 개발한 강력한 브라우저 자동화 프레임워크로, AI 에이전트가 다음과 같은 작업을 수행할 수 있도록 합니다:
- 웹사이트 탐색
- 버튼, 링크, 기타 요소 클릭
- 폼 작성
- 웹 페이지에서 데이터 추출
- 요소 관찰 및 식별
- 복잡한 워크플로우 수행
StagehandTool은 Stagehand Python SDK를 감싸 CrewAI 에이전트에게 세 가지 핵심 원시 기능을 통해 브라우저 제어 능력을 제공합니다:
1. **Act**: 클릭, 입력, 탐색과 같은 액션 수행
2. **Extract**: 웹 페이지에서 구조화된 데이터 추출
3. **Observe**: 페이지의 요소 식별 및 분석
## 사전 준비 사항
이 도구를 사용하기 전에 다음을 확인하세요:
1. API 키와 프로젝트 ID가 있는 [Browserbase](https://www.browserbase.com/) 계정
2. LLM(OpenAI 또는 Anthropic Claude)용 API 키
3. Stagehand Python SDK 설치
필수 종속성을 설치하세요:
```bash
pip install stagehand-py
```
## 사용법
### 기본 구현
StagehandTool은 두 가지 방법으로 구현할 수 있습니다:
#### 1. 컨텍스트 매니저 사용하기 (권장)
<Tip>
컨텍스트 매니저 방식은 예외가 발생하더라도 리소스가 적절하게 정리되므로 권장됩니다.
</Tip>
```python
from crewai import Agent, Task, Crew
from crewai_tools import StagehandTool
from stagehand.schemas import AvailableModel
# Initialize the tool with your API keys using a context manager
with StagehandTool(
api_key="your-browserbase-api-key",
project_id="your-browserbase-project-id",
model_api_key="your-llm-api-key", # OpenAI 또는 Anthropic API 키
model_name=AvailableModel.CLAUDE_3_7_SONNET_LATEST, # 선택 사항: 사용할 모델 지정
) as stagehand_tool:
# Create an agent with the tool
researcher = Agent(
role="Web Researcher",
goal="Find and summarize information from websites",
backstory="I'm an expert at finding information online.",
verbose=True,
tools=[stagehand_tool],
)
# Create a task that uses the tool
research_task = Task(
description="Go to https://www.example.com and tell me what you see on the homepage.",
agent=researcher,
)
# Run the crew
crew = Crew(
agents=[researcher],
tasks=[research_task],
verbose=True,
)
result = crew.kickoff()
print(result)
```
#### 2. 수동 리소스 관리
```python
from crewai import Agent, Task, Crew
from crewai_tools import StagehandTool
from stagehand.schemas import AvailableModel
# Initialize the tool with your API keys
stagehand_tool = StagehandTool(
api_key="your-browserbase-api-key",
project_id="your-browserbase-project-id",
model_api_key="your-llm-api-key",
model_name=AvailableModel.CLAUDE_3_7_SONNET_LATEST,
)
try:
# Create an agent with the tool
researcher = Agent(
role="Web Researcher",
goal="Find and summarize information from websites",
backstory="I'm an expert at finding information online.",
verbose=True,
tools=[stagehand_tool],
)
# Create a task that uses the tool
research_task = Task(
description="Go to https://www.example.com and tell me what you see on the homepage.",
agent=researcher,
)
# Run the crew
crew = Crew(
agents=[researcher],
tasks=[research_task],
verbose=True,
)
result = crew.kickoff()
print(result)
finally:
# Explicitly clean up resources
stagehand_tool.close()
```
## 명령 유형
StagehandTool은 특정 웹 자동화 작업을 위한 세 가지 명령 유형을 지원합니다.
### 1. Act 명령어
`act` 명령어 유형(기본값)은 버튼 클릭, 양식 작성, 내비게이션과 같은 웹페이지 상호작용을 활성화합니다.
```python
# Perform an action (default behavior)
result = stagehand_tool.run(
instruction="Click the login button",
url="https://example.com",
command_type="act" # Default, so can be omitted
)
# Fill out a form
result = stagehand_tool.run(
instruction="Fill the contact form with name 'John Doe', email 'john@example.com', and message 'Hello world'",
url="https://example.com/contact"
)
```
### 2. 추출(Extract) 명령
`extract` 명령 유형은 웹페이지에서 구조화된 데이터를 가져옵니다.
```python
# 모든 상품 정보 추출
result = stagehand_tool.run(
instruction="Extract all product names, prices, and descriptions",
url="https://example.com/products",
command_type="extract"
)
# 선택자를 사용하여 특정 정보 추출
result = stagehand_tool.run(
instruction="Extract the main article title and content",
url="https://example.com/blog/article",
command_type="extract",
selector=".article-container" # 선택적 CSS 선택자
)
```
### 3. Observe 명령어
`observe` 명령어 유형은 웹페이지 요소를 식별하고 분석합니다.
```python
# 인터랙티브 요소 찾기
result = stagehand_tool.run(
instruction="Find all interactive elements in the navigation menu",
url="https://example.com",
command_type="observe"
)
# 폼 필드 식별
result = stagehand_tool.run(
instruction="Identify all the input fields in the registration form",
url="https://example.com/register",
command_type="observe",
selector="#registration-form"
)
```
## 구성 옵션
다음 매개변수로 StagehandTool의 동작을 사용자 지정할 수 있습니다:
```python
stagehand_tool = StagehandTool(
api_key="your-browserbase-api-key",
project_id="your-browserbase-project-id",
model_api_key="your-llm-api-key",
model_name=AvailableModel.CLAUDE_3_7_SONNET_LATEST,
dom_settle_timeout_ms=5000, # DOM이 안정될 때까지 더 오래 대기
headless=True, # 브라우저를 헤드리스 모드로 실행
self_heal=True, # 오류에서 복구를 시도
wait_for_captcha_solves=True, # CAPTCHA 해결을 기다림
verbose=1, # 로깅 상세 수준 제어 (0-3)
)
```
## 모범 사례
1. **구체적으로 작성하기**: 더 나은 결과를 위해 상세한 지침을 제공하세요
2. **적절한 명령 유형 선택**: 작업에 맞는 올바른 명령 유형을 선택하세요
3. **셀렉터 사용하기**: CSS 셀렉터를 활용하여 정확성을 높이세요
4. **복잡한 작업 분할**: 복잡한 작업 흐름을 여러 번의 도구 호출로 분할하세요
5. **오류 처리 구현**: 잠재적인 문제를 대비하여 오류 처리를 추가하세요
## 문제 해결
일반적인 문제 및 해결 방법:
- **세션 문제**: Browserbase와 LLM 공급자 모두의 API 키를 확인하세요.
- **요소를 찾을 수 없음**: 느린 페이지의 경우 `dom_settle_timeout_ms`를 늘리세요.
- **동작 실패**: 먼저 `observe`를 사용하여 올바른 요소를 식별하세요.
- **불완전한 데이터**: 지시사항을 개선하거나 구체적인 셀렉터를 제공하세요.
## 추가 자료
CrewAI 통합에 대한 질문이 있으신가요?
- Stagehand의 [Slack 커뮤니티](https://stagehand.dev/slack)에 참여하세요
- [Stagehand 저장소](https://github.com/browserbase/stagehand)에 이슈를 등록하세요
- [Stagehand 문서](https://docs.stagehand.dev/)를 방문하세요