> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To act on Guild from an MCP client, connect to https://api.guild.ai/mcp (OAuth) or run `guild mcp` locally. Setup: https://docs.guild.ai/api-reference/mcp.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Manage Google Ads campaigns and budgets from Guild agents

> Connect Guild agents to Google Ads to run GAQL queries, adjust campaign and ad group statuses, update budgets and bids, and discover accessible accounts.

Integrations · Google Ads

A Guild agent reads Google Ads performance data and makes campaign, ad group, and budget changes on your behalf. Guild injects the API key server-side so agent code never sees the credential. Credential policies let you restrict which operations each agent can perform before any request reaches Google Ads.

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Google Ads.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Google Ads to your first agent.

## What the Google Ads integration exposes

The integration provides tools for account discovery, GAQL reporting, and mutations across campaigns, ad groups, ads, and budgets. Query tools accept any Google Ads Query Language statement and return performance and account data. Mutation tools update statuses, adjust bids in micros, and change daily budget amounts. Tools follow the google\_ads\_ naming prefix.

## How it works

**1. Open credentials in Guild**

Go to Access & setup > Credentials in Guild. Click Connect, select google-ads, and paste your key into the API Key field.

**2. Import and spread the tools**

Import GoogleAdsTools from the integration package and spread it into your agent's tools object. Use pick() to include only the tools your agent needs.

**3. Scope the credential**

By default a credential serves every workspace the account owns. You can scope it to one workspace, one member, or one agent from the credentials page or the installed agent's detail page.

## Why Google Ads access needs governing

Google Ads mutations are immediate and affect live spend. Guild's credential proxy enforces credential policies before any request reaches Google Ads, so you can write ALLOW and DENY rules that restrict agents to specific operations, such as read-only GAQL queries, without touching the credential itself. Rules can be scoped to individual agents or workspaces, so a reporting agent and a budget-management agent can share one credential with different permissions.

Guild stores the API key server-side and injects it at request time; agents never see it. Every request is auditable through Guild's standard run history. Restricting a workspace to its own credentials prevents agents in that workspace from using the organization's shared Google Ads credential.

## About the Google Ads integration

Agents can query Google Ads data using GAQL to retrieve performance and account information. They can adjust campaign and ad group statuses, update budgets and bids, and pause or enable individual ads. Account discovery lets agents list all accessible customer accounts. The integration is `guildai~google-ads`.

## Authentication

* **Type:** API key
* **Header:** Guild sends the key as a bearer token in the `Authorization` header

### Setup

**1. Connect Google Ads**

In Guild, go to **Access & setup > Credentials**, click **Connect**, select **google-ads**, and paste the key into **API Key**.

See [Credentials](https://docs.guild.ai/platform/credentials.md) for workspace, member, and agent-scoped credentials.

## Usage

```typescript theme={null}
import { GoogleAdsTools } from "@guildai-services/guildai~google-ads"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  systemPrompt: "You work with Google Ads.",
  tools: { ...GoogleAdsTools },
})
```

### Selecting specific tools

Tools are named with the `google_ads_` prefix. Use [`pick()`](https://docs.guild.ai/sdk/tools#selecting-specific-tools) to include only what your agent needs.

## Tools

Tools in the latest published version of `guildai~google-ads`:

| Tool | What it does |
| - | - |
| `google_ads_list_accessible_customers` | Returns resource names such as customers/1234567890. |
| `google_ads_mutate_ad_group_ads` | Pause, enable, or remove an ad. |
| `google_ads_mutate_ad_group_criteria` | Keyword and criterion bids. updateMask cpc\_bid\_micros with update.cpcBidMicros. |
| `google_ads_mutate_ad_groups` | Pause or enable an ad group, or set cpcBidMicros. updateMask examples: status, cpc\_bid\_micros. |
| `google_ads_mutate_campaign_budgets` | Changes daily budget. amountMicros is in account currency micros (1 unit = 1000000). updateMask uses snake\_case, for example amount\_micros. |
| `google_ads_mutate_campaigns` | Status changes use updateMask status and update.status ENABLED or PAUSED. remove takes the campaign resource name and sets status REMOVED. |
| `google_ads_search_google_ads` | One Google Ads Query Language query. |
| `google_ads_search_google_ads_stream` | Same queries as search\_google\_ads. |

## Frequently asked questions

> [accordion] Can I limit an agent to only reading Google Ads data and not making changes?
>
> Yes. Write a credential policy with DENY rules on the mutate operations, or an ALLOW rule scoped to google\_ads\_search\_google\_ads and google\_ads\_search\_google\_ads\_stream only. The credential proxy blocks any other operation before it reaches Google Ads.

> [accordion] Does the Google Ads integration support webhook events?
>
> No. The catalog entry for guildai\~google-ads lists no webhook events, so the integration does not receive push notifications from Google Ads.

> [accordion] How do I give one agent its own Google Ads credential?
>
> Open the installed agent's page in the workspace, choose Dedicated to this agent, and paste the API key. That credential serves only that agent and does not affect other agents or workspaces.

> [accordion] What unit does the integration use for budgets and bids?
>
> Budget amounts use amountMicros in account currency micros, where one currency unit equals 1,000,000 micros. Bid updates use cpcBidMicros on the same scale.

## Put a governed agent on Google Ads this week

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Google Ads.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Google Ads to your first agent.

## Related

**Also runs on Guild:** [Affinity](https://docs.guild.ai/integrations/affinity-openapi.md) · [Attio](https://docs.guild.ai/integrations/attio.md) · [Brex](https://docs.guild.ai/integrations/brex-openapi.md) · [Gong](https://docs.guild.ai/integrations/gong-openapi.md)

**Read:** Docs: [Credential policies](https://docs.guild.ai/platform/credential-policies.md) · [Credentials](https://docs.guild.ai/platform/credentials.md) · [Tools in agents](https://docs.guild.ai/sdk/tools.md)
