Agent Web Search

AI 에이전트를 위한 멀티 프로바이더 웹 검색.

Agent Web Search는 Hermes, Codex CLI, Claude Code, OpenCode 및 일반 스크립트에 일관된 웹 검색 도구를 제공합니다. 독립적인 프로바이더를 동시에 실행하고 정규화된 결과를 반환합니다. 기본 프로바이더 세트는 다음과 같습니다:

• ARK grounding — Volcengine ARK Responses API + web_search (Doubao)

• DDGS — DuckDuckGo 검색

• Exa — Exa MCP 검색(최선의 노력; 가용성은 엔드포인트에 따라 다름)

선택적 프로바이더도 구현되어 있습니다:

• Gemini — Gemini Interactions API를 통한 Google 검색 grounding

• Grok — 기본 웹 검색 및 X Search를 갖춘 xAI Responses API

• Tavily — 기본 결과 수 및 기간 필터가 있는 Tavily Search API

아키텍처는 프로바이더 기반이므로 MCP 또는 Hermes 인터페이스를 변경하지 않고도 DeepSeek, Brave 및 기타 검색 가능한 프로바이더를 추가할 수 있습니다.

빠른 시작

# Omit this line when the ARK provider is not enabled.
export ARK_API_KEY="your_ark_api_key"
pipx install 'git+https://github.com/JerryLiu369/agent-web-search.git'
agent-web-search-mcp

API 키를 셸 기록, 소스 코드, Git 커밋 또는 스크린샷에 넣지 마십시오. 로컬 .env/비밀 관리자를 사용하고 프로세스 환경에서 변수를 내보내십시오.

Related MCP server: GroundRoute

Codex CLI에서 사용

export ARK_API_KEY="your_ark_api_key"
codex mcp add agent-web-search -- \
  agent-web-search-mcp
codex mcp list

Claude Code에서 사용

export ARK_API_KEY="your_ark_api_key"
claude mcp add agent-web-search -- \
  agent-web-search-mcp

또는 프로젝트 .mcp.json을 추가하십시오:

{
  "mcpServers": {
    "agent-web-search": {
      "command": "agent-web-search-mcp",
      "args": [],
      "env": {"ARK_API_KEY": "${ARK_API_KEY}"}
    }
  }
}

OpenCode에서 사용

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agent-web-search": {
      "type": "local",
      "command": ["agent-web-search-mcp"],
      "environment": {"ARK_API_KEY": "${ARK_API_KEY}"},
      "enabled": true
    }
  }
}

Hermes에서 사용

GitHub에서 기본 플러그인을 직접 설치하십시오:

pip install 'ddgs>=9.0'
hermes plugins install JerryLiu369/agent-web-search --no-enable
hermes plugins enable agent-web-search --allow-tool-override

플러그인은 표준 web_search 도구를 등록하고 MCP 및 CLI에서 사용하는 것과 동일한 Agent Web Search 코어를 호출합니다. 일반 MCP 경로를 선호하는 경우 Hermes는 hermes mcp add로 연결할 수도 있습니다.

GitHub 설치 프로그램은 패키지와 선택적 종속성을 설치합니다:

pipx install 'git+https://github.com/JerryLiu369/agent-web-search.git'

Hermes는 이 플러그인이 내장된 web_search 도구를 의도적으로 대체하므로 명시적인 --allow-tool-override 권한이 필요합니다. 활성화한 후 새 Hermes 세션을 시작하십시오. 메시징 채널을 사용하는 경우 게이트웨이를 다시 시작하십시오.

CLI

agent-web-search "What changed in the latest OpenAI Codex CLI?"
agent-web-search "GPU kernel generation papers from the past month" --time-range m --max-results 5
agent-web-search "latest news" --provider ark --provider ddgs

Volcengine 협업 보상

Agent Web Search는 보상 프로그램 참여를 요구하지 않습니다. ARK를 사용하기로 선택한 사용자는 자체 API 키를 만들고 선택적으로 공식 Volcengine 협업 보상 프로그램 을 검토할 수 있습니다. 이 프로그램은 현재 규칙에 따라 보상 리소스를 제공할 수 있지만, 할당량, 지원 모델, 유효 기간 및 데이터 권한 부여 조건은 변경될 수 있습니다. 옵트인하기 전에 공식 페이지를 확인하십시오. 참여는 프로바이더의 데이터 권한 부여 조건을 수락하는 것을 의미합니다. Agent Web Search를 사용하는 데 필요하지는 않습니다.

구성

• ARK_API_KEY: 선택 사항; ARK 프로바이더가 활성화된 경우에만 필요합니다. 쉼표/줄바꿈으로 구분된 키가 허용됩니다.

• AGENT_WEB_SEARCH_PROVIDERS: 시작 시 활성화된 프로바이더 세트; 기본값은 ark,ddgs,exa입니다.

• AGENT_WEB_SEARCH_TIMEOUT: 프로바이더별 제한 시간(초) (기본값 60).

• AGENT_WEB_SEARCH_ARK_MODELS: 쉼표로 구분된 ARK 모델 ID.

• EXA_MCP_URL: 선택적 Exa MCP 엔드포인트 재정의.

• GEMINI_API_KEY: 선택적 Gemini 프로바이더 키.

• AGENT_WEB_SEARCH_GEMINI_MODEL: 선택적 Gemini 모델 ID.

• XAI_API_KEY: 선택적 Grok 프로바이더 키.

• AGENT_WEB_SEARCH_GROK_MODEL: 선택적 Grok 모델 ID.

• TAVILY_API_KEY: 선택적 Tavily 프로바이더 키.

프로바이더 세트는 Hermes 플러그인 또는 MCP 서버가 시작될 때 확인됩니다. 공개 web_search 스키마는 해당 세트에서 생성됩니다. 요청은 providers로 세트를 좁힐 수 있지만 시작 시 비활성화된 프로바이더를 활성화할 수는 없습니다. grok이 시작 시 활성화되면 스키마는 web_search, x_search 및 both 값을 가진 grok_search_mode를 추가로 노출합니다. both는 두 xAI 서버 측 도구를 단일 요청으로 전달하고 Grok이 호출할 항목을 결정하도록 합니다. 두 개의 독립적인 요청을 보내지 않습니다.

일반 검색 컨트롤

공개 인터페이스는 프로바이더 중립적인 컨트롤 세트 하나를 유지합니다. 각 백엔드는 가능한 경우 기본 API에 매핑하고 지원되지 않는 컨트롤은 자동으로 무시합니다:

프롬프트 제약은 모델 기반 프로바이더에 대한 최선의 노력이며 엄격한 보장으로 제시되지 않습니다.

설계 원칙

• 하나의 코어, 여러 어댑터.

• 실패한 프로바이더가 성공한 프로바이더를 폐기하지 않습니다.

• 프로바이더 응답은 모든 HTTP 200이 성공적인 검색인 것처럼 가장하는 대신 searched, error 및 model로 표시됩니다.

• 원격 측정 및 공유 API 키 서비스가 없습니다.

개발

python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev,ddgs,mcp]'
pytest -q
ruff check .

라이선스

MIT.