Search Engines

This page describes the runtime egress path of every supported search engine. Each engine has a sequence diagram showing what data leaves assistants-core, where it goes, and how the response comes back. Each diagram is followed by a short "what's in the request, what's in the response" summary.

This page does not describe credentials or environment variables. For deployment-side setup of each engine, see Search Engine Setup under Infrastructure. For which engines are exposed in a given Spaces UI, see Activation Reference under Infrastructure.

For the orchestrator-side framing of how a tool call gets dispatched into a per-engine call, see Tool Lifecycle and Search Modes.

Google Search

Direct integration with the Google Custom Search JSON API. Sends paginated requests over the corporate proxy.

Request: the query string, the configured Custom Search Engine ID (cx), the Google API key, optional date filter and locale parameters. Sent as URL query parameters.

Response: JSON list of items with link, title, snippet. Page content is not returned; the executor follows up with a Web Page Reader fetch for each URL.

Egress destination: customsearch.googleapis.com (or whatever endpoint the Google client is configured with). Egress goes through the corporate proxy when configured.

Grounding with Bing

Not a classic search-API integration. The tool delegates the search to an Azure AI Foundry Agent that has Bing grounding enabled. Two sub-modes exist: the agent can be auto-provisioned at first use (default) or pre-configured by an admin.

Auto-provisioned agent

The Web Search tool finds (or creates on first use) an agent named UNIQUE_GROUNDING_WITH_BING_AGENT in the configured Azure AI project. Each search creates a fresh thread, posts the user query, attaches the Bing grounding tool, runs to completion, and parses the agent's free-text answer into structured results.

Pre-configured agent

When the Spaces config has Agent ID set (or the AZURE_AI_ASSISTANT_ID env var is set platform-wide), the tool uses that agent as-is and skips provisioning, instructions injection, and tool attachment. Useful for environments where agent configuration is centrally managed.

Request: the user query. In auto-provisioned mode, also the model name, the configured generation instructions, and a Bing connection ID. In pre-configured mode, only the agent ID and the query.

Response: the agent's textual answer plus URL citation annotations. The Web Search tool then parses that answer either as JSON (preferred) or via a fallback LLM parser.

Egress destination: the Azure AI Foundry endpoint configured in the Space (or via AZURE_AI_PROJECT_ENDPOINT). The agent itself egresses to Bing on Azure's side.

Grounding with VertexAI

Not a classic search-API integration. The tool calls a Gemini model on Vertex AI with Google's Grounding tool attached. Gemini autonomously runs web searches, reads pages, and returns a grounded text answer with citation metadata.

Request: the user query, the Gemini model name, the generation instructions, and the grounding-tool config (with optional Vertex Enterprise Search enabled).

Response: Gemini's text answer plus grounding metadata (chunk → source URL mapping). The Web Search tool inlines those citations and parses the resulting text.

Egress destination: the Vertex AI endpoint for the bound GCP project. The grounding tool itself egresses to the public web on Google's side. Optional redirect-resolution pass uses an in-pod HTTPX client to follow redirects on each citation URL.

Brave Search

Direct integration with Brave's Search API. Single-page or paginated request, returns URLs plus rich snippets.

Request: the query, the Brave API key in the X-Subscription-Token header, count + offset for pagination.

Response: JSON with web.results[] and news.results[] arrays. Snippets include both description and additional fragments.

Egress destination: Brave's Search API endpoint over HTTPS.

Jina Search

Direct integration with Jina's Search API. Returns URLs plus full Markdown content per result in one call.

Request: the query and any locale / return-format / engine-mode headers configured for the Space. API key in the Authorization: Bearer header.

Response: JSON with a data[] array, each item containing the URL, title, description, and Markdown content.

Egress destination: Jina's Search API endpoint over HTTPS.

Tavily Search

Direct integration with Tavily's Search API via the Tavily Python SDK. Returns URLs plus content per result in one call (when advanced depth is selected).

Request: the query, max-results, search-depth, optional topic. API key supplied to the SDK client.

Response: structured JSON with results, scores, and (in advanced depth) raw content per row.

Egress destination: Tavily's API endpoint over HTTPS (via the SDK).

Firecrawl Search

Direct integration with Firecrawl's Search API via the Firecrawl Python SDK. Returns results with Markdown content per page.

Request: the query, the requested sources (web, news), and the desired output format (markdown). API key supplied to the SDK client.

Response: structured response with web and news documents, each containing metadata (URL, title, description) plus Markdown content.

Egress destination: Firecrawl's API endpoint over HTTPS (via the SDK).

Customized API Search

Direct integration with a user-defined REST endpoint. The shape of the request and response is determined by the Spaces config and platform env vars.

Request: the query (in params for GET, in body for POST), headers and additional params/body keys exactly as configured. Any platform-side CUSTOM_WEB_SEARCH_API_* env var locks the corresponding field.

Response: must match the standard WebSearchResults JSON schema with results[] of {url, title, snippet, content?}. The content field is optional; if absent and requires_scraping = true, the executor will run the Web Page Reader.

Egress destination: the configured customer endpoint over HTTPS. Egress goes through the corporate proxy when configured.

Summary: what comes back from each engine

For the per-reader fetch path when the engine doesn't return content directly, see Web Page Readers.