Google Search

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.

Web search as a tool

A single search tool gives agents fresh, post-cutoff web information — news, prices, schedules, official docs, product specs — instead of guessing.

Grounded answers

The default Gemini Grounding backend returns a synthesized answer plus cited sources, rendered as clickable source cards in the chat.

Filtered & image search

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.

Agent builder

You build agents in Agent Factory and want them to search the web. → Agent builder tab.

Platform admin

You run the platform and set up a shared Google Search key once for everyone. → Platform admin setup accordion below.

Workspace builder

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. 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).

Platform admin (Governance) — one-time platform setup

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

Enable the right API in the Cloud project

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, 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).

Get a Google credential

In the Google Cloud Console, 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.

Enter the key through the core workspace's config app

Open the central google-search workspace and launch its Configuration app maintainer view — <studio>/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.

Open AI Governance > Capabilities

Create (or edit) the Google Search capability.

Point it at the MCP endpoint

Set the capability’s MCP server URL to the connector’s MCP Endpoint, and set its Scope to:

context_id,agent_id,user_id

The agent_id in the scope is what lets the connector identify the calling agent.

Make it available to agent builders

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.

Smoke-test

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 (Agent Factory)
Workspace builder (DSUL)

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 your agent in Agent Factory

Open the agent you want to extend and go to its capabilities / tools.

Add the Google Search capability

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.

Use it

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.

Install and configure the connector in your workspace

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.

Allowlist your agent

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.

Add the MCP capability to your agent

In your agent, add a capability pointing at your workspace’s MCP Endpoint URL, and set its Scope to:

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:

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:

{
  "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

{
  "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

Go to Apps in your workspace
Search for Google Search and install it
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):

- 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:

- 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):

- 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:

- 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

Custom Search JSON API

Official reference for the Custom Search JSON API, query parameters and Programmable Search Engines.

Grounding with Google Search

How Gemini grounds answers with Google Search — the default backend of this connector.

Tool Agents

Learn how Agent Factory agents consume MCP tools in Prisme.ai.

Overview

App Store

Web search as a tool

Grounded answers

Filtered & image search

Who is this for?

Agent builder

Platform admin

Workspace builder

Prerequisites (Google side)

1. Configure the shared platform key

2. Declare the capability in AI Governance

Agent builder

Option A — Enable the shared capability from the catalog

Option B — Run it from your own workspace (recommended)

Brief the agent in its system prompt

Available Tools

Output Formats

Tool Details

search

Workspace builder

Installation

Configuration

Available Instructions

Web Search

DSUL Examples

Error Handling

Common Issues

External Resources

Custom Search JSON API

Grounding with Google Search

Tool Agents

Web search as a tool

Grounded answers

Filtered & image search

​Who is this for?

Agent builder

Platform admin

Workspace builder

​Prerequisites (Google side)

​1. Configure the shared platform key

​2. Declare the capability in AI Governance

​Agent builder

​Option A — Enable the shared capability from the catalog

​Option B — Run it from your own workspace (recommended)

​Brief the agent in its system prompt

​Available Tools

​Output Formats

​Tool Details

​search

​Workspace builder

​Installation

​Configuration

​Available Instructions

​Web Search

​DSUL Examples

​Error Handling

​Common Issues

​External Resources

Custom Search JSON API

Grounding with Google Search

Tool Agents

Who is this for?

Prerequisites (Google side)

1. Configure the shared platform key

2. Declare the capability in AI Governance

Agent builder

Option A — Enable the shared capability from the catalog

Option B — Run it from your own workspace (recommended)

Brief the agent in its system prompt

Available Tools

Output Formats

Tool Details

search

Workspace builder

Installation

Configuration

Available Instructions

Web Search

DSUL Examples

Error Handling

Common Issues

External Resources