Brave Search 도구

Brave Search 도구 (Brave Search Tools)

CrewAI는 각각 특정 Brave Search API 엔드포인트를 겨냥한 Brave Search 도구 패밀리를 제공해요. 하나의 만능 도구 대신, 에이전트가 필요로 하는 결과 유형에 정확히 맞는 도구를 고를 수 있답니다. 웹·뉴스·이미지·비디오·로컬 POI까지 상황에 맞는 전용 도구를 골라 쓰세요.

출처: 문서

본문

CrewAI는 각각 특정 Brave Search API 엔드포인트를 겨냥한 Brave Search 도구 패밀리를 제공합니다. 만능 단일 도구 대신 에이전트가 필요한 결과 유형과 정확히 일치하는 도구를 고를 수 있어요.

Tool	Endpoint	Use case
`BraveWebSearchTool`	Web Search	일반 웹 결과, 스니펫, URL
`BraveNewsSearchTool`	News Search	최신 뉴스 기사와 헤드라인
`BraveImageSearchTool`	Image Search	크기와 소스 URL이 포함된 이미지 결과
`BraveVideoSearchTool`	Video Search	웹 전역의 비디오 결과
`BraveLocalPOIsTool`	Local POIs	관심 지점(예: 레스토랑) 찾기
`BraveLocalPOIsDescriptionTool`	Local POIs	AI 생성 위치 설명 검색
`BraveLLMContextTool`	LLM Context	AI 에이전트, LLM 그라운딩, RAG 파이프라인에 최적화된 사전 추출 웹 콘텐츠

모든 도구는 공통 기본 클래스(BraveSearchToolBase)를 공유하며, 일관된 동작(속도 제한, 429 응답 시 자동 재시도, 헤더·파라미터 검증, 선택적 파일 저장)을 제공합니다.

더 오래된 BraveSearchTool 클래스는 하위 호환성을 위해 여전히 사용 가능하지만, 레거시로 간주되며 앞으로 동일한 수준의 관리를 받지 못할 거예요. 위에 나열된 특정 도구들이 더 풍부한 설정과 집중된 인터페이스를 제공하니, 새 코드에서는 그쪽으로 마이그레이션하는 것을 권장합니다.

많은 도구(예: BraveWebSearchTool, BraveNewsSearchTool, BraveImageSearchTool, BraveVideoSearchTool)는 무료 Brave Search API 구독/요금제로 사용할 수 있지만, 일부 파라미터(예: enable_snippets)와 도구(예: BraveLocalPOIsTool, BraveLocalPOIsDescriptionTool)는 유료 요금제가 필요해요. 자세한 내용은 구독 요금제의 기능을 확인하세요.

설치 (Installation)

pip install 'crewai[tools]'

시작하기 (Getting Started)

패키지 설치 — Python 환경에 crewai[tools]가 설치되어 있는지 확인하세요.
API 키 받기 — api-dashboard.search.brave.com/login에서 가입해 키를 생성하세요.
환경변수 설정 — 키를 BRAVE_API_KEY로 저장하거나, 직접 api_key 파라미터로 전달하세요.

빠른 예시 (Quick Examples)

웹 검색 (Web Search)

from crewai_tools import BraveWebSearchTool

tool = BraveWebSearchTool()
results = tool.run(q="CrewAI agent framework")
print(results)

뉴스 검색 (News Search)

from crewai_tools import BraveNewsSearchTool

tool = BraveNewsSearchTool()
results = tool.run(q="latest AI breakthroughs")
print(results)

이미지 검색 (Image Search)

from crewai_tools import BraveImageSearchTool

tool = BraveImageSearchTool()
results = tool.run(q="northern lights photography")
print(results)

비디오 검색 (Video Search)

from crewai_tools import BraveVideoSearchTool

tool = BraveVideoSearchTool()
results = tool.run(q="how to build AI agents")
print(results)

위치 POI 설명 (Location POI Descriptions)

from crewai_tools import (
    BraveWebSearchTool,
    BraveLocalPOIsDescriptionTool,
)

web_search = BraveWebSearchTool(raw=True)
poi_details = BraveLocalPOIsDescriptionTool()

results = web_search.run(q="italian restaurants in pensacola, florida")

if "locations" in results:
    location_ids = [ loc["id"] for loc in results["locations"]["results"] ]
    if location_ids:
        descriptions = poi_details.run(ids=location_ids)
        print(descriptions)

공통 생성자 파라미터 (Common Constructor Parameters)

모든 Brave Search 도구는 초기화 시 다음 파라미터를 받습니다.

