> For the complete documentation index, see [llms.txt](https://whitepaper.aitech.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whitepaper.aitech.io/agentforge/tools/google_search.md).

# google\_search

[Google Search](https://www.google.com/) is the world’s most widely used search engine. This block lets your agents fetch live results via Google’s Custom Search JSON API (often called the Google Search API) and use them inside workflows for research, fact-checking, and data gathering.

### Setup (one-time)

Follow these steps to get a **Search Engine ID (`searchEngineId` / `cx`)** and an **API key**:

{% stepper %}
{% step %}

#### Create a Programmable Search Engine (CSE)

1. Open **Programmable Search Engine**: [programmablesearchengine.google.com/about](https://programmablesearchengine.google.com/about/)
2. Click **Get started** → create a new search engine.
3. Choose what to search:
   * **Entire web** (recommended for broad queries), or
   * **Specific sites** (restrict to one or more domains).
4. After creating, go to your CSE **Control Panel** → copy the **Search engine ID** (also shown as **cx**).\
   You’ll pass this as `searchEngineId` to the tool.
   {% endstep %}

{% step %}

#### Enable the Google Search API

1. In your Google Cloud project, enable **Custom Search JSON API** (sometimes listed as **google\_search\_api** or **Custom Search API**).
2. Ensure **Billing** is enabled on the project (Google may require billing for sustained usage or higher quotas).
   {% endstep %}

{% step %}

#### Create an API Key (Google Cloud)

1. In the same Google Cloud project (you can reuse a project you already use for **BigQuery**):
   * Go to **APIs & Services → Credentials**.
   * Click **Create credentials → API key**.
2. Copy the generated **API key** and store it securely.
3. (Optional but recommended) **Restrict** the key:
   * **API restrictions:** limit to the **Custom Search API**.
   * **Application restrictions:** HTTP referrers or IPs as appropriate.
     {% endstep %}
     {% endstepper %}

### Usage Instructions

This tool queries Google via the **Custom Search JSON API**. You’ll provide:

* `query` — the search text
* `searchEngineId` — your CSE ID (cx)
* `apiKey` — your Google API key
* `num` — number of results (1–10, default 10)

### Tools

#### `google_search`

Search the web with the Custom Search API.

**Input**

| Parameter        | Type   | Required | Description                                        |
| ---------------- | ------ | -------- | -------------------------------------------------- |
| `query`          | string | Yes      | The search query to execute                        |
| `searchEngineId` | string | Yes      | Your CSE ID (aka `cx`)                             |
| `num`            | string | No       | Number of results to return (default: 10, max: 10) |
| `apiKey`         | string | Yes      | Google API key                                     |

**Output**

| Parameter           | Type | Description         |
| ------------------- | ---- | ------------------- |
| `items`             | json | Search result items |
| `searchInformation` | json | Search metadata     |

### Troubleshooting

* **403 / Daily limit exceeded**\
  You’ve hit your free quota or billing isn’t enabled. Enable billing or raise quota in your Cloud project.
* **400 / Invalid `cx` or `key`**\
  Verify your **Search engine ID** and **API key**; ensure the key is restricted to the correct API.
* **Empty results with broad queries**\
  Check your CSE settings: if restricted to specific sites, switch to **Search the entire web** or add more sites.
* **`num` > 10 ignored**\
  The API caps each call at 10 results; paginate if you need more.
* **Referrer/IP restrictions blocking calls**\
  If you restricted the key, confirm your requests match the allowed referrers or IP addresses.

### Notes

* **Category:** `tools`
* **Type:** `google_search`
* Uses Google’s **Custom Search JSON API** behind the scenes.
* Requires a **Programmable Search Engine (CSE)** and an **API key** created in your Google Cloud project (a project that also hosts **BigQuery** is fine).