Agent Web Search

Búsqueda web multiproveedor para agentes de IA.

Agent Web Search ofrece a Hermes, Codex CLI, Claude Code, OpenCode y scripts ordinarios una herramienta de búsqueda web coherente. Ejecuta proveedores independientes de forma concurrente y devuelve resultados normalizados. El conjunto de proveedores predeterminado es:

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

• DDGS — Búsqueda de DuckDuckGo

• Exa — Búsqueda Exa MCP (mejor esfuerzo; la disponibilidad depende del endpoint)

También se implementan proveedores opcionales:

• Gemini — Google Search grounding mediante Gemini Interactions API

• Grok — xAI Responses API con búsqueda web nativa y X Search

• Tavily — Tavily Search API con filtros nativos de recuento de resultados y rango de fechas

La arquitectura está basada en proveedores, por lo que se pueden añadir DeepSeek, Brave y otros proveedores con capacidad de búsqueda sin cambiar las interfaces MCP o Hermes.

Inicio rápido

# 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

No pongas claves de API en el historial del shell, el código fuente, los commits de Git ni las capturas de pantalla. Usa un gestor local de .env/secretos y exporta la variable en el entorno del proceso.

Related MCP server: GroundRoute

Uso desde Codex CLI

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

Uso desde Claude Code

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

O añade un .mcp.json de proyecto:

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

Uso desde 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
    }
  }
}

Uso desde Hermes

Instala el plugin nativo directamente desde GitHub:

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

El plugin registra la herramienta estándar web_search y llama al mismo núcleo de Agent Web Search que usan MCP y CLI. Si prefieres la ruta MCP genérica, Hermes también puede conectarse con hermes mcp add.

El instalador de GitHub instala el paquete y sus dependencias opcionales:

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

Hermes requiere la concesión explícita --allow-tool-override porque este plugin reemplaza intencionadamente su herramienta integrada web_search. Inicia una nueva sesión de Hermes después de habilitarlo; reinicia la puerta de enlace si usas un canal de mensajería.

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

Recompensas de colaboración de Volcengine

Agent Web Search no requiere participar en ningún programa de recompensas. Los usuarios que decidan usar ARK pueden crear su propia clave de API y, opcionalmente, revisar el Programa de recompensas de colaboración de Volcengine oficial. El programa puede proporcionar recursos de recompensa según sus reglas actuales, pero la cuota, los modelos compatibles, el período de validez y los términos de autorización de datos pueden cambiar. Consulta la página oficial antes de aceptar. La participación implica aceptar los términos de autorización de datos del proveedor; no es necesario para usar Agent Web Search.

Configuración

• ARK_API_KEY: opcional; solo se requiere cuando el proveedor ARK está habilitado. Se aceptan claves separadas por comas/saltos de línea.

• AGENT_WEB_SEARCH_PROVIDERS: conjunto de proveedores habilitados al inicio; el valor predeterminado es ark,ddgs,exa.

• AGENT_WEB_SEARCH_TIMEOUT: tiempo de espera por proveedor en segundos (predeterminado 60).

• AGENT_WEB_SEARCH_ARK_MODELS: IDs de modelo ARK separados por comas.

• EXA_MCP_URL: anulación opcional del endpoint Exa MCP.

• GEMINI_API_KEY: clave opcional del proveedor Gemini.

• AGENT_WEB_SEARCH_GEMINI_MODEL: ID de modelo Gemini opcional.

• XAI_API_KEY: clave opcional del proveedor Grok.

• AGENT_WEB_SEARCH_GROK_MODEL: ID de modelo Grok opcional.

• TAVILY_API_KEY: clave opcional del proveedor Tavily.

El conjunto de proveedores se resuelve cuando se inicia el plugin de Hermes o el servidor MCP. El esquema público web_search se genera a partir de ese conjunto. Una solicitud puede reducir el conjunto con providers, pero no puede activar un proveedor que se deshabilitó al inicio. Si grok está habilitado al inicio, el esquema también expone grok_search_mode con los valores web_search, x_search y both. both pasa ambas herramientas del lado del servidor de xAI en una sola solicitud y deja que Grok decida cuál llamar; no envía dos solicitudes independientes.

Controles de búsqueda comunes

La interfaz pública mantiene un conjunto de controles neutrales para el proveedor. Cada backend los asigna a su API nativa cuando es posible e ignora silenciosamente los controles no compatibles:

Las restricciones de prompt son de mejor esfuerzo para los proveedores respaldados por modelos; no se presentan como garantías estrictas.

Principios de diseño

• Un núcleo, múltiples adaptadores.

• Un proveedor con fallo no descarta a los proveedores que tuvieron éxito.

• Las respuestas de los proveedores se marcan con searched, error y model en lugar de fingir que cada HTTP 200 fue una búsqueda exitosa.

• Sin telemetría y sin servicio compartido de claves de API.

Desarrollo

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

Licencia

MIT.