Parameter	Type	Default	Description
`api_key`	`str \| None`	`None`	Brave API 키. `BRAVE_API_KEY` 환경변수로 폴백됩니다.
`headers`	`dict \| None`	`None`	모든 요청에 보낼 추가 HTTP 헤더 (예: `api-version`, 지오로케이션 헤더)
`requests_per_second`	`float`	`1.0`	최대 요청 속도. 이 한도 내에 유지되도록 호출 사이에 슬립합니다.
`save_file`	`bool`	`False`	`True`이면 각 응답을 타임스탬프가 붙은 `.txt` 파일로 저장합니다.
`raw`	`bool`	`False`	`True`이면 정제 없이 전체 API JSON 응답을 반환합니다.
`timeout`	`int`	`30`	HTTP 요청 타임아웃(초).
`country`	`str \| None`	`None`	지오타게팅용 레거시 약칭 (예: `"US"`). `country` 쿼리 파라미터를 직접 쓰는 걸 권장합니다.
`n_results`	`int`	`10`	결과 수용 레거시 약칭. `count` 쿼리 파라미터를 직접 쓰는 걸 권장합니다.

country와 n_results 생성자 파라미터는 하위 호환을 위해 존재합니다. 호출 시점에 해당 쿼리 파라미터(country, count)가 제공되지 않으면 기본값으로 적용됩니다. 새 코드에서는 country와 count를 쿼리 파라미터로 직접 전달하는 것을 권장합니다.

쿼리 파라미터 (Query Parameters)

각 도구는 요청을 보내기 전에 Pydantic 스키마로 쿼리 파라미터를 검증합니다. 엔드포인트마다 파라미터가 약간씩 다르며, 가장 흔히 쓰이는 것들의 요약은 다음과 같습니다.

BraveWebSearchTool

Parameter	Description
`q`	(필수) 검색 쿼리 문자열 (최대 400자).
`country`	지오타게팅용 두 글자 국가 코드 (예: `"US"`).
`search_lang`	결과용 두 글자 언어 코드 (예: `"en"`).
`count`	반환할 최대 결과 수 (1–20).
`offset`	처음 N개 결과 페이지를 건너뜁니다 (0–9).
`safesearch`	콘텐츠 필터: `"off"`, `"moderate"`, 또는 `"strict"`.
`freshness`	최신성 필터: `"pd"`(하루 전), `"pw"`(일주일 전), `"pm"`(한 달 전), `"py"`(일년 전), 또는 `"2025-01-01to2025-06-01"` 같은 날짜 범위.
`extra_snippets`	결과당 최대 5개의 추가 텍스트 스니펫 포함.
`goggles`	커스텀 재정렬을 위한 Brave Goggles URL 및/또는 소스.

전체 파라미터와 헤더 레퍼런스는 Brave Web Search API 문서를 참고하세요.

BraveNewsSearchTool

Parameter	Description
`q`	(필수) 검색 쿼리 문자열 (최대 400자).
`country`	지오타게팅용 두 글자 국가 코드.
`search_lang`	결과용 두 글자 언어 코드.
`count`	반환할 최대 결과 수 (1–50).
`offset`	처음 N개 결과 페이지를 건너뜁니다 (0–9).
`safesearch`	콘텐츠 필터: `"off"`, `"moderate"`, 또는 `"strict"`.
`freshness`	최신성 필터 (Web Search와 동일한 옵션).
`goggles`	커스텀 재정렬을 위한 Brave Goggles URL 및/또는 소스.

전체 레퍼런스는 Brave News Search API 문서를 참고하세요.

BraveImageSearchTool

Parameter	Description
`q`	(필수) 검색 쿼리 문자열 (최대 400자).
`country`	지오타게팅용 두 글자 국가 코드.
`search_lang`	결과용 두 글자 언어 코드.
`count`	반환할 최대 결과 수 (1–200).
`safesearch`	콘텐츠 필터: `"off"` 또는 `"strict"`.
`spellcheck`	쿼리의 철자 오류를 교정하려 시도.

전체 레퍼런스는 Brave Image Search API 문서를 참고하세요.

BraveVideoSearchTool

Parameter	Description
`q`	(필수) 검색 쿼리 문자열 (최대 400자).
`country`	지오타게팅용 두 글자 국가 코드.
`search_lang`	결과용 두 글자 언어 코드.
`count`	반환할 최대 결과 수 (1–50).
`offset`	처음 N개 결과 페이지를 건너뜁니다 (0–9).
`safesearch`	콘텐츠 필터: `"off"`, `"moderate"`, 또는 `"strict"`.
`freshness`	최신성 필터 (Web Search와 동일한 옵션).

