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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://whitepaper.aitech.io/agentforge/tools/google_search.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.