# 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

| Engine                     | Returns content directly     | Where the content originates                                     |
|----------------------------|------------------------------|-----------------------------------------------------------------|
| Google Search              | No (URL + snippet only)      | Web Page Reader fetches each URL                               |
| Grounding with Bing        | Yes                          | The Azure agent reads sources internally                         |
| Grounding with VertexAI    | Yes                          | Gemini grounding reads sources internally                        |
| Brave Search               | No (URL + rich snippets)     | Web Page Reader fetches each URL by default                    |
| Jina Search                | Yes (Markdown)               | Jina API returns per-row Markdown                               |
| Tavily Search              | Yes (in `advanced` depth)    | Tavily API returns per-row raw content                          |
| Firecrawl Search           | Yes (Markdown)               | Firecrawl API returns per-document Markdown                     |
| Customized API Search      | Depends on endpoint           | Endpoint or Web Page Reader

For the per-reader fetch path when the engine _doesn't_ return content directly, see **Web Page Readers**.