Google-Ads
The Google-Ads agent connector is a Python package that equips AI agents to interact with Google-Ads through strongly typed, well-documented tools. It's ready to use directly in your Python app, in an agent framework, or exposed through an MCP.
Google Ads API connector for accessing advertising account data including campaigns, ad groups, ads, and labels. This connector uses the Google Ads Query Language (GAQL) via the REST search endpoint to retrieve structured advertising data. Requires OAuth2 credentials and a Google Ads developer token for authentication. All data retrieval is read-only.
Example prompts
The Google-Ads connector is optimized to handle prompts like these.
- List all accessible Google Ads customer accounts
- Show me all campaigns and their statuses
- List all ad groups across my campaigns
- What ads are running in my ad groups?
- Show me campaign labels
- List all ad group labels
- What labels are applied to my ads?
- Pause campaign 'Summer Sale 2025'
- Enable the ad group 'Brand Keywords'
- Create a label called 'High Priority'
- Apply the 'Q4 Campaigns' label to my search campaign
- Update the name of campaign 123456 to 'Winter Promo'
- Which campaigns have the highest cost this month?
- Show me all paused campaigns
- Find ad groups with the most impressions
- What are my top performing ads by click-through rate?
- Show campaigns with budget over $100 per day
Unsupported prompts
The Google-Ads connector isn't currently able to handle prompts like these.
- Create a new campaign
- Delete an ad
- Delete a campaign
- Delete a label
Entities and actions
This connector supports the following entities and actions. For more details, see this connector's full reference documentation.
| Entity | Actions |
|---|---|
| Accessible Customers | List |
| Accounts | List, Context Store Search |
| Campaigns | List, Update, Context Store Search |
| Ad Groups | List, Update, Context Store Search |
| Ad Group Ads | List, Context Store Search |
| Campaign Labels | List, Create, Context Store Search |
| Ad Group Labels | List, Create, Context Store Search |
| Ad Group Ad Labels | List, Context Store Search |
| Labels | Create |
Google-Ads API docs
See the official Google-Ads API reference.
SDK installation
uv pip install airbyte-agent-sdk
SDK usage
Connectors can run in hosted or open source mode.
Hosted
In hosted mode, API credentials are stored securely in Airbyte Agents. You provide your Airbyte credentials instead.
If your Airbyte client can access multiple organizations, also set organization_id.
This example assumes you've already authenticated your connector with Airbyte. See Authentication to learn more about authenticating. If you need a step-by-step guide, see the hosted execution tutorial.
The connect() factory returns a fully typed GoogleAdsConnector and reads AIRBYTE_CLIENT_ID / AIRBYTE_CLIENT_SECRET from the environment:
- Pydantic AI
- LangChain
- OpenAI Agents
- FastMCP
Pydantic AI
from pydantic_ai import Agent
from airbyte_agent_sdk import connect
from airbyte_agent_sdk.connectors.google_ads import GoogleAdsConnector
connector = connect("google-ads", workspace_name="<your_workspace_name>")
agent = Agent("openai:gpt-4o")
@agent.tool_plain
@GoogleAdsConnector.tool_utils
async def google_ads_execute(entity: str, action: str, params: dict | None = None):
return await connector.execute(entity, action, params or {})
LangChain
from langchain_core.tools import tool
from airbyte_agent_sdk import connect
from airbyte_agent_sdk.connectors.google_ads import GoogleAdsConnector
connector = connect("google-ads", workspace_name="<your_workspace_name>")
@tool
@GoogleAdsConnector.tool_utils
async def google_ads_execute(entity: str, action: str, params: dict | None = None):
"""Execute Google-Ads connector operations."""
result = await connector.execute(entity, action, params or {})
# connector.execute returns a Pydantic envelope for typed actions; fall back to raw data otherwise.
return result.model_dump(mode="json") if hasattr(result, "model_dump") else result
OpenAI Agents
from agents import Agent, function_tool
from airbyte_agent_sdk import connect
from airbyte_agent_sdk.connectors.google_ads import GoogleAdsConnector
connector = connect("google-ads", workspace_name="<your_workspace_name>")
# strict_mode=False because `params: dict` is permissive and the default strict
# JSON schema rejects objects with additionalProperties.
@function_tool(strict_mode=False)
@GoogleAdsConnector.tool_utils(framework="openai_agents")
async def google_ads_execute(entity: str, action: str, params: dict | None = None):
"""Execute Google-Ads connector operations."""
result = await connector.execute(entity, action, params or {})
return result.model_dump(mode="json") if hasattr(result, "model_dump") else result
agent = Agent(name="Google-Ads Assistant", tools=[google_ads_execute])
FastMCP
from fastmcp import FastMCP
from airbyte_agent_sdk import connect
from airbyte_agent_sdk.connectors.google_ads import GoogleAdsConnector
connector = connect("google-ads", workspace_name="<your_workspace_name>")
mcp = FastMCP("Google-Ads Agent")
@mcp.tool
@GoogleAdsConnector.tool_utils
async def google_ads_execute(entity: str, action: str, params: dict | None = None):
"""Execute Google-Ads connector operations."""
result = await connector.execute(entity, action, params or {})
return result.model_dump(mode="json") if hasattr(result, "model_dump") else result
Or pass credentials explicitly (equivalent, useful when you're not loading them from the environment):
- Pydantic AI
- LangChain
- OpenAI Agents
- FastMCP
Pydantic AI
from pydantic_ai import Agent
from airbyte_agent_sdk.connectors.google_ads import GoogleAdsConnector
from airbyte_agent_sdk.types import AirbyteAuthConfig
connector = GoogleAdsConnector(
auth_config=AirbyteAuthConfig(
workspace_name="<your_workspace_name>",
organization_id="<your_organization_id>", # Optional for multi-org clients
airbyte_client_id="<your-client-id>",
airbyte_client_secret="<your-client-secret>"
)
)
agent = Agent("openai:gpt-4o")
@agent.tool_plain
@GoogleAdsConnector.tool_utils
async def google_ads_execute(entity: str, action: str, params: dict | None = None):
return await connector.execute(entity, action, params or {})
LangChain
from langchain_core.tools import tool
from airbyte_agent_sdk.connectors.google_ads import GoogleAdsConnector
from airbyte_agent_sdk.types import AirbyteAuthConfig
connector = GoogleAdsConnector(
auth_config=AirbyteAuthConfig(
workspace_name="<your_workspace_name>",
organization_id="<your_organization_id>", # Optional for multi-org clients
airbyte_client_id="<your-client-id>",
airbyte_client_secret="<your-client-secret>"
)
)
@tool
@GoogleAdsConnector.tool_utils
async def google_ads_execute(entity: str, action: str, params: dict | None = None):
"""Execute Google-Ads connector operations."""
result = await connector.execute(entity, action, params or {})
# connector.execute returns a Pydantic envelope for typed actions; fall back to raw data otherwise.
return result.model_dump(mode="json") if hasattr(result, "model_dump") else result
OpenAI Agents
from agents import Agent, function_tool
from airbyte_agent_sdk.connectors.google_ads import GoogleAdsConnector
from airbyte_agent_sdk.types import AirbyteAuthConfig
connector = GoogleAdsConnector(
auth_config=AirbyteAuthConfig(
workspace_name="<your_workspace_name>",
organization_id="<your_organization_id>", # Optional for multi-org clients
airbyte_client_id="<your-client-id>",
airbyte_client_secret="<your-client-secret>"
)
)
# strict_mode=False because `params: dict` is permissive and the default strict
# JSON schema rejects objects with additionalProperties.
@function_tool(strict_mode=False)
@GoogleAdsConnector.tool_utils(framework="openai_agents")
async def google_ads_execute(entity: str, action: str, params: dict | None = None):
"""Execute Google-Ads connector operations."""
result = await connector.execute(entity, action, params or {})
return result.model_dump(mode="json") if hasattr(result, "model_dump") else result
agent = Agent(name="Google-Ads Assistant", tools=[google_ads_execute])
FastMCP
from fastmcp import FastMCP
from airbyte_agent_sdk.connectors.google_ads import GoogleAdsConnector
from airbyte_agent_sdk.types import AirbyteAuthConfig
connector = GoogleAdsConnector(
auth_config=AirbyteAuthConfig(
workspace_name="<your_workspace_name>",
organization_id="<your_organization_id>", # Optional for multi-org clients
airbyte_client_id="<your-client-id>",
airbyte_client_secret="<your-client-secret>"
)
)
mcp = FastMCP("Google-Ads Agent")
@mcp.tool
@GoogleAdsConnector.tool_utils
async def google_ads_execute(entity: str, action: str, params: dict | None = None):
"""Execute Google-Ads connector operations."""
result = await connector.execute(entity, action, params or {})
return result.model_dump(mode="json") if hasattr(result, "model_dump") else result
Open source
In open source mode, you provide API credentials directly to the connector.
- Pydantic AI
- LangChain
- OpenAI Agents
- FastMCP
Pydantic AI
from pydantic_ai import Agent
from airbyte_agent_sdk.connectors.google_ads import GoogleAdsConnector
from airbyte_agent_sdk.connectors.google_ads.models import GoogleAdsAuthConfig
connector = GoogleAdsConnector(
auth_config=GoogleAdsAuthConfig(
client_id="<OAuth2 client ID from Google Cloud Console>",
client_secret="<OAuth2 client secret from Google Cloud Console>",
refresh_token="<OAuth2 refresh token>",
developer_token="<Google Ads API developer token>"
)
)
agent = Agent("openai:gpt-4o")
@agent.tool_plain
@GoogleAdsConnector.tool_utils
async def google_ads_execute(entity: str, action: str, params: dict | None = None):
return await connector.execute(entity, action, params or {})
LangChain
from langchain_core.tools import tool
from airbyte_agent_sdk.connectors.google_ads import GoogleAdsConnector
from airbyte_agent_sdk.connectors.google_ads.models import GoogleAdsAuthConfig
connector = GoogleAdsConnector(
auth_config=GoogleAdsAuthConfig(
client_id="<OAuth2 client ID from Google Cloud Console>",
client_secret="<OAuth2 client secret from Google Cloud Console>",
refresh_token="<OAuth2 refresh token>",
developer_token="<Google Ads API developer token>"
)
)
@tool
@GoogleAdsConnector.tool_utils
async def google_ads_execute(entity: str, action: str, params: dict | None = None):
"""Execute Google-Ads connector operations."""
result = await connector.execute(entity, action, params or {})
# connector.execute returns a Pydantic envelope for typed actions; fall back to raw data otherwise.
return result.model_dump(mode="json") if hasattr(result, "model_dump") else result
OpenAI Agents
from agents import Agent, function_tool
from airbyte_agent_sdk.connectors.google_ads import GoogleAdsConnector
from airbyte_agent_sdk.connectors.google_ads.models import GoogleAdsAuthConfig
connector = GoogleAdsConnector(
auth_config=GoogleAdsAuthConfig(
client_id="<OAuth2 client ID from Google Cloud Console>",
client_secret="<OAuth2 client secret from Google Cloud Console>",
refresh_token="<OAuth2 refresh token>",
developer_token="<Google Ads API developer token>"
)
)
# strict_mode=False because `params: dict` is permissive and the default strict
# JSON schema rejects objects with additionalProperties.
@function_tool(strict_mode=False)
@GoogleAdsConnector.tool_utils(framework="openai_agents")
async def google_ads_execute(entity: str, action: str, params: dict | None = None):
"""Execute Google-Ads connector operations."""
result = await connector.execute(entity, action, params or {})
return result.model_dump(mode="json") if hasattr(result, "model_dump") else result
agent = Agent(name="Google-Ads Assistant", tools=[google_ads_execute])
FastMCP
from fastmcp import FastMCP
from airbyte_agent_sdk.connectors.google_ads import GoogleAdsConnector
from airbyte_agent_sdk.connectors.google_ads.models import GoogleAdsAuthConfig
connector = GoogleAdsConnector(
auth_config=GoogleAdsAuthConfig(
client_id="<OAuth2 client ID from Google Cloud Console>",
client_secret="<OAuth2 client secret from Google Cloud Console>",
refresh_token="<OAuth2 refresh token>",
developer_token="<Google Ads API developer token>"
)
)
mcp = FastMCP("Google-Ads Agent")
@mcp.tool
@GoogleAdsConnector.tool_utils
async def google_ads_execute(entity: str, action: str, params: dict | None = None):
"""Execute Google-Ads connector operations."""
result = await connector.execute(entity, action, params or {})
return result.model_dump(mode="json") if hasattr(result, "model_dump") else result
Authentication
For all authentication options, see the connector's authentication documentation.
Version information
Connector version: 1.0.9