andre/crewAI
1
0
Fork 0
mirror of https://github.com/crewAIInc/crewAI.git synced 2026-01-10 16:48:30 +00:00
Code Issues Actions 4 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

118
docs/ko/tools/ai-ml/aimindtool.mdx Normal file
View File

@@ -0,0 +1,118 @@
---
title: AI 마인드 툴
description: AIMindTool은 자연어로 데이터 소스를 질의하도록 설계되었습니다.
icon: brain
---
# `AIMindTool`
## 설명
`AIMindTool`은 [MindsDB](https://mindsdb.com/)에서 제공하는 [AI-Minds](https://mindsdb.com/minds)의 래퍼입니다. 이 도구를 사용하면 연결 매개변수만 구성하여 자연어로 데이터 소스를 쿼리할 수 있습니다. 이 도구는 PostgreSQL, MySQL, MariaDB, ClickHouse, Snowflake, Google BigQuery 등 다양한 데이터 소스에 저장된 데이터에서 질문에 대한 답변이 필요할 때 유용합니다.
Mind는 LLM(Large Language Model)과 유사하게 작동하는 AI 시스템이지만, 그 이상으로 모든 데이터에서 모든 질문에 답변할 수 있습니다. 이는 다음과 같이 달성됩니다:
- 파라메트릭 검색을 사용하여 답변에 가장 관련성 높은 데이터를 선택
- 의미론적 검색을 통해 의미를 이해하고 올바른 맥락에서 응답 제공
- 데이터를 분석하고 머신러닝(ML) 모델을 사용하여 정확한 답변 제공
## 설치
이 도구를 프로젝트에 통합하려면 Minds SDK를 설치해야 합니다:
```shell
uv add minds-sdk
```
## 시작 단계
`AIMindTool`을 효과적으로 사용하려면 다음 단계를 따르세요:
1. **패키지 설치**: Python 환경에 `crewai[tools]`와 `minds-sdk` 패키지가 설치되어 있는지 확인하세요.
2. **API 키 획득**: Minds 계정에 [여기](https://mdb.ai/register)에서 가입하고 API 키를 받으세요.
3. **환경 설정**: 획득한 API 키를 `MINDS_API_KEY`라는 환경 변수에 저장하여 툴이 사용할 수 있도록 하세요.
## 예시
다음 예시는 도구를 초기화하고 쿼리를 실행하는 방법을 보여줍니다:
```python Code
from crewai_tools import AIMindTool
# Initialize the AIMindTool
aimind_tool = AIMindTool(
datasources=[
{
"description": "house sales data",
"engine": "postgres",
"connection_data": {
"user": "demo_user",
"password": "demo_password",
"host": "samples.mindsdb.com",
"port": 5432,
"database": "demo",
"schema": "demo_data"
},
"tables": ["house_sales"]
}
]
)
# Run a natural language query
result = aimind_tool.run("How many 3 bedroom houses were sold in 2008?")
print(result)
```
## 매개변수
`AIMindTool`은 다음과 같은 매개변수를 허용합니다:
- **api_key**: 선택 사항입니다. 사용자의 Minds API 키입니다. 제공하지 않으면 `MINDS_API_KEY` 환경 변수에서 읽습니다.
- **datasources**: 각 항목에 다음 키를 포함하는 사전들의 목록입니다:
- **description**: 데이터 소스에 포함된 데이터에 대한 설명입니다.
- **engine**: 데이터 소스의 엔진(또는 유형)입니다.
- **connection_data**: 데이터 소스의 연결 매개변수를 포함하는 사전입니다.
- **tables**: 데이터 소스에서 사용할 테이블 목록입니다. 이 항목은 선택 사항이며, 데이터 소스의 모든 테이블을 사용할 경우 생략할 수 있습니다.
지원되는 데이터 소스와 그 연결 매개변수 목록은 [여기](https://docs.mdb.ai/docs/data_sources)에서 확인할 수 있습니다.
## 에이전트 통합 예시
다음은 `AIMindTool`을 CrewAI 에이전트와 통합하는 방법입니다:
```python Code
from crewai import Agent
from crewai.project import agent
from crewai_tools import AIMindTool
# Initialize the tool
aimind_tool = AIMindTool(
datasources=[
{
"description": "sales data",
"engine": "postgres",
"connection_data": {
"user": "your_user",
"password": "your_password",
"host": "your_host",
"port": 5432,
"database": "your_db",
"schema": "your_schema"
},
"tables": ["sales"]
}
]
)
# Define an agent with the AIMindTool
@agent
def data_analyst(self) -> Agent:
return Agent(
config=self.agents_config["data_analyst"],
allow_delegation=False,
tools=[aimind_tool]
)
```
## 결론
`AIMindTool`은 자연어를 사용하여 데이터 소스를 쿼리할 수 있는 강력한 방법을 제공하여 복잡한 SQL 쿼리를 작성하지 않고도 인사이트를 쉽게 추출할 수 있도록 해줍니다. 다양한 데이터 소스에 연결하고 AI-Minds 기술을 활용하여 이 도구는 agent들이 데이터를 효율적으로 접근하고 분석할 수 있게 해줍니다.

208
docs/ko/tools/ai-ml/codeinterpretertool.mdx Normal file
View File

@@ -0,0 +1,208 @@
---
title: 코드 인터프리터
description: CodeInterpreterTool은(는) 안전하고 격리된 환경 내에서 Python 3 코드를 실행하도록 설계된 강력한 도구입니다.
icon: code-simple
---
# `CodeInterpreterTool`
## 설명
`CodeInterpreterTool`은 CrewAI 에이전트가 자율적으로 생성한 Python 3 코드를 실행할 수 있도록 합니다. 이 기능은 에이전트가 코드를 생성하고, 실행하며, 결과를 얻고, 그 정보를 활용하여 이후의 결정과 행동에 반영할 수 있다는 점에서 특히 유용합니다.
이 도구를 사용하는 방법에는 여러 가지가 있습니다:
### Docker 컨테이너(권장)
이것이 기본 옵션입니다. 코드는 안전하고 격리된 Docker 컨테이너에서 실행되어, 그 내용과 상관없이 안전성을 보장합니다.
시스템에 Docker가 설치되어 실행 중인지 확인하세요. 설치되어 있지 않다면, [여기](https://docs.docker.com/get-docker/)에서 설치할 수 있습니다.
### 샌드박스 환경
Docker를 사용할 수 없을 경우—설치되어 있지 않거나 어떤 이유로든 접근할 수 없는 경우—코드는 샌드박스라고 불리는 제한된 Python 환경에서 실행됩니다.
이 환경은 매우 제한적이며, 많은 모듈과 내장 함수들에 대해 엄격한 제한이 있습니다.
### 비안전 실행
**프로덕션 환경에서는 권장하지 않음**
이 모드는 `sys, os..` 및 유사한 모듈에 대한 위험한 호출을 포함하여 모든 Python 코드를 실행할 수 있게 합니다. [비안전 모드 활성화 방법](/ko/tools/ai-ml/codeinterpretertool#enabling-unsafe-mode)를 확인하세요
## 로깅
`CodeInterpreterTool`은 선택된 실행 전략을 STDOUT에 기록합니다.
## 설치
이 도구를 사용하려면 CrewAI tools 패키지를 설치해야 합니다:
```shell
pip install 'crewai[tools]'
```
## 예시
다음 예시는 `CodeInterpreterTool`을 CrewAI agent와 함께 사용하는 방법을 보여줍니다:
```python Code
from crewai import Agent, Task, Crew, Process
from crewai_tools import CodeInterpreterTool
# Initialize the tool
code_interpreter = CodeInterpreterTool()
# Define an agent that uses the tool
programmer_agent = Agent(
role="Python Programmer",
goal="Write and execute Python code to solve problems",
backstory="An expert Python programmer who can write efficient code to solve complex problems.",
tools=[code_interpreter],
verbose=True,
)
# Example task to generate and execute code
coding_task = Task(
description="Write a Python function to calculate the Fibonacci sequence up to the 10th number and print the result.",
expected_output="The Fibonacci sequence up to the 10th number.",
agent=programmer_agent,
)
# Create and run the crew
crew = Crew(
agents=[programmer_agent],
tasks=[coding_task],
verbose=True,
process=Process.sequential,
)
result = crew.kickoff()
```
agent를 생성할 때 코드 실행을 직접 활성화할 수도 있습니다:
```python Code
from crewai import Agent
# Create an agent with code execution enabled
programmer_agent = Agent(
role="Python Programmer",
goal="Write and execute Python code to solve problems",
backstory="An expert Python programmer who can write efficient code to solve complex problems.",
allow_code_execution=True, # This automatically adds the CodeInterpreterTool
verbose=True,
)
```
### `unsafe_mode` 활성화
```python Code
from crewai_tools import CodeInterpreterTool
code = """
import os
os.system("ls -la")
"""
CodeInterpreterTool(unsafe_mode=True).run(code=code)
```
## 파라미터
`CodeInterpreterTool`은(는) 초기화 시 다음과 같은 파라미터를 허용합니다:
- **user_dockerfile_path**: 선택 사항. 코드 인터프리터 컨테이너에서 사용할 커스텀 Dockerfile의 경로입니다.
- **user_docker_base_url**: 선택 사항. 컨테이너 실행에 사용할 Docker 데몬의 URL입니다.
- **unsafe_mode**: 선택 사항. Docker 컨테이너나 샌드박스 대신 코드가 호스트 머신에서 직접 실행될지 여부입니다. 기본값은 `False`입니다. 주의해서 사용하세요!
- **default_image_tag**: 선택 사항. 기본 Docker 이미지 태그입니다. 기본값은 `code-interpreter:latest`입니다.
에이전트와 함께 이 도구를 사용할 때 에이전트는 다음을 제공해야 합니다:
- **code**: 필수. 실행할 Python 3 코드입니다.
- **libraries_used**: 선택 사항. 코드에서 사용하여 설치가 필요한 라이브러리들의 목록입니다. 기본값은 `[]`입니다.
## 에이전트 통합 예제
여기 `CodeInterpreterTool`을 CrewAI 에이전트와 통합하는 방법에 대한 좀 더 자세한 예제가 있습니다:
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import CodeInterpreterTool
# Initialize the tool
code_interpreter = CodeInterpreterTool()
# Define an agent that uses the tool
data_analyst = Agent(
role="Data Analyst",
goal="Analyze data using Python code",
backstory="""You are an expert data analyst who specializes in using Python
to analyze and visualize data. You can write efficient code to process
large datasets and extract meaningful insights.""",
tools=[code_interpreter],
verbose=True,
)
# Create a task for the agent
analysis_task = Task(
description="""
Write Python code to:
1. Generate a random dataset of 100 points with x and y coordinates
2. Calculate the correlation coefficient between x and y
3. Create a scatter plot of the data
4. Print the correlation coefficient and save the plot as 'scatter.png'
Make sure to handle any necessary imports and print the results.
""",
expected_output="The correlation coefficient and confirmation that the scatter plot has been saved.",
agent=data_analyst,
)
# Run the task
crew = Crew(
agents=[data_analyst],
tasks=[analysis_task],
verbose=True,
process=Process.sequential,
)
result = crew.kickoff()
```
## 구현 세부사항
`CodeInterpreterTool`은 코드 실행을 위한 안전한 환경을 만들기 위해 Docker를 사용합니다:
```python Code
class CodeInterpreterTool(BaseTool):
name: str = "Code Interpreter"
description: str = "Interprets Python3 code strings with a final print statement."
args_schema: Type[BaseModel] = CodeInterpreterSchema
default_image_tag: str = "code-interpreter:latest"
def _run(self, **kwargs) -> str:
code = kwargs.get("code", self.code)
libraries_used = kwargs.get("libraries_used", [])
if self.unsafe_mode:
return self.run_code_unsafe(code, libraries_used)
else:
return self.run_code_safety(code, libraries_used)
```
이 도구는 다음과 같은 단계를 수행합니다:
1. Docker 이미지가 존재하는지 확인하거나 필요 시 이미지를 빌드합니다
2. 현재 작업 디렉토리가 마운트된 Docker 컨테이너를 생성합니다
3. 에이전트가 지정한 필요한 라이브러리를 설치합니다
4. 컨테이너 내에서 Python 코드를 실행합니다
5. 코드 실행 결과를 반환합니다
6. 컨테이너를 중지하고 제거하여 정리합니다
## 보안 고려사항
기본적으로 `CodeInterpreterTool`은 코드를 격리된 Docker 컨테이너에서 실행하며, 이는 하나의 보안 계층을 제공합니다. 그러나 다음과 같은 보안 사항들을 염두에 두어야 합니다:
1. Docker 컨테이너는 현재 작업 디렉토리에 접근할 수 있으므로, 민감한 파일이 잠재적으로 접근될 수 있습니다.
2. Docker 컨테이너를 사용할 수 없고 코드를 안전하게 실행해야 하는 경우, 샌드박스 환경에서 실행됩니다. 보안상의 이유로 임의의 라이브러리 설치는 허용되지 않습니다.
3. `unsafe_mode` 매개변수를 사용하면 코드를 호스트 머신에서 직접 실행할 수 있으며, 이는 신뢰할 수 있는 환경에서만 사용해야 합니다.
4. 에이전트가 임의의 라이브러리를 설치하도록 허용할 때는 주의해야 하며, 악성 코드가 포함될 가능성이 있습니다.
## 결론
`CodeInterpreterTool`은 CrewAI 에이전트가 비교적 안전한 환경에서 Python 코드를 실행할 수 있는 강력한 방법을 제공합니다. 에이전트가 코드를 작성하고 실행할 수 있도록 함으로써, 데이터 분석, 계산 또는 기타 계산 작업이 포함된 작업에서 특히 문제 해결 능력을 크게 확장합니다. 이 도구는 복잡한 연산을 자연어보다 코드로 표현하는 것이 더 효율적인 경우에 작업을 수행해야 하는 에이전트에게 특히 유용합니다.

50
docs/ko/tools/ai-ml/dalletool.mdx Normal file
View File

@@ -0,0 +1,50 @@
---
title: DALL-E 도구
description: DallETool은(는) 텍스트 설명으로부터 이미지를 생성할 수 있도록 설계된 강력한 도구입니다.
icon: image
---
# `DallETool`
## 설명
이 도구는 Agent가 DALL-E 모델을 사용하여 이미지를 생성할 수 있는 기능을 제공합니다. 이는 텍스트 설명으로부터 이미지를 생성하는 트랜스포머 기반 모델입니다.
이 도구를 통해 사용자가 제공한 텍스트 입력을 바탕으로 Agent가 이미지를 생성할 수 있습니다.
## 설치
crewai_tools 패키지를 설치하세요
```shell
pip install 'crewai[tools]'
```
## 예시
이 도구를 사용할 때는 텍스트가 반드시 Agent 자체에 의해 생성되어야 합니다. 텍스트는 생성하려는 이미지에 대한 설명이어야 합니다.
```python Code
from crewai_tools import DallETool
Agent(
...
tools=[DallETool()],
)
```
필요하다면 `DallETool` 클래스에 인자를 전달하여 DALL-E 모델의 파라미터를 조정할 수도 있습니다. 예를 들면 다음과 같습니다:
```python Code
from crewai_tools import DallETool
dalle_tool = DallETool(model="dall-e-3",
size="1024x1024",
quality="standard",
n=1)
Agent(
...
tools=[dalle_tool]
)
```
파라미터는 OpenAI API의 `client.images.generate` 메서드를 기반으로 합니다. 파라미터에 대한 자세한 내용은 [OpenAI API 문서](https://platform.openai.com/docs/guides/images/introduction?lang=python)를 참고하세요.

56
docs/ko/tools/ai-ml/langchaintool.mdx Normal file
View File

@@ -0,0 +1,56 @@
---
title: LangChain 도구
description: LangChainTool은 LangChain 도구 및 쿼리 엔진을 위한 래퍼(wrapper)입니다.
icon: link
---
## `LangChainTool`
<Info>
CrewAI는 LangChain의 포괄적인 [도구 목록](https://python.langchain.com/docs/integrations/tools/)과 원활하게 통합되며, 이 모든 도구들은 CrewAI와 함께 사용할 수 있습니다.
</Info>
```python Code
import os
from dotenv import load_dotenv
from crewai import Agent, Task, Crew
from crewai.tools import BaseTool
from pydantic import Field
from langchain_community.utilities import GoogleSerperAPIWrapper
# Set up your SERPER_API_KEY key in an .env file, eg:
# SERPER_API_KEY=<your api key>
load_dotenv()
search = GoogleSerperAPIWrapper()
class SearchTool(BaseTool):
name: str = "Search"
description: str = "Useful for search-based queries. Use this to find current information about markets, companies, and trends."
search: GoogleSerperAPIWrapper = Field(default_factory=GoogleSerperAPIWrapper)
def _run(self, query: str) -> str:
"""Execute the search query and return results"""
try:
return self.search.run(query)
except Exception as e:
return f"Error performing search: {str(e)}"
# Create Agents
researcher = Agent(
role='Research Analyst',
goal='Gather current market data and trends',
backstory="""You are an expert research analyst with years of experience in
gathering market intelligence. You're known for your ability to find
relevant and up-to-date market information and present it in a clear,
actionable format.""",
tools=[SearchTool()],
verbose=True
)
# rest of the code ...
```
## 결론
도구는 CrewAI agent의 역량을 확장하는 데 핵심적인 역할을 하며, 다양한 작업을 수행하고 효과적으로 협업할 수 있도록 합니다. CrewAI로 솔루션을 구축할 때는 맞춤형 도구와 기존 도구를 모두 활용하여 agent를 강화하고 AI 생태계를 향상시키세요. 에러 처리, 캐싱 메커니즘, 그리고 도구 인자(argument)의 유연성 등을 활용하여 agent의 성능과 역량을 최적화하는 것을 고려해야 합니다.

146
docs/ko/tools/ai-ml/llamaindextool.mdx Normal file
View File

@@ -0,0 +1,146 @@
---
title: LlamaIndex 도구
description: LlamaIndexTool은 LlamaIndex 도구와 쿼리 엔진의 래퍼입니다.
icon: address-book
---
# `LlamaIndexTool`
## 설명
`LlamaIndexTool`은 LlamaIndex 도구 및 쿼리 엔진에 대한 일반적인 래퍼로 설계되어, LlamaIndex 리소스를 RAG/agentic 파이프라인의 도구로 활용하여 CrewAI 에이전트에 연동할 수 있도록 합니다. 이 도구를 통해 LlamaIndex의 강력한 데이터 처리 및 검색 기능을 CrewAI 워크플로우에 원활하게 통합할 수 있습니다.
## 설치
이 도구를 사용하려면 LlamaIndex를 설치해야 합니다:
```shell
uv add llama-index
```
## 시작하는 단계
`LlamaIndexTool`을 효과적으로 사용하려면 다음 단계를 따르세요:
1. **LlamaIndex 설치**: 위의 명령어를 사용하여 LlamaIndex 패키지를 설치하세요.
2. **LlamaIndex 설정**: [LlamaIndex 문서](https://docs.llamaindex.ai/)를 참고하여 RAG/에이전트 파이프라인을 설정하세요.
3. **도구 또는 쿼리 엔진 생성**: CrewAI와 함께 사용할 LlamaIndex 도구 또는 쿼리 엔진을 생성하세요.
## 예시
다음 예시들은 다양한 LlamaIndex 컴포넌트에서 도구를 초기화하는 방법을 보여줍니다:
### LlamaIndex Tool에서
```python Code
from crewai_tools import LlamaIndexTool
from crewai import Agent
from llama_index.core.tools import FunctionTool
# Example 1: Initialize from FunctionTool
def search_data(query: str) -> str:
"""Search for information in the data."""
# Your implementation here
return f"Results for: {query}"
# Create a LlamaIndex FunctionTool
og_tool = FunctionTool.from_defaults(
search_data,
name="DataSearchTool",
description="Search for information in the data"
)
# Wrap it with LlamaIndexTool
tool = LlamaIndexTool.from_tool(og_tool)
# Define an agent that uses the tool
@agent
def researcher(self) -> Agent:
'''
This agent uses the LlamaIndexTool to search for information.
'''
return Agent(
config=self.agents_config["researcher"],
tools=[tool]
)
```
### LlamaHub 도구에서
```python Code
from crewai_tools import LlamaIndexTool
from llama_index.tools.wolfram_alpha import WolframAlphaToolSpec
# Initialize from LlamaHub Tools
wolfram_spec = WolframAlphaToolSpec(app_id="your_app_id")
wolfram_tools = wolfram_spec.to_tool_list()
tools = [LlamaIndexTool.from_tool(t) for t in wolfram_tools]
```
### LlamaIndex 쿼리 엔진에서
```python Code
from crewai_tools import LlamaIndexTool
from llama_index.core import VectorStoreIndex
from llama_index.core.readers import SimpleDirectoryReader
# Load documents
documents = SimpleDirectoryReader("./data").load_data()
# Create an index
index = VectorStoreIndex.from_documents(documents)
# Create a query engine
query_engine = index.as_query_engine()
# Create a LlamaIndexTool from the query engine
query_tool = LlamaIndexTool.from_query_engine(
query_engine,
name="Company Data Query Tool",
description="Use this tool to lookup information in company documents"
)
```
## 클래스 메서드
`LlamaIndexTool`은 인스턴스를 생성하기 위한 두 가지 주요 클래스 메서드를 제공합니다:
### from_tool
LlamaIndex tool에서 `LlamaIndexTool`을 생성합니다.
```python Code
@classmethod
def from_tool(cls, tool: Any, **kwargs: Any) -> "LlamaIndexTool":
# Implementation details
```
### from_query_engine
LlamaIndex query engine에서 `LlamaIndexTool`을 생성합니다.
```python Code
@classmethod
def from_query_engine(
cls,
query_engine: Any,
name: Optional[str] = None,
description: Optional[str] = None,
return_direct: bool = False,
**kwargs: Any,
) -> "LlamaIndexTool":
# Implementation details
```
## 파라미터
`from_query_engine` 메서드는 다음과 같은 파라미터를 받습니다:
- **query_engine**: 필수. 래핑할 LlamaIndex 쿼리 엔진입니다.
- **name**: 선택 사항. 도구의 이름입니다.
- **description**: 선택 사항. 도구의 설명입니다.
- **return_direct**: 선택 사항. 응답을 직접 반환할지 여부입니다. 기본값은 `False`입니다.
## 결론
`LlamaIndexTool`은 LlamaIndex의 기능을 CrewAI 에이전트에 통합할 수 있는 강력한 방법을 제공합니다. LlamaIndex 도구와 쿼리 엔진을 래핑함으로써, 에이전트가 정교한 데이터 검색 및 처리 기능을 활용할 수 있게 하여, 복잡한 정보 소스를 다루는 능력을 강화합니다.

63
docs/ko/tools/ai-ml/overview.mdx Normal file
View File

@@ -0,0 +1,63 @@
---
title: "개요"
description: "AI 서비스를 활용하고, 이미지를 생성하며, 비전 처리를 수행하고, 지능형 시스템을 구축합니다"
icon: "face-smile"
---
이러한 도구들은 AI 및 머신러닝 서비스와 통합되어 이미지 생성, 비전 처리, 지능형 코드 실행과 같은 고급 기능으로 에이전트를 강화합니다.
## **사용 가능한 도구**
<CardGroup cols={2}>
<Card title="DALL-E 도구" icon="image" href="/ko/tools/ai-ml/dalletool">
OpenAI의 DALL-E 모델을 사용하여 AI 이미지를 생성합니다.
</Card>
<Card title="Vision 도구" icon="eye" href="/ko/tools/ai-ml/visiontool">
컴퓨터 비전 기능으로 이미지를 처리하고 분석합니다.
</Card>
<Card title="AI Mind 도구" icon="brain" href="/ko/tools/ai-ml/aimindtool">
고급 AI 추론 및 의사결정 기능을 제공합니다.
</Card>
<Card title="LlamaIndex 도구" icon="llama" href="/ko/tools/ai-ml/llamaindextool">
LlamaIndex로 지식 베이스 및 검색 시스템을 구축합니다.
</Card>
<Card title="LangChain 도구" icon="link" href="/ko/tools/ai-ml/langchaintool">
LangChain과 통합하여 복잡한 AI 워크플로우를 구현합니다.
</Card>
<Card title="RAG 도구" icon="database" href="/ko/tools/ai-ml/ragtool">
Retrieval-Augmented Generation 시스템을 구현합니다.
</Card>
<Card title="Code Interpreter 도구" icon="code" href="/ko/tools/ai-ml/codeinterpretertool">
Python 코드를 실행하고 데이터 분석을 수행합니다.
</Card>
</CardGroup>
## **일반적인 사용 사례**
- **콘텐츠 생성**: 이미지, 텍스트, 멀티미디어 콘텐츠 생성
- **데이터 분석**: 코드 실행 및 복잡한 데이터셋 분석
- **지식 시스템**: RAG 시스템 및 지능형 데이터베이스 구축
- **컴퓨터 비전**: 시각적 콘텐츠 처리 및 이해
- **AI 안전성**: 콘텐츠 모더레이션 및 안전성 점검 구현
```python
from crewai_tools import DallETool, VisionTool, CodeInterpreterTool
# Create AI tools
image_generator = DallETool()
vision_processor = VisionTool()
code_executor = CodeInterpreterTool()
# Add to your agent
agent = Agent(
role="AI Specialist",
tools=[image_generator, vision_processor, code_executor],
goal="Create and analyze content using AI capabilities"
)
```

172
docs/ko/tools/ai-ml/ragtool.mdx Normal file
View File

@@ -0,0 +1,172 @@
---
title: RAG 도구
description: RagTool은 Retrieval-Augmented Generation을 사용하여 질문에 답변하는 동적 지식 기반 도구입니다.
icon: vector-square
---
# `RagTool`
## 설명
`RagTool`은 EmbedChain을 통한 RAG(Retrieval-Augmented Generation)의 강력함을 활용하여 질문에 답하도록 설계되었습니다.
이는 다양한 데이터 소스에서 관련 정보를 검색할 수 있는 동적 지식 기반을 제공합니다.
이 도구는 방대한 정보에 접근해야 하고 맥락에 맞는 답변을 제공해야 하는 애플리케이션에 특히 유용합니다.
## 예시
다음 예시는 도구를 초기화하고 다양한 데이터 소스와 함께 사용하는 방법을 보여줍니다:
```python Code
from crewai_tools import RagTool
# Create a RAG tool with default settings
rag_tool = RagTool()
# Add content from a file
rag_tool.add(data_type="file", path="path/to/your/document.pdf")
# Add content from a web page
rag_tool.add(data_type="web_page", url="https://example.com")
# Define an agent with the RagTool
@agent
def knowledge_expert(self) -> Agent:
'''
This agent uses the RagTool to answer questions about the knowledge base.
'''
return Agent(
config=self.agents_config["knowledge_expert"],
allow_delegation=False,
tools=[rag_tool]
)
```
## 지원되는 데이터 소스
`RagTool`은 다양한 데이터 소스와 함께 사용할 수 있습니다. 예를 들어:
- 📰 PDF 파일
- 📊 CSV 파일
- 📃 JSON 파일
- 📝 텍스트
- 📁 디렉터리/폴더
- 🌐 HTML 웹 페이지
- 📽️ YouTube 채널
- 📺 YouTube 동영상
- 📚 문서화 웹사이트
- 📝 MDX 파일
- 📄 DOCX 파일
- 🧾 XML 파일
- 📬 Gmail
- 📝 GitHub 저장소
- 🐘 PostgreSQL 데이터베이스
- 🐬 MySQL 데이터베이스
- 🤖 Slack 대화
- 💬 Discord 메시지
- 🗨️ Discourse 포럼
- 📝 Substack 뉴스레터
- 🐝 Beehiiv 콘텐츠
- 💾 Dropbox 파일
- 🖼️ 이미지
- ⚙️ 사용자 정의 데이터 소스
## 매개변수
`RagTool`은 다음과 같은 매개변수를 허용합니다:
- **summarize**: 선택 사항. 검색된 콘텐츠를 요약할지 여부입니다. 기본값은 `False`입니다.
- **adapter**: 선택 사항. 지식 베이스에 대한 사용자 지정 어댑터입니다. 제공되지 않은 경우 EmbedchainAdapter가 사용됩니다.
- **config**: 선택 사항. 내부 EmbedChain App의 구성입니다.
## 콘텐츠 추가
`add` 메서드를 사용하여 지식 베이스에 콘텐츠를 추가할 수 있습니다:
```python Code
# PDF 파일 추가
rag_tool.add(data_type="file", path="path/to/your/document.pdf")
# 웹 페이지 추가
rag_tool.add(data_type="web_page", url="https://example.com")
# YouTube 비디오 추가
rag_tool.add(data_type="youtube_video", url="https://www.youtube.com/watch?v=VIDEO_ID")
# 파일이 있는 디렉터리 추가
rag_tool.add(data_type="directory", path="path/to/your/directory")
```
## 에이전트 통합 예시
아래는 `RagTool`을 CrewAI 에이전트와 통합하는 방법입니다:
```python Code
from crewai import Agent
from crewai.project import agent
from crewai_tools import RagTool
# Initialize the tool and add content
rag_tool = RagTool()
rag_tool.add(data_type="web_page", url="https://docs.crewai.com")
rag_tool.add(data_type="file", path="company_data.pdf")
# Define an agent with the RagTool
@agent
def knowledge_expert(self) -> Agent:
return Agent(
config=self.agents_config["knowledge_expert"],
allow_delegation=False,
tools=[rag_tool]
)
```
## 고급 구성
`RagTool`의 동작을 구성 사전을 제공하여 사용자 지정할 수 있습니다.
```python Code
from crewai_tools import RagTool
# 사용자 지정 구성으로 RAG 도구 생성
config = {
"app": {
"name": "custom_app",
},
"llm": {
"provider": "openai",
"config": {
"model": "gpt-4",
}
},
"embedding_model": {
"provider": "openai",
"config": {
"model": "text-embedding-ada-002"
}
},
"vectordb": {
"provider": "elasticsearch",
"config": {
"collection_name": "my-collection",
"cloud_id": "deployment-name:xxxx",
"api_key": "your-key",
"verify_certs": False
}
},
"chunker": {
"chunk_size": 400,
"chunk_overlap": 100,
"length_function": "len",
"min_chunk_size": 0
}
}
rag_tool = RagTool(config=config, summarize=True)
```
내부 RAG 도구는 Embedchain 어댑터를 사용하므로 Embedchain에서 지원하는 모든 구성 옵션을 전달할 수 있습니다.
자세한 내용은 [Embedchain 문서](https://docs.embedchain.ai/components/introduction)를 참조하세요.
.yaml 파일에서 제공되는 구성 옵션을 반드시 검토하시기 바랍니다.
## 결론
`RagTool`은 다양한 데이터 소스에서 지식 베이스를 생성하고 질의할 수 있는 강력한 방법을 제공합니다. Retrieval-Augmented Generation을 활용하여, 에이전트가 관련 정보를 효율적으로 접근하고 검색할 수 있게 하여, 보다 정확하고 상황에 맞는 응답을 제공하는 능력을 향상시킵니다.

49
docs/ko/tools/ai-ml/visiontool.mdx Normal file
View File

@@ -0,0 +1,49 @@
---
title: 비전 도구
description: VisionTool은 이미지에서 텍스트를 추출하도록 설계되었습니다.
icon: eye
---
# `VisionTool`
## 설명
이 도구는 이미지에서 텍스트를 추출하는 데 사용됩니다. 에이전트에 전달되면 이미지에서 텍스트를 추출한 후 이를 사용하여 응답, 보고서 또는 기타 출력을 생성합니다.
이미지의 URL 또는 경로(PATH)를 에이전트에 전달해야 합니다.
## 설치
crewai_tools 패키지를 설치하세요
```shell
pip install 'crewai[tools]'
```
## 사용법
VisionTool을 사용하려면 OpenAI API 키를 환경 변수 `OPENAI_API_KEY`에 설정해야 합니다.
```python Code
from crewai_tools import VisionTool
vision_tool = VisionTool()
@agent
def researcher(self) -> Agent:
'''
이 agent는 VisionTool을 사용하여 이미지에서 텍스트를 추출합니다.
'''
return Agent(
config=self.agents_config["researcher"],
allow_delegation=False,
tools=[vision_tool]
)
```
## 인수
VisionTool은 다음과 같은 인수가 필요합니다:
| 인수 | 타입 | 설명 |
| :------------------ | :------- | :-------------------------------------------------------------------------------- |
| **image_path_url** | `string` | **필수**. 텍스트를 추출해야 하는 이미지 파일의 경로입니다. |

99
docs/ko/tools/automation/apifyactorstool.mdx Normal file
View File

@@ -0,0 +1,99 @@
---
title: Apify 액터
description: "`ApifyActorsTool`을(를) 사용하면 Apify 액터를 호출하여 CrewAI 워크플로우에 웹 스크래핑, 크롤링, 데이터 추출 및 웹 자동화 기능을 제공할 수 있습니다."
# hack to use custom Apify icon
icon: "); -webkit-mask-image: url('https://upload.wikimedia.org/wikipedia/commons/a/ae/Apify.svg');/*"
---
# `ApifyActorsTool`
[Apify Actors](https://apify.com/actors)를 CrewAI 워크플로우에 통합합니다.
## 설명
`ApifyActorsTool`은 [Apify Actors](https://apify.com/actors)와 CrewAI 워크플로우를 연결합니다. Apify Actors는 웹 스크래핑 및 자동화를 위한 클라우드 기반 프로그램입니다.
[Apify Store](https://apify.com/store)에 있는 4,000개 이상의 Actor를 활용하여 소셜 미디어, 검색 엔진, 온라인 지도, 이커머스 사이트, 여행 포털 또는 일반 웹사이트에서 데이터를 추출하는 등 다양한 용도로 사용할 수 있습니다.
자세한 내용은 Apify 문서의 [Apify CrewAI 통합](https://docs.apify.com/platform/integrations/crewai)을 참조하세요.
## 시작 단계
<Steps>
<Step title="의존성 설치">
`crewai[tools]`와 `langchain-apify`를 pip으로 설치하세요: `pip install 'crewai[tools]' langchain-apify`.
</Step>
<Step title="Apify API 토큰 받기">
[Apify Console](https://console.apify.com/)에 회원가입하고 [Apify API 토큰](https://console.apify.com/settings/integrations)을 받아주세요.
</Step>
<Step title="환경 구성">
Apify API 토큰을 `APIFY_API_TOKEN` 환경 변수로 설정해 도구의 기능을 활성화하세요.
</Step>
</Steps>
## 사용 예시
`ApifyActorsTool`을 수동으로 사용하여 [RAG Web Browser Actor](https://apify.com/apify/rag-web-browser)를 실행하고 웹 검색을 수행할 수 있습니다:
```python
from crewai_tools import ApifyActorsTool
# Initialize the tool with an Apify Actor
tool = ApifyActorsTool(actor_name="apify/rag-web-browser")
# Run the tool with input parameters
results = tool.run(run_input={"query": "What is CrewAI?", "maxResults": 5})
# Process the results
for result in results:
print(f"URL: {result['metadata']['url']}")
print(f"Content: {result.get('markdown', 'N/A')[:100]}...")
```
### 예상 출력
위의 코드를 실행했을 때의 출력은 다음과 같습니다:
```text
URL: https://www.example.com/crewai-intro
Content: CrewAI is a framework for building AI-powered workflows...
URL: https://docs.crewai.com/
Content: Official documentation for CrewAI...
```
`ApifyActorsTool`은 제공된 `actor_name`을 사용하여 Apify에서 Actor 정의와 입력 스키마를 자동으로 가져오고, 그 후 도구 설명과 인자 스키마를 생성합니다. 이는 유효한 `actor_name`만 지정하면 도구가 에이전트와 함께 사용할 때 나머지 과정을 처리하므로, 별도로 `run_input`을 지정할 필요가 없다는 의미입니다. 작동 방식은 다음과 같습니다:
```python
from crewai import Agent
from crewai_tools import ApifyActorsTool
rag_browser = ApifyActorsTool(actor_name="apify/rag-web-browser")
agent = Agent(
role="Research Analyst",
goal="Find and summarize information about specific topics",
backstory="You are an experienced researcher with attention to detail",
tools=[rag_browser],
)
```
[Apify Store](https://apify.com/store)에 있는 다른 Actor도 `actor_name`만 변경하고, 수동으로 사용할 경우 Actor 입력 스키마에 따라 `run_input`을 조정하여 간단히 실행할 수 있습니다.
에이전트와 함께 사용하는 예시는 [CrewAI Actor 템플릿](https://apify.com/templates/python-crewai)을 참고하세요.
## 구성
`ApifyActorsTool`을 사용하려면 다음 입력값이 필요합니다:
- **`actor_name`**
실행할 Apify Actor의 ID입니다. 예: `"apify/rag-web-browser"`. 모든 Actor는 [Apify Store](https://apify.com/store)에서 확인할 수 있습니다.
- **`run_input`**
도구를 수동으로 실행할 때 Actor에 전달할 입력 파라미터의 딕셔너리입니다.
- 예를 들어, `apify/rag-web-browser` Actor의 경우: `{"query": "search term", "maxResults": 5}`
- 입력 파라미터 목록은 Actor의 [input schema](https://apify.com/apify/rag-web-browser/input-schema)에서 확인할 수 있습니다.
## 리소스
- **[Apify](https://apify.com/)**: Apify 플랫폼을 살펴보세요.
- **[Apify에서 AI 에이전트 구축하기](https://blog.apify.com/how-to-build-an-ai-agent/)** - Apify 플랫폼에서 AI 에이전트를 생성, 게시 및 수익화하는 단계별 완전 가이드입니다.
- **[RAG Web Browser Actor](https://apify.com/apify/rag-web-browser)**: LLM을 위한 웹 검색에 많이 사용되는 Actor입니다.
- **[CrewAI 통합 가이드](https://docs.apify.com/platform/integrations/crewai)**: Apify와 CrewAI를 통합하는 공식 가이드를 따라보세요.

118
docs/ko/tools/automation/composiotool.mdx Normal file
View File

@@ -0,0 +1,118 @@
---
title: Composio 도구
description: Composio는 유연한 인증 관리가 가능한 AI 에이전트를 위한 250개 이상의 프로덕션 준비 도구를 제공합니다.
icon: gear-code
---
# `ComposioToolSet`
## 설명
Composio는 AI 에이전트를 250개 이상의 도구와 연결할 수 있는 통합 플랫폼입니다. 주요 기능은 다음과 같습니다:
- **엔터프라이즈급 인증**: OAuth, API 키, JWT를 기본적으로 지원하며 자동 토큰 갱신 기능 제공
- **완벽한 가시성**: 도구 사용 로그, 실행 타임스탬프 등 상세 정보 제공
## 설치
Composio 도구를 프로젝트에 통합하려면 아래 지침을 따르세요:
```shell
pip install composio-crewai
pip install crewai
```
설치가 완료된 후, `composio login`을 실행하거나 Composio API 키를 `COMPOSIO_API_KEY`로 export하세요. Composio API 키는 [여기](https://app.composio.dev)에서 받을 수 있습니다.
## 예시
다음 예시는 도구를 초기화하고 github action을 실행하는 방법을 보여줍니다:
1. Composio 도구 세트 초기화
```python Code
from composio_crewai import ComposioToolSet, App, Action
from crewai import Agent, Task, Crew
toolset = ComposioToolSet()
```
2. GitHub 계정 연결
<CodeGroup>
```shell CLI
composio add github
```
```python Code
request = toolset.initiate_connection(app=App.GITHUB)
print(f"Open this URL to authenticate: {request.redirectUrl}")
```
</CodeGroup>
3. 도구 가져오기
- 앱에서 모든 도구를 가져오기 (프로덕션 환경에서는 권장하지 않음):
```python Code
tools = toolset.get_tools(apps=[App.GITHUB])
```
- 태그를 기반으로 도구 필터링:
```python Code
tag = "users"
filtered_action_enums = toolset.find_actions_by_tags(
App.GITHUB,
tags=[tag],
)
tools = toolset.get_tools(actions=filtered_action_enums)
```
- 사용 사례를 기반으로 도구 필터링:
```python Code
use_case = "Star a repository on GitHub"
filtered_action_enums = toolset.find_actions_by_use_case(
App.GITHUB, use_case=use_case, advanced=False
)
tools = toolset.get_tools(actions=filtered_action_enums)
```
<Tip>`advanced`를 True로 설정하면 복잡한 사용 사례를 위한 액션을 가져올 수 있습니다</Tip>
- 특정 도구 사용하기:
이 데모에서는 GitHub 앱의 `GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER` 액션을 사용합니다.
```python Code
tools = toolset.get_tools(
actions=[Action.GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER]
)
```
액션 필터링에 대해 더 자세한 내용을 보려면 [여기](https://docs.composio.dev/patterns/tools/use-tools/use-specific-actions)를 참고하세요.
4. 에이전트 정의
```python Code
crewai_agent = Agent(
role="GitHub Agent",
goal="You take action on GitHub using GitHub APIs",
backstory="You are AI agent that is responsible for taking actions on GitHub on behalf of users using GitHub APIs",
verbose=True,
tools=tools,
llm= # pass an llm
)
```
5. 작업 실행
```python Code
task = Task(
description="Star a repo composiohq/composio on GitHub",
agent=crewai_agent,
expected_output="Status of the operation",
)
crew = Crew(agents=[crewai_agent], tasks=[task])
crew.kickoff()
```
* 더욱 자세한 도구 리스트는 [여기](https://app.composio.dev)에서 확인하실 수 있습니다.

126
docs/ko/tools/automation/multiontool.mdx Normal file
View File

@@ -0,0 +1,126 @@
---
title: MultiOn Tool
description: MultiOnTool은 CrewAI agent가 자연어 지시를 통해 웹을 탐색하고 상호작용할 수 있는 기능을 제공합니다.
icon: globe
---
## 개요
`MultiOnTool`은 [MultiOn](https://docs.multion.ai/welcome)의 웹 브라우징 기능을 래핑하도록 설계되어, CrewAI 에이전트가 자연어 명령을 사용하여 웹 브라우저를 제어할 수 있게 해줍니다. 이 도구는 원활한 웹 브라우징을 지원하여, 동적인 웹 데이터 상호작용 및 웹 기반 작업의 자동화가 필요한 프로젝트에 필수적인 자산이 됩니다.
## 설치
이 도구를 사용하려면 MultiOn 패키지를 설치해야 합니다:
```shell
uv add multion
```
또한 MultiOn 브라우저 확장 프로그램을 설치하고 API 사용을 활성화해야 합니다.
## 시작하는 단계
`MultiOnTool`을 효과적으로 사용하려면 다음 단계를 따르세요:
1. **CrewAI 설치**: Python 환경에 `crewai[tools]` 패키지가 설치되어 있는지 확인하세요.
2. **MultiOn 설치 및 사용**: [MultiOn 문서](https://docs.multion.ai/learn/browser-extension)를 참고하여 MultiOn 브라우저 확장 프로그램을 설치하세요.
3. **API 사용 활성화**: 브라우저의 확장 프로그램 폴더에서 MultiOn 확장 프로그램을 클릭하여(웹 페이지에 떠 있는 MultiOn 아이콘이 아님) 확장 프로그램 설정을 엽니다. API 활성화 토글을 클릭하여 API를 활성화하세요.
## 예시
다음 예시는 도구를 초기화하고 웹 브라우징 작업을 실행하는 방법을 보여줍니다:
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import MultiOnTool
# Initialize the tool
multion_tool = MultiOnTool(api_key="YOUR_MULTION_API_KEY", local=False)
# Define an agent that uses the tool
browser_agent = Agent(
role="Browser Agent",
goal="Control web browsers using natural language",
backstory="An expert browsing agent.",
tools=[multion_tool],
verbose=True,
)
# Example task to search and summarize news
browse_task = Task(
description="Summarize the top 3 trending AI News headlines",
expected_output="A summary of the top 3 trending AI News headlines",
agent=browser_agent,
)
# Create and run the crew
crew = Crew(agents=[browser_agent], tasks=[browse_task])
result = crew.kickoff()
```
## 매개변수
`MultiOnTool`은(는) 초기화 시 다음과 같은 매개변수를 허용합니다:
- **api_key**: 선택 사항. MultiOn API 키를 지정합니다. 제공되지 않은 경우, `MULTION_API_KEY` 환경 변수를 찾습니다.
- **local**: 선택 사항. 에이전트를 로컬 브라우저에서 실행하려면 `True`로 설정합니다. MultiOn 브라우저 확장 프로그램이 설치되어 있고 API 사용이 체크되어 있는지 확인하세요. 기본값은 `False`입니다.
- **max_steps**: 선택 사항. MultiOn 에이전트가 명령에 대해 수행할 수 있는 최대 단계 수를 설정합니다. 기본값은 `3`입니다.
## 사용법
`MultiOnTool`을 사용할 때, 에이전트는 도구가 웹 브라우징 동작으로 변환하는 자연어 지시를 제공합니다. 도구는 브라우징 세션 결과와 상태를 함께 반환합니다.
```python Code
# Example of using the tool with an agent
browser_agent = Agent(
role="Web Browser Agent",
goal="Search for and summarize information from the web",
backstory="An expert at finding and extracting information from websites.",
tools=[multion_tool],
verbose=True,
)
# Create a task for the agent
search_task = Task(
description="Search for the latest AI news on TechCrunch and summarize the top 3 headlines",
expected_output="A summary of the top 3 AI news headlines from TechCrunch",
agent=browser_agent,
)
# Run the task
crew = Crew(agents=[browser_agent], tasks=[search_task])
result = crew.kickoff()
```
반환된 상태가 `CONTINUE`인 경우, 에이전트가 실행을 계속하기 위해 동일한 지시를 다시 내리도록 해야 합니다.
## 구현 세부사항
`MultiOnTool`은 CrewAI의 `BaseTool`의 하위 클래스로 구현됩니다. 이는 MultiOn 클라이언트를 래핑하여 웹 브라우징 기능을 제공합니다:
```python Code
class MultiOnTool(BaseTool):
"""Tool to wrap MultiOn Browse Capabilities."""
name: str = "Multion Browse Tool"
description: str = """Multion gives the ability for LLMs to control web browsers using natural language instructions.
If the status is 'CONTINUE', reissue the same instruction to continue execution
"""
# Implementation details...
def _run(self, cmd: str, *args: Any, **kwargs: Any) -> str:
"""
Run the Multion client with the given command.
Args:
cmd (str): The detailed and specific natural language instruction for web browsing
*args (Any): Additional arguments to pass to the Multion client
**kwargs (Any): Additional keyword arguments to pass to the Multion client
"""
# Implementation details...
```
## 결론
`MultiOnTool`은 CrewAI 에이전트에 웹 브라우징 기능을 통합할 수 있는 강력한 방법을 제공합니다. 에이전트가 자연어 지시를 통해 웹사이트와 상호작용할 수 있게 함으로써, 데이터 수집 및 연구에서 웹 서비스와의 자동화된 상호작용에 이르기까지 웹 기반 작업의 다양한 가능성을 열어줍니다.

59
docs/ko/tools/automation/overview.mdx Normal file
View File

@@ -0,0 +1,59 @@
---
title: "개요"
description: "워크플로우를 자동화하고 외부 플랫폼 및 서비스와 통합합니다"
icon: "face-smile"
---
이러한 도구들은 에이전트가 워크플로를 자동화하고, 외부 플랫폼과 통합하며, 다양한 서드파티 서비스와 연동하여 기능을 향상시킬 수 있도록 합니다.
## **사용 가능한 도구**
<CardGroup cols={2}>
<Card title="Apify Actor Tool" icon="spider" href="/ko/tools/automation/apifyactorstool">
웹 스크래핑 및 자동화 작업을 위해 Apify actor를 실행합니다.
</Card>
<Card title="Composio Tool" icon="puzzle-piece" href="/ko/tools/automation/composiotool">
Composio를 통해 수백 개의 앱 및 서비스와 통합합니다.
</Card>
<Card title="Multion Tool" icon="window-restore" href="/ko/tools/automation/multiontool">
브라우저 상호작용과 웹 기반 워크플로우를 자동화합니다.
</Card>
<Card title="Zapier Actions Adapter" icon="bolt" href="/ko/tools/automation/zapieractionstool">
수천 개의 앱을 자동화할 수 있도록 Zapier Actions를 CrewAI 도구로 제공합니다.
</Card>
</CardGroup>
## **일반적인 사용 사례**
- **워크플로 자동화**: 반복적인 작업과 프로세스 자동화
- **API 통합**: 외부 API 및 서비스와 연동
- **데이터 동기화**: 다양한 플랫폼 간 데이터 동기화
- **프로세스 오케스트레이션**: 복잡한 다단계 워크플로의 조정
- **서드파티 서비스**: 외부 도구 및 플랫폼 활용
```python
from crewai_tools import ApifyActorTool, ComposioTool, MultiOnTool
# Create automation tools
apify_automation = ApifyActorTool()
platform_integration = ComposioTool()
browser_automation = MultiOnTool()
# Add to your agent
agent = Agent(
role="Automation Specialist",
tools=[apify_automation, platform_integration, browser_automation],
goal="Automate workflows and integrate systems"
)
```
## **통합 이점**
- **효율성**: 자동화를 통해 수작업을 줄임
- **확장성**: 증가하는 작업량을 자동으로 처리
- **신뢰성**: 워크플로우의 일관된 실행
- **연결성**: 다양한 시스템과 플랫폼을 연결
- **생산성**: 자동화가 반복 작업을 처리하는 동안 고부가가치 업무에 집중

56
docs/ko/tools/automation/zapieractionstool.mdx Normal file
View File

@@ -0,0 +1,56 @@
---
title: Zapier 액션 도구
description: ZapierActionsAdapter는 Zapier 액션을 CrewAI 도구로 노출하여 자동화를 지원합니다.
icon: bolt
---
# `ZapierActionsAdapter`
## 설명
Zapier 어댑터를 사용하여 Zapier 작업을 CrewAI 도구로 나열하고 호출할 수 있습니다. 이를 통해 에이전트가 수천 개의 앱에서 자동화를 트리거할 수 있습니다.
## 설치
이 어댑터는 `crewai-tools`에 포함되어 있습니다. 별도의 설치가 필요하지 않습니다.
## 환경 변수
- `ZAPIER_API_KEY` (필수): Zapier API 키입니다. https://actions.zapier.com/의 Zapier Actions 대시보드에서 받을 수 있습니다(계정을 생성한 후 API 키를 생성). 어댑터를 생성할 때 `zapier_api_key`를 직접 전달할 수도 있습니다.
## 예시
```python Code
from crewai import Agent, Task, Crew
from crewai_tools.adapters.zapier_adapter import ZapierActionsAdapter
adapter = ZapierActionsAdapter(api_key="your_zapier_api_key")
tools = adapter.tools()
agent = Agent(
role="Automator",
goal="Execute Zapier actions",
backstory="Automation specialist",
tools=tools,
verbose=True,
)
task = Task(
description="Create a new Google Sheet and add a row using Zapier actions",
expected_output="Confirmation with created resource IDs",
agent=agent,
)
crew = Crew(agents=[agent], tasks=[task])
result = crew.kickoff()
```
## 참고 사항 및 제한 사항
- 어댑터는 키에 사용할 수 있는 작업을 나열하고 `BaseTool` 래퍼를 동적으로 생성합니다.
- 작업별 필수 필드는 작업 지침이나 도구 호출에서 처리하세요.
- 속도 제한은 Zapier 요금제에 따라 다르며, 자세한 내용은 Zapier Actions 문서를 참조하세요.
## 참고 사항
- 어댑터는 사용 가능한 작업을 가져와 `BaseTool` 래퍼를 동적으로 생성합니다.

187
docs/ko/tools/cloud-storage/bedrockinvokeagenttool.mdx Normal file
View File

@@ -0,0 +1,187 @@
---
title: Bedrock Invoke Agent 도구
description: CrewAI 에이전트가 Amazon Bedrock 에이전트를 호출하고, 워크플로우 내에서 그 기능을 활용할 수 있도록 합니다
icon: aws
---
# `BedrockInvokeAgentTool`
`BedrockInvokeAgentTool`은 CrewAI agent가 Amazon Bedrock Agent를 호출하여 워크플로우 내에서 해당 기능을 활용할 수 있도록 해줍니다.
## 설치
```bash
uv pip install 'crewai[tools]'
```
## 요구 사항
- AWS 자격 증명이 구성되어 있어야 합니다(AWS CLI 또는 환경 변수 사용)
- `boto3` 및 `python-dotenv` 패키지
- Amazon Bedrock Agents에 대한 액세스 권한
## 사용법
CrewAI agent와 함께 이 도구를 사용하는 방법은 다음과 같습니다:
```python {2, 4-8}
from crewai import Agent, Task, Crew
from crewai_tools.aws.bedrock.agents.invoke_agent_tool import BedrockInvokeAgentTool
# Initialize the tool
agent_tool = BedrockInvokeAgentTool(
agent_id="your-agent-id",
agent_alias_id="your-agent-alias-id"
)
# Create a CrewAI agent that uses the tool
aws_expert = Agent(
role='AWS Service Expert',
goal='Help users understand AWS services and quotas',
backstory='I am an expert in AWS services and can provide detailed information about them.',
tools=[agent_tool],
verbose=True
)
# Create a task for the agent
quota_task = Task(
description="Find out the current service quotas for EC2 in us-west-2 and explain any recent changes.",
agent=aws_expert
)
# Create a crew with the agent
crew = Crew(
agents=[aws_expert],
tasks=[quota_task],
verbose=2
)
# Run the crew
result = crew.kickoff()
print(result)
```
## 도구 인수
| 인수 | 타입 | 필수 여부 | 기본값 | 설명 |
|:---------|:-----|:---------|:--------|:------------|
| **agent_id** | `str` | 예 | 없음 | Bedrock agent의 고유 식별자 |
| **agent_alias_id** | `str` | 예 | 없음 | agent alias의 고유 식별자 |
| **session_id** | `str` | 아니오 | timestamp | 세션의 고유 식별자 |
| **enable_trace** | `bool` | 아니오 | False | 디버깅을 위한 trace 활성화 여부 |
| **end_session** | `bool` | 아니오 | False | 호출 후 세션 종료 여부 |
| **description** | `str` | 아니오 | 없음 | 도구에 대한 사용자 지정 설명 |
## 환경 변수
```bash
BEDROCK_AGENT_ID=your-agent-id # Alternative to passing agent_id
BEDROCK_AGENT_ALIAS_ID=your-agent-alias-id # Alternative to passing agent_alias_id
AWS_REGION=your-aws-region # Defaults to us-west-2
AWS_ACCESS_KEY_ID=your-access-key # Required for AWS authentication
AWS_SECRET_ACCESS_KEY=your-secret-key # Required for AWS authentication
```
## 고급 사용법
### 세션 관리가 포함된 다중 에이전트 워크플로우
```python {2, 4-22}
from crewai import Agent, Task, Crew, Process
from crewai_tools.aws.bedrock.agents.invoke_agent_tool import BedrockInvokeAgentTool
# Initialize tools with session management
initial_tool = BedrockInvokeAgentTool(
agent_id="your-agent-id",
agent_alias_id="your-agent-alias-id",
session_id="custom-session-id"
)
followup_tool = BedrockInvokeAgentTool(
agent_id="your-agent-id",
agent_alias_id="your-agent-alias-id",
session_id="custom-session-id"
)
final_tool = BedrockInvokeAgentTool(
agent_id="your-agent-id",
agent_alias_id="your-agent-alias-id",
session_id="custom-session-id",
end_session=True
)
# Create agents for different stages
researcher = Agent(
role='AWS Service Researcher',
goal='Gather information about AWS services',
backstory='I am specialized in finding detailed AWS service information.',
tools=[initial_tool]
)
analyst = Agent(
role='Service Compatibility Analyst',
goal='Analyze service compatibility and requirements',
backstory='I analyze AWS services for compatibility and integration possibilities.',
tools=[followup_tool]
)
summarizer = Agent(
role='Technical Documentation Writer',
goal='Create clear technical summaries',
backstory='I specialize in creating clear, concise technical documentation.',
tools=[final_tool]
)
# Create tasks
research_task = Task(
description="Find all available AWS services in us-west-2 region.",
agent=researcher
)
analysis_task = Task(
description="Analyze which services support IPv6 and their implementation requirements.",
agent=analyst
)
summary_task = Task(
description="Create a summary of IPv6-compatible services and their key features.",
agent=summarizer
)
# Create a crew with the agents and tasks
crew = Crew(
agents=[researcher, analyst, summarizer],
tasks=[research_task, analysis_task, summary_task],
process=Process.sequential,
verbose=2
)
# Run the crew
result = crew.kickoff()
```
## 사용 사례
### 하이브리드 멀티 에이전트 협업
- CrewAI 에이전트가 AWS에서 서비스로 실행되는 관리형 Bedrock 에이전트와 협력하는 워크플로우를 생성합니다.
- 민감한 데이터 처리가 AWS 환경 내에서 이루어지면서, 다른 에이전트는 외부에서 작동하는 시나리오를 구현합니다.
- 온프레미스 CrewAI 에이전트와 클라우드 기반 Bedrock 에이전트를 연결하여 분산 지능 워크플로우를 실현합니다.
### 데이터 주권 및 준수
- 데이터에 민감한 에이전틱 워크플로우를 AWS 환경 내에서 유지하면서, 외부 CrewAI 에이전트가 작업을 오케스트레이션할 수 있도록 허용합니다
- 민감한 정보를 오직 귀하의 AWS 계정 내에서 처리함으로써 데이터 보관 위치 요건을 준수합니다
- 일부 에이전트가 귀 조직의 비공개 데이터에 접근할 수 없는 안전한 다중 에이전트 협업을 가능하게 합니다
### 원활한 AWS 서비스 통합
- 복잡한 통합 코드를 작성하지 않고도 Amazon Bedrock Actions를 통해 모든 AWS 서비스에 액세스할 수 있습니다.
- CrewAI 에이전트가 자연어 요청을 통해 AWS 서비스와 상호작용할 수 있습니다.
- Bedrock Knowledge Bases, Lambda 등과 같은 AWS 서비스와 상호작용할 수 있도록 사전 구축된 Bedrock 에이전트 기능을 활용할 수 있습니다.
### 확장 가능한 하이브리드 에이전트 아키텍처
- 계산 집약적인 작업은 관리형 Bedrock 에이전트에 오프로드하고, 경량 작업은 CrewAI에서 실행
- 로컬 CrewAI 에이전트와 클라우드 기반 Bedrock 에이전트 간에 워크로드를 분산하여 에이전트 처리를 확장
### 조직 간 에이전트 협업
- 귀 조직의 CrewAI 에이전트와 파트너 조직의 Bedrock 에이전트 간의 안전한 협업을 지원합니다
- 민감한 데이터를 노출하지 않고도 Bedrock 에이전트의 외부 전문 지식을 워크플로우에 통합할 수 있습니다
- 보안 및 데이터 통제를 유지하면서 조직 경계를 넘는 에이전트 생태계를 구축합니다

165
docs/ko/tools/cloud-storage/bedrockkbretriever.mdx Normal file
View File

@@ -0,0 +1,165 @@
---
title: 'Bedrock 지식 베이스 검색기'
description: '자연어 쿼리를 사용하여 Amazon Bedrock 지식 베이스에서 정보를 검색합니다'
icon: aws
---
# `BedrockKBRetrieverTool`
`BedrockKBRetrieverTool`은 CrewAI 에이전트가 자연어 쿼리를 사용하여 Amazon Bedrock Knowledge Bases에서 정보를 검색할 수 있도록 합니다.
## 설치
```bash
uv pip install 'crewai[tools]'
```
## 요구 사항
- AWS 자격 증명이 구성되어 있음 (환경 변수 또는 AWS CLI를 통해)
- `boto3` 및 `python-dotenv` 패키지
- Amazon Bedrock Knowledge Base에 대한 액세스
## 사용법
CrewAI agent와 함께 이 도구를 사용하는 방법은 다음과 같습니다:
```python {2, 4-17}
from crewai import Agent, Task, Crew
from crewai_tools.aws.bedrock.knowledge_base.retriever_tool import BedrockKBRetrieverTool
# Initialize the tool
kb_tool = BedrockKBRetrieverTool(
knowledge_base_id="your-kb-id",
number_of_results=5
)
# Create a CrewAI agent that uses the tool
researcher = Agent(
role='Knowledge Base Researcher',
goal='Find information about company policies',
backstory='I am a researcher specialized in retrieving and analyzing company documentation.',
tools=[kb_tool],
verbose=True
)
# Create a task for the agent
research_task = Task(
description="Find our company's remote work policy and summarize the key points.",
agent=researcher
)
# Create a crew with the agent
crew = Crew(
agents=[researcher],
tasks=[research_task],
verbose=2
)
# Run the crew
result = crew.kickoff()
print(result)
```
## 도구 인자
| 인자 | 타입 | 필수 여부 | 기본값 | 설명 |
|:---------|:-----|:---------|:---------|:-------------|
| **knowledge_base_id** | `str` | 예 | 없음 | 지식 베이스의 고유 식별자 (0-10자리 영숫자) |
| **number_of_results** | `int` | 아니오 | 5 | 반환할 최대 결과 개수 |
| **retrieval_configuration** | `dict` | 아니오 | 없음 | 지식 베이스 쿼리를 위한 사용자 지정 설정 |
| **guardrail_configuration** | `dict` | 아니오 | 없음 | 콘텐츠 필터링 설정 |
| **next_token** | `str` | 아니오 | 없음 | 페이지네이션을 위한 토큰 |
## 환경 변수
```bash
BEDROCK_KB_ID=your-knowledge-base-id # Alternative to passing knowledge_base_id
AWS_REGION=your-aws-region # Defaults to us-east-1
AWS_ACCESS_KEY_ID=your-access-key # Required for AWS authentication
AWS_SECRET_ACCESS_KEY=your-secret-key # Required for AWS authentication
```
## 응답 형식
도구는 결과를 JSON 형식으로 반환합니다:
```json
{
"results": [
{
"content": "Retrieved text content",
"content_type": "text",
"source_type": "S3",
"source_uri": "s3://bucket/document.pdf",
"score": 0.95,
"metadata": {
"additional": "metadata"
}
}
],
"nextToken": "pagination-token",
"guardrailAction": "NONE"
}
```
## 고급 사용법
### 사용자 지정 검색 구성
```python
kb_tool = BedrockKBRetrieverTool(
knowledge_base_id="your-kb-id",
retrieval_configuration={
"vectorSearchConfiguration": {
"numberOfResults": 10,
"overrideSearchType": "HYBRID"
}
}
)
policy_expert = Agent(
role='Policy Expert',
goal='Analyze company policies in detail',
backstory='I am an expert in corporate policy analysis with deep knowledge of regulatory requirements.',
tools=[kb_tool]
)
```
## 지원되는 데이터 소스
- Amazon S3
- Confluence
- Salesforce
- SharePoint
- 웹 페이지
- 사용자 지정 문서 위치
- Amazon Kendra
- SQL 데이터베이스
## 사용 사례
### 엔터프라이즈 지식 통합
- 민감한 데이터를 노출하지 않고도 CrewAI 에이전트가 귀사의 독점 지식에 접근할 수 있도록 합니다.
- 에이전트가 귀사의 특정 정책, 절차 및 문서를 기반으로 의사 결정을 내릴 수 있도록 허용합니다.
- 데이터 보안을 유지하면서 내부 문서를 기반으로 질문에 답변할 수 있는 에이전트를 생성합니다.
### 전문 분야 지식
- CrewAI 에이전트를 도메인별 지식 베이스(법률, 의료, 기술 등)에 재학습 없이 연결할 수 있습니다
- 이미 AWS 환경에서 관리되고 있는 기존 지식 저장소를 활용할 수 있습니다
- CrewAI의 추론과 지식 베이스의 도메인별 정보를 결합할 수 있습니다
### 데이터 기반 의사결정
- Ground CrewAI 에이전트 응답을 일반 지식이 아닌 실제 회사 데이터에 기반하게 하세요
- 에이전트가 귀사의 특정 비즈니스 맥락과 문서를 바탕으로 추천을 제공하도록 보장하세요
- 지식 기반에서 사실 정보를 검색하여 환각을 줄이세요
### 확장 가능한 정보 접근
- 모델에 모든 지식을 삽입하지 않고도 조직의 테라바이트급 지식에 접근할 수 있습니다.
- 특정 작업에 필요한 관련 정보만 동적으로 쿼리합니다.
- 대규모 지식 베이스를 효율적으로 처리하기 위해 AWS의 확장 가능한 인프라를 활용합니다.
### 컴플라이언스 및 거버넌스
- CrewAI 에이전트가 회사의 승인된 문서에 부합하는 응답을 제공하도록 보장하십시오
- 에이전트가 사용한 정보 출처에 대한 감사 가능한 기록을 만드십시오
- 에이전트가 접근할 수 있는 정보 출처를 제어하십시오

51
docs/ko/tools/cloud-storage/overview.mdx Normal file
View File

@@ -0,0 +1,51 @@
---
title: "개요"
description: "클라우드 서비스, 스토리지 시스템, 클라우드 기반 AI 플랫폼과 상호작용합니다"
icon: "face-smile"
---
이러한 도구를 통해 에이전트는 클라우드 서비스와 상호 작용하고, 클라우드 스토리지에 접근하며, 대규모 운영을 위해 클라우드 기반 AI 플랫폼을 활용할 수 있습니다.
## **사용 가능한 도구**
<CardGroup cols={2}>
<Card title="S3 리더 도구" icon="cloud" href="/ko/tools/cloud-storage/s3readertool">
Amazon S3 버킷에서 파일과 데이터를 읽습니다.
</Card>
<Card title="S3 라이터 도구" icon="cloud-arrow-up" href="/ko/tools/cloud-storage/s3writertool">
파일을 Amazon S3 스토리지에 작성하고 업로드합니다.
</Card>
<Card title="Bedrock Invoke Agent" icon="aws" href="/ko/tools/cloud-storage/bedrockinvokeagenttool">
AI 기반 작업을 위해 Amazon Bedrock 에이전트를 호출합니다.
</Card>
<Card title="Bedrock KB Retriever" icon="database" href="/ko/tools/cloud-storage/bedrockkbretriever">
Amazon Bedrock 지식 베이스에서 정보를 검색합니다.
</Card>
</CardGroup>
## **일반적인 사용 사례**
- **파일 저장**: 클라우드 스토리지 시스템에 파일을 저장하고 가져오기
- **데이터 백업**: 중요한 데이터를 클라우드 스토리지에 백업하기
- **AI 서비스**: 클라우드 기반의 AI 모델 및 서비스에 접근하기
- **지식 검색**: 클라우드에 호스팅된 지식 베이스를 질의하기
- **확장 가능한 운영**: 처리 작업을 위해 클라우드 인프라 활용하기
```python
from crewai_tools import S3ReaderTool, S3WriterTool, BedrockInvokeAgentTool
# Create cloud tools
s3_reader = S3ReaderTool()
s3_writer = S3WriterTool()
bedrock_agent = BedrockInvokeAgentTool()
# Add to your agent
agent = Agent(
role="Cloud Operations Specialist",
tools=[s3_reader, s3_writer, bedrock_agent],
goal="Manage cloud resources and AI services"
)
```

144
docs/ko/tools/cloud-storage/s3readertool.mdx Normal file
View File

@@ -0,0 +1,144 @@
---
title: S3 리더 도구
description: S3ReaderTool은 CrewAI 에이전트가 Amazon S3 버킷에서 파일을 읽을 수 있도록 합니다.
icon: aws
---
# `S3ReaderTool`
## 설명
`S3ReaderTool`은 Amazon S3 버킷에서 파일을 읽기 위해 설계되었습니다. 이 도구를 사용하면 CrewAI 에이전트가 S3에 저장된 콘텐츠에 접근하고 가져올 수 있어, 데이터를 읽거나 설정 파일 또는 AWS S3 스토리지에 저장된 기타 콘텐츠를 필요로 하는 워크플로우에 이상적입니다.
## 설치
이 도구를 사용하려면 필요한 종속성을 설치해야 합니다:
```shell
uv add boto3
```
## 시작 단계
`S3ReaderTool`을 효과적으로 사용하려면 다음 단계를 따르세요:
1. **의존성 설치**: 위 명령어를 사용하여 필요한 패키지를 설치합니다.
2. **AWS 자격 증명 구성**: 환경 변수로 AWS 자격 증명을 설정합니다.
3. **도구 초기화**: 도구의 인스턴스를 생성합니다.
4. **S3 경로 지정**: 읽고자 하는 파일의 S3 경로를 제공합니다.
## 예시
다음 예시는 `S3ReaderTool`을 사용하여 S3 버킷에서 파일을 읽는 방법을 보여줍니다:
```python Code
from crewai import Agent, Task, Crew
from crewai_tools.aws.s3 import S3ReaderTool
# Initialize the tool
s3_reader_tool = S3ReaderTool()
# Define an agent that uses the tool
file_reader_agent = Agent(
role="File Reader",
goal="Read files from S3 buckets",
backstory="An expert in retrieving and processing files from cloud storage.",
tools=[s3_reader_tool],
verbose=True,
)
# Example task to read a configuration file
read_task = Task(
description="Read the configuration file from {my_bucket} and summarize its contents.",
expected_output="A summary of the configuration file contents.",
agent=file_reader_agent,
)
# Create and run the crew
crew = Crew(agents=[file_reader_agent], tasks=[read_task])
result = crew.kickoff(inputs={"my_bucket": "s3://my-bucket/config/app-config.json"})
```
## 매개변수
`S3ReaderTool`은 에이전트에 의해 사용될 때 다음과 같은 매개변수를 허용합니다:
- **file_path**: 필수입니다. `s3://bucket-name/file-name` 형식의 S3 파일 경로입니다.
## AWS 자격 증명
이 도구는 S3 버킷에 접근하기 위해 AWS 자격 증명이 필요합니다. 환경 변수를 사용하여 이러한 자격 증명을 구성할 수 있습니다:
- **CREW_AWS_REGION**: S3 버킷이 위치한 AWS 리전입니다. 기본값은 `us-east-1`입니다.
- **CREW_AWS_ACCESS_KEY_ID**: AWS 액세스 키 ID입니다.
- **CREW_AWS_SEC_ACCESS_KEY**: AWS 시크릿 액세스 키입니다.
## 사용법
`S3ReaderTool`을 agent와 함께 사용할 때, agent는 S3 파일 경로를 제공해야 합니다:
```python Code
# Example of using the tool with an agent
file_reader_agent = Agent(
role="File Reader",
goal="Read files from S3 buckets",
backstory="An expert in retrieving and processing files from cloud storage.",
tools=[s3_reader_tool],
verbose=True,
)
# Create a task for the agent to read a specific file
read_config_task = Task(
description="Read the application configuration file from {my_bucket} and extract the database connection settings.",
expected_output="The database connection settings from the configuration file.",
agent=file_reader_agent,
)
# Run the task
crew = Crew(agents=[file_reader_agent], tasks=[read_config_task])
result = crew.kickoff(inputs={"my_bucket": "s3://my-bucket/config/app-config.json"})
```
## 오류 처리
`S3ReaderTool`은 일반적인 S3 문제에 대한 오류 처리를 포함하고 있습니다:
- 잘못된 S3 경로 형식
- 누락되었거나 접근할 수 없는 파일
- 권한 문제
- AWS 자격 증명 문제
오류가 발생하면, 도구는 문제에 대한 세부 정보가 포함된 오류 메시지를 반환합니다.
## 구현 세부사항
`S3ReaderTool`은 AWS SDK for Python(boto3)을 사용하여 S3와 상호작용합니다:
```python Code
class S3ReaderTool(BaseTool):
name: str = "S3 Reader Tool"
description: str = "Reads a file from Amazon S3 given an S3 file path"
def _run(self, file_path: str) -> str:
try:
bucket_name, object_key = self._parse_s3_path(file_path)
s3 = boto3.client(
's3',
region_name=os.getenv('CREW_AWS_REGION', 'us-east-1'),
aws_access_key_id=os.getenv('CREW_AWS_ACCESS_KEY_ID'),
aws_secret_access_key=os.getenv('CREW_AWS_SEC_ACCESS_KEY')
)
# Read file content from S3
response = s3.get_object(Bucket=bucket_name, Key=object_key)
file_content = response['Body'].read().decode('utf-8')
return file_content
except ClientError as e:
return f"Error reading file from S3: {str(e)}"
```
## 결론
`S3ReaderTool`은 Amazon S3 버킷에서 파일을 읽을 수 있는 간단한 방법을 제공합니다. 에이전트가 S3에 저장된 콘텐츠에 액세스할 수 있도록 하여, 클라우드 기반 파일 액세스가 필요한 워크플로우를 지원합니다. 이 도구는 데이터 처리, 구성 관리, 그리고 AWS S3 스토리지에서 정보를 검색하는 모든 작업에 특히 유용합니다.

150
docs/ko/tools/cloud-storage/s3writertool.mdx Normal file
View File

@@ -0,0 +1,150 @@
---
title: S3 Writer Tool
description: S3WriterTool은 CrewAI 에이전트가 Amazon S3 버킷의 파일에 콘텐츠를 쓸 수 있도록 해줍니다.
icon: aws
---
# `S3WriterTool`
## 설명
`S3WriterTool`은 Amazon S3 버킷의 파일에 콘텐츠를 기록하도록 설계되었습니다. 이 도구를 사용하면 CrewAI 에이전트가 S3에서 파일을 생성하거나 업데이트할 수 있어, 데이터를 저장하거나 구성 파일을 저장하거나 기타 콘텐츠를 AWS S3 스토리지에 영구적으로 보관해야 하는 워크플로우에 이상적입니다.
## 설치
이 도구를 사용하려면 필요한 종속성을 설치해야 합니다:
```shell
uv add boto3
```
## 시작 단계
`S3WriterTool`을 효과적으로 사용하려면 다음 단계를 따르세요:
1. **필수 패키지 설치**: 위 명령어를 사용하여 필요한 패키지를 설치합니다.
2. **AWS 자격 증명 구성**: 환경 변수로 AWS 자격 증명을 설정합니다.
3. **도구 초기화**: 도구의 인스턴스를 생성합니다.
4. **S3 경로 및 내용 지정**: 파일을 작성할 S3 경로와 작성할 내용을 제공합니다.
## 예시
다음 예시는 `S3WriterTool`을 사용하여 S3 버킷의 파일에 콘텐츠를 쓰는 방법을 보여줍니다:
```python Code
from crewai import Agent, Task, Crew
from crewai_tools.aws.s3 import S3WriterTool
# Initialize the tool
s3_writer_tool = S3WriterTool()
# Define an agent that uses the tool
file_writer_agent = Agent(
role="File Writer",
goal="Write content to files in S3 buckets",
backstory="An expert in storing and managing files in cloud storage.",
tools=[s3_writer_tool],
verbose=True,
)
# Example task to write a report
write_task = Task(
description="Generate a summary report of the quarterly sales data and save it to {my_bucket}.",
expected_output="Confirmation that the report was successfully saved to S3.",
agent=file_writer_agent,
)
# Create and run the crew
crew = Crew(agents=[file_writer_agent], tasks=[write_task])
result = crew.kickoff(inputs={"my_bucket": "s3://my-bucket/reports/quarterly-summary.txt"})
```
## 파라미터
`S3WriterTool`은 에이전트가 사용할 때 다음 파라미터를 허용합니다:
- **file_path**: 필수. `s3://bucket-name/file-name` 형식의 S3 파일 경로입니다.
- **content**: 필수. 파일에 쓸 내용입니다.
## AWS 자격 증명
이 도구는 S3 버킷에 접근하기 위해 AWS 자격 증명이 필요합니다. 다음과 같이 환경 변수로 자격 증명을 설정할 수 있습니다:
- **CREW_AWS_REGION**: S3 버킷이 위치한 AWS 리전. 기본값은 `us-east-1`입니다.
- **CREW_AWS_ACCESS_KEY_ID**: AWS 액세스 키 ID.
- **CREW_AWS_SEC_ACCESS_KEY**: AWS 시크릿 액세스 키.
## 사용법
`S3WriterTool`을 agent와 함께 사용할 때, agent는 S3 파일 경로와 작성할 내용을 모두 제공해야 합니다:
```python Code
# Example of using the tool with an agent
file_writer_agent = Agent(
role="File Writer",
goal="Write content to files in S3 buckets",
backstory="An expert in storing and managing files in cloud storage.",
tools=[s3_writer_tool],
verbose=True,
)
# Create a task for the agent to write a specific file
write_config_task = Task(
description="""
Create a configuration file with the following database settings:
- host: db.example.com
- port: 5432
- username: app_user
- password: secure_password
Save this configuration as JSON to {my_bucket}.
""",
expected_output="Confirmation that the configuration file was successfully saved to S3.",
agent=file_writer_agent,
)
# Run the task
crew = Crew(agents=[file_writer_agent], tasks=[write_config_task])
result = crew.kickoff(inputs={"my_bucket": "s3://my-bucket/config/db-config.json"})
```
## 오류 처리
`S3WriterTool`은 일반적인 S3 문제에 대한 오류 처리를 포함합니다:
- 잘못된 S3 경로 형식
- 권한 문제(예: 버킷에 대한 쓰기 권한 없음)
- AWS 자격 증명 문제
- 버킷이 존재하지 않음
오류가 발생하면 도구는 문제에 대한 세부 정보가 포함된 오류 메시지를 반환합니다.
## 구현 세부 정보
`S3WriterTool`은 S3와 상호 작용하기 위해 AWS SDK for Python(boto3)를 사용합니다:
```python Code
class S3WriterTool(BaseTool):
name: str = "S3 Writer Tool"
description: str = "Writes content to a file in Amazon S3 given an S3 file path"
def _run(self, file_path: str, content: str) -> str:
try:
bucket_name, object_key = self._parse_s3_path(file_path)
s3 = boto3.client(
's3',
region_name=os.getenv('CREW_AWS_REGION', 'us-east-1'),
aws_access_key_id=os.getenv('CREW_AWS_ACCESS_KEY_ID'),
aws_secret_access_key=os.getenv('CREW_AWS_SEC_ACCESS_KEY')
)
s3.put_object(Bucket=bucket_name, Key=object_key, Body=content.encode('utf-8'))
return f"Successfully wrote content to {file_path}"
except ClientError as e:
return f"Error writing file to S3: {str(e)}"
```
## 결론
`S3WriterTool`은 Amazon S3 버킷의 파일에 콘텐츠를 간편하게 작성할 수 있는 방법을 제공합니다. 이 도구를 통해 에이전트가 S3에서 파일을 생성하고 업데이트할 수 있어 클라우드 기반 파일 저장소가 필요한 워크플로우를 지원합니다. 이 도구는 데이터 영속성, 구성 관리, 보고서 생성 및 AWS S3 저장소에 정보를 저장해야 하는 작업에 특히 유용합니다.

166
docs/ko/tools/database-data/mongodbvectorsearchtool.mdx Normal file
View File

@@ -0,0 +1,166 @@
---
title: MongoDB 벡터 검색 도구
description: MongoDBVectorSearchTool은(는) 선택적인 인덱싱 도우미와 함께 MongoDB Atlas에서 벡터 검색을 수행합니다.
icon: "leaf"
---
# `MongoDBVectorSearchTool`
## 설명
MongoDB Atlas 컬렉션에서 벡터 유사성 쿼리를 수행합니다. 인덱스 생성 도우미 및 임베디드 텍스트의 일괄 삽입을 지원합니다.
MongoDB Atlas는 네이티브 벡터 검색을 지원합니다. 자세히 알아보기:
https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-overview/
## 설치
MongoDB 추가 기능과 함께 설치하세요:
```shell
pip install crewai-tools[mongodb]
```
또는
```shell
uv add crewai-tools --extra mongodb
```
## 파라미터
### 초기화
- `connection_string` (str, 필수)
- `database_name` (str, 필수)
- `collection_name` (str, 필수)
- `vector_index_name` (str, 기본값 `vector_index`)
- `text_key` (str, 기본값 `text`)
- `embedding_key` (str, 기본값 `embedding`)
- `dimensions` (int, 기본값 `1536`)
### 실행 매개변수
- `query` (str, 필수): 임베드 및 검색할 자연어 쿼리.
## 빠른 시작
```python Code
from crewai_tools import MongoDBVectorSearchTool
tool = MongoDBVectorSearchTool(
connection_string="mongodb+srv://...",
database_name="mydb",
collection_name="docs",
)
print(tool.run(query="how to create vector index"))
```
## 인덱스 생성 도우미
`create_vector_search_index(...)`를 사용하여 올바른 차원과 유사성을 가진 Atlas Vector Search 인덱스를 프로비저닝하세요.
## 일반적인 문제
- 인증 실패: Atlas IP 액세스 목록에 러너가 허용되어 있는지 확인하고, 연결 문자열에 자격 증명이 포함되어 있는지 확인하세요.
- 인덱스를 찾을 수 없음: 벡터 인덱스를 먼저 생성하세요; 이름이 `vector_index_name`과 일치해야 합니다.
- 차원 불일치: 임베딩 모델의 차원을 `dimensions`와 일치시켜야 합니다.
## 추가 예시
### 기본 초기화
```python Code
from crewai_tools import MongoDBVectorSearchTool
tool = MongoDBVectorSearchTool(
database_name="example_database",
collection_name="example_collection",
connection_string="<your_mongodb_connection_string>",
)
```
### 사용자 지정 쿼리 구성
```python Code
from crewai_tools import MongoDBVectorSearchConfig, MongoDBVectorSearchTool
query_config = MongoDBVectorSearchConfig(limit=10, oversampling_factor=2)
tool = MongoDBVectorSearchTool(
database_name="example_database",
collection_name="example_collection",
connection_string="<your_mongodb_connection_string>",
query_config=query_config,
vector_index_name="my_vector_index",
)
rag_agent = Agent(
name="rag_agent",
role="You are a helpful assistant that can answer questions with the help of the MongoDBVectorSearchTool.",
goal="...",
backstory="...",
tools=[tool],
)
```
### 데이터베이스 미리 로드 및 인덱스 생성
```python Code
import os
from crewai_tools import MongoDBVectorSearchTool
tool = MongoDBVectorSearchTool(
database_name="example_database",
collection_name="example_collection",
connection_string="<your_mongodb_connection_string>",
)
# Load text content from a local folder and add to MongoDB
texts = []
for fname in os.listdir("knowledge"):
path = os.path.join("knowledge", fname)
if os.path.isfile(path):
with open(path, "r", encoding="utf-8") as f:
texts.append(f.read())
tool.add_texts(texts)
# Create the Atlas Vector Search index (e.g., 3072 dims for text-embedding-3-large)
tool.create_vector_search_index(dimensions=3072)
```
## 예시
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import MongoDBVectorSearchTool
tool = MongoDBVectorSearchTool(
connection_string="mongodb+srv://...",
database_name="mydb",
collection_name="docs",
)
agent = Agent(
role="RAG Agent",
goal="Answer using MongoDB vector search",
backstory="Knowledge retrieval specialist",
tools=[tool],
verbose=True,
)
task = Task(
description="Find relevant content for 'indexing guidance'",
expected_output="A concise answer citing the most relevant matches",
agent=agent,
)
crew = Crew(
agents=[agent],
tasks=[task],
verbose=True,
)
result = crew.kickoff()
```

69
docs/ko/tools/database-data/mysqltool.mdx Normal file
View File

@@ -0,0 +1,69 @@
---
title: MySQL RAG 검색
description: MySQLSearchTool은 MySQL 데이터베이스를 검색하고 가장 관련성 높은 결과를 반환하도록 설계되었습니다.
icon: database
---
## 개요
이 도구는 MySQL 데이터베이스 테이블 내에서 시맨틱 검색을 용이하게 하기 위해 설계되었습니다. RAG(Retrieve and Generate) 기술을 활용하여,
MySQLSearchTool은 사용자가 MySQL 데이터베이스에 특화된 데이터베이스 테이블 콘텐츠를 효율적으로 쿼리할 수 있는 수단을 제공합니다.
시맨틱 검색 쿼리를 통해 관련 데이터를 쉽게 찾을 수 있도록 하여, MySQL 데이터베이스 내의 방대한 데이터셋에 대해 고급 쿼리를 수행해야 하는 사용자를 위한
소중한 리소스가 됩니다.
## 설치
`crewai_tools` 패키지를 설치하고 MySQLSearchTool을 사용하려면, 터미널에서 다음 명령어를 실행하세요:
```shell
pip install 'crewai[tools]'
```
## 예시
아래는 MySQL 데이터베이스 내의 테이블에서 MySQLSearchTool을 사용하여 시맨틱 검색을 수행하는 방법을 보여주는 예시입니다:
```python Code
from crewai_tools import MySQLSearchTool
# Initialize the tool with the database URI and the target table name
tool = MySQLSearchTool(
db_uri='mysql://user:password@localhost:3306/mydatabase',
table_name='employees'
)
```
## 인수
MySQLSearchTool은 작동을 위해 다음 인수들이 필요합니다:
- `db_uri`: 조회할 MySQL 데이터베이스의 URI를 나타내는 문자열입니다. 이 인수는 필수이며, 필요한 인증 정보와 데이터베이스 위치가 포함되어야 합니다.
- `table_name`: 데이터베이스 내에서 시맨틱 검색이 수행될 테이블의 이름을 지정하는 문자열입니다. 이 인수는 필수입니다.
## 커스텀 모델 및 임베딩
기본적으로 이 도구는 임베딩과 요약 모두에 OpenAI를 사용합니다. 모델을 커스터마이즈하려면 다음과 같이 config 딕셔너리를 사용할 수 있습니다.
```python Code
tool = MySQLSearchTool(
config=dict(
llm=dict(
provider="ollama", # or google, openai, anthropic, llama2, ...
config=dict(
model="llama2",
# temperature=0.5,
# top_p=1,
# stream=true,
),
),
embedder=dict(
provider="google",
config=dict(
model="models/embedding-001",
task_type="retrieval_document",
# title="Embeddings",
),
),
)
)
```

77
docs/ko/tools/database-data/nl2sqltool.mdx Normal file
View File

@@ -0,0 +1,77 @@
---
title: NL2SQL 도구
description: NL2SQLTool은 자연어를 SQL 쿼리로 변환하도록 설계되었습니다.
icon: language
---
## 개요
이 도구는 자연어를 SQL 쿼리로 변환하는 데 사용됩니다. 에이전트에 전달되면 쿼리를 생성하고 이를 사용하여 데이터베이스와 상호작용합니다.
이를 통해 에이전트가 데이터베이스에 접근하여 목표에 따라 정보를 가져오고, 해당 정보를 사용해 응답, 보고서 또는 기타 출력물을 생성하는 다양한 워크플로우가 가능해집니다. 또한 에이전트가 자신의 목표에 맞춰 데이터베이스를 업데이트할 수 있는 기능도 제공합니다.
**주의**: 에이전트가 Read-Replica에 접근할 수 있거나, 에이전트가 데이터베이스에 insert/update 쿼리를 실행해도 괜찮은지 반드시 확인하십시오.
## 요구 사항
- SqlAlchemy
- 모든 DB 호환 라이브러리(예: psycopg2, mysql-connector-python)
## 설치
crewai_tools 패키지 설치
```shell
pip install 'crewai[tools]'
```
## 사용법
NL2SQLTool을 사용하려면 데이터베이스 URI를 도구에 전달해야 합니다. URI는 `dialect+driver://username:password@host:port/database` 형식이어야 합니다.
```python Code
from crewai_tools import NL2SQLTool
# psycopg2 was installed to run this example with PostgreSQL
nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config["researcher"],
allow_delegation=False,
tools=[nl2sql]
)
```
## 예시
주요 작업 목표는 다음과 같았습니다:
"각 도시에 대해 월별 평균, 최대, 최소 매출을 조회하되, 사용자 수가 1명 초과인 도시만 포함하세요. 또한 각 도시의 사용자 수를 세고, 평균 월 매출을 기준으로 내림차순 정렬하십시오."
그래서 에이전트는 DB에서 정보를 얻으려고 시도했고, 처음 시도는 잘못되었으므로 에이전트가 다시 시도하여 올바른 정보를 얻은 후 다음 에이전트로 전달합니다.
![alt text](https://github.com/crewAIInc/crewAI-tools/blob/main/crewai_tools/tools/nl2sql/images/image-2.png?raw=true)
![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-3.png)
두 번째 작업 목표는 다음과 같았습니다:
"데이터를 검토하고 상세한 보고서를 작성한 다음, 제공된 데이터를 기반으로 필드를 갖는 테이블을 데이터베이스에 생성하세요. 각 도시에 대해 월별 평균, 최대, 최소 매출 정보를 포함하되, 사용자 수가 1명 초과인 도시만 포함시키세요. 또한 각 도시의 사용자 수를 세고, 평균 월 매출을 기준으로 내림차순 정렬하십시오."
이제 상황이 흥미로워집니다. 에이전트는 테이블을 생성할 SQL 쿼리뿐만 아니라 데이터를 테이블에 삽입하는 쿼리도 생성합니다. 그리고 마지막에는 데이터베이스에 있던 것과 정확히 일치하는 최종 보고서도 반환합니다.
![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-4.png)
![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-5.png)
![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-9.png)
![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-7.png)
이것은 NL2SQLTool이 데이터베이스와 상호작용하고, 데이터베이스의 데이터를 기반으로 보고서를 생성하는 데 어떻게 사용될 수 있는지에 대한 간단한 예시입니다.
이 도구는 에이전트의 논리와 데이터베이스와 상호작용하는 방식에 대해 무한한 가능성을 제공합니다.
```md
DB -> Agent -> ... -> Agent -> DB
```

66
docs/ko/tools/database-data/overview.mdx Normal file
View File

@@ -0,0 +1,66 @@
---
title: "개요"
description: "포괄적인 데이터 액세스를 위해 데이터베이스, 벡터 스토어, 데이터 웨어하우스에 연결하세요"
icon: "face-smile"
---
이러한 툴을 통해 에이전트는 전통적인 SQL 데이터베이스부터 최신 벡터 저장소 및 데이터 웨어하우스에 이르기까지 다양한 데이터베이스 시스템과 상호 작용할 수 있습니다.
## **사용 가능한 도구**
<CardGroup cols={2}>
<Card title="MySQL 도구" icon="database" href="/ko/tools/database-data/mysqltool">
SQL 연산을 사용하여 MySQL 데이터베이스에 연결하고 쿼리할 수 있습니다.
</Card>
<Card title="PostgreSQL 검색" icon="elephant" href="/ko/tools/database-data/pgsearchtool">
PostgreSQL 데이터베이스를 효율적으로 검색하고 쿼리할 수 있습니다.
</Card>
<Card title="Snowflake 검색" icon="snowflake" href="/ko/tools/database-data/snowflakesearchtool">
분석 및 리포팅을 위해 Snowflake 데이터 웨어하우스에 접근합니다.
</Card>
<Card title="NL2SQL 도구" icon="language" href="/ko/tools/database-data/nl2sqltool">
자연어 쿼리를 자동으로 SQL 구문으로 변환합니다.
</Card>
<Card title="Qdrant 벡터 검색" icon="vector-square" href="/ko/tools/database-data/qdrantvectorsearchtool">
Qdrant 벡터 데이터베이스를 사용하여 벡터 임베딩을 검색합니다.
</Card>
<Card title="Weaviate 벡터 검색" icon="network-wired" href="/ko/tools/database-data/weaviatevectorsearchtool">
Weaviate 벡터 데이터베이스로 의미론적 검색을 수행합니다.
</Card>
<Card title="MongoDB 벡터 검색" icon="leaf" href="/ko/tools/database-data/mongodbvectorsearchtool">
인덱싱 도우미를 사용하여 MongoDB Atlas에서 벡터 유사도 검색을 실행합니다.
</Card>
<Card title="SingleStore 검색" icon="database" href="/ko/tools/database-data/singlestoresearchtool">
풀링과 검증을 통해 SingleStore에서 안전한 SELECT/SHOW 쿼리를 실행할 수 있습니다.
</Card>
</CardGroup>
## **일반적인 사용 사례**
- **데이터 분석**: 비즈니스 인텔리전스와 보고를 위해 데이터베이스 쿼리
- **벡터 검색**: 시맨틱 임베딩을 사용하여 유사한 콘텐츠 찾기
- **ETL 작업**: 시스템 간 데이터 추출, 변환 및 적재
- **실시간 분석**: 의사 결정에 필요한 실시간 데이터 접근
```python
from crewai_tools import MySQLTool, QdrantVectorSearchTool, NL2SQLTool
# Create database tools
mysql_db = MySQLTool()
vector_search = QdrantVectorSearchTool()
nl_to_sql = NL2SQLTool()
# Add to your agent
agent = Agent(
role="Data Analyst",
tools=[mysql_db, vector_search, nl_to_sql],
goal="Extract insights from various data sources"
)
```

82
docs/ko/tools/database-data/pgsearchtool.mdx Normal file
View File

@@ -0,0 +1,82 @@
---
title: PG RAG 검색
description: PGSearchTool은 PostgreSQL 데이터베이스를 검색하고 가장 관련성 높은 결과를 반환하도록 설계되었습니다.
icon: elephant
---
생각: 이제 훌륭한 답변을 드릴 수 있습니다.
최종 답변:
## 개요
<Note>
PGSearchTool은 현재 개발 중입니다. 이 문서에서는 의도된 기능과 인터페이스에 대해 설명합니다.
개발이 진행됨에 따라 일부 기능이 제공되지 않거나 변경될 수 있으니 참고하시기 바랍니다.
</Note>
## 설명
PGSearchTool은 PostgreSQL 데이터베이스 테이블 내에서 시맨틱 검색을 용이하게 하는 강력한 도구로 구상되었습니다. 고급 Retrieve and Generate (RAG) 기술을 활용하여, 이 도구는 특히 PostgreSQL 데이터베이스에 최적화된 데이터베이스 테이블 콘텐츠 쿼리를 위한 효율적인 수단을 제공하는 것을 목표로 합니다.
이 도구의 목표는 시맨틱 검색 쿼리를 통해 관련 데이터를 찾는 과정을 단순화하여, PostgreSQL 환경에서 방대한 데이터셋에 대한 고급 쿼리가 필요한 사용자에게 유용한 리소스를 제공하는 것입니다.
## 설치
`crewai_tools` 패키지는 출시 시 PGSearchTool을 포함하게 되며, 다음 명령어를 사용하여 설치할 수 있습니다:
```shell
pip install 'crewai[tools]'
```
<Note>
PGSearchTool은 현재 버전의 `crewai_tools` 패키지에는 아직 포함되어 있지 않습니다. 이 설치 명령어는 도구가 출시되는 즉시 업데이트될 예정입니다.
</Note>
## 예시 사용법
아래는 PostgreSQL 데이터베이스 내의 테이블에서 의미론적 검색을 수행하기 위해 PGSearchTool을 사용하는 방법을 보여주는 예시입니다:
```python Code
from crewai_tools import PGSearchTool
# Initialize the tool with the database URI and the target table name
tool = PGSearchTool(
db_uri='postgresql://user:password@localhost:5432/mydatabase',
table_name='employees'
)
```
## 인자(Arguments)
PGSearchTool은 작동을 위해 다음과 같은 인자를 요구합니다:
| 인자 | 타입 | 설명 |
|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------|
| **db_uri** | `string` | **필수**. 쿼리할 PostgreSQL 데이터베이스의 URI를 나타내는 문자열입니다. 이 인자는 필수이며, 필요한 인증 정보와 데이터베이스의 위치를 포함해야 합니다. |
| **table_name** | `string` | **필수**. 데이터베이스 내에서 시맨틱 검색이 수행될 테이블의 이름을 지정하는 문자열입니다. 이 인자 또한 필수입니다. |
## 커스텀 모델 및 임베딩
이 툴은 기본적으로 임베딩과 요약을 위해 OpenAI를 사용하도록 설계되었습니다. 사용자는 아래와 같이 config 딕셔너리를 통해 모델을 커스터마이즈할 수 있는 옵션을 제공합니다.
```python Code
tool = PGSearchTool(
config=dict(
llm=dict(
provider="ollama", # 혹은 google, openai, anthropic, llama2, ...
config=dict(
model="llama2",
# temperature=0.5,
# top_p=1,
# stream=true,
),
),
embedder=dict(
provider="google", # 혹은 openai, ollama, ...
config=dict(
model="models/embedding-001",
task_type="retrieval_document",
# title="Embeddings",
),
),
)
)
```

272
docs/ko/tools/database-data/qdrantvectorsearchtool.mdx Normal file
View File

@@ -0,0 +1,272 @@
---
title: 'Qdrant 벡터 검색 도구'
description: 'Qdrant 벡터 데이터베이스를 활용한 CrewAI 에이전트의 시맨틱 검색 기능'
icon: vector-square
---
## 개요
Qdrant Vector Search Tool은 [Qdrant](https://qdrant.tech/) 벡터 유사성 검색 엔진을 활용하여 CrewAI 에이전트에 시맨틱 검색 기능을 제공합니다. 이 도구를 사용하면 에이전트가 Qdrant 컬렉션에 저장된 문서를 시맨틱 유사성을 기반으로 검색할 수 있습니다.
## 설치
필수 패키지를 설치하세요:
```bash
uv add qdrant-client
```
## 기본 사용법
아래는 도구를 사용하는 최소한의 예시입니다:
```python
from crewai import Agent
from crewai_tools import QdrantVectorSearchTool
# Initialize the tool
qdrant_tool = QdrantVectorSearchTool(
qdrant_url="your_qdrant_url",
qdrant_api_key="your_qdrant_api_key",
collection_name="your_collection"
)
# Create an agent that uses the tool
agent = Agent(
role="Research Assistant",
goal="Find relevant information in documents",
tools=[qdrant_tool]
)
# The tool will automatically use OpenAI embeddings
# and return the 3 most relevant results with scores > 0.35
```
## 완전한 작동 예시
아래는 다음과 같은 방법을 보여주는 완전한 예시입니다:
1. PDF에서 텍스트 추출
2. OpenAI를 사용하여 임베딩 생성
3. Qdrant에 저장
4. CrewAI agentic RAG 워크플로우로 시맨틱 검색 생성
```python
import os
import uuid
import pdfplumber
from openai import OpenAI
from dotenv import load_dotenv
from crewai import Agent, Task, Crew, Process, LLM
from crewai_tools import QdrantVectorSearchTool
from qdrant_client import QdrantClient
from qdrant_client.models import PointStruct, Distance, VectorParams
# Load environment variables
load_dotenv()
# Initialize OpenAI client
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
# Extract text from PDF
def extract_text_from_pdf(pdf_path):
text = []
with pdfplumber.open(pdf_path) as pdf:
for page in pdf.pages:
page_text = page.extract_text()
if page_text:
text.append(page_text.strip())
return text
# Generate OpenAI embeddings
def get_openai_embedding(text):
response = client.embeddings.create(
input=text,
model="text-embedding-3-small"
)
return response.data[0].embedding
# Store text and embeddings in Qdrant
def load_pdf_to_qdrant(pdf_path, qdrant, collection_name):
# Extract text from PDF
text_chunks = extract_text_from_pdf(pdf_path)
# Create Qdrant collection
if qdrant.collection_exists(collection_name):
qdrant.delete_collection(collection_name)
qdrant.create_collection(
collection_name=collection_name,
vectors_config=VectorParams(size=1536, distance=Distance.COSINE)
)
# Store embeddings
points = []
for chunk in text_chunks:
embedding = get_openai_embedding(chunk)
points.append(PointStruct(
id=str(uuid.uuid4()),
vector=embedding,
payload={"text": chunk}
))
qdrant.upsert(collection_name=collection_name, points=points)
# Initialize Qdrant client and load data
qdrant = QdrantClient(
url=os.getenv("QDRANT_URL"),
api_key=os.getenv("QDRANT_API_KEY")
)
collection_name = "example_collection"
pdf_path = "path/to/your/document.pdf"
load_pdf_to_qdrant(pdf_path, qdrant, collection_name)
# Initialize Qdrant search tool
qdrant_tool = QdrantVectorSearchTool(
qdrant_url=os.getenv("QDRANT_URL"),
qdrant_api_key=os.getenv("QDRANT_API_KEY"),
collection_name=collection_name,
limit=3,
score_threshold=0.35
)
# Create CrewAI agents
search_agent = Agent(
role="Senior Semantic Search Agent",
goal="Find and analyze documents based on semantic search",
backstory="""You are an expert research assistant who can find relevant
information using semantic search in a Qdrant database.""",
tools=[qdrant_tool],
verbose=True
)
answer_agent = Agent(
role="Senior Answer Assistant",
goal="Generate answers to questions based on the context provided",
backstory="""You are an expert answer assistant who can generate
answers to questions based on the context provided.""",
tools=[qdrant_tool],
verbose=True
)
# Define tasks
search_task = Task(
description="""Search for relevant documents about the {query}.
Your final answer should include:
- The relevant information found
- The similarity scores of the results
- The metadata of the relevant documents""",
agent=search_agent
)
answer_task = Task(
description="""Given the context and metadata of relevant documents,
generate a final answer based on the context.""",
agent=answer_agent
)
# Run CrewAI workflow
crew = Crew(
agents=[search_agent, answer_agent],
tasks=[search_task, answer_task],
process=Process.sequential,
verbose=True
)
result = crew.kickoff(
inputs={"query": "What is the role of X in the document?"}
)
print(result)
```
## 도구 매개변수
### 필수 파라미터
- `qdrant_url` (str): Qdrant 서버의 URL
- `qdrant_api_key` (str): Qdrant 인증을 위한 API 키
- `collection_name` (str): 검색할 Qdrant 컬렉션의 이름
### 선택적 매개변수
- `limit` (int): 반환할 최대 결과 수 (기본값: 3)
- `score_threshold` (float): 최소 유사도 점수 임계값 (기본값: 0.35)
- `custom_embedding_fn` (Callable[[str], list[float]]): 텍스트 벡터화를 위한 사용자 지정 함수
## 검색 매개변수
이 도구는 스키마에서 다음과 같은 매개변수를 허용합니다:
- `query` (str): 유사한 문서를 찾기 위한 검색 쿼리
- `filter_by` (str, 선택 사항): 필터링할 메타데이터 필드
- `filter_value` (str, 선택 사항): 필터 기준 값
## 반환 형식
이 도구는 결과를 JSON 형식으로 반환합니다:
```json
[
{
"metadata": {
// Any metadata stored with the document
},
"context": "The actual text content of the document",
"distance": 0.95 // Similarity score
}
]
```
## 기본 임베딩
기본적으로, 이 도구는 벡터화를 위해 OpenAI의 `text-embedding-3-small` 모델을 사용합니다. 이를 위해서는 다음이 필요합니다:
- 환경변수에 설정된 OpenAI API 키: `OPENAI_API_KEY`
## 커스텀 임베딩
기본 임베딩 모델 대신 다음과 같은 경우에 사용자 정의 임베딩 함수를 사용하고 싶을 수 있습니다:
1. 다른 임베딩 모델을 사용하고 싶은 경우 (예: Cohere, HuggingFace, Ollama 모델)
2. 오픈소스 임베딩 모델을 사용하여 비용을 절감해야 하는 경우
3. 벡터 차원 또는 임베딩 품질에 대한 특정 요구 사항이 있는 경우
4. 도메인 특화 임베딩을 사용하고 싶은 경우 (예: 의료 또는 법률 텍스트)
다음은 HuggingFace 모델을 사용하는 예시입니다:
```python
from transformers import AutoTokenizer, AutoModel
import torch
# Load model and tokenizer
tokenizer = AutoTokenizer.from_pretrained('sentence-transformers/all-MiniLM-L6-v2')
model = AutoModel.from_pretrained('sentence-transformers/all-MiniLM-L6-v2')
def custom_embeddings(text: str) -> list[float]:
# Tokenize and get model outputs
inputs = tokenizer(text, return_tensors="pt", padding=True, truncation=True)
outputs = model(**inputs)
# Use mean pooling to get text embedding
embeddings = outputs.last_hidden_state.mean(dim=1)
# Convert to list of floats and return
return embeddings[0].tolist()
# Use custom embeddings with the tool
tool = QdrantVectorSearchTool(
qdrant_url="your_url",
qdrant_api_key="your_key",
collection_name="your_collection",
custom_embedding_fn=custom_embeddings # Pass your custom function
)
```
## 오류 처리
이 도구는 다음과 같은 특정 오류를 처리합니다:
- `qdrant-client`가 설치되어 있지 않으면 ImportError를 발생시킵니다 (자동 설치 옵션 제공)
- `QDRANT_URL`이 설정되어 있지 않으면 ValueError를 발생시킵니다
- 누락된 경우 `uv add qdrant-client`를 사용하여 `qdrant-client` 설치를 안내합니다
## 환경 변수
필수 환경 변수:
```bash
export QDRANT_URL="your_qdrant_url" # If not provided in constructor
export QDRANT_API_KEY="your_api_key" # If not provided in constructor
export OPENAI_API_KEY="your_openai_key" # If using default embeddings
```

59
docs/ko/tools/database-data/singlestoresearchtool.mdx Normal file
View File

@@ -0,0 +1,59 @@
---
title: SingleStore 검색 도구
description: SingleStoreSearchTool은 풀링과 함께 SingleStore에서 SELECT/SHOW 쿼리를 안전하게 실행합니다.
icon: circle
---
# `SingleStoreSearchTool`
## 설명
SingleStore에 대해 연결 풀링과 입력 유효성 검사를 사용하여 읽기 전용 쿼리(`SELECT`/`SHOW`)를 실행합니다.
## 설치
```shell
uv add crewai-tools[singlestore]
```
## 환경 변수
`SINGLESTOREDB_HOST`, `SINGLESTOREDB_USER`, `SINGLESTOREDB_PASSWORD` 등과 같은 변수를 사용할 수 있으며, 또는 `SINGLESTOREDB_URL`을 단일 DSN으로 사용할 수 있습니다.
SingleStore 대시보드에서 API 키를 생성하세요. [문서はこちら](https://docs.singlestore.com/cloud/reference/management-api/#generate-an-api-key).
## 예시
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import SingleStoreSearchTool
tool = SingleStoreSearchTool(
tables=["products"],
host="host",
user="user",
password="pass",
database="db",
)
agent = Agent(
role="Analyst",
goal="Query SingleStore",
tools=[tool],
verbose=True,
)
task = Task(
description="List 5 products",
expected_output="5 rows as JSON/text",
agent=agent,
)
crew = Crew(
agents=[agent],
tasks=[task],
verbose=True,
)
result = crew.kickoff()
```

202
docs/ko/tools/database-data/snowflakesearchtool.mdx Normal file
View File

@@ -0,0 +1,202 @@
---
title: Snowflake 검색 도구
description: SnowflakeSearchTool은 CrewAI 에이전트가 Snowflake 데이터 웨어하우스에서 SQL 쿼리를 실행하고 시맨틱 검색을 수행할 수 있도록 합니다.
icon: snowflake
---
# `SnowflakeSearchTool`
## 설명
`SnowflakeSearchTool`은 Snowflake 데이터 웨어하우스에 연결하고, 연결 풀링, 재시도 로직, 비동기 실행과 같은 고급 기능으로 SQL 쿼리를 실행하도록 설계되었습니다. 이 도구를 통해 CrewAI 에이전트는 Snowflake 데이터베이스와 상호작용할 수 있으므로, Snowflake에 저장된 엔터프라이즈 데이터에 접근이 필요한 데이터 분석, 리포팅, 비즈니스 인텔리전스 작업에 이상적입니다.
## 설치
이 도구를 사용하려면 필요한 종속 항목을 설치해야 합니다:
```shell
uv add cryptography snowflake-connector-python snowflake-sqlalchemy
```
또는 다음과 같이 할 수도 있습니다:
```shell
uv sync --extra snowflake
```
## 시작 단계
`SnowflakeSearchTool`을(를) 효과적으로 사용하려면 다음 단계를 따르세요:
1. **필수 패키지 설치**: 위의 명령어 중 하나를 사용하여 필요한 패키지들을 설치하세요.
2. **Snowflake 연결 구성**: Snowflake 자격 증명을 사용하여 `SnowflakeConfig` 객체를 생성하세요.
3. **도구 초기화**: 필요한 구성을 포함하여 도구의 인스턴스를 생성하세요.
4. **쿼리 실행**: 도구를 사용하여 Snowflake 데이터베이스에서 SQL 쿼리를 실행하세요.
## 예시
다음 예시는 `SnowflakeSearchTool`을 사용하여 Snowflake 데이터베이스에서 데이터를 쿼리하는 방법을 보여줍니다:
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import SnowflakeSearchTool, SnowflakeConfig
# Create Snowflake configuration
config = SnowflakeConfig(
account="your_account",
user="your_username",
password="your_password",
warehouse="COMPUTE_WH",
database="your_database",
snowflake_schema="your_schema"
)
# Initialize the tool
snowflake_tool = SnowflakeSearchTool(config=config)
# Define an agent that uses the tool
data_analyst_agent = Agent(
role="Data Analyst",
goal="Analyze data from Snowflake database",
backstory="An expert data analyst who can extract insights from enterprise data.",
tools=[snowflake_tool],
verbose=True,
)
# Example task to query sales data
query_task = Task(
description="Query the sales data for the last quarter and summarize the top 5 products by revenue.",
expected_output="A summary of the top 5 products by revenue for the last quarter.",
agent=data_analyst_agent,
)
# Create and run the crew
crew = Crew(agents=[data_analyst_agent],
tasks=[query_task])
result = crew.kickoff()
```
추가 매개변수를 사용하여 툴을 맞춤 설정할 수도 있습니다:
```python Code
# Initialize the tool with custom parameters
snowflake_tool = SnowflakeSearchTool(
config=config,
pool_size=10,
max_retries=5,
retry_delay=2.0,
enable_caching=True
)
```
## 매개변수
### SnowflakeConfig 매개변수
`SnowflakeConfig` 클래스는 다음과 같은 매개변수를 받습니다:
- **account**: 필수. Snowflake 계정 식별자.
- **user**: 필수. Snowflake 사용자명.
- **password**: 선택 사항*. Snowflake 비밀번호.
- **private_key_path**: 선택 사항*. 비공개 키 파일 경로(비밀번호의 대안).
- **warehouse**: 필수. Snowflake 웨어하우스 이름.
- **database**: 필수. 기본 데이터베이스.
- **snowflake_schema**: 필수. 기본 스키마.
- **role**: 선택 사항. Snowflake 역할.
- **session_parameters**: 선택 사항. 딕셔너리 형태의 사용자 지정 세션 파라미터.
*`password` 또는 `private_key_path` 중 하나는 반드시 제공되어야 합니다.
### SnowflakeSearchTool 매개변수
`SnowflakeSearchTool`은(는) 초기화 시 다음과 같은 매개변수를 받습니다:
- **config**: 필수. 연결 세부 정보를 포함하는 `SnowflakeConfig` 객체입니다.
- **pool_size**: 선택 사항. 풀 내의 연결 수입니다. 기본값은 5입니다.
- **max_retries**: 선택 사항. 실패한 쿼리에 대한 최대 재시도 횟수입니다. 기본값은 3입니다.
- **retry_delay**: 선택 사항. 재시도 간의 지연 시간(초)입니다. 기본값은 1.0입니다.
- **enable_caching**: 선택 사항. 쿼리 결과 캐싱 활성화 여부입니다. 기본값은 True입니다.
## 사용법
`SnowflakeSearchTool`을 사용할 때는 다음과 같은 매개변수를 제공해야 합니다:
- **query**: 필수. 실행할 SQL 쿼리입니다.
- **database**: 선택 사항. config에 지정된 기본 데이터베이스를 재정의합니다.
- **snowflake_schema**: 선택 사항. config에 지정된 기본 스키마를 재정의합니다.
- **timeout**: 선택 사항. 쿼리 타임아웃(초)입니다. 기본값은 300입니다.
이 도구는 각 행을 컬럼 이름을 키로 갖는 딕셔너리로 표현하여, 결과를 딕셔너리 리스트 형태로 반환합니다.
```python Code
# Example of using the tool with an agent
data_analyst = Agent(
role="Data Analyst",
goal="Analyze sales data from Snowflake",
backstory="An expert data analyst with experience in SQL and data visualization.",
tools=[snowflake_tool],
verbose=True
)
# The agent will use the tool with parameters like:
# query="SELECT product_name, SUM(revenue) as total_revenue FROM sales GROUP BY product_name ORDER BY total_revenue DESC LIMIT 5"
# timeout=600
# Create a task for the agent
analysis_task = Task(
description="Query the sales database and identify the top 5 products by revenue for the last quarter.",
expected_output="A detailed analysis of the top 5 products by revenue.",
agent=data_analyst
)
# Run the task
crew = Crew(
agents=[data_analyst],
tasks=[analysis_task]
)
result = crew.kickoff()
```
## 고급 기능
### 커넥션 풀링
`SnowflakeSearchTool`은 데이터베이스 커넥션을 재사용하여 성능을 향상시키기 위해 커넥션 풀링을 구현합니다. `pool_size` 매개변수를 통해 풀의 크기를 조절할 수 있습니다.
### 자동 재시도
이 도구는 실패한 쿼리를 자동으로 지수적 백오프(Exponential Backoff) 방식으로 재시도합니다. `max_retries` 및 `retry_delay` 매개변수로 재시도 동작을 설정할 수 있습니다.
### 쿼리 결과 캐싱
반복 쿼리의 성능을 향상시키기 위해, 이 도구는 쿼리 결과를 캐싱할 수 있습니다. 이 기능은 기본적으로 활성화되어 있지만 `enable_caching=False`로 설정하면 비활성화할 수 있습니다.
### 키-페어 인증
비밀번호 인증 외에도 도구는 보안 강화를 위해 키-페어 인증을 지원합니다:
```python Code
config = SnowflakeConfig(
account="your_account",
user="your_username",
private_key_path="/path/to/your/private/key.p8",
warehouse="COMPUTE_WH",
database="your_database",
snowflake_schema="your_schema"
)
```
## 오류 처리
`SnowflakeSearchTool`은 일반적인 Snowflake 문제에 대한 포괄적인 오류 처리를 포함하고 있습니다:
- 연결 실패
- 쿼리 시간 초과
- 인증 오류
- 데이터베이스 및 스키마 오류
오류가 발생하면, 도구는 (설정된 경우) 작업을 재시도하고 자세한 오류 정보를 제공합니다.
## 결론
`SnowflakeSearchTool`은 Snowflake 데이터 웨어하우스를 CrewAI 에이전트와 통합할 수 있는 강력한 방법을 제공합니다. 커넥션 풀링, 자동 재시도, 쿼리 캐싱과 같은 기능을 통해 엔터프라이즈 데이터에 효율적이고 신뢰성 있게 접근할 수 있습니다. 이 도구는 특히 Snowflake에 저장된 구조화된 데이터에 접근해야 하는 데이터 분석, 리포팅, 비즈니스 인텔리전스 작업에 유용합니다.

162
docs/ko/tools/database-data/weaviatevectorsearchtool.mdx Normal file
View File

@@ -0,0 +1,162 @@
---
title: Weaviate 벡터 검색
description: WeaviateVectorSearchTool은(는) Weaviate 벡터 데이터베이스에서 의미적으로 유사한 문서를 검색하도록 설계되었습니다.
icon: network-wired
---
## 개요
`WeaviateVectorSearchTool`은 Weaviate 벡터 데이터베이스에 저장된 문서 내에서 의미론적 검색을 수행하도록 특별히 설계되었습니다. 이 도구를 사용하면 주어진 쿼리에 대해 의미적으로 유사한 문서를 찾을 수 있으며, 벡터 임베딩의 강점을 활용하여 더욱 정확하고 문맥에 맞는 검색 결과를 제공합니다.
[Weaviate](https://weaviate.io/)는 벡터 임베딩을 저장하고 쿼리할 수 있는 벡터 데이터베이스로, 의미론적 검색 기능을 제공합니다.
## 설치
이 도구를 프로젝트에 포함하려면 Weaviate 클라이언트를 설치해야 합니다:
```shell
uv add weaviate-client
```
## 시작하는 단계
`WeaviateVectorSearchTool`을 효과적으로 사용하려면 다음 단계를 따르세요:
1. **패키지 설치**: Python 환경에 `crewai[tools]` 및 `weaviate-client` 패키지가 설치되어 있는지 확인하세요.
2. **Weaviate 설정**: Weaviate 클러스터를 설정하세요. 안내는 [Weaviate 공식 문서](https://weaviate.io/developers/wcs/manage-clusters/connect)를 참고하세요.
3. **API 키**: Weaviate 클러스터 URL과 API 키를 확보하세요.
4. **OpenAI API 키**: 환경 변수에 `OPENAI_API_KEY`로 OpenAI API 키가 설정되어 있는지 확인하세요.
## 예시
다음 예시는 도구를 초기화하고 검색을 실행하는 방법을 보여줍니다:
```python Code
from crewai_tools import WeaviateVectorSearchTool
# Initialize the tool
tool = WeaviateVectorSearchTool(
collection_name='example_collections',
limit=3,
weaviate_cluster_url="https://your-weaviate-cluster-url.com",
weaviate_api_key="your-weaviate-api-key",
)
@agent
def search_agent(self) -> Agent:
'''
This agent uses the WeaviateVectorSearchTool to search for
semantically similar documents in a Weaviate vector database.
'''
return Agent(
config=self.agents_config["search_agent"],
tools=[tool]
)
```
## 매개변수
`WeaviateVectorSearchTool`은 다음과 같은 매개변수를 허용합니다:
- **collection_name**: 필수. 검색할 컬렉션의 이름입니다.
- **weaviate_cluster_url**: 필수. Weaviate 클러스터의 URL입니다.
- **weaviate_api_key**: 필수. Weaviate 클러스터의 API 키입니다.
- **limit**: 선택 사항. 반환할 결과 수입니다. 기본값은 `3`입니다.
- **vectorizer**: 선택 사항. 사용할 벡터라이저입니다. 제공되지 않으면 `nomic-embed-text` 모델의 `text2vec_openai`를 사용합니다.
- **generative_model**: 선택 사항. 사용할 생성 모델입니다. 제공되지 않으면 OpenAI의 `gpt-4o`를 사용합니다.
## 고급 구성
도구에서 사용하는 벡터라이저와 생성 모델을 사용자 지정할 수 있습니다:
```python Code
from crewai_tools import WeaviateVectorSearchTool
from weaviate.classes.config import Configure
# Setup custom model for vectorizer and generative model
tool = WeaviateVectorSearchTool(
collection_name='example_collections',
limit=3,
vectorizer=Configure.Vectorizer.text2vec_openai(model="nomic-embed-text"),
generative_model=Configure.Generative.openai(model="gpt-4o-mini"),
weaviate_cluster_url="https://your-weaviate-cluster-url.com",
weaviate_api_key="your-weaviate-api-key",
)
```
## 문서 미리 로드하기
도구를 사용하기 전에 Weaviate 데이터베이스에 문서를 미리 로드할 수 있습니다:
```python Code
import os
from crewai_tools import WeaviateVectorSearchTool
import weaviate
from weaviate.classes.init import Auth
# Connect to Weaviate
client = weaviate.connect_to_weaviate_cloud(
cluster_url="https://your-weaviate-cluster-url.com",
auth_credentials=Auth.api_key("your-weaviate-api-key"),
headers={"X-OpenAI-Api-Key": "your-openai-api-key"}
)
# Get or create collection
test_docs = client.collections.get("example_collections")
if not test_docs:
test_docs = client.collections.create(
name="example_collections",
vectorizer_config=Configure.Vectorizer.text2vec_openai(model="nomic-embed-text"),
generative_config=Configure.Generative.openai(model="gpt-4o"),
)
# Load documents
docs_to_load = os.listdir("knowledge")
with test_docs.batch.dynamic() as batch:
for d in docs_to_load:
with open(os.path.join("knowledge", d), "r") as f:
content = f.read()
batch.add_object(
{
"content": content,
"year": d.split("_")[0],
}
)
# Initialize the tool
tool = WeaviateVectorSearchTool(
collection_name='example_collections',
limit=3,
weaviate_cluster_url="https://your-weaviate-cluster-url.com",
weaviate_api_key="your-weaviate-api-key",
)
```
## 에이전트 통합 예시
다음은 `WeaviateVectorSearchTool`을 CrewAI 에이전트와 통합하는 방법입니다:
```python Code
from crewai import Agent
from crewai_tools import WeaviateVectorSearchTool
# Initialize the tool
weaviate_tool = WeaviateVectorSearchTool(
collection_name='example_collections',
limit=3,
weaviate_cluster_url="https://your-weaviate-cluster-url.com",
weaviate_api_key="your-weaviate-api-key",
)
# Create an agent with the tool
rag_agent = Agent(
name="rag_agent",
role="You are a helpful assistant that can answer questions with the help of the WeaviateVectorSearchTool.",
llm="gpt-4o-mini",
tools=[weaviate_tool],
)
```
## 결론
`WeaviateVectorSearchTool`은 Weaviate 벡터 데이터베이스에서 의미적으로 유사한 문서를 검색할 수 있는 강력한 방법을 제공합니다. 벡터 임베딩을 활용함으로써, 기존의 키워드 기반 검색에 비해 더 정확하고 맥락에 맞는 검색 결과를 얻을 수 있습니다. 이 도구는 정확한 일치가 아닌 의미에 기반하여 정보를 찾아야 하는 애플리케이션에 특히 유용합니다.

77
docs/ko/tools/file-document/csvsearchtool.mdx Normal file
View File

@@ -0,0 +1,77 @@
---
title: CSV RAG 검색
description: CSVSearchTool은 CSV 파일의 콘텐츠 내에서 의미론적 검색을 수행하기 위해 설계된 강력한 RAG(Retrieval-Augmented Generation) 도구입니다.
icon: file-csv
---
# `CSVSearchTool`
<Note>
**실험적 기능**: 우리는 여전히 도구를 개선하고 있으므로, 예기치 않은 동작이나 변경이 발생할 수 있습니다.
</Note>
## 설명
이 도구는 CSV 파일의 내용 내에서 RAG(검색 기반 생성) 검색을 수행하는 데 사용됩니다. 사용자는 지정된 CSV 파일의 콘텐츠에서 쿼리를 의미적으로 검색할 수 있습니다.
이 기능은 기존의 검색 방법이 비효율적일 수 있는 대용량 CSV 데이터셋에서 정보를 추출할 때 특히 유용합니다. "Search"라는 이름이 포함된 모든 도구, 예를 들어 CSVSearchTool을 포함하여,
다양한 데이터 소스를 검색하도록 설계된 RAG 도구입니다.
## 설치
crewai_tools 패키지 설치
```shell
pip install 'crewai[tools]'
```
## 예시
```python Code
from crewai_tools import CSVSearchTool
# Initialize the tool with a specific CSV file.
# This setup allows the agent to only search the given CSV file.
tool = CSVSearchTool(csv='path/to/your/csvfile.csv')
# OR
# Initialize the tool without a specific CSV file.
# Agent will need to provide the CSV path at runtime.
tool = CSVSearchTool()
```
## 인자
다음 매개변수들은 `CSVSearchTool`의 동작을 사용자 정의하는 데 사용할 수 있습니다:
| 인자 | 타입 | 설명 |
|:------------------|:-----------|:---------------------------------------------------------------------------------------------------------------------------------|
| **csv** | `string` | _선택 사항_. 검색하려는 CSV 파일의 경로입니다. 이 인자는 도구가 특정 CSV 파일 없이 초기화된 경우 필수이며, 그렇지 않은 경우 선택 사항입니다. |
## 커스텀 모델 및 임베딩
기본적으로 이 도구는 임베딩과 요약 모두에 OpenAI를 사용합니다. 모델을 사용자 지정하려면 다음과 같이 config 딕셔너리를 사용할 수 있습니다:
```python Code
tool = CSVSearchTool(
config=dict(
llm=dict(
provider="ollama", # or google, openai, anthropic, llama2, ...
config=dict(
model="llama2",
# temperature=0.5,
# top_p=1,
# stream=true,
),
),
embedder=dict(
provider="google", # or openai, ollama, ...
config=dict(
model="models/embedding-001",
task_type="retrieval_document",
# title="Embeddings",
),
),
)
)
```

52
docs/ko/tools/file-document/directoryreadtool.mdx Normal file
View File

@@ -0,0 +1,52 @@
---
title: 디렉터리 읽기
description: DirectoryReadTool은 디렉터리의 내용을 포괄적으로 나열할 수 있도록 설계된 강력한 유틸리티입니다.
icon: folder-tree
---
# `DirectoryReadTool`
<Note>
저희는 아직 도구를 개선하는 중이므로, 예기치 않은 동작이나 변경 사항이 있을 수 있습니다.
</Note>
## 설명
DirectoryReadTool은 디렉터리 내용을 포괄적으로 나열해주는 강력한 유틸리티입니다.
지정된 디렉터리를 재귀적으로 탐색할 수 있으며, 하위 디렉터리를 포함한 모든 파일을 상세하게 나열해 사용자에게 제공합니다.
이 도구는 디렉터리 구조에 대한 철저한 인벤토리가 필요하거나, 디렉터리 내 파일의 구성이 올바른지 검증할 때 매우 중요합니다.
## 설치
프로젝트에서 DirectoryReadTool을 사용하려면 `crewai_tools` 패키지를 설치해야 합니다. 이 패키지가 아직 환경에 없다면 아래 명령어를 사용하여 pip로 설치할 수 있습니다:
```shell
pip install 'crewai[tools]'
```
이 명령어는 `crewai_tools` 패키지의 최신 버전을 설치하며, DirectoryReadTool을 비롯한 다양한 유틸리티를 사용할 수 있습니다.
## 예시
DirectoryReadTool을 사용하는 것은 간단합니다. 다음 코드 스니펫은 지정한 디렉터리의 내용을 나열하기 위해 이 도구를 설정하고 사용하는 방법을 보여줍니다:
```python Code
from crewai_tools import DirectoryReadTool
# 에이전트가 실행 중에 알게 되는 모든 디렉터리의 내용을 읽을 수 있도록 도구를 초기화합니다.
tool = DirectoryReadTool()
# 또는
# 특정 디렉터리로 도구를 초기화하여,
# 에이전트가 지정한 디렉터리의 내용만 읽을 수 있도록 합니다.
tool = DirectoryReadTool(directory='/path/to/your/directory')
```
## 인수
다음 매개변수들은 `DirectoryReadTool`의 동작을 사용자 정의하는 데 사용할 수 있습니다:
| 인수 | 타입 | 설명 |
|:---------------|:---------|:-----------------------------------------------------------------------------------------------------------------------------------------|
| **directory** | `string` | _선택 사항_. 나열하려는 디렉터리의 경로를 지정하는 인수입니다. 절대 경로와 상대 경로 모두 허용하며, 원하는 디렉터리로 도구를 안내하여 내용을 나열할 수 있습니다. |

67
docs/ko/tools/file-document/directorysearchtool.mdx Normal file
View File

@@ -0,0 +1,67 @@
---
title: 디렉터리 RAG 검색
description: DirectorySearchTool은 디렉터리의 콘텐츠 내에서 의미 기반 검색을 수행하도록 설계된 강력한 RAG(Retrieval-Augmented Generation) 도구입니다.
icon: address-book
---
# `DirectorySearchTool`
<Note>
**실험적 기능**: DirectorySearchTool은 지속적으로 개발되고 있습니다. 기능과 특성이 변경될 수 있으며, 도구를 개선하는 과정에서 예기치 않은 동작이 발생할 수 있습니다.
</Note>
## 설명
DirectorySearchTool은 지정된 디렉터리의 콘텐츠 내에서 시맨틱 검색을 가능하게 하며, 파일 탐색의 효율성을 높이기 위해 Retrieval-Augmented Generation(RAG) 방법론을 활용합니다. 유연성을 고려하여 설계되어, 사용자는 런타임 중 검색 디렉터리를 동적으로 지정하거나 초기 설정 시 고정 디렉터리를 지정할 수 있습니다.
## 설치
DirectorySearchTool을 사용하려면 먼저 crewai_tools 패키지를 설치해야 합니다. 터미널에서 다음 명령어를 실행하세요:
```shell
pip install 'crewai[tools]'
```
## 초기화 및 사용법
`crewai_tools` 패키지에서 DirectorySearchTool을 임포트하여 시작하세요. 디렉토리를 지정하지 않고 도구를 초기화할 수 있으며, 이를 통해 런타임 시 검색 디렉토리를 설정할 수 있습니다. 또는 미리 정의된 디렉토리로 도구를 초기화할 수도 있습니다.
```python Code
from crewai_tools import DirectorySearchTool
# 런타임에 동적으로 디렉토리를 지정할 때
tool = DirectorySearchTool()
# 고정된 디렉토리에서 검색할 때
tool = DirectorySearchTool(directory='/path/to/directory')
```
## 인수
- `directory`: 검색 디렉토리를 지정하는 문자열 인수입니다. 이 인수는 초기화 시 선택 사항이지만, 처음에 설정되지 않은 경우 검색 시 필수입니다.
## 커스텀 모델과 임베딩
DirectorySearchTool은 기본적으로 OpenAI를 사용하여 임베딩 및 요약을 수행합니다. 이 설정의 커스터마이즈 옵션에는 모델 공급자 및 구성을 변경하는 것이 포함되어 있어, 고급 사용자를 위한 유연성을 향상시킵니다.
```python Code
tool = DirectorySearchTool(
config=dict(
llm=dict(
provider="ollama", # Options include ollama, google, anthropic, llama2, and more
config=dict(
model="llama2",
# Additional configurations here
),
),
embedder=dict(
provider="google", # or openai, ollama, ...
config=dict(
model="models/embedding-001",
task_type="retrieval_document",
# title="Embeddings",
),
),
)
)
```

79
docs/ko/tools/file-document/docxsearchtool.mdx Normal file
View File

@@ -0,0 +1,79 @@
---
title: DOCX RAG 검색
description: DOCXSearchTool은 DOCX 문서 내에서 의미 기반 검색을 수행하도록 설계된 RAG 도구입니다.
icon: file-word
---
# `DOCXSearchTool`
<Note>
저희는 아직 도구를 개선하는 중이므로, 예기치 않은 동작이나 변경 사항이 발생할 수 있습니다.
</Note>
## 설명
`DOCXSearchTool`은 DOCX 문서 내에서 의미 기반 검색을 수행하기 위해 설계된 RAG 도구입니다.
사용자는 쿼리 기반 검색을 통해 DOCX 파일에서 관련 정보를 효과적으로 검색하고 추출할 수 있습니다.
이 도구는 데이터 분석, 정보 관리, 연구 작업에 매우 유용하며,
대규모 문서 컬렉션에서 특정 정보를 찾는 과정을 간소화해 줍니다.
## 설치
터미널에서 다음 명령어를 실행하여 crewai_tools 패키지를 설치하세요:
```shell
uv pip install docx2txt 'crewai[tools]'
```
## 예시
다음 예시는 DOCXSearchTool을 초기화하여 모든 DOCX 파일의 내용에서 검색하거나 특정 DOCX 파일 경로로 검색하는 방법을 보여줍니다.
```python Code
from crewai_tools import DOCXSearchTool
# Initialize the tool to search within any DOCX file's content
tool = DOCXSearchTool()
# OR
# Initialize the tool with a specific DOCX file,
# so the agent can only search the content of the specified DOCX file
tool = DOCXSearchTool(docx='path/to/your/document.docx')
```
## 인자
다음 매개변수를 사용하여 `DOCXSearchTool`의 동작을 사용자 정의할 수 있습니다:
| 인자 | 타입 | 설명 |
|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------|
| **docx** | `string` | _선택 사항_. 검색하려는 DOCX 파일의 경로를 지정하는 인자입니다. 초기화 시 제공하지 않은 경우, 도구는 이후에 검색을 위한 DOCX 파일의 내용 경로를 지정할 수 있도록 허용합니다. |
## 커스텀 모델과 임베딩
기본적으로 이 도구는 임베딩과 요약 모두에 OpenAI를 사용합니다. 모델을 커스터마이즈하려면 다음과 같이 config 딕셔너리를 사용할 수 있습니다:
```python Code
tool = DOCXSearchTool(
config=dict(
llm=dict(
provider="ollama", # or google, openai, anthropic, llama2, ...
config=dict(
model="llama2",
# temperature=0.5,
# top_p=1,
# stream=true,
),
),
embedder=dict(
provider="google", # or openai, ollama, ...
config=dict(
model="models/embedding-001",
task_type="retrieval_document",
# title="Embeddings",
),
),
)
)
```

44
docs/ko/tools/file-document/filereadtool.mdx Normal file
View File

@@ -0,0 +1,44 @@
---
title: 파일 읽기
description: FileReadTool은 로컬 파일 시스템에서 파일을 읽도록 설계되었습니다.
icon: folders
---
## 개요
<Note>
우리는 도구를 계속 개선하고 있으므로, 향후 예기치 않은 동작이나 변경 사항이 발생할 수 있습니다.
</Note>
FileReadTool은 crewai_tools 패키지 내에서 파일 읽기와 콘텐츠 검색을 용이하게 하는 기능 모음입니다.
이 모음에는 배치 텍스트 파일 처리, 런타임 구성 파일 읽기, 분석을 위한 데이터 가져오기 등 다양한 도구가 포함되어 있습니다.
`.txt`, `.csv`, `.json` 등 다양한 텍스트 기반 파일 형식을 지원합니다. 파일 유형에 따라 이 모음은
JSON 콘텐츠를 Python 딕셔너리로 변환하여 사용을 쉽게 하는 등 특화된 기능을 제공합니다.
## 설치
이전에 FileReadTool에 할당된 기능을 사용하려면 crewai_tools 패키지를 설치하세요:
```shell
pip install 'crewai[tools]'
```
## 사용 예시
FileReadTool을 시작하려면:
```python Code
from crewai_tools import FileReadTool
# 에이전트가 알고 있거나 경로를 학습한 파일을 읽기 위해 도구를 초기화합니다.
file_read_tool = FileReadTool()
# 또는
# 특정 파일 경로로 도구를 초기화하여 에이전트가 지정된 파일의 내용만 읽을 수 있도록 합니다.
file_read_tool = FileReadTool(file_path='path/to/your/file.txt')
```
## 인수
- `file_path`: 읽고자 하는 파일의 경로입니다. 절대 경로와 상대 경로 모두 허용됩니다. 파일이 존재하는지와 필요한 접근 권한이 있는지 반드시 확인하세요.

50
docs/ko/tools/file-document/filewritetool.mdx Normal file
View File

@@ -0,0 +1,50 @@
---
title: 파일 쓰기
description: FileWriterTool은 파일에 내용을 쓰도록 설계되었습니다.
icon: file-pen
---
# `FileWriterTool`
## 설명
`FileWriterTool`은 crewai_tools 패키지의 구성 요소로, 다양한 운영 체제(Windows, Linux, macOS)에서 파일에 내용을 작성하는 과정을 간소화하도록 설계되었습니다.
이 도구는 보고서 생성, 로그 저장, 설정 파일 작성 등과 같은 시나리오에서 특히 유용합니다.
운영 체제마다 다른 경로 처리를 지원하며, UTF-8 인코딩을 지원하고, 디렉토리가 존재하지 않으면 자동으로 생성하여, 다양한 플랫폼에서 출력 결과를 안정적으로 정리할 수 있도록 도와줍니다.
## 설치
프로젝트에서 `FileWriterTool`을 사용하려면 crewai_tools 패키지를 설치하세요:
```shell
pip install 'crewai[tools]'
```
## 예시
`FileWriterTool`을(를) 시작하려면:
```python Code
from crewai_tools import FileWriterTool
# Initialize the tool
file_writer_tool = FileWriterTool()
# Write content to a file in a specified directory
result = file_writer_tool._run('example.txt', 'This is a test content.', 'test_directory')
print(result)
```
## 인자
- `filename`: 생성하거나 덮어쓸 파일의 이름입니다.
- `content`: 파일에 쓸 내용입니다.
- `directory` (선택 사항): 파일이 생성될 디렉터리의 경로입니다. 기본값은 현재 디렉터리(`.`)입니다. 디렉터리가 존재하지 않으면 생성됩니다.
## 결론
`FileWriterTool`을 crew에 통합함으로써, 에이전트는 다양한 운영 체제에서 파일에 내용을 안정적으로 쓸 수 있습니다.
이 도구는 출력 데이터를 저장하거나, 구조화된 파일 시스템을 생성하거나, 크로스 플랫폼 파일 작업을 처리해야 하는 작업에 필수적입니다.
특히 표준 Python 파일 작업에서 파일 쓰기 이슈가 발생할 수 있는 Windows 사용자에게 권장됩니다.
제공된 설정 및 사용 가이드라인을 준수하면, 이 도구를 프로젝트에 통합하는 과정이 간단하며 모든 플랫폼에서 일관된 파일 쓰기 동작을 보장합니다.

72
docs/ko/tools/file-document/jsonsearchtool.mdx Normal file
View File

@@ -0,0 +1,72 @@
---
title: JSON RAG 검색
description: JSONSearchTool은 JSON 파일을 검색하여 가장 관련성 높은 결과를 반환하도록 설계되었습니다.
icon: file-code
---
# `JSONSearchTool`
<Note>
JSONSearchTool은 현재 실험 단계에 있습니다. 이 도구는 활발히 개발 중이므로, 사용자들이 예기치 못한 동작이나 변경 사항을 경험할 수 있습니다. 문제점이나 개선 제안이 있으시다면 적극적으로 피드백을 제공해 주시기 바랍니다.
</Note>
## 설명
JSONSearchTool은 JSON 파일 내용 내에서 효율적이고 정확한 검색을 지원하도록 설계되었습니다. 이 도구는 RAG(Retrieve and Generate) 검색 메커니즘을 활용하여 사용자가 특정 JSON 파일 내에서 타겟팅된 검색을 위해 JSON 경로를 지정할 수 있습니다. 이 기능은 검색 결과의 정확성과 관련성을 크게 향상시킵니다.
## 설치
JSONSearchTool을 설치하려면 다음 pip 명령어를 사용하세요:
```shell
pip install 'crewai[tools]'
```
## 사용 예시
여기 JSONSearchTool을 효과적으로 활용하여 JSON 파일 내에서 검색하는 방법에 대한 업데이트된 예시가 있습니다. 이 예시들은 코드베이스에서 확인된 현재 구현 및 사용 패턴을 반영합니다.
```python Code
from crewai_tools import JSONSearchTool
# 일반적인 JSON 내용 검색
# 이 방법은 JSON 경로를 사전에 알고 있거나 동적으로 식별할 수 있을 때 적합합니다.
tool = JSONSearchTool()
# 특정 JSON 파일로 검색 범위 제한
# 검색 범위를 특정 JSON 파일로 제한하고 싶을 때 이 초기화 방법을 사용하세요.
tool = JSONSearchTool(json_path='./path/to/your/file.json')
```
## 인자
- `json_path` (str, 선택적): 검색할 JSON 파일의 경로를 지정합니다. 이 인자는 도구가 일반 검색을 위해 초기화된 경우 필수가 아닙니다. 제공될 경우, 지정된 JSON 파일로 검색이 제한됩니다.
## 구성 옵션
JSONSearchTool은 구성 딕셔너리를 통해 광범위한 커스터마이징을 지원합니다. 이를 통해 사용자는 임베딩 및 요약을 위한 다양한 모델을 요구 사항에 따라 선택할 수 있습니다.
```python Code
tool = JSONSearchTool(
config={
"llm": {
"provider": "ollama", # Other options include google, openai, anthropic, llama2, etc.
"config": {
"model": "llama2",
# Additional optional configurations can be specified here.
# temperature=0.5,
# top_p=1,
# stream=true,
},
},
"embedding_model": {
"provider": "google", # or openai, ollama, ...
"config": {
"model": "models/embedding-001",
"task_type": "retrieval_document",
# Further customization options can be added here.
},
},
}
)
```

73
docs/ko/tools/file-document/mdxsearchtool.mdx Normal file
View File

@@ -0,0 +1,73 @@
---
title: MDX RAG 검색
description: MDXSearchTool은 MDX 파일을 검색하고 가장 관련성 높은 결과를 반환하도록 설계되었습니다.
icon: markdown
---
# `MDXSearchTool`
<Note>
MDXSearchTool은 지속적으로 개발 중입니다. 기능이 추가되거나 제거될 수 있으며, 도구를 개선하는 과정에서 기능이 예측할 수 없이 변경될 수 있습니다.
</Note>
## 설명
MDX Search Tool은 고급 markdown 언어 추출을 용이하게 하기 위해 설계된 `crewai_tools` 패키지의 구성 요소입니다. 이 도구는 사용자가 쿼리 기반 검색을 통해 MD 파일에서 관련 정보를 효과적으로 검색하고 추출할 수 있게 해줍니다. 데이터 분석, 정보 관리, 연구 작업에 매우 유용하며, 대규모 문서 컬렉션 내에서 특정 정보를 찾는 과정을 간소화합니다.
## 설치
MDX Search Tool을 사용하기 전에 `crewai_tools` 패키지가 설치되어 있는지 확인하세요. 설치되어 있지 않다면, 다음 명령어로 설치할 수 있습니다:
```shell
pip install 'crewai[tools]'
```
## 사용 예시
MDX Search Tool을 사용하려면 먼저 필요한 환경 변수를 설정해야 합니다. 그런 다음 이 도구를 crewAI 프로젝트에 통합하여 시장 조사를 시작할 수 있습니다. 아래는 이를 수행하는 기본 예시입니다:
```python Code
from crewai_tools import MDXSearchTool
# Initialize the tool to search any MDX content it learns about during execution
tool = MDXSearchTool()
# OR
# Initialize the tool with a specific MDX file path for an exclusive search within that document
tool = MDXSearchTool(mdx='path/to/your/document.mdx')
```
## 매개변수
- mdx: **선택 사항**. 검색에 사용할 MDX 파일 경로를 지정합니다. 초기화 시 제공할 수 있습니다.
## 모델 및 임베딩 커스터마이징
이 도구는 기본적으로 임베딩과 요약을 위해 OpenAI를 사용합니다. 커스터마이징을 위해 아래와 같이 설정 딕셔너리를 사용할 수 있습니다.
```python Code
tool = MDXSearchTool(
config=dict(
llm=dict(
provider="ollama", # 옵션에는 google, openai, anthropic, llama2 등이 있습니다.
config=dict(
model="llama2",
# 선택적 파라미터를 여기에 포함할 수 있습니다.
# temperature=0.5,
# top_p=1,
# stream=true,
),
),
embedder=dict(
provider="google", # 또는 openai, ollama, ...
config=dict(
model="models/embedding-001",
task_type="retrieval_document",
# 임베딩에 대한 선택적 제목을 여기에 추가할 수 있습니다.
# title="Embeddings",
),
),
)
)
```

87
docs/ko/tools/file-document/ocrtool.mdx Normal file
View File

@@ -0,0 +1,87 @@
---
title: OCR 도구
description: OCRTool은 비전 기능을 가진 LLM을 사용하여 로컬 이미지나 이미지 URL에서 텍스트를 추출합니다.
icon: image
---
# `OCRTool`
## 설명
이미지(로컬 경로 또는 URL)에서 텍스트를 추출합니다. CrewAI의 LLM 인터페이스를 통해 비전 기능이 있는 LLM을 사용합니다.
## 설치
`crewai-tools` 외에 추가 설치는 필요하지 않습니다. 선택한 LLM이 비전 기능을 지원하는지 확인하세요.
## 파라미터
### 실행 매개변수
- `image_path_url` (str, 필수): 로컬 이미지 경로 또는 HTTP(S) URL.
## 예시
### 직접 사용
```python Code
from crewai_tools import OCRTool
print(OCRTool().run(image_path_url="/tmp/receipt.png"))
```
### 에이전트와 함께
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import OCRTool
ocr = OCRTool()
agent = Agent(
role="OCR",
goal="Extract text",
tools=[ocr],
)
task = Task(
description="Extract text from https://example.com/invoice.jpg",
expected_output="All detected text in plain text",
agent=agent,
)
crew = Crew(agents=[agent], tasks=[task])
result = crew.kickoff()
```
## 참고 사항
- 선택한 LLM이 이미지 입력을 지원하는지 확인하세요.
- 큰 이미지는 토큰 사용량을 줄이기 위해 다운스케일링을 고려하세요.
- 필요하다면 README 지침에 맞게 특정 LLM 인스턴스(예: `LLM(model="gpt-4o")`)를 도구에 전달할 수 있습니다.
## 예시
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import OCRTool
tool = OCRTool()
agent = Agent(
role="OCR Specialist",
goal="Extract text from images",
backstory="Vision‑enabled analyst",
tools=[tool],
verbose=True,
)
task = Task(
description="Extract text from https://example.com/receipt.png",
expected_output="All detected text in plain text",
agent=agent,
)
crew = Crew(agents=[agent], tasks=[task])
result = crew.kickoff()
```

96
docs/ko/tools/file-document/overview.mdx Normal file
View File

@@ -0,0 +1,96 @@
---
title: "개요"
description: "CrewAI의 문서 처리 도구를 사용하여 다양한 파일 형식을 읽고, 쓰고, 검색하세요"
icon: "face-smile"
---
이러한 도구들은 에이전트가 다양한 파일 형식과 문서 유형을 다룰 수 있도록 해줍니다. PDF를 읽는 것부터 JSON 데이터를 처리하는 것까지, 이 도구들은 모든 문서 처리 요구를 충족합니다.
## **사용 가능한 도구**
<CardGroup cols={2}>
<Card title="파일 읽기 도구" icon="folders" href="/ko/tools/file-document/filereadtool">
텍스트, 마크다운 등 다양한 파일 유형에서 내용을 읽어옵니다.
</Card>
<Card title="파일 쓰기 도구" icon="file-pen" href="/ko/tools/file-document/filewritetool">
파일에 내용을 쓰고, 새로운 문서를 생성하거나 처리된 데이터를 저장합니다.
</Card>
<Card title="PDF 검색 도구" icon="file-pdf" href="/ko/tools/file-document/pdfsearchtool">
PDF 문서에서 텍스트를 효율적으로 검색하고 추출합니다.
</Card>
<Card title="DOCX 검색 도구" icon="file-word" href="/ko/tools/file-document/docxsearchtool">
Microsoft Word 문서를 검색하고 관련된 내용을 추출합니다.
</Card>
<Card title="JSON 검색 도구" icon="brackets-curly" href="/ko/tools/file-document/jsonsearchtool">
JSON 파일을 파싱하고 고급 쿼리 기능으로 검색합니다.
</Card>
<Card title="CSV 검색 도구" icon="table" href="/ko/tools/file-document/csvsearchtool">
CSV 파일을 처리하고, 특정 행과 열을 추출하여 검색합니다.
</Card>
<Card title="XML 검색 도구" icon="code" href="/ko/tools/file-document/xmlsearchtool">
XML 파일을 파싱하고 특정 요소 및 속성을 검색합니다.
</Card>
<Card title="MDX 검색 도구" icon="markdown" href="/ko/tools/file-document/mdxsearchtool">
MDX 파일을 검색하여 문서의 내용을 추출합니다.
</Card>
<Card title="TXT 검색 도구" icon="file-lines" href="/ko/tools/file-document/txtsearchtool">
일반 텍스트 파일을 패턴 매칭 기능으로 검색합니다.
</Card>
<Card title="디렉터리 검색 도구" icon="folder-open" href="/ko/tools/file-document/directorysearchtool">
디렉터리 구조 내의 파일 및 폴더를 검색합니다.
</Card>
<Card title="디렉터리 읽기 도구" icon="folder" href="/ko/tools/file-document/directoryreadtool">
디렉터리의 내용, 파일 구조 및 메타데이터를 읽고 나열합니다.
</Card>
<Card title="OCR 도구" icon="image" href="/ko/tools/file-document/ocrtool">
비전 기능이 있는 LLM을 사용하여 이미지(로컬 파일 또는 URL)에서 텍스트를 추출합니다.
</Card>
<Card title="PDF 텍스트 쓰기 도구" icon="file-pdf" href="/ko/tools/file-document/pdf-text-writing-tool">
PDF에서 특정 좌표에 텍스트를 작성하고, 옵션으로 커스텀 폰트도 지원합니다.
</Card>
</CardGroup>
## **공통 사용 사례**
- **문서 처리**: 다양한 파일 형식에서 콘텐츠를 추출하고 분석
- **데이터 가져오기**: CSV, JSON, XML 파일에서 구조화된 데이터 읽기
- **콘텐츠 검색**: 대용량 문서 컬렉션 내에서 특정 정보 찾기
- **파일 관리**: 파일 및 디렉터리 구성 및 조작
- **데이터 내보내기**: 처리된 결과를 다양한 파일 형식으로 저장
## **빠른 시작 예시**
```python
from crewai_tools import FileReadTool, PDFSearchTool, JSONSearchTool
# Create tools
file_reader = FileReadTool()
pdf_searcher = PDFSearchTool()
json_processor = JSONSearchTool()
# Add to your agent
agent = Agent(
role="Document Analyst",
tools=[file_reader, pdf_searcher, json_processor],
goal="Process and analyze various document types"
)
```
## **문서 처리 팁**
- **파일 권한**: 에이전트가 적절한 읽기/쓰기 권한을 가지고 있는지 확인하세요
- **대용량 파일**: 매우 큰 문서의 경우 청킹(chunking)을 고려하세요
- **형식 지원**: 도구 문서에서 지원되는 파일 형식을 확인하세요
- **오류 처리**: 손상되었거나 접근이 불가능한 파일에 대해 적절한 오류 처리를 구현하세요

74
docs/ko/tools/file-document/pdf-text-writing-tool.mdx Normal file
View File

@@ -0,0 +1,74 @@
---
title: PDF 텍스트 작성 도구
description: PDFTextWritingTool은 PDF의 특정 위치에 텍스트를 작성하며, 커스텀 폰트를 지원합니다.
icon: file-pdf
---
# `PDFTextWritingTool`
## 설명
PDF 페이지의 정확한 좌표에 텍스트를 작성하고, 필요에 따라 커스텀 TrueType 폰트를 임베드할 수 있습니다.
## 파라미터
### 실행 매개변수
- `pdf_path` (str, 필수): 입력 PDF의 경로.
- `text` (str, 필수): 추가할 텍스트.
- `position` (tuple[int, int], 필수): `(x, y)` 좌표.
- `font_size` (int, 기본값 `12`)
- `font_color` (str, 기본값 `"0 0 0 rg"`)
- `font_name` (str, 기본값 `"F1"`)
- `font_file` (str, 선택): `.ttf` 파일의 경로.
- `page_number` (int, 기본값 `0`)
## 예시
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import PDFTextWritingTool
tool = PDFTextWritingTool()
agent = Agent(
role="PDF Editor",
goal="Annotate PDFs",
backstory="Documentation specialist",
tools=[tool],
verbose=True,
)
task = Task(
description="Write 'CONFIDENTIAL' at (72, 720) on page 1 of ./sample.pdf",
expected_output="Confirmation message",
agent=agent,
)
crew = Crew(
agents=[agent],
tasks=[task],
verbose=True,
)
result = crew.kickoff()
```
### 직접 사용
```python Code
from crewai_tools import PDFTextWritingTool
PDFTextWritingTool().run(
pdf_path="./input.pdf",
text="CONFIDENTIAL",
position=(72, 720),
font_size=18,
page_number=0,
)
```
## 팁
- 좌표 원점은 왼쪽 하단 모서리입니다.
- 커스텀 폰트(`font_file`)를 사용할 경우, 유효한 `.ttf` 파일인지 확인하세요.

71
docs/ko/tools/file-document/pdfsearchtool.mdx Normal file
View File

@@ -0,0 +1,71 @@
---
title: PDF RAG 검색
description: PDFSearchTool은 PDF 파일을 검색하고 가장 관련성 높은 결과를 반환하도록 설계되었습니다.
icon: file-pdf
---
# `PDFSearchTool`
<Note>
도구를 계속 개선하고 있으므로, 예기치 않은 동작이나 변경사항이 있을 수 있습니다.
</Note>
## 설명
PDFSearchTool은 PDF 콘텐츠 내에서 의미론적 검색을 위해 설계된 RAG 도구입니다. 이 도구는 검색 쿼리와 PDF 문서를 입력받아 고급 검색 기법을 활용하여 관련 콘텐츠를 효율적으로 찾을 수 있습니다.
이 기능을 통해 대용량 PDF 파일에서 특정 정보를 신속하게 추출할 수 있어 특히 유용합니다.
## 설치
PDFSearchTool을 시작하려면 먼저 crewai_tools 패키지가 다음 명령어로 설치되어 있는지 확인하세요:
```shell
pip install 'crewai[tools]'
```
## 예시
다음은 PDFSearchTool을 사용하여 PDF 문서 내에서 검색하는 방법입니다:
```python Code
from crewai_tools import PDFSearchTool
# 실행 시 경로가 제공되면 모든 PDF 콘텐츠 검색을 허용하도록 도구를 초기화합니다.
tool = PDFSearchTool()
# 또는
# 특정 PDF 경로로 도구를 초기화하여 해당 문서 내에서만 검색합니다.
tool = PDFSearchTool(pdf='path/to/your/document.pdf')
```
## 인수
- `pdf`: **선택 사항** 검색할 PDF 경로입니다. 초기화 시 또는 `run` 메서드의 인수로 제공할 수 있습니다. 초기화 시 제공되면, 도구는 지정된 문서로 검색 범위를 제한합니다.
## 커스텀 모델 및 임베딩
기본적으로 이 도구는 임베딩과 요약 모두에 OpenAI를 사용합니다. 모델을 커스터마이즈하려면 다음과 같이 config 딕셔너리를 사용할 수 있습니다:
```python Code
tool = PDFSearchTool(
config=dict(
llm=dict(
provider="ollama", # or google, openai, anthropic, llama2, ...
config=dict(
model="llama2",
# temperature=0.5,
# top_p=1,
# stream=true,
),
),
embedder=dict(
provider="google", # or openai, ollama, ...
config=dict(
model="models/embedding-001",
task_type="retrieval_document",
# title="Embeddings",
),
),
)
)
```

80
docs/ko/tools/file-document/txtsearchtool.mdx Normal file
View File

@@ -0,0 +1,80 @@
---
title: TXT RAG 검색
description: TXTSearchTool은 텍스트 파일의 내용 내에서 RAG(Retrieval-Augmented Generation) 검색을 수행하도록 설계되었습니다.
icon: file-lines
---
## 개요
<Note>
저희는 도구를 계속 개선하고 있으므로, 추후에 예기치 않은 동작이나 변경이 발생할 수 있습니다.
</Note>
이 도구는 텍스트 파일의 콘텐츠 내에서 RAG(Retrieval-Augmented Generation) 검색을 수행하는 데 사용됩니다.
지정된 텍스트 파일의 콘텐츠에서 쿼리를 의미적으로 검색할 수 있어,
제공된 쿼리를 기반으로 정보를 신속하게 추출하거나 특정 텍스트 섹션을 찾는 데 매우 유용한 리소스입니다.
## 설치
`TXTSearchTool`을 사용하려면 먼저 `crewai_tools` 패키지를 설치해야 합니다.
이 작업은 Python용 패키지 관리자 pip를 사용하여 수행할 수 있습니다.
터미널 또는 명령 프롬프트를 열고 다음 명령어를 입력하세요:
```shell
pip install 'crewai[tools]'
```
이 명령어는 TXTSearchTool과 필요한 모든 종속성을 다운로드하고 설치합니다.
## 예시
다음 예시는 TXTSearchTool을 사용하여 텍스트 파일 내에서 검색하는 방법을 보여줍니다.
이 예시는 특정 텍스트 파일로 도구를 초기화하는 방법과, 해당 파일의 내용에서 검색을 수행하는 방법을 모두 포함하고 있습니다.
```python Code
from crewai_tools import TXTSearchTool
# Initialize the tool to search within any text file's content
# the agent learns about during its execution
tool = TXTSearchTool()
# OR
# Initialize the tool with a specific text file,
# so the agent can search within the given text file's content
tool = TXTSearchTool(txt='path/to/text/file.txt')
```
## 인자
- `txt` (str): **선택 사항**입니다. 검색하려는 텍스트 파일의 경로입니다.
이 인자는 도구가 특정 텍스트 파일로 초기화되지 않은 경우에만 필요합니다;
그렇지 않은 경우 검색은 처음에 제공된 텍스트 파일 내에서 수행됩니다.
## 커스텀 모델 및 임베딩
기본적으로 이 도구는 임베딩과 요약을 위해 OpenAI를 사용합니다.
모델을 커스터마이징하려면 다음과 같이 config 딕셔너리를 사용할 수 있습니다:
```python Code
tool = TXTSearchTool(
config=dict(
llm=dict(
provider="ollama", # or google, openai, anthropic, llama2, ...
config=dict(
model="llama2",
# temperature=0.5,
# top_p=1,
# stream=true,
),
),
embedder=dict(
provider="google", # or openai, ollama, ...
config=dict(
model="models/embedding-001",
task_type="retrieval_document",
# title="Embeddings",
),
),
)
)
```

77
docs/ko/tools/file-document/xmlsearchtool.mdx Normal file
View File

@@ -0,0 +1,77 @@
---
title: XML RAG 검색
description: XMLSearchTool은 XML 파일의 콘텐츠 내에서 RAG(Retrieval-Augmented Generation) 검색을 수행하도록 설계되었습니다.
icon: file-xml
---
# `XMLSearchTool`
<Note>
도구를 개선하는 작업이 계속 진행 중이므로, 향후 예기치 않은 동작이나 변경이 발생할 수 있습니다.
</Note>
## 설명
XMLSearchTool은 XML 파일 내에서 의미 기반 검색을 수행하도록 설계된 최첨단 RAG 도구입니다.
XML 콘텐츠에서 정보를 효율적으로 파싱하고 추출해야 하는 사용자를 위해 이상적으로 설계되었으며, 이 도구는 검색 쿼리와 선택적으로 XML 파일 경로 입력을 지원합니다.
XML 경로를 지정함으로써 사용자는 해당 파일의 콘텐츠에 대해 더 정확하게 검색 대상을 지정할 수 있어, 보다 관련성 높은 검색 결과를 얻을 수 있습니다.
## 설치
XMLSearchTool을 사용하려면 먼저 crewai_tools 패키지를 설치해야 합니다. 아래 명령어를 사용하면 쉽게 설치할 수 있습니다:
```shell
pip install 'crewai[tools]'
```
## 예시
여기 XMLSearchTool을 사용하는 방법을 보여주는 두 가지 예시가 있습니다.
첫 번째 예시는 특정 XML 파일 내에서 검색하는 방법을 보여주고, 두 번째 예시는 XML 경로를 미리 정의하지 않고 검색을 시작하여 검색 범위에 유연성을 제공하는 방법을 설명합니다.
```python Code
from crewai_tools import XMLSearchTool
# Allow agents to search within any XML file's content
#as it learns about their paths during execution
tool = XMLSearchTool()
# OR
# Initialize the tool with a specific XML file path
#for exclusive search within that document
tool = XMLSearchTool(xml='path/to/your/xmlfile.xml')
```
## 인자
- `xml`: 검색하려는 XML 파일의 경로입니다.
이 매개변수는 도구 초기화 시 선택적으로 제공할 수 있지만, 검색을 실행하기 위해서는 초기화 시 또는 `run` 메서드의 인자로 반드시 제공되어야 합니다.
## 커스텀 모델 및 임베딩
기본적으로 이 도구는 임베딩과 요약 모두에 OpenAI를 사용합니다. 모델을 커스터마이징하려면 다음과 같이 config 딕셔너리를 사용할 수 있습니다.
```python Code
tool = XMLSearchTool(
config=dict(
llm=dict(
provider="ollama", # or google, openai, anthropic, llama2, ...
config=dict(
model="llama2",
# temperature=0.5,
# top_p=1,
# stream=true,
),
),
embedder=dict(
provider="google", # or openai, ollama, ...
config=dict(
model="models/embedding-001",
task_type="retrieval_document",
# title="Embeddings",
),
),
)
)
```

120
docs/ko/tools/overview.mdx Normal file
View File

@@ -0,0 +1,120 @@
---
title: "도구 개요"
description: "CrewAI의 AI 에이전트를 강화하는 40개 이상의 방대한 도구 라이브러리를 확인해보세요"
icon: "toolbox"
---
CrewAI는 에이전트의 기능을 향상시키기 위한 다양한 사전 구축 도구 라이브러리를 제공합니다. 파일 처리부터 웹 스크래핑, 데이터베이스 쿼리, AI 서비스에 이르기까지 모두 지원합니다.
## **도구 카테고리**
<CardGroup cols={2}>
<Card
title="파일 & 문서"
icon="file-check"
href="/ko/tools/file-document/overview"
color="#3B82F6"
>
PDF, DOCX, JSON, CSV 등 다양한 파일 형식을 읽고, 작성하고, 검색할 수 있습니다. 문서 처리 워크플로우에 적합합니다.
</Card>
<Card
title="웹 스크래핑 & 브라우징"
icon="globe"
href="/ko/tools/web-scraping/overview"
color="#10B981"
>
웹사이트에서 데이터를 추출하고, 브라우저 상호작용을 자동화하며, Firecrawl, Selenium 등과 같은 도구로 대규모로 콘텐츠를 스크래핑할 수 있습니다.
</Card>
<Card
title="검색 & 리서치"
icon="magnifying-glass"
href="/ko/tools/search-research/overview"
color="#F59E0B"
>
웹 검색을 수행하고, 코드 저장소를 찾으며, YouTube 콘텐츠를 리서치하고, 인터넷 전반에 걸쳐 정보를 탐색할 수 있습니다.
</Card>
<Card
title="데이터베이스 & 데이터"
icon="database"
href="/ko/tools/database-data/overview"
color="#8B5CF6"
>
SQL 데이터베이스, 벡터 스토어, 데이터 웨어하우스에 연결합니다. MySQL, PostgreSQL, Snowflake, Qdrant, Weaviate를 쿼리할 수 있습니다.
</Card>
<Card
title="AI & 머신러닝"
icon="brain"
href="/ko/tools/ai-ml/overview"
color="#EF4444"
>
DALL-E로 이미지 생성, 비전 태스크 처리, LangChain과의 통합, RAG 시스템 구축, 코드 인터프리터 활용 등이 가능합니다.
</Card>
<Card
title="클라우드 & 스토리지"
icon="cloud"
href="/ko/tools/cloud-storage/overview"
color="#06B6D4"
>
AWS S3, Amazon Bedrock 및 기타 클라우드 스토리지 및 AI 서비스 등 클라우드 서비스와 상호작용할 수 있습니다.
</Card>
<Card
title="자동화 & 통합"
icon="bolt"
href="/ko/tools/automation/overview"
color="#84CC16"
>
Apify, Composio 및 기타 통합 플랫폼으로 워크플로우를 자동화하고, 에이전트를 외부 서비스와 연결할 수 있습니다.
</Card>
</CardGroup>
## **빠른 접근**
특정 도구가 필요하신가요? 인기 있는 옵션들을 소개합니다:
<CardGroup cols={3}>
<Card title="RAG Tool" icon="image" href="/ko/tools/ai-ml/ragtool">
검색 기반 생성(Retrieval-Augmented Generation) 구현
</Card>
<Card title="Serper Dev" icon="book-atlas" href="/ko/tools/search-research/serperdevtool">
구글 검색 API
</Card>
<Card title="File Read" icon="file" href="/ko/tools/file-document/filereadtool">
모든 파일 유형 읽기
</Card>
<Card title="Scrape Website" icon="globe" href="/ko/tools/web-scraping/scrapewebsitetool">
웹 콘텐츠 추출
</Card>
<Card title="Code Interpreter" icon="code" href="/ko/tools/ai-ml/codeinterpretertool">
Python 코드 실행
</Card>
<Card title="S3 Reader" icon="cloud" href="/ko/tools/cloud-storage/s3readertool">
AWS S3 파일 액세스
</Card>
</CardGroup>
## **시작하기**
CrewAI 프로젝트에서 어떤 도구를 사용하려면:
1. **도구를 임포트**하여 crew 설정에 추가합니다.
2. **에이전트의 tool 목록**에 추가합니다.
3. 필요한 **API 키 또는 설정을 구성**합니다.
```python
from crewai_tools import FileReadTool, SerperDevTool
# Add tools to your agent
agent = Agent(
role="Research Analyst",
tools=[FileReadTool(), SerperDevTool()],
# ... other configuration
)
```
탐험을 시작할 준비가 되셨나요? 위에서 카테고리를 선택하여 사용 사례에 맞는 도구를 찾아보세요!

110
docs/ko/tools/search-research/arxivpapertool.mdx Normal file
View File

@@ -0,0 +1,110 @@
---
title: Arxiv 논문 도구
description: ArxivPaperTool은 쿼리에 맞는 논문을 arXiv에서 검색하고, 선택적으로 PDF를 다운로드합니다.
icon: box-archive
---
# `ArxivPaperTool`
## 설명
`ArxivPaperTool`은 arXiv API를 통해 학술 논문을 검색하고 간결하고 읽기 쉬운 결과를 반환합니다. 또한 선택적으로 PDF 파일을 디스크에 다운로드할 수도 있습니다.
## 설치
이 도구는 `crewai-tools` 외에 별도의 특별한 설치가 필요하지 않습니다.
```shell
uv add crewai-tools
```
API 키가 필요하지 않습니다. 이 도구는 공개 arXiv Atom API를 사용합니다.
## 시작 단계
1. 도구를 초기화합니다.
2. `search_query`를 제공합니다 (예: "transformer neural network").
3. 선택적으로 생성자에서 `max_results`(1–100)를 설정하고 PDF 다운로드를 활성화할 수 있습니다.
## 예시
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import ArxivPaperTool
tool = ArxivPaperTool(
download_pdfs=False,
save_dir="./arxiv_pdfs",
use_title_as_filename=True,
)
agent = Agent(
role="Researcher",
goal="Find relevant arXiv papers",
backstory="Expert at literature discovery",
tools=[tool],
verbose=True,
)
task = Task(
description="Search arXiv for 'transformer neural network' and list top 5 results.",
expected_output="A concise list of 5 relevant papers with titles, links, and summaries.",
agent=agent,
)
crew = Crew(agents=[agent], tasks=[task])
result = crew.kickoff()
```
### 직접 사용 (Agent 없이)
```python Code
from crewai_tools import ArxivPaperTool
tool = ArxivPaperTool(
download_pdfs=True,
save_dir="./arxiv_pdfs",
)
print(tool.run(search_query="mixture of experts", max_results=3))
```
## 매개변수
### 초기화 매개변수
- `download_pdfs` (bool, 기본값 `False`): PDF를 다운로드할지 여부입니다.
- `save_dir` (str, 기본값 `./arxiv_pdfs`): PDF를 저장할 디렉터리입니다.
- `use_title_as_filename` (bool, 기본값 `False`): 논문 제목을 파일명으로 사용할지 여부입니다.
### 실행 매개변수
- `search_query` (str, 필수): arXiv 검색 쿼리입니다.
- `max_results` (int, 기본값 `5`, 범위 1–100): 결과 수.
## 출력 형식
이 도구는 다음과 같이 사람이 읽을 수 있는 논문 목록을 반환합니다:
- 제목
- 링크 (초록 페이지)
- 요약/설명 (생략됨)
`download_pdfs=True`로 설정하면, PDF 파일이 디스크에 저장되며 요약에 저장된 파일이 언급됩니다.
## 사용 참고 사항
- 이 도구는 주요 메타데이터와 링크가 포함된 서식을 갖춘 텍스트를 반환합니다.
- `download_pdfs=True`인 경우, PDF는 `save_dir`에 저장됩니다.
## 문제 해결
- 네트워크 시간 초과가 발생하면 다시 시도하거나 `max_results` 값을 줄이십시오.
- 잘못된 XML 오류는 arXiv 응답 파싱 문제를 나타냅니다. 더 간단한 쿼리를 시도해 보십시오.
- 파일 시스템 오류(예: 권한 거부)는 PDF를 저장할 때 발생할 수 있습니다. `save_dir`가 쓰기 가능한지 확인하십시오.
## 관련 링크
- arXiv API 문서: https://info.arxiv.org/help/api/index.html
## 오류 처리
- 네트워크 문제, 잘못된 XML, 그리고 OS 오류는 안내 메시지로 처리됩니다.

96
docs/ko/tools/search-research/bravesearchtool.mdx Normal file
View File

@@ -0,0 +1,96 @@
---
title: Brave Search
description: BraveSearchTool은 Brave Search API를 사용하여 인터넷을 검색하도록 설계되었습니다.
icon: searchengin
---
# `BraveSearchTool`
## 설명
이 도구는 Brave Search API를 사용하여 웹 검색을 수행하도록 설계되었습니다. 지정한 쿼리를 사용하여 인터넷을 검색하고 관련 결과를 가져올 수 있습니다. 이 도구는 결과 개수와 국가별 검색을 사용자 지정할 수 있는 기능을 지원합니다.
## 설치
이 도구를 프로젝트에 통합하려면 아래의 설치 지침을 따르세요:
```shell
pip install 'crewai[tools]'
```
## 시작 단계
`BraveSearchTool`을(를) 효과적으로 사용하려면 다음 단계를 따르세요:
1. **패키지 설치**: Python 환경에 `crewai[tools]` 패키지가 설치되어 있는지 확인합니다.
2. **API 키 획득**: https://api.search.brave.com/app/keys 에서 Brave Search API 키를 획득합니다(로그인하여 키를 생성).
3. **환경 설정**: 획득한 API 키를 `BRAVE_API_KEY`라는 환경 변수에 저장하여 도구에서 사용할 수 있도록 합니다.
## 예시
다음 예시는 도구를 초기화하고 주어진 쿼리로 검색을 실행하는 방법을 보여줍니다:
```python Code
from crewai_tools import BraveSearchTool
# 인터넷 검색 기능을 위한 도구 초기화
tool = BraveSearchTool()
# 검색 실행
results = tool.run(search_query="CrewAI agent framework")
print(results)
```
## 매개변수
`BraveSearchTool`은 다음과 같은 매개변수를 받습니다:
- **search_query**: 필수. 인터넷 검색에 사용할 검색 쿼리입니다.
- **country**: 선택. 검색 결과의 국가를 지정합니다. 기본값은 빈 문자열입니다.
- **n_results**: 선택. 반환할 검색 결과의 개수입니다. 기본값은 `10`입니다.
- **save_file**: 선택. 검색 결과를 파일로 저장할지 여부입니다. 기본값은 `False`입니다.
## 매개변수와 함께 사용하는 예시
다음은 추가 매개변수를 사용하여 도구를 활용하는 방법을 보여주는 예시입니다:
```python Code
from crewai_tools import BraveSearchTool
# Initialize the tool with custom parameters
tool = BraveSearchTool(
country="US",
n_results=5,
save_file=True
)
# Execute a search
results = tool.run(search_query="Latest AI developments")
print(results)
```
## 에이전트 통합 예시
다음은 `BraveSearchTool`을 CrewAI 에이전트와 통합하는 방법입니다:
```python Code
from crewai import Agent
from crewai.project import agent
from crewai_tools import BraveSearchTool
# Initialize the tool
brave_search_tool = BraveSearchTool()
# Define an agent with the BraveSearchTool
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config["researcher"],
allow_delegation=False,
tools=[brave_search_tool]
)
```
## 결론
`BraveSearchTool`을 Python 프로젝트에 통합함으로써, 사용자는 애플리케이션 내에서 직접 실시간으로 관련성 높은 인터넷 검색을 수행할 수 있습니다. 이 도구는 강력한 Brave Search API에 대한 간단한 인터페이스를 제공하여, 검색 결과를 프로그래밍적으로 손쉽게 가져오고 처리할 수 있게 해줍니다. 제공된 설정 및 사용 지침을 따르면, 이 도구를 프로젝트에 통합하는 과정이 간편하고 직관적입니다.

84
docs/ko/tools/search-research/codedocssearchtool.mdx Normal file
View File

@@ -0,0 +1,84 @@
---
title: 코드 문서 RAG 검색
description: CodeDocsSearchTool은(는) 코드 문서 내에서 의미론적 검색을 위해 설계된 강력한 RAG(Retrieval-Augmented Generation) 도구입니다.
icon: code
---
# `CodeDocsSearchTool`
<Note>
**실험적**: 저희는 도구를 계속 개선하고 있으므로, 향후 예기치 않은 동작이나 변경 사항이 발생할 수 있습니다.
</Note>
## 설명
CodeDocsSearchTool은 코드 문서 내에서 의미론적 검색을 할 수 있도록 설계된 강력한 RAG(Retrieval-Augmented Generation) 도구입니다.
이 도구를 사용하면 사용자는 코드 문서 내에서 특정 정보나 주제를 효율적으로 찾을 수 있습니다. 초기화 시 `docs_url`을 제공하면,
검색 범위를 해당 문서 사이트로 한정할 수 있습니다. 또는 특정 `docs_url`이 없는 경우,
실행 중에 알려지거나 발견된 다양한 코드 문서 전체를 대상으로 검색하므로, 다양한 문서 검색에 유연하게 활용할 수 있습니다.
## 설치
CodeDocsSearchTool을 사용하려면 먼저 pip를 통해 crewai_tools 패키지를 설치하세요:
```shell
pip install 'crewai[tools]'
```
## 예시
CodeDocsSearchTool을 다음과 같이 활용하여 코드 문서 내에서 검색을 수행할 수 있습니다:
```python Code
from crewai_tools import CodeDocsSearchTool
# URL이 알려졌거나 실행 중에 발견된 경우
# 모든 코드 문서 내용을 검색하려면:
tool = CodeDocsSearchTool()
# 또는
# 특정 문서 사이트 내에서 검색을 집중적으로 수행하려면
# 해당 사이트의 URL을 제공하세요:
tool = CodeDocsSearchTool(docs_url='https://docs.example.com/reference')
```
<Note>
'https://docs.example.com/reference'를 원하는 문서 URL로,
'How to use search tool'을 필요에 맞는 검색 쿼리로 대체하세요.
</Note>
## 인수
다음 매개변수들은 `CodeDocsSearchTool`의 동작을 사용자 지정하는 데 사용할 수 있습니다:
| 인수 | 타입 | 설명 |
|:------------------|:----------|:-----------------------------------------------------------------------------------------------------|
| **docs_url** | `string` | _선택 사항_. 검색할 코드 도큐멘테이션의 URL을 지정합니다. |
## 커스텀 모델 및 임베딩
기본적으로 이 도구는 임베딩과 요약 모두에 OpenAI를 사용합니다. 모델을 커스터마이즈하려면 아래와 같이 config 딕셔너리를 사용할 수 있습니다.
```python Code
tool = CodeDocsSearchTool(
config=dict(
llm=dict(
provider="ollama", # or google, openai, anthropic, llama2, ...
config=dict(
model="llama2",
# temperature=0.5,
# top_p=1,
# stream=true,
),
),
embedder=dict(
provider="google", # or openai, ollama, ...
config=dict(
model="models/embedding-001",
task_type="retrieval_document",
# title="Embeddings",
),
),
)
)
```

78
docs/ko/tools/search-research/databricks-query-tool.mdx Normal file
View File

@@ -0,0 +1,78 @@
---
title: Databricks SQL 쿼리 도구
description: DatabricksQueryTool은 Databricks 워크스페이스 테이블에 대해 SQL 쿼리를 실행합니다.
icon: trowel-bricks
---
# `DatabricksQueryTool`
## 설명
CLI 프로필 또는 직접 호스트/토큰 인증을 사용하여 Databricks 워크스페이스 테이블에 대해 SQL을 실행합니다.
## 설치
```shell
uv add crewai-tools[databricks-sdk]
```
## 환경 변수
- `DATABRICKS_CONFIG_PROFILE` 또는 (`DATABRICKS_HOST` + `DATABRICKS_TOKEN`)
개인 액세스 토큰을 생성하고 Databricks 작업 공간의 사용자 설정 → 개발자 메뉴에서 호스트 정보를 확인하세요.
문서: https://docs.databricks.com/ko/dev-tools/auth/pat.html
## 예시
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import DatabricksQueryTool
tool = DatabricksQueryTool(
default_catalog="main",
default_schema="default",
)
agent = Agent(
role="Data Analyst",
goal="Query Databricks",
tools=[tool],
verbose=True,
)
task = Task(
description="SELECT * FROM my_table LIMIT 10",
expected_output="10 rows",
agent=agent,
)
crew = Crew(
agents=[agent],
tasks=[task],
verbose=True,
)
result = crew.kickoff()
print(result)
```
## 매개변수
- `query` (필수): 실행할 SQL 쿼리
- `catalog` (선택): 기본 카탈로그 재정의
- `db_schema` (선택): 기본 스키마 재정의
- `warehouse_id` (선택): 기본 SQL 웨어하우스 재정의
- `row_limit` (선택): 반환할 최대 행 수 (기본값: 1000)
## 초기화 시 기본값
- `default_catalog`
- `default_schema`
- `default_warehouse_id`
### 오류 처리 및 팁
- 인증 오류: `DATABRICKS_HOST`가 `https://`로 시작하는지와 토큰이 유효한지 확인하세요.
- 권한: SQL 웨어하우스와 스키마에 토큰으로 접근할 수 있는지 확인하세요.
- 한계: 장시간 실행되는 쿼리는 에이전트 루프에서 피해야 하며, 필터나 제한을 추가하세요.

52
docs/ko/tools/search-research/exasearchtool.mdx Normal file
View File

@@ -0,0 +1,52 @@
---
title: EXA 검색 웹 로더
description: EXASearchTool은 인터넷 전반에 걸쳐 텍스트의 내용에서 지정된 쿼리에 대한 시맨틱 검색을 수행하도록 설계되었습니다.
icon: globe-pointer
---
# `EXASearchTool`
## 설명
EXASearchTool은 텍스트의 내용을 기반으로 지정된 쿼리를 인터넷 전반에 걸쳐 의미론적으로 검색하도록 설계되었습니다.
사용자가 제공한 쿼리를 기반으로 가장 관련성 높은 검색 결과를 가져오고 표시하기 위해 [exa.ai](https://exa.ai/) API를 활용합니다.
## 설치
이 도구를 프로젝트에 포함하려면 아래 설치 지침을 따르세요:
```shell
pip install 'crewai[tools]'
```
## 예제
다음 예제는 도구를 초기화하고 주어진 쿼리로 검색을 실행하는 방법을 보여줍니다:
```python Code
from crewai_tools import EXASearchTool
# Initialize the tool for internet searching capabilities
tool = EXASearchTool()
```
## 시작 단계
EXASearchTool을 효과적으로 사용하려면 다음 단계를 따르세요:
<Steps>
<Step title="패키지 설치">
Python 환경에 `crewai[tools]` 패키지가 설치되어 있는지 확인하세요.
</Step>
<Step title="API 키 획득">
[exa.ai](https://exa.ai/)에서 무료 계정을 등록하여 [exa.ai](https://exa.ai/) API 키를 획득하세요.
</Step>
<Step title="환경 설정">
획득한 API 키를 도구에서 사용할 수 있도록 `EXA_API_KEY`라는 환경 변수에 저장하세요.
</Step>
</Steps>
## 결론
`EXASearchTool`을 Python 프로젝트에 통합함으로써, 사용자는 애플리케이션 내에서 실시간으로 인터넷을 직접 검색할 수 있는 능력을 얻게 됩니다.
제공된 설정 및 사용 지침을 따르면, 이 도구를 프로젝트에 포함하는 과정이 간편하고 직관적입니다.

85
docs/ko/tools/search-research/githubsearchtool.mdx Normal file
View File

@@ -0,0 +1,85 @@
---
title: Github 검색
description: GithubSearchTool은 웹사이트를 검색하고 이를 깔끔한 마크다운 또는 구조화된 데이터로 변환하도록 설계되었습니다.
icon: github
---
# `GithubSearchTool`
<Note>
저희는 도구를 계속 개선하고 있으므로, 예기치 않은 동작이나 향후 변경 사항이 있을 수 있습니다.
</Note>
## 설명
GithubSearchTool은 GitHub 리포지토리 내에서 시맨틱 검색을 수행하기 위해 특별히 설계된 Retrieval-Augmented Generation (RAG) 도구입니다. 고도화된 시맨틱 검색 기능을 활용하여 코드, 풀 리퀘스트, 이슈, 리포지토리를 탐색하므로, 개발자, 연구자 또는 GitHub에서 정확한 정보를 필요로 하는 모든 사람에게 필수적인 도구입니다.
## 설치
GithubSearchTool을 사용하려면 먼저 Python 환경에 crewai_tools 패키지가 설치되어 있어야 합니다:
```shell
pip install 'crewai[tools]'
```
이 명령어는 GithubSearchTool과 crewai_tools 패키지에 포함된 기타 도구들을 실행하는 데 필요한 패키지를 설치합니다.
GitHub Personal Access Token은 https://github.com/settings/tokens (Developer settings → Fine‑grained tokens 또는 classic tokens)에서 발급받으실 수 있습니다.
## 예시
다음은 GithubSearchTool을 사용하여 GitHub 저장소 내에서 시맨틱 검색을 수행하는 방법입니다:
```python Code
from crewai_tools import GithubSearchTool
# 특정 GitHub 저장소 내에서 시맨틱 검색을 위한 도구 초기화
tool = GithubSearchTool(
github_repo='https://github.com/example/repo',
gh_token='your_github_personal_access_token',
content_types=['code', 'issue'] # 옵션: code, repo, pr, issue
)
# 또는
# 특정 GitHub 저장소 내에서 시맨틱 검색을 위한 도구를 초기화하여, agent가 실행 중에 알게 된 어떤 저장소라도 검색할 수 있도록 함
tool = GithubSearchTool(
gh_token='your_github_personal_access_token',
content_types=['code', 'issue'] # 옵션: code, repo, pr, issue
)
```
## 인자
- `github_repo` : 검색이 수행될 GitHub 저장소의 URL입니다. 이 필드는 필수이며, 검색 대상 저장소를 지정합니다.
- `gh_token` : 인증에 필요한 GitHub 개인 액세스 토큰(PAT)입니다. GitHub 계정의 설정 > 개발자 설정 > 개인 액세스 토큰에서 생성할 수 있습니다.
- `content_types` : 검색에 포함할 콘텐츠 유형을 지정합니다. 다음 옵션 중에서 콘텐츠 유형의 목록을 제공해야 합니다: 코드 내에서 검색하려면 `code`, 저장소의 일반 정보 내에서 검색하려면 `repo`, 풀 리퀘스트에서 검색하려면 `pr`, 이슈에서 검색하려면 `issue`.
이 필드는 필수이며, GitHub 저장소 내에서 특정 콘텐츠 유형에 맞춰 검색을 조정할 수 있습니다.
## 커스텀 모델 및 임베딩
기본적으로 이 도구는 임베딩과 요약 모두에 OpenAI를 사용합니다. 모델을 커스터마이징하려면 다음과 같이 config 딕셔너리를 사용할 수 있습니다.
```python Code
tool = GithubSearchTool(
config=dict(
llm=dict(
provider="ollama", # 또는 google, openai, anthropic, llama2, ...
config=dict(
model="llama2",
# temperature=0.5,
# top_p=1,
# stream=true,
),
),
embedder=dict(
provider="google", # 또는 openai, ollama, ...
config=dict(
model="models/embedding-001",
task_type="retrieval_document",
# title="Embeddings",
),
),
)
)
```

112
docs/ko/tools/search-research/linkupsearchtool.mdx Normal file
View File

@@ -0,0 +1,112 @@
---
title: Linkup 검색 도구
description: LinkupSearchTool은 Linkup API를 통해 컨텍스트 정보를 질의할 수 있도록 합니다.
icon: link
---
# `LinkupSearchTool`
## 설명
`LinkupSearchTool`은 Linkup API에 쿼리하여 컨텍스트 정보와 구조화된 결과를 가져올 수 있는 기능을 제공합니다. 이 도구는 Linkup으로부터 최신의 신뢰할 수 있는 정보를 워크플로우에 추가하는 데 이상적이며, 에이전트가 작업 중에 관련 데이터를 접근할 수 있도록 해줍니다.
## 설치
이 도구를 사용하려면 Linkup SDK를 설치해야 합니다:
```shell
uv add linkup-sdk
```
## 시작 단계
`LinkupSearchTool`을 효과적으로 사용하려면 다음 단계를 따라주세요:
1. **API 키**: Linkup API 키를 발급받으세요.
2. **환경 설정**: API 키로 환경을 설정하세요.
3. **SDK 설치**: 위의 명령어를 사용하여 Linkup SDK를 설치하세요.
## 예시
다음 예시는 도구를 초기화하고 에이전트에서 사용하는 방법을 보여줍니다:
```python Code
from crewai_tools import LinkupSearchTool
from crewai import Agent
import os
# Initialize the tool with your API key
linkup_tool = LinkupSearchTool(api_key=os.getenv("LINKUP_API_KEY"))
# Define an agent that uses the tool
@agent
def researcher(self) -> Agent:
'''
이 에이전트는 LinkupSearchTool을 사용하여 Linkup API에서
컨텍스트 정보를 가져옵니다.
'''
return Agent(
config=self.agents_config["researcher"],
tools=[linkup_tool]
)
```
## 매개변수
`LinkupSearchTool`은 다음과 같은 매개변수를 사용합니다:
### 생성자 매개변수
- **api_key**: 필수. 사용자의 Linkup API 키입니다.
### 실행 매개변수
- **query**: 필수입니다. 검색어 또는 구문입니다.
- **depth**: 선택 사항입니다. 검색 깊이입니다. 기본값은 "standard"입니다.
- **output_type**: 선택 사항입니다. 출력 유형입니다. 기본값은 "searchResults"입니다.
## 고급 사용법
더 구체적인 결과를 얻기 위해 검색 매개변수를 사용자 지정할 수 있습니다.
```python Code
# Perform a search with custom parameters
results = linkup_tool.run(
query="Women Nobel Prize Physics",
depth="deep",
output_type="searchResults"
)
```
## 반환 형식
도구는 다음과 같은 형식으로 결과를 반환합니다:
```json
{
"success": true,
"results": [
{
"name": "Result Title",
"url": "https://example.com/result",
"content": "Content of the result..."
},
// Additional results...
]
}
```
오류가 발생한 경우 응답은 다음과 같습니다:
```json
{
"success": false,
"error": "Error message"
}
```
## 오류 처리
이 도구는 API 오류를 우아하게 처리하고 구조화된 피드백을 제공합니다. API 요청이 실패할 경우, 도구는 `success: false`와 오류 메시지가 포함된 딕셔너리를 반환합니다.
## 결론
`LinkupSearchTool`은 Linkup의 컨텍스트 기반 정보 검색 기능을 CrewAI agent에 원활하게 통합할 수 있는 방법을 제공합니다. 이 도구를 활용하여 agent는 의사 결정 및 작업 수행을 향상시키기 위해 관련성 높고 최신의 정보에 접근할 수 있습니다.

93
docs/ko/tools/search-research/overview.mdx Normal file
View File

@@ -0,0 +1,93 @@
---
title: "개요"
description: "웹 검색을 수행하고, 저장소를 찾으며, 인터넷 전반에 걸쳐 정보를 조사합니다"
icon: "face-smile"
---
이러한 도구들은 에이전트가 웹을 검색하고, 다양한 주제를 조사하며, 검색 엔진, GitHub, YouTube 등 다양한 플랫폼에서 정보를 찾을 수 있도록 지원합니다.
## **사용 가능한 도구**
<CardGroup cols={2}>
<Card title="Serper Dev Tool" icon="google" href="/ko/tools/search-research/serperdevtool">
종합적인 웹 검색 기능을 위한 Google 검색 API 통합.
</Card>
<Card title="Brave Search Tool" icon="shield" href="/ko/tools/search-research/bravesearchtool">
Brave의 독립적인 검색 인덱스를 활용한 프라이버시 중심의 검색.
</Card>
<Card title="Exa Search Tool" icon="magnifying-glass" href="/ko/tools/search-research/exasearchtool">
특정하고 관련성 높은 콘텐츠를 찾기 위한 AI 기반 검색.
</Card>
<Card title="LinkUp Search Tool" icon="link" href="/ko/tools/search-research/linkupsearchtool">
최신 콘텐츠 인덱싱을 통한 실시간 웹 검색.
</Card>
<Card title="GitHub Search Tool" icon="github" href="/ko/tools/search-research/githubsearchtool">
GitHub 저장소, 코드, 이슈, 문서를 검색합니다.
</Card>
<Card title="Website Search Tool" icon="globe" href="/ko/tools/search-research/websitesearchtool">
특정 웹사이트 및 도메인 내에서 검색합니다.
</Card>
<Card title="Code Docs Search Tool" icon="code" href="/ko/tools/search-research/codedocssearchtool">
코드 문서와 기술 자료를 검색합니다.
</Card>
<Card title="YouTube Channel Search" icon="youtube" href="/ko/tools/search-research/youtubechannelsearchtool">
특정 콘텐츠 및 크리에이터를 찾기 위한 YouTube 채널 검색.
</Card>
<Card title="YouTube Video Search" icon="play" href="/ko/tools/search-research/youtubevideosearchtool">
주제, 키워드 또는 조건별로 YouTube 동영상을 찾고 분석합니다.
</Card>
<Card title="Tavily Search Tool" icon="magnifying-glass" href="/ko/tools/search-research/tavilysearchtool">
Tavily의 AI 기반 검색 API를 활용한 종합 웹 검색.
</Card>
<Card title="Tavily Extractor Tool" icon="file-text" href="/ko/tools/search-research/tavilyextractortool">
Tavily API를 사용하여 웹 페이지에서 구조화된 콘텐츠를 추출합니다.
</Card>
<Card title="Arxiv Paper Tool" icon="box-archive" href="/ko/tools/search-research/arxivpapertool">
arXiv에서 논문을 검색하고 선택적으로 PDF를 다운로드합니다.
</Card>
<Card title="SerpApi Google Search" icon="search" href="/ko/tools/search-research/serpapi-googlesearchtool">
구조화된 결과를 제공하는 SerpApi를 통한 Google 검색.
</Card>
<Card title="SerpApi Google Shopping" icon="cart-shopping" href="/ko/tools/search-research/serpapi-googleshoppingtool">
SerpApi를 통한 Google 쇼핑 쿼리.
</Card>
</CardGroup>
## **일반적인 사용 사례**
- **시장 조사**: 산업 트렌드와 경쟁사 분석 검색
- **콘텐츠 발견**: 관련 기사, 영상 및 자료 찾기
- **코드 연구**: 저장소 및 문서에서 솔루션 검색
- **리드 생성**: 기업 및 개인 조사
- **학술 연구**: 학술 기사 및 기술 논문 찾기
```python
from crewai_tools import SerperDevTool, GitHubSearchTool, YoutubeVideoSearchTool, TavilySearchTool, TavilyExtractorTool
# Create research tools
web_search = SerperDevTool()
code_search = GitHubSearchTool()
video_research = YoutubeVideoSearchTool()
tavily_search = TavilySearchTool()
content_extractor = TavilyExtractorTool()
# Add to your agent
agent = Agent(
role="Research Analyst",
tools=[web_search, code_search, video_research, tavily_search, content_extractor],
goal="Gather comprehensive information on any topic"
)
```

63
docs/ko/tools/search-research/serpapi-googlesearchtool.mdx Normal file
View File

@@ -0,0 +1,63 @@
---
title: SerpApi 구글 검색 도구
description: SerpApiGoogleSearchTool은 SerpApi 서비스를 사용하여 구글 검색을 수행합니다.
icon: google
---
# `SerpApiGoogleSearchTool`
## 설명
`SerpApiGoogleSearchTool`을 사용하여 SerpApi로 Google 검색을 실행하고 구조화된 결과를 가져올 수 있습니다. SerpApi API 키가 필요합니다.
## 설치
```shell
uv add crewai-tools[serpapi]
```
## 환경 변수
- `SERPAPI_API_KEY` (필수): SerpApi용 API 키입니다. https://serpapi.com/에서 생성할 수 있습니다(무료 요금제 제공).
## 예시
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import SerpApiGoogleSearchTool
tool = SerpApiGoogleSearchTool()
agent = Agent(
role="Researcher",
goal="Answer questions using Google search",
backstory="Search specialist",
tools=[tool],
verbose=True,
)
task = Task(
description="Search for the latest CrewAI releases",
expected_output="A concise list of relevant results with titles and links",
agent=agent,
)
crew = Crew(agents=[agent], tasks=[task])
result = crew.kickoff()
```
## 참고 사항
- 환경 변수에 `SERPAPI_API_KEY`를 설정하세요. https://serpapi.com/ 에서 키를 생성할 수 있습니다.
- SerpApi를 통한 Google Shopping도 참조하세요: `/ko/tools/search-research/serpapi-googleshoppingtool`
## 파라미터
### 실행 파라미터
- `search_query` (str, 필수): Google 쿼리.
- `location` (str, 선택): 지리적 위치 파라미터.
## 참고 사항
- 이 도구는 SerpApi를 래핑하고 구조화된 검색 결과를 반환합니다.

59
docs/ko/tools/search-research/serpapi-googleshoppingtool.mdx Normal file
View File

@@ -0,0 +1,59 @@
---
title: SerpApi 구글 쇼핑 도구
description: SerpApiGoogleShoppingTool은 SerpApi를 사용하여 구글 쇼핑 결과를 검색합니다.
icon: cart-shopping
---
# `SerpApiGoogleShoppingTool`
## 설명
`SerpApiGoogleShoppingTool`을 활용하여 SerpApi를 통해 Google 쇼핑을 쿼리하고 제품 중심 결과를 받아올 수 있습니다.
## 설치
```shell
uv add crewai-tools[serpapi]
```
## 환경 변수
- `SERPAPI_API_KEY` (필수): SerpApi용 API 키입니다. https://serpapi.com/에서 생성할 수 있습니다(무료 티어 제공).
## 예시
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import SerpApiGoogleShoppingTool
tool = SerpApiGoogleShoppingTool()
agent = Agent(
role="Shopping Researcher",
goal="Find relevant products",
backstory="Expert in product search",
tools=[tool],
verbose=True,
)
task = Task(
description="Search Google Shopping for 'wireless noise-canceling headphones'",
expected_output="Top relevant products with titles and links",
agent=agent,
)
crew = Crew(agents=[agent], tasks=[task])
result = crew.kickoff()
```
## 참고 사항
- 환경 변수에 `SERPAPI_API_KEY`를 설정하세요. https://serpapi.com/ 에서 키를 생성할 수 있습니다.
- 또한 SerpApi를 통한 Google 웹 검색도 참고하세요: `/ko/tools/search-research/serpapi-googlesearchtool`
## 매개변수
### 실행 매개변수
- `search_query` (str, 필수): 제품 검색 쿼리.
- `location` (str, 선택): 지리적 위치 매개변수.

105
docs/ko/tools/search-research/serperdevtool.mdx Normal file
View File

@@ -0,0 +1,105 @@
---
title: Google Serper 검색
description: SerperDevTool은(는) 인터넷을 검색하여 가장 관련성 높은 결과를 반환하도록 설계되었습니다.
icon: google
---
# `SerperDevTool`
## 설명
이 도구는 인터넷 전체의 텍스트 내용에서 지정된 쿼리에 대한 시맨틱 검색을 수행하도록 설계되었습니다. 사용자가 제공한 쿼리를 기반으로 가장 관련성 높은 검색 결과를 가져와 표시하기 위해 [serper.dev](https://serper.dev) API를 활용합니다.
## 설치
`SerperDevTool`을 효과적으로 사용하려면 다음 단계를 따르십시오:
1. **패키지 설치**: Python 환경에 `crewai[tools]` 패키지가 설치되어 있는지 확인하세요.
2. **API 키 획득**: https://serper.dev/ (무료 플랜 제공)에서 `serper.dev` API 키를 획득하세요.
3. **환경 변수 설정**: 획득한 API 키를 `SERPER_API_KEY`라는 환경 변수에 저장하여 도구에서 사용할 수 있게 하세요.
이 도구를 프로젝트에 통합하려면 아래의 설치 지침을 따르십시오:
```shell
pip install 'crewai[tools]'
```
## 예제
다음 예제는 도구를 초기화하고 주어진 쿼리로 검색을 실행하는 방법을 보여줍니다:
```python Code
from crewai_tools import SerperDevTool
# Initialize the tool for internet searching capabilities
tool = SerperDevTool()
```
## 매개변수
`SerperDevTool`은 API에 전달될 여러 매개변수를 제공합니다:
- **search_url**: 검색 API의 URL 엔드포인트입니다. (기본값은 `https://google.serper.dev/search`)
- **country**: 선택 사항. 검색 결과에 사용할 국가를 지정합니다.
- **location**: 선택 사항. 검색 결과에 사용할 위치를 지정합니다.
- **locale**: 선택 사항. 검색 결과에 사용할 로케일을 지정합니다.
- **n_results**: 반환할 검색 결과의 개수입니다. 기본값은 `10`입니다.
`country`, `location`, `locale`, `search_url`의 값은 [Serper Playground](https://serper.dev/playground)에서 확인할 수 있습니다.
## 매개변수를 활용한 예시
다음은 추가 매개변수를 사용하여 도구를 활용하는 방법을 보여주는 예시입니다:
```python Code
from crewai_tools import SerperDevTool
tool = SerperDevTool(
search_url="https://google.serper.dev/scholar",
n_results=2,
)
print(tool.run(search_query="ChatGPT"))
# Using Tool: Search the internet
# Search results: Title: Role of chat gpt in public health
# Link: https://link.springer.com/article/10.1007/s10439-023-03172-7
# Snippet: … ChatGPT in public health. In this overview, we will examine the potential uses of ChatGPT in
# ---
# Title: Potential use of chat gpt in global warming
# Link: https://link.springer.com/article/10.1007/s10439-023-03171-8
# Snippet: … as ChatGPT, have the potential to play a critical role in advancing our understanding of climate
# ---
```
```python Code
from crewai_tools import SerperDevTool
tool = SerperDevTool(
country="fr",
locale="fr",
location="Paris, Paris, Ile-de-France, France",
n_results=2,
)
print(tool.run(search_query="Jeux Olympiques"))
# Using Tool: Search the internet
# Search results: Title: Jeux Olympiques de Paris 2024 - Actualités, calendriers, résultats
# Link: https://olympics.com/fr/paris-2024
# Snippet: Quels sont les sports présents aux Jeux Olympiques de Paris 2024 ? · Athlétisme · Aviron · Badminton · Basketball · Basketball 3x3 · Boxe · Breaking · Canoë ...
# ---
# Title: Billetterie Officielle de Paris 2024 - Jeux Olympiques et Paralympiques
# Link: https://tickets.paris2024.org/
# Snippet: Achetez vos billets exclusivement sur le site officiel de la billetterie de Paris 2024 pour participer au plus grand événement sportif au monde.
# ---
```
## 결론
`SerperDevTool`을 Python 프로젝트에 통합함으로써, 사용자는 애플리케이션에서 직접 인터넷 전반에 걸친 실시간 및 관련성 높은 검색을 수행할 수 있는 능력을 갖게 됩니다.
업데이트된 매개변수들은 보다 맞춤화되고 지역화된 검색 결과를 제공합니다. 제공된 설정 및 사용 지침을 준수함으로써, 이 도구를 프로젝트에 통합하는 과정이 간소화되고 직관적으로 이루어집니다.

139
docs/ko/tools/search-research/tavilyextractortool.mdx Normal file
View File

@@ -0,0 +1,139 @@
---
title: "Tavily 추출기 도구"
description: "Tavily API를 사용하여 웹 페이지에서 구조화된 콘텐츠를 추출합니다"
icon: square-poll-horizontal
---
`TavilyExtractorTool`은 CrewAI 에이전트가 Tavily API를 사용하여 웹 페이지에서 구조화된 콘텐츠를 추출할 수 있도록 합니다. 이 도구는 단일 URL 또는 URL 목록을 처리할 수 있으며, 추출 깊이를 제어하고 이미지를 포함하는 등의 옵션을 제공합니다.
## 설치
`TavilyExtractorTool`을 사용하려면 `tavily-python` 라이브러리를 설치해야 합니다:
```shell
pip install 'crewai[tools]' tavily-python
```
또한 Tavily API 키를 환경 변수로 설정해야 합니다:
```bash
export TAVILY_API_KEY='your-tavily-api-key'
```
## 예제 사용법
다음은 CrewAI agent 내에서 `TavilyExtractorTool`을 초기화하고 사용하는 방법입니다:
```python
import os
from crewai import Agent, Task, Crew
from crewai_tools import TavilyExtractorTool
# Ensure TAVILY_API_KEY is set in your environment
# os.environ["TAVILY_API_KEY"] = "YOUR_API_KEY"
# Initialize the tool
tavily_tool = TavilyExtractorTool()
# Create an agent that uses the tool
extractor_agent = Agent(
role='Web Content Extractor',
goal='Extract key information from specified web pages',
backstory='You are an expert at extracting relevant content from websites using the Tavily API.',
tools=[tavily_tool],
verbose=True
)
# Define a task for the agent
extract_task = Task(
description='Extract the main content from the URL https://example.com using basic extraction depth.',
expected_output='A JSON string containing the extracted content from the URL.',
agent=extractor_agent
)
# Create and run the crew
crew = Crew(
agents=[extractor_agent],
tasks=[extract_task],
verbose=2
)
result = crew.kickoff()
print(result)
```
## 구성 옵션
`TavilyExtractorTool`은 다음과 같은 인자를 받습니다:
- `urls` (Union[List[str], str]): **필수**. 데이터를 추출할 단일 URL 문자열 또는 URL 문자열의 리스트.
- `include_images` (Optional[bool]): 추출 결과에 이미지를 포함할지 여부. 기본값은 `False`입니다.
- `extract_depth` (Literal["basic", "advanced"]): 추출의 깊이. 더 빠르고 표면적인 추출에는 `"basic"`을, 더 포괄적인 추출에는 `"advanced"`를 사용합니다. 기본값은 `"basic"`입니다.
- `timeout` (int): 추출 요청이 완료될 때까지 대기하는 최대 시간(초)입니다. 기본값은 `60`입니다.
## 고급 사용법
### 여러 URL과 고급 추출 기능
```python
# Example with multiple URLs and advanced extraction
multi_extract_task = Task(
description='Extract content from https://example.com and https://anotherexample.org using advanced extraction.',
expected_output='A JSON string containing the extracted content from both URLs.',
agent=extractor_agent
)
# Configure the tool with custom parameters
custom_extractor = TavilyExtractorTool(
extract_depth='advanced',
include_images=True,
timeout=120
)
agent_with_custom_tool = Agent(
role="Advanced Content Extractor",
goal="Extract comprehensive content with images",
tools=[custom_extractor]
)
```
### 도구 매개변수
도구의 동작을 초기화 시 매개변수를 설정하여 사용자 정의할 수 있습니다:
```python
# 사용자 정의 설정으로 초기화
extractor_tool = TavilyExtractorTool(
extract_depth='advanced', # 보다 포괄적인 추출
include_images=True, # 이미지 결과 포함
timeout=90 # 사용자 정의 타임아웃
)
```
## 기능
- **단일 또는 여러 URL**: 하나의 URL에서 콘텐츠를 추출하거나 한 번의 요청으로 여러 URL을 처리할 수 있습니다
- **구성 가능한 깊이**: 기본(빠른) 및 고급(포괄적인) 추출 모드 중에서 선택할 수 있습니다
- **이미지 지원**: 원할 경우 추출 결과에 이미지를 포함할 수 있습니다
- **구조화된 출력**: 추출된 콘텐츠가 잘 포맷된 JSON으로 반환됩니다
- **오류 처리**: 네트워크 시간 초과 및 추출 오류에 대한 견고한 처리
## 응답 형식
도구는 제공된 URL에서 추출한 구조화된 데이터를 나타내는 JSON 문자열을 반환합니다. 정확한 구조는 페이지의 내용과 사용된 `extract_depth`에 따라 달라집니다.
일반적인 응답 요소는 다음과 같습니다:
- **Title**: 페이지 제목
- **Content**: 페이지의 주요 텍스트 내용
- **Images**: 이미지 URL 및 메타데이터 (`include_images=True`인 경우)
- **Metadata**: 저자, 설명 등 추가적인 페이지 정보
## 사용 사례
- **콘텐츠 분석**: 경쟁사 웹사이트에서 콘텐츠를 추출하고 분석
- **연구**: 다양한 소스에서 구조화된 데이터를 수집하여 분석
- **콘텐츠 마이그레이션**: 기존 웹사이트에서 콘텐츠를 추출하여 마이그레이션
- **모니터링**: 변경 감지를 위해 정기적으로 콘텐츠 추출
- **데이터 수집**: 웹 소스에서 정보를 체계적으로 추출
응답 구조와 사용 가능한 옵션에 대한 자세한 정보는 [Tavily API 문서](https://docs.tavily.com/docs/tavily-api/python-sdk#extract)를 참고하세요.

124
docs/ko/tools/search-research/tavilysearchtool.mdx Normal file
View File

@@ -0,0 +1,124 @@
---
title: "Tavily 검색 도구"
description: "Tavily Search API를 사용하여 종합적인 웹 검색 수행"
icon: "magnifying-glass"
---
`TavilySearchTool`은 Tavily Search API에 대한 인터페이스를 제공하여 CrewAI 에이전트가 포괄적인 웹 검색을 수행할 수 있도록 합니다. 이 도구는 검색 깊이, 주제, 시간 범위, 포함/제외 도메인, 그리고 결과에 직접 답변, 원시 콘텐츠, 이미지 포함 여부 등을 지정할 수 있게 해줍니다.
## 설치
`TavilySearchTool`을 사용하려면 `tavily-python` 라이브러리를 설치해야 합니다:
```shell
pip install 'crewai[tools]' tavily-python
```
## 환경 변수
Tavily API 키가 환경 변수로 설정되어 있는지 확인하세요:
```bash
export TAVILY_API_KEY='your_tavily_api_key'
```
https://app.tavily.com/에서 API 키를 발급받으세요(회원가입 후 키를 생성하면 됩니다).
## 예제 사용법
다음은 CrewAI agent 내에서 `TavilySearchTool`을 초기화하고 사용하는 방법입니다:
```python
import os
from crewai import Agent, Task, Crew
from crewai_tools import TavilySearchTool
# Ensure the TAVILY_API_KEY environment variable is set
# os.environ["TAVILY_API_KEY"] = "YOUR_TAVILY_API_KEY"
# Initialize the tool
tavily_tool = TavilySearchTool()
# Create an agent that uses the tool
researcher = Agent(
role='Market Researcher',
goal='Find information about the latest AI trends',
backstory='An expert market researcher specializing in technology.',
tools=[tavily_tool],
verbose=True
)
# Create a task for the agent
research_task = Task(
description='Search for the top 3 AI trends in 2024.',
expected_output='A JSON report summarizing the top 3 AI trends found.',
agent=researcher
)
# Form the crew and kick it off
crew = Crew(
agents=[researcher],
tasks=[research_task],
verbose=2
)
result = crew.kickoff()
print(result)
```
## 구성 옵션
`TavilySearchTool`은 초기화 시 또는 `run` 메서드를 호출할 때 다음과 같은 인자를 받습니다:
- `query` (str): **필수**. 검색 쿼리 문자열입니다.
- `search_depth` (Literal["basic", "advanced"], 선택): 검색의 심도입니다. 기본값은 `"basic"`입니다.
- `topic` (Literal["general", "news", "finance"], 선택): 검색을 집중할 주제입니다. 기본값은 `"general"`입니다.
- `time_range` (Literal["day", "week", "month", "year"], 선택): 검색을 위한 시간 범위입니다. 기본값은 `None`입니다.
- `days` (int, 선택): 과거 며칠까지 검색할지 지정합니다. `time_range`가 설정되지 않은 경우에 해당합니다. 기본값은 `7`입니다.
- `max_results` (int, 선택): 반환할 최대 검색 결과 수입니다. 기본값은 `5`입니다.
- `include_domains` (Sequence[str], 선택): 검색 시 우선순위를 둘 도메인 목록입니다. 기본값은 `None`입니다.
- `exclude_domains` (Sequence[str], 선택): 검색에서 제외할 도메인 목록입니다. 기본값은 `None`입니다.
- `include_answer` (Union[bool, Literal["basic", "advanced"]], 선택): 검색 결과로부터 직접적으로 생성된 답변을 포함할지 여부입니다. 기본값은 `False`입니다.
- `include_raw_content` (bool, 선택): 검색된 페이지의 원시 HTML 콘텐츠를 포함할지 여부입니다. 기본값은 `False`입니다.
- `include_images` (bool, 선택): 이미지 결과를 포함할지 여부입니다. 기본값은 `False`입니다.
- `timeout` (int, 선택): 요청의 타임아웃(초)입니다. 기본값은 `60`입니다.
## 고급 사용법
도구를 사용자 지정 매개변수로 구성할 수 있습니다:
```python
# Example: Initialize with specific parameters
custom_tavily_tool = TavilySearchTool(
search_depth='advanced',
max_results=10,
include_answer=True
)
# The agent will use these defaults
agent_with_custom_tool = Agent(
role="Advanced Researcher",
goal="Conduct detailed research with comprehensive results",
tools=[custom_tavily_tool]
)
```
## 기능
- **포괄적 검색**: Tavily의 강력한 검색 인덱스에 접근
- **설정 가능한 깊이**: 기본 및 고급 검색 모드 선택 가능
- **주제 필터링**: 일반, 뉴스, 금융 주제에 집중하여 검색
- **시간 범위 제어**: 결과를 특정 기간으로 제한
- **도메인 제어**: 특정 도메인을 포함하거나 제외 가능
- **직접 답변**: 검색 결과에서 통합된 답변 제공
- **콘텐츠 필터링**: 자동 콘텐츠 잘라내기를 통해 컨텍스트 윈도우 문제 방지
## 응답 형식
이 도구는 다음을 포함하는 JSON 문자열로 검색 결과를 반환합니다:
- 제목, URL, 본문 요약이 포함된 검색 결과
- 선택적으로 쿼리에 대한 직접 답변
- 선택적으로 이미지 결과
- 선택적으로 원시 HTML 콘텐츠(활성화된 경우)
각 결과의 콘텐츠는 컨텍스트 윈도우 문제를 방지하면서 가장 관련성 높은 정보를 유지하도록 자동으로 잘립니다.

77
docs/ko/tools/search-research/websitesearchtool.mdx Normal file
View File

@@ -0,0 +1,77 @@
---
title: 웹사이트 RAG 검색
description: WebsiteSearchTool은(는) 웹사이트의 콘텐츠 내에서 RAG(Retrieval-Augmented Generation) 검색을 수행하도록 설계되었습니다.
icon: globe-stand
---
# `WebsiteSearchTool`
<Note>
WebsiteSearchTool은 현재 실험 단계에 있습니다. 저희는 이 도구를 제품군에 통합하기 위해 적극적으로 작업 중이며, 이에 따라 문서를 업데이트할 예정입니다.
</Note>
## 설명
WebsiteSearchTool은 웹사이트 내용 내에서 의미론적 검색을 수행하기 위한 개념으로 설계되었습니다.
이 도구는 Retrieval-Augmented Generation(RAG)과 같은 첨단 머신러닝 모델을 활용하여 지정된 URL에서 정보를 효율적으로 탐색하고 추출하는 것을 목표로 합니다.
사용자가 모든 웹사이트에서 검색을 수행하거나 관심 있는 특정 웹사이트에 집중할 수 있도록 유연성을 제공하는 것이 목적입니다.
현재 WebsiteSearchTool의 구현 세부 사항은 개발 중에 있으며, 설명된 기능들이 아직 제공되지 않을 수 있으니 참고 바랍니다.
## 설치
WebsiteSearchTool이 출시될 때 환경을 미리 준비하려면, 기본 패키지를 다음과 같이 설치할 수 있습니다:
```shell
pip install 'crewai[tools]'
```
이 명령어는 도구가 완전히 통합된 이후 즉시 사용할 수 있도록 필요한 종속성들을 설치합니다.
## 사용 예시
아래는 다양한 시나리오에서 WebsiteSearchTool을 어떻게 활용할 수 있는지에 대한 예시입니다. 참고로, 이 예시는 설명을 위한 것이며 계획된 기능을 나타냅니다:
```python Code
from crewai_tools import WebsiteSearchTool
# 에이전트가 사용할 수 있도록 도구를 초기화하는 예제
# 발견된 모든 웹사이트에서 검색할 수 있음
tool = WebsiteSearchTool()
# 특정 웹사이트의 콘텐츠로 검색을 제한하는 예제
# 이제 에이전트는 해당 웹사이트 내에서만 검색할 수 있음
tool = WebsiteSearchTool(website='https://example.com')
```
## 인자
- `website`: 선택적으로 웹사이트 URL을 지정하여 집중적인 검색을 수행할 수 있도록 하는 인자입니다. 이 인자는 필요에 따라 타겟팅된 검색을 가능하게 하여 도구의 유연성을 높이기 위해 설계되었습니다.
## 커스터마이즈 옵션
기본적으로 이 도구는 임베딩과 요약 모두에 OpenAI를 사용합니다. 모델을 커스터마이즈하려면 다음과 같이 config 딕셔너리를 사용할 수 있습니다:
```python Code
tool = WebsiteSearchTool(
config=dict(
llm=dict(
provider="ollama", # or google, openai, anthropic, llama2, ...
config=dict(
model="llama2",
# temperature=0.5,
# top_p=1,
# stream=true,
),
),
embedder=dict(
provider="google", # or openai, ollama, ...
config=dict(
model="models/embedding-001",
task_type="retrieval_document",
# title="Embeddings",
),
),
)
)
```

194
docs/ko/tools/search-research/youtubechannelsearchtool.mdx Normal file
View File

@@ -0,0 +1,194 @@
---
title: YouTube 채널 RAG 검색
description: YoutubeChannelSearchTool은 YouTube 채널의 콘텐츠 내에서 RAG(검색 증강 생성) 검색을 수행하도록 설계되었습니다.
icon: youtube
---
# `YoutubeChannelSearchTool`
<Note>
저희는 여전히 도구를 개선하고 있으므로, 향후 예기치 않은 동작이나 변경 사항이 발생할 수 있습니다.
</Note>
## 설명
이 도구는 특정 Youtube 채널의 콘텐츠 내에서 시맨틱 검색을 수행하도록 설계되었습니다.
RAG(Retrieval-Augmented Generation) 방법론을 활용하여 관련성 높은 검색 결과를 제공하며,
영상을 일일이 찾아보지 않고도 정보를 추출하거나 특정 콘텐츠를 찾는 데 매우 유용합니다.
이 도구는 Youtube 채널 내에서의 검색 과정을 간소화하여, 연구자, 콘텐츠 제작자, 그리고 특정 정보나 주제를 찾는 시청자들에게 적합합니다.
## 설치
YoutubeChannelSearchTool을 사용하려면 `crewai_tools` 패키지를 설치해야 합니다. 설치하려면 셸에서 다음 명령어를 실행하세요:
```shell
pip install 'crewai[tools]'
```
## 예제
다음 예제는 CrewAI 에이전트와 함께 `YoutubeChannelSearchTool`을 사용하는 방법을 보여줍니다:
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import YoutubeChannelSearchTool
# 전체 YouTube 채널 검색을 위한 도구를 초기화합니다
youtube_channel_tool = YoutubeChannelSearchTool()
# 도구를 사용하는 에이전트 정의
channel_researcher = Agent(
role="Channel Researcher",
goal="YouTube 채널에서 관련 정보를 추출하기",
backstory="YouTube 채널 콘텐츠 분석을 전문으로 하는 전문가 연구원입니다.",
tools=[youtube_channel_tool],
verbose=True,
)
# 특정 채널에서 정보를 검색하기 위한 예시 작업
research_task = Task(
description="YouTube 채널 {youtube_channel_handle}에서 머신러닝 튜토리얼에 대한 정보를 검색하세요.",
expected_output="채널에서 제공되는 주요 머신러닝 튜토리얼 요약.",
agent=channel_researcher,
)
# crew 생성 및 실행
crew = Crew(agents=[channel_researcher], tasks=[research_task])
result = crew.kickoff(inputs={"youtube_channel_handle": "@exampleChannel"})
```
특정 YouTube 채널 핸들로 도구를 초기화할 수도 있습니다:
```python Code
# 특정 YouTube 채널 핸들로 도구를 초기화합니다
youtube_channel_tool = YoutubeChannelSearchTool(
youtube_channel_handle='@exampleChannel'
)
# 도구를 사용하는 에이전트 정의
channel_researcher = Agent(
role="Channel Researcher",
goal="특정 YouTube 채널에서 관련 정보 추출",
backstory="YouTube 채널 콘텐츠 분석을 전문으로 하는 전문가 연구원입니다.",
tools=[youtube_channel_tool],
verbose=True,
)
```
## 파라미터
`YoutubeChannelSearchTool`은 다음 파라미터를 허용합니다:
- **youtube_channel_handle**: 선택 사항. 검색할 YouTube 채널의 핸들입니다. 초기화 시 제공되면, 에이전트가 도구를 사용할 때 별도로 입력할 필요가 없습니다. 핸들이 '@'로 시작하지 않으면 자동으로 추가됩니다.
- **config**: 선택 사항. LLM 및 임베더 설정을 포함한 기본 RAG 시스템의 구성입니다.
- **summarize**: 선택 사항. 검색된 콘텐츠를 요약할지 여부입니다. 기본값은 `False`입니다.
에이전트와 함께 도구를 사용할 때 에이전트가 제공해야 하는 값은 다음과 같습니다:
- **search_query**: 필수. 채널 콘텐츠에서 관련 정보를 찾기 위한 검색어입니다.
- **youtube_channel_handle**: 초기화 시 제공하지 않은 경우에만 필수. 검색할 YouTube 채널의 핸들입니다.
## 커스텀 모델 및 임베딩
기본적으로, 해당 도구는 임베딩과 요약 모두에 OpenAI를 사용합니다. 모델을 사용자 정의하려면 아래와 같이 config 딕셔너리를 사용할 수 있습니다:
```python Code
youtube_channel_tool = YoutubeChannelSearchTool(
config=dict(
llm=dict(
provider="ollama", # 또는 google, openai, anthropic, llama2, ...
config=dict(
model="llama2",
# temperature=0.5,
# top_p=1,
# stream=true,
),
),
embedder=dict(
provider="google", # 또는 openai, ollama, ...
config=dict(
model="models/embedding-001",
task_type="retrieval_document",
# title="Embeddings",
),
),
)
)
```
## 에이전트 통합 예시
다음은 `YoutubeChannelSearchTool`을 CrewAI 에이전트와 통합하는 방법에 대한 좀 더 자세한 예시입니다:
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import YoutubeChannelSearchTool
# Initialize the tool
youtube_channel_tool = YoutubeChannelSearchTool()
# Define an agent that uses the tool
channel_researcher = Agent(
role="Channel Researcher",
goal="Extract and analyze information from YouTube channels",
backstory="""You are an expert channel researcher who specializes in extracting
and analyzing information from YouTube channels. You have a keen eye for detail
and can quickly identify key points and insights from video content across an entire channel.""",
tools=[youtube_channel_tool],
verbose=True,
)
# Create a task for the agent
research_task = Task(
description="""
Search for information about data science projects and tutorials
in the YouTube channel {youtube_channel_handle}.
Focus on:
1. Key data science techniques covered
2. Popular tutorial series
3. Most viewed or recommended videos
Provide a comprehensive summary of these points.
""",
expected_output="A detailed summary of data science content available on the channel.",
agent=channel_researcher,
)
# Run the task
crew = Crew(agents=[channel_researcher], tasks=[research_task])
result = crew.kickoff(inputs={"youtube_channel_handle": "@exampleDataScienceChannel"})
```
## 구현 세부사항
`YoutubeChannelSearchTool`은 Retrieval-Augmented Generation의 기본 기능을 제공하는 `RagTool`의 하위 클래스로 구현되었습니다:
```python Code
class YoutubeChannelSearchTool(RagTool):
name: str = "Search a Youtube Channels content"
description: str = "A tool that can be used to semantic search a query from a Youtube Channels content."
args_schema: Type[BaseModel] = YoutubeChannelSearchToolSchema
def __init__(self, youtube_channel_handle: Optional[str] = None, **kwargs):
super().__init__(**kwargs)
if youtube_channel_handle is not None:
kwargs["data_type"] = DataType.YOUTUBE_CHANNEL
self.add(youtube_channel_handle)
self.description = f"A tool that can be used to semantic search a query the {youtube_channel_handle} Youtube Channels content."
self.args_schema = FixedYoutubeChannelSearchToolSchema
self._generate_description()
def add(
self,
youtube_channel_handle: str,
**kwargs: Any,
) -> None:
if not youtube_channel_handle.startswith("@"):
youtube_channel_handle = f"@{youtube_channel_handle}"
super().add(youtube_channel_handle, **kwargs)
```
## 결론
`YoutubeChannelSearchTool`은 RAG 기법을 활용하여 YouTube 채널 콘텐츠에서 정보를 검색하고 추출하는 강력한 방법을 제공합니다. 에이전트가 채널 전체의 영상을 대상으로 검색할 수 있도록 하여, 그렇지 않으면 수행하기 어려운 정보 추출 및 분석 작업을 용이하게 해줍니다. 이 도구는 특히 YouTube 채널에서의 연구, 콘텐츠 분석, 지식 추출에 유용합니다.

187
docs/ko/tools/search-research/youtubevideosearchtool.mdx Normal file
View File

@@ -0,0 +1,187 @@
---
title: YouTube 동영상 RAG 검색
description: YoutubeVideoSearchTool은 YouTube 동영상의 콘텐츠 내에서 RAG(Retrieval-Augmented Generation) 검색을 수행하도록 설계되었습니다.
icon: youtube
---
# `YoutubeVideoSearchTool`
<Note>
우리는 도구를 계속 개선하고 있으므로, 향후 예기치 않은 동작이나 변경이 있을 수 있습니다.
</Note>
## 설명
이 도구는 `crewai_tools` 패키지의 일부로, Youtube 동영상 콘텐츠 내에서 의미 기반 검색을 수행하도록 설계되었으며 Retrieval-Augmented Generation (RAG) 기술을 활용합니다.
이 도구는 패키지 내 여러 "검색" 도구 중 하나로, 다양한 소스에 대해 RAG를 활용합니다.
YoutubeVideoSearchTool은 검색에 유연성을 제공합니다. 사용자는 특정 동영상 URL을 지정하지 않고도 Youtube 동영상 콘텐츠 전반에 걸쳐 검색할 수 있으며,
URL을 제공하여 특정 Youtube 동영상에 대해 검색을 제한할 수도 있습니다.
## 설치
`YoutubeVideoSearchTool`을 사용하려면 먼저 `crewai_tools` 패키지를 설치해야 합니다.
이 패키지에는 데이터 분석 및 처리 작업을 향상시키기 위해 설계된 다양한 유틸리티와 함께 `YoutubeVideoSearchTool`이 포함되어 있습니다.
터미널에서 다음 명령어를 실행하여 패키지를 설치하세요:
```shell
pip install 'crewai[tools]'
```
## 예시
다음 예시는 `YoutubeVideoSearchTool`을 CrewAI agent와 함께 사용하는 방법을 보여줍니다.
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import YoutubeVideoSearchTool
# Initialize the tool for general YouTube video searches
youtube_search_tool = YoutubeVideoSearchTool()
# Define an agent that uses the tool
video_researcher = Agent(
role="Video Researcher",
goal="Extract relevant information from YouTube videos",
backstory="An expert researcher who specializes in analyzing video content.",
tools=[youtube_search_tool],
verbose=True,
)
# Example task to search for information in a specific video
research_task = Task(
description="Search for information about machine learning frameworks in the YouTube video at {youtube_video_url}",
expected_output="A summary of the key machine learning frameworks mentioned in the video.",
agent=video_researcher,
)
# Create and run the crew
crew = Crew(agents=[video_researcher], tasks=[research_task])
result = crew.kickoff(inputs={"youtube_video_url": "https://youtube.com/watch?v=example"})
```
도구를 특정 YouTube 동영상 URL로 초기화할 수도 있습니다:
```python Code
# Initialize the tool with a specific YouTube video URL
youtube_search_tool = YoutubeVideoSearchTool(
youtube_video_url='https://youtube.com/watch?v=example'
)
# Define an agent that uses the tool
video_researcher = Agent(
role="Video Researcher",
goal="Extract relevant information from a specific YouTube video",
backstory="An expert researcher who specializes in analyzing video content.",
tools=[youtube_search_tool],
verbose=True,
)
```
## 매개변수
`YoutubeVideoSearchTool`은(는) 다음과 같은 매개변수를 허용합니다:
- **youtube_video_url**: 선택 사항. 검색할 YouTube 비디오의 URL입니다. 초기화 시 제공되면, 에이전트가 도구를 사용할 때 해당 URL을 지정할 필요가 없습니다.
- **config**: 선택 사항. LLM 및 임베더 설정을 포함한 기본 RAG 시스템의 구성입니다.
- **summarize**: 선택 사항. 검색된 콘텐츠를 요약할지 여부입니다. 기본값은 `False`입니다.
에이전트와 함께 도구를 사용할 때 에이전트가 제공해야 하는 항목:
- **search_query**: 필수. 비디오 콘텐츠에서 관련 정보를 찾기 위한 검색 질의입니다.
- **youtube_video_url**: 초기화 시 제공되지 않은 경우에만 필수. 검색할 YouTube 비디오의 URL입니다.
## 사용자 지정 모델 및 임베딩
기본적으로 이 도구는 임베딩과 요약 모두에 OpenAI를 사용합니다. 모델을 사용자 지정하려면 다음과 같이 config 딕셔너리를 사용할 수 있습니다:
```python Code
youtube_search_tool = YoutubeVideoSearchTool(
config=dict(
llm=dict(
provider="ollama", # or google, openai, anthropic, llama2, ...
config=dict(
model="llama2",
# temperature=0.5,
# top_p=1,
# stream=true,
),
),
embedder=dict(
provider="google", # or openai, ollama, ...
config=dict(
model="models/embedding-001",
task_type="retrieval_document",
# title="Embeddings",
),
),
)
)
```
## 에이전트 통합 예시
아래는 `YoutubeVideoSearchTool`을 CrewAI 에이전트와 통합하는 방법에 대한 보다 자세한 예제입니다.
```python Code
from crewai import Agent, Task, Crew
from crewai_tools import YoutubeVideoSearchTool
# Initialize the tool
youtube_search_tool = YoutubeVideoSearchTool()
# Define an agent that uses the tool
video_researcher = Agent(
role="Video Researcher",
goal="Extract and analyze information from YouTube videos",
backstory="""You are an expert video researcher who specializes in extracting
and analyzing information from YouTube videos. You have a keen eye for detail
and can quickly identify key points and insights from video content.""",
tools=[youtube_search_tool],
verbose=True,
)
# Create a task for the agent
research_task = Task(
description="""
Search for information about recent advancements in artificial intelligence
in the YouTube video at {youtube_video_url}.
Focus on:
1. Key AI technologies mentioned
2. Real-world applications discussed
3. Future predictions made by the speaker
Provide a comprehensive summary of these points.
""",
expected_output="A detailed summary of AI advancements, applications, and future predictions from the video.",
agent=video_researcher,
)
# Run the task
crew = Crew(agents=[video_researcher], tasks=[research_task])
result = crew.kickoff(inputs={"youtube_video_url": "https://youtube.com/watch?v=example"})
```
## 구현 세부사항
`YoutubeVideoSearchTool`은 Retrieval-Augmented Generation의 기본 기능을 제공하는 `RagTool`의 하위 클래스로 구현됩니다.
```python Code
class YoutubeVideoSearchTool(RagTool):
name: str = "Search a Youtube Video content"
description: str = "A tool that can be used to semantic search a query from a Youtube Video content."
args_schema: Type[BaseModel] = YoutubeVideoSearchToolSchema
def __init__(self, youtube_video_url: Optional[str] = None, **kwargs):
super().__init__(**kwargs)
if youtube_video_url is not None:
kwargs["data_type"] = DataType.YOUTUBE_VIDEO
self.add(youtube_video_url)
self.description = f"A tool that can be used to semantic search a query the {youtube_video_url} Youtube Video content."
self.args_schema = FixedYoutubeVideoSearchToolSchema
self._generate_description()
```
## 결론
`YoutubeVideoSearchTool`은 RAG 기술을 사용하여 YouTube 비디오 콘텐츠에서 정보를 검색하고 추출할 수 있는 강력한 방법을 제공합니다. 이 도구를 통해 에이전트는 비디오 콘텐츠 내에서 검색을 수행할 수 있으므로, 그렇지 않으면 수행하기 어려운 정보 추출 및 분석 작업을 용이하게 할 수 있습니다. 이 도구는 특히 연구, 콘텐츠 분석, 그리고 비디오 소스에서 지식 추출을 위해 매우 유용합니다.

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/)를 방문하세요