전체 레퍼런스는 Brave Video Search API 문서를 참고하세요.

BraveLocalPOIsTool

Parameter	Description
`ids`	(필수) 원하는 위치들의 고유 식별자 목록.
`search_lang`	결과용 두 글자 언어 코드.

전체 레퍼런스는 Brave Local POIs API 문서를 참고하세요.

BraveLocalPOIsDescriptionTool

Parameter	Description
`ids`	(필수) 원하는 위치들의 고유 식별자 목록.

전체 레퍼런스는 Brave POI Descriptions API 문서를 참고하세요.

커스텀 헤더 (Custom Headers)

모든 도구는 커스텀 HTTP 요청 헤더를 지원합니다. 예를 들어 Web Search 도구는 위치 인지 결과를 위한 지오로케이션 헤더를 받습니다.

from crewai_tools import BraveWebSearchTool

tool = BraveWebSearchTool(
    headers={
        "x-loc-lat": "37.7749",
        "x-loc-long": "-122.4194",
        "x-loc-city": "San Francisco",
        "x-loc-state": "CA",
        "x-loc-country": "US",
    }
)

results = tool.run(q="best coffee shops nearby")

초기화 후에도 set_headers() 메서드로 헤더를 갱신할 수 있어요.

tool.set_headers({"api-version": "2025-01-01"})

Raw 모드 (Raw Mode)

기본적으로 각 도구는 API 응답을 간결한 결과 목록으로 정제합니다. 가공되지 않은 전체 API 응답이 필요하다면 raw 모드를 활성화하세요.

from crewai_tools import BraveWebSearchTool

tool = BraveWebSearchTool(raw=True)
full_response = tool.run(q="Brave Search API")

에이전트 통합 예시 (Agent Integration Example)

CrewAI 에이전트에 여러 Brave Search 도구를 장착하는 방법은 다음과 같습니다.

from crewai import Agent
from crewai.project import agent
from crewai_tools import BraveWebSearchTool, BraveNewsSearchTool

web_search = BraveWebSearchTool()
news_search = BraveNewsSearchTool()

@agent
def researcher(self) -> Agent:
    return Agent(
        config=self.agents_config["researcher"],
        tools=[web_search, news_search],
    )

고급 예시 (Advanced Example)

여러 파라미터를 조합한 타겟 검색:

from crewai_tools import BraveWebSearchTool

tool = BraveWebSearchTool(
    requests_per_second=0.5,  # 보수적인 속도 제한
    save_file=True,
)

results = tool.run(
    q="artificial intelligence news",
    country="US",
    search_lang="en",
    count=5,
    freshness="pm",           # 지난 한 달만
    extra_snippets=True,
)
print(results)

`BraveSearchTool`(레거시)에서 마이그레이션하기

현재 BraveSearchTool을 사용 중이라면 새 도구로 전환하는 것은 간단합니다.

# Before (legacy)
from crewai_tools import BraveSearchTool

tool = BraveSearchTool(country="US", n_results=5, save_file=True)
results = tool.run(search_query="AI agents")

# After (recommended)
from crewai_tools import BraveWebSearchTool

tool = BraveWebSearchTool(save_file=True)
results = tool.run(q="AI agents", country="US", count=5)

주요 차이점:

Import: BraveSearchTool 대신 BraveWebSearchTool(또는 뉴스/이미지/비디오 변형)을 사용하세요.
쿼리 파라미터: search_query 대신 q를 사용하세요. (편의를 위해 search_query와 query도 여전히 받아들이지만, q가 선호 파라미터입니다.)
결과 수: 초기화 시 n_results 대신 쿼리 파라미터로 count를 전달하세요.
국가: 초기화 시점이 아니라 쿼리 파라미터로 country를 전달하세요.
API 키: 이제 BRAVE_API_KEY 환경변수 외에도 api_key=로 직접 전달할 수 있어요.
속도 제한: 429 응답 시 자동 재시도와 함께 requests_per_second로 설정 가능합니다.

결론 (Conclusion)

Brave Search 도구 모음은 CrewAI 에이전트에 유연하고 엔드포인트별로 특화된 Brave Search API 접근을 제공합니다. 웹 페이지, 속보, 이미지, 비디오 중 무엇이 필요하든, 검증된 파라미터와 내장된 탄력성을 갖춘 전용 도구가 있습니다. 사용 사례에 맞는 도구를 고르고, 사용 가능한 파라미터와 응답 형식에 대한 전체 내용은 Brave Search API 문서를 참고하세요.

Brave Search 도구