> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Google Search
> Run Google web searches from Agent Factory agents and Builder workflows — synthesized grounded answers or rich filtered results, with a Google API key or service account
The Google Search app exposes Google web search through a single `search` tool. It can be consumed two ways: as a remote MCP server that **Agent Factory** agents call as a tool, or as a Builder app whose instruction you call directly from DSUL. It runs in the **tenant app-instance context** (it resolves the installing workspace's own Google credential) and automatically routes between two backends depending on the tenant configuration:
* **Gemini Grounding** (default — when no `cx` is set) — behaves like a real google.com search of the **entire web** and returns a synthesized `answer` with cited sources.
* **Custom Search JSON API** (legacy — when a Programmable Search Engine `cx` is set) — returns ranked organic results with rich filters (date, site, language, file type) and image search, but searches **only the sites whitelisted in the Programmable Search Engine's context**, never the open web. Google has **removed the "Search the entire web" option for new Programmable Search Engines**, so this backend cannot cover the whole web — use Grounding (leave `cx` empty) for that.
Authentication is a **Google Cloud API key** (`AIza…`) or a **service-account JSON** (signed into a short-lived Bearer token). Agents are identified by the capability **Scope** `context_id,agent_id,user_id` and gated by a per-workspace authorized-agents allowlist.
A single `search` tool gives agents fresh, post-cutoff web information — news, prices, schedules, official docs, product specs — instead of guessing.
The default Gemini Grounding backend returns a synthesized answer plus cited sources, rendered as clickable source cards in the chat.
With a Programmable Search Engine (`cx`), switch to the Custom Search backend for date/site/language filters, file-type restriction and image search.
## Who is this for?
This connector is used by three different roles. Jump to the section that matches yours — each one is self-contained.
You build agents in **Agent Factory** and want them to search the web. → *Agent builder* tab.
You run the platform and set up a shared Google Search key once for everyone. → *Platform admin setup* accordion below.
You write Builder automations (DSUL) that call the `search` instruction directly. → *Workspace builder* tab.
## Prerequisites (Google side)
* A **Google** account with a **Google Cloud project**.
* The matching API must be **enabled** in that project:
* **Gemini API** (listed as **Generative Language API**, `generativelanguage.googleapis.com`) — for the default Gemini Grounding backend.
* **Custom Search API** (`customsearch.googleapis.com`) — for the legacy `cx` backend.
* A **credential**, one of:
* A **Google Cloud API key** (`AIza…`) — *APIs & Services > Credentials > Create credentials > API key*.
* A **service-account key** JSON — for server-to-server use (signed JWT exchanged for a Bearer token).
* For the Custom Search backend only: a **Programmable Search Engine** (the `cx` id), created at [programmablesearchengine.google.com](https://programmablesearchengine.google.com). A PSE searches **only the sites you add to its context** — Google has **retired the "Search the entire web" option for newly created engines**, so the Custom Search backend can no longer span the open web. For whole-web coverage, leave `cx` empty and use the Grounding backend.
The Gemini API free tier is limited (e.g. \~20 requests/day for `gemini-2.5-flash`). For production traffic, enable billing on the Cloud project or use the Custom Search backend (100 free queries/day, then paid).
**Goal:** two optional one-time tasks — (1) set a **shared platform Google key** so workspaces that have not configured their own credential can still search, and (2) expose Google Search as a reusable **capability** in AI Governance so agent builders can pick it without pasting endpoint URLs.
Both tasks are optional. If every workspace pastes its own Google key, you can skip this section entirely — there is no per-tenant credential to register on the platform.
## 1. Configure the shared platform key
The backend you use decides which API to enable in the Google Cloud project:
* **Gemini Grounding (default).** Enable the **Gemini API** — listed in the Cloud Console as **Generative Language API** (`generativelanguage.googleapis.com`); the two names are the same service. *Grounding with Google Search* is **not** a separate API to enable: it is the `google_search` tool exposed inside the Gemini `generateContent` call, so enabling the Gemini API is all that the Grounding backend needs.
* **Custom Search (legacy, `cx` set).** Enable the **Custom Search API** (`customsearch.googleapis.com`) and create a **Programmable Search Engine** at [programmablesearchengine.google.com](https://programmablesearchengine.google.com), noting its `cx`. Note the scope: a PSE returns results **only from the sites whitelisted in its context**, never the whole web — Google has **removed the "Search the entire web" option for new engines**. For broad web coverage, leave `cx` empty and use the Grounding backend instead.
Enable it from **APIs & Services > Library** (or run `gcloud services enable generativelanguage.googleapis.com`).
In the [Google Cloud Console](https://console.cloud.google.com/apis/credentials), in that same project, create an **API key** (or a service-account key JSON). For a service account, the connector requests the `https://www.googleapis.com/auth/generative-language` scope when exchanging the JWT.
Open the central `google-search` workspace and launch its **Configuration app** maintainer view — `/apps/google-search` (e.g. `https://studio.prisme.ai/apps/google-search`). Follow the in-app instructions to paste the **platform global key** (and optional `cx`). The app stores it in the core workspace's secrets for you — do not edit Studio's raw Secrets by hand. The global key stays in the `google-search` workspace and is never inherited by tenant instances; only search **results** are returned to tenants (proxied through the core `centralSearch` webhook).
When a platform global key is set, the shared connector instance becomes a **global endpoint**: the per-agent allowlist no longer applies there, and every agent granted the capability (Option A in the *Agent builder* tab) is accepted. The global key is the gate.
## 2. Declare the capability in AI Governance
Generic connectors — broad tool surfaces meant to be shared across many agents — are best exposed as a named **capability** in the org Capabilities catalog. Agent builders then enable that capability on their agents instead of pasting a raw MCP endpoint.
**Easiest path — the one-click "Add to catalog" button.** The configuration app has an **Add to catalog** button (in the *MCP endpoint* section) that registers the connector org-wide in one click: it creates an `mcp`-type catalog entry pointing at this workspace's MCP endpoint with the *Scope* `context_id,agent_id,user_id` already set. It also detects an existing entry and offers **Update catalog entry** instead. The button is shown only to **org owners / admins**, and the published entry is **org-wide** — every builder in the org can then attach the connector. Use this instead of the manual steps below; they remain for when you want to author the capability by hand.
Create (or edit) the **Google Search** capability.
Set the capability's MCP server URL to the connector's **MCP Endpoint**, and set its **Scope** to:
```text theme={null}
context_id,agent_id,user_id
```
The `agent_id` in the scope is what lets the connector identify the calling agent.
Once created, the capability appears in the capability picker for agent builders in your organization, who enable it on their agents. Access to the catalog follows your organization's existing roles; there is no per-capability role grant.
From an agent that has the capability, trigger any web question. The agent calls `search` and grounds its answer on the returned sources.
Declaring the capability makes the connector **available**; it does not by itself authorize a specific agent. This connector follows the **tenant-context model** — when a workspace runs its own instance (Option B), which agents may actually call it is gated per-workspace by the **authorized-agents allowlist** in the configuration app. There is **no OAuth auth-config JSON** to attach in Governance: authentication is a server-side Google key, not a per-user OAuth flow.
***
## Agent builder
**Goal:** let an agent you build in Agent Factory search the web through the `search` MCP tool.
Before an agent can call the connector, a *Workspace builder* must have installed and configured the Google Search app in a workspace (see the *Workspace builder* tab) — or a *Platform admin* must have set a shared platform key and published the capability (see the *Platform admin setup* accordion above).
This connector runs in the **tenant app-instance context**: your agent is identified by the `agent_id` that Agent Factory injects through the capability *Scope*, and that agent must appear in the connector's **authorized-agents allowlist** (managed in the configuration app). The Google credential itself is resolved server-side — never exposed to the agent.
There are two ways to wire it up. Pick based on how much isolation you need.
## Option A — Enable the shared capability from the catalog
The fastest path: an *org owner / admin* has published a **Google Search** capability to the org Capabilities catalog (typically via the config app's one-click **Add to catalog** button — see the *Platform admin setup* accordion above, §2), so you just pick it from the catalog. When the published entry points at a shared instance backed by a platform Google key, no per-agent allowlist applies.
Open the agent you want to extend and go to its capabilities / tools.
Browse the capability catalog, select **Google Search**, and enable it. The MCP endpoint URL and the *Scope* (`context_id,agent_id,user_id`) are already wired by the admin — nothing to paste, and the shared instance accepts every agent granted the capability, so there is no allowlist step on your side.
No sign-in is needed — the platform key backs every call. Ask the agent a question that needs the web; it calls `search` and grounds its answer with cited sources.
Convenient, but your agent runs against a **shared, platform-managed instance**: its Google credential and quota are owned by the platform and the instance accepts every agent that is granted the capability. Prefer Option B for anything beyond quick experiments.
## Option B — Run it from your own workspace (recommended)
For production agents, install the connector in **your own workspace** and point the agent at *that* workspace's MCP endpoint.
**Prefer this mode for security.** Because the MCP runs in *your* app-instance context, the Google credential, the search quota and the authorized-agents allowlist are all **scoped to your workspace** — not shared platform-wide. You decide exactly which agents may call it and which Google key / backend backs them, and a misconfiguration elsewhere can never consume your quota. The shared catalog capability (Option A) is a broad surface many agents can reach; your own workspace is an isolated, least-privilege boundary.
Follow the *Workspace builder* tab: install **Google Search** in your workspace, open its **Configuration app**, paste your Google API key (or service-account JSON) and — optionally — a Programmable Search Engine `cx`.
In that workspace's config app, open **Authorized agents** and tick your agent (the **Install capability** button does this for you), or enable **Allow all agents**.
In your agent, add a capability pointing at **your workspace's MCP Endpoint** URL, and set its **Scope** to:
```text theme={null}
context_id,agent_id,user_id
```
The `agent_id` is what lets the connector identify and authorize your agent — without it, every call is rejected with an explicit "agent could not be identified" message.
To skip pasting the endpoint by hand, an org owner / admin can use the config app's one-click **Add to catalog** button to register *this workspace's* endpoint as a Capabilities-catalog entry — then any builder picks it from the catalog (Option A). The connector still enforces this workspace's authorized-agents allowlist, so only the agents you ticked can actually call it.
## Brief the agent in its system prompt
Whichever option you pick, wiring the capability is not enough — the agent must know the tool exists and when to use it. Copy-pasteable starter:
```text theme={null}
You have access to the Google Search MCP server (tool: search). Use it whenever the question needs fresh, post-cutoff or external web information (news, prices, schedules, official docs, product specs) — prefer calling search over guessing. Pass the user's intent as `q`; combine Google operators (site:, intitle:, -exclude, "exact phrase") inside q. When the tool returns an `answer` with sources, ground your reply on them and cite the links.
```
**Legacy AI Knowledge agents** (no native MCP picker): add the connector under **Advanced > Tools > MCP** and paste the **MCP Endpoint** URL. The agent still has to be allowlisted in the config app and its identity propagated so the connector can read its `agent_id`.
## Available Tools
| Tool | Description |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search` | Google web search returning top organic results plus, when available, a synthesized `answer` with cited sources. Backend auto-selected per tenant: Custom Search (with a configured `cx`, rich filters + image search) or Gemini Grounding (whole-web search of the entire web). Only `q` is required; combine Google operators inside `q`. |
## Output Formats
The `search` tool accepts an `outputFormat` argument that controls the MCP response shape:
* **`verbose`** (default) — a human-readable markdown view (answer + sources with links + the queries actually run), optimized for LLM consumption and clickable source cards.
* **`structured`** — concise machine-readable JSON in `structuredContent`.
* **`both`** — the structured payload, with its JSON also rendered as text.
The structured payload shape is:
```json theme={null}
{
"query": "…",
"backend": "grounding | customSearch",
"answer": "synthesized answer (Grounding only)",
"totalResults": "123000",
"searchQueries": ["…"],
"items": [{ "title": "…", "link": "…", "displayLink": "…", "snippet": "…" }],
"warnings": []
}
```
In Grounding mode, most `options.*` parameters are *hints* Gemini may ignore — anything skipped is reported in `warnings`. `searchType: "image"` is rejected in Grounding mode (Custom Search only).
## Tool Details
### search
```json theme={null}
{
"name": "search",
"arguments": {
"q": "prisme.ai pricing",
"options": {
"dateRestrict": "m1",
"siteSearch": "prisme.ai",
"num": 5
}
}
}
```
| Parameter | Required | Description |
| ------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q` | Yes | Search query. Supports Google operators (`site:`, `intitle:`, `-exclude`, `"exact phrase"`). |
| `options.cx` | No | Programmable Search Engine id — overrides the tenant `cx` for this call (Custom Search only). |
| `options.num` | No | Number of results, 1-10 (Custom Search only). |
| `options.dateRestrict` | No | Restrict by date: `d{n}` / `w{n}` / `m{n}` / `y{n}` (e.g. `d7` = last 7 days). |
| `options.siteSearch` | No | Limit to a site (e.g. `wikipedia.org`); pair with `options.siteSearchFilter` (`i` include / `e` exclude). |
| `options.lr` / `options.gl` / `options.hl` | No | Language restriction (`lang_fr`), country boost (`fr`), interface language. |
| `options.searchType` | No | Set to `image` for an image search (**Custom Search only** — rejected in Grounding). Pair with `imgSize` / `imgType` / `imgColorType` / `imgDominantColor`. |
| `outputFormat` | No | `verbose` (default), `structured`, or `both`. |
## Workspace builder
**Goal:** install the connector in a workspace, configure the Google credential and the agent allowlist, and call `search` from your automations.
## Installation
1. Go to **Apps** in your workspace
2. Search for **Google Search** and install it
3. Open the **Configuration app** (the link auto-populated on install) to paste your Google credential, optionally set a Programmable Search Engine `cx`, and allow the agents that may call the connector
## Configuration
| Field | Description |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Configuration app** | Auto-populated on install — open this link to set the Google credential (API key or service-account JSON), choose the backend via `cx`, and manage the authorized-agents allowlist. |
The configuration app drives everything; the app instance itself has no per-field credential form. From it you provide a credential, which selects the auth mode:
| Credential | What you provide | Best for |
| ------------------------ | ---------------------------------------------------------------------------------- | --------------------------------------------- |
| **Google Cloud API key** | An `AIza…` key (sent as `X-goog-api-key`) | Simplest setup; interactive / low-volume use |
| **Service-account JSON** | A Google service-account key JSON (signed into a short-lived Bearer token, cached) | Server-to-server, no interactive key rotation |
The **backend** is selected automatically from the `cx` field:
| Backend | Selected when | Behavior |
| ----------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Gemini Grounding** (default) | `cx` is empty | Real google.com search of the whole web; returns a synthesized `answer` + cited sources. `options.*` are hints. |
| **Custom Search JSON API** (legacy) | `cx` is set (a Programmable Search Engine id) | Ranked organic results with rich filters (`num`, `dateRestrict`, `siteSearch`, language) and image search. Scoped to the **sites whitelisted in the PSE context** — never the open web (Google retired "Search the entire web" for new engines). |
Credentials are provisioned into the workspace's Secrets and resolved server-side. The agent allowlist (**Authorized agents**) gates which Agent Factory agents may call the MCP endpoint — see the *Agent builder* tab. A workspace with no credential of its own transparently falls back to the platform global key (if a *Platform admin* set one).
## Available Instructions
Every instruction resolves the credential from the workspace configuration.
### Web Search
| Instruction | Description | Returns |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `search` | Run a Google web search. `q` (required) is the query — combine Google operators inside it (`site:`, `intitle:`, `-exclude`, `"exact phrase"`). `options` carries fine-grained filters (date, site, language, file type, image search) honored by the Custom Search backend and treated as hints by Grounding. The backend is auto-selected from the tenant `cx`. | `{ query, backend, answer, totalResults, searchQueries, items: [{ title, link, displayLink, snippet }], warnings }` |
`Returns` shows the shape of the operation output. In Grounding mode `answer` is the synthesized response and `items` are the cited sources; in Custom Search mode `answer` is empty and `items` are the ranked organic results.
## DSUL Examples
**Grounded web search (default backend):**
```yaml theme={null}
- Google Search.search:
q: "latest Prisme.ai release notes"
output: result
# result.answer = synthesized answer, result.items = cited sources
```
**Recent news restricted to a site:**
```yaml theme={null}
- Google Search.search:
q: "AI regulation"
options:
dateRestrict: w2
siteSearch: lemonde.fr
siteSearchFilter: i
num: 5
output: news
```
**Image search (Custom Search backend — requires a `cx`):**
```yaml theme={null}
- Google Search.search:
q: "Eiffel tower at night"
options:
searchType: image
imgSize: large
imgType: photo
num: 8
output: images
```
**Find PDFs on a specific domain:**
```yaml theme={null}
- Google Search.search:
q: "annual report filetype:pdf site:berkshirehathaway.com"
options:
num: 10
output: docs
```
***
## Error Handling
| HTTP code | Meaning |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400` | Bad request — invalid parameters or a malformed query. |
| `401` | Authentication failed — the Google API key is missing, invalid or revoked. |
| `403` | Forbidden — the key lacks access, or the matching API is not enabled (Generative Language API for Grounding, Custom Search API for the legacy `cx` backend). |
| `404` | Not found — wrong endpoint or resource. |
| `429` | Rate limit / quota exceeded — back off and retry (the Gemini free tier is especially low). |
| `500` / `503` | Google service error — transient; retry shortly. |
### Common Issues
**"This agent is not authorized to use this connector"** — The calling agent is not in the allowlist. Open the configuration app → **Authorized agents** → tick this agent (or enable **Allow all agents**) and Save.
**"The calling agent could not be identified"** — The MCP capability *Scope* does not declare `agent_id`, so Agent Factory never injects the agent identity. Set the Scope to `context_id,agent_id,user_id` on the capability, then allow the agent in the config app.
**"The platform global Google key is not configured" / "No platform global Google key is configured"** — The workspace has no credential of its own and no platform global key is set. Paste a Google API key in the config app, or ask the platform administrator to set the global key on the core `google-search` workspace.
**"Google API credential is malformed"** — The pasted value is neither a valid `AIza…` API key nor a parseable service-account JSON. Re-copy the credential from the Google Cloud Console.
**Image search returns nothing / an error** — `searchType: image` only works on the **Custom Search** backend. Configure a Programmable Search Engine `cx` in the config app; in Grounding mode image search is rejected.
**Filters seem ignored** — In Grounding mode most `options.*` parameters (`num`, `dateRestrict`, `siteSearch`, …) are *hints* Gemini may not honor; check the `warnings` array in the structured output. Set a `cx` to switch to Custom Search, where filters are enforced.
## External Resources
Official reference for the Custom Search JSON API, query parameters and Programmable Search Engines.
How Gemini grounds answers with Google Search — the default backend of this connector.
Learn how Agent Factory agents consume MCP tools in Prisme.ai.