Google Ads AI Automation은 Google Ads 계정을 읽고 광고를 점검·계획하는 오픈소스 도구다. Google Ad Grants를 쓰는 비영리단체에 특히 초점을 맞췄으며, 기본값은 읽기 전용이다. 광고 계정에 변경을 적용하려면 사용자가 직접 실시간 쓰기 모드로 전환해야 한다.
이 프로젝트는 버전 0.1.0 알파다. Python 3.11 이상에서 로컬 웹 대시보드와 ads-agents 명령줄 인터페이스(CLI)를 제공한다. 에이전트는 Python 규칙과 휴리스틱으로 로컬에서 작동하며, 계정 데이터는 공식 Google Ads API로 읽어 reports/에 저장한다. 제작자는 Google과 제휴하거나 Google의 보증을 받은 프로젝트가 아니라고 밝혔다.
무엇을 하는 도구인가
광고 운영 업무를 전문 역할별 에이전트에 나눠 맡긴다. 전환 추적과 비용을 점검하고, 경쟁 상황과 검색 추세를 살피며, 캠페인 구조·키워드·광고 문안·예산 계획을 제안한다. 결과는 JSON이나 Markdown 보고서로 컴퓨터에 저장되므로 사용자가 검토하고 결정할 수 있다.
전체 에이전트는 41개다. ‘Revenue Growth OS’ 플랫폼 에이전트 31개는 시장 정보, 전략, 광고 소재, 고객 획득, 전환율 최적화, 매출·분석을 맡는다. Google Ads 운영 에이전트 10개는 sense → compete → structure → create → allocate → guard 순서의 일일 업무를 다룬다. 수치는 프로젝트의 실시간 에이전트 목록과 docs/AGENTS.md에 근거한다고 프로젝트는 설명한다.
플랫폼 에이전트 31개는 6개 계층으로 구성된다.
- 시장 정보(6개): 경쟁사 정보, 검색 기회, 검색 의도 분석, 앱스토어·플레이 정보, 규제 동향, 검색 결과·광고 투명성
- 전략(4개): CEO AI, 전략 엔진, 포트폴리오 에이전트, 실험 우선순위 지정
- 크리에이티브 스튜디오(6개): Creative Lab, Copy AI, Image AI, Video AI, Localization AI, Brand & Policy Gate
- 고객 획득(5개): Google Ads CONTROLLED_LIVE, SEO Agent, ASO Agent, Email / Content Agent, Demand Gen / YouTube
- 전환 최적화(5개): CRO Funnel Agent, Landing AI, Onboarding Agent, Paywall / Pricing Agent, Activation Chat Agent
- 매출·분석(5개): Revenue Agent, Experiment Agent, Analytics / Cohort, Measurement / Data Manager, Rollback / Kill-switch Guardian
Google Ads 운영 에이전트 10개는 다음과 같다.
- MeasurementAgent: 전환 추적과 결과당 비용 상태를 점검한다.
- CompetitorAgent: 경쟁사와 경매 압력에 관한 정보를 정리한다.
- TrendAgent: 수요와 추세를 갱신한다.
- StrategyAgent: 포트폴리오와 캠페인 구조를 제안한다.
- CampaignBuilderAgent: 캠페인과 광고그룹 초안을 만든다.
- KeywordAgent: 키워드와 제외 키워드를 제안하며 Ad Grants 규칙을 고려한다.
- AssetAgent: 광고 문안, 사이트링크, 콜아웃, 구조화된 스니펫 묶음을 만든다.
- BudgetAgent: Ad Grants 또는 유료 예산에 맞춰 지출 속도를 관리한다.
- PolicyQAAgent: 게시 전 브랜드·정책을 점검한다.
- WatchdogAgent: 광고 게재, 변동, 긴급 정지 장치를 감시한다.
각 플랫폼 에이전트에는 수행 가능한 작업을 제한하는 변경 정책이 있다. never는 조언만 하고, draft_only는 보고서만 작성하며 광고 계정을 건드리지 않는다. approval은 사람의 승인이 필요하고, controlled는 CONTROLLED_LIVE 모드에서 제한된 실시간 변경만 허용한다.
기본은 읽기 전용
READ_ONLY 모드에서는 Google Ads에 쓰는 모든 작업을 차단한다. 도구는 계정을 읽고 감사 결과, 일일 계획, KPI 대시보드 파일을 만든다. 사용자가 원하면 CONTROLLED_LIVE에서 제한된 변경을 허용할 수 있고, 더 폭넓은 자동화는 Guardian을 켠 AUTONOMOUS_LIVE 모드에서 제공한다.
예산 변경에는 기본적으로 한 번에 최대 10%라는 제한이 있다. 15%를 넘는 변경은 사람의 승인이 필요하며, 예산 이동 사이에는 3일의 대기 시간이 적용된다. 계정 전체의 일일 지출 한도도 둔다. 기본값은 하루 329달러다. 실시간 모드에서도 쓰기 작업은 승인된 범위와 한도 안에서만 허용된다. 설정값을 READ_ONLY로 바꾸면 모든 쓰기를 즉시 다시 차단하는 긴급 정지 장치로 작동한다.
Google의 자동 추천은 그대로 적용하지 않고 검토할 증거로 취급한다. 전환 수치를 부풀릴 수 있는 스크롤·클릭 같은 미세 이벤트를 찾아 정리 계획을 제안하며, Google 변경 이력을 가져와 중요한 수정 사항을 설명할 수 있도록 한다. 보고서는 reports/ 아래에 저장돼 읽고 비교하거나 보관할 수 있다.
비영리단체와 Ad Grants
Google Ad Grants는 비영리단체에 제공되는 월 약 10,000달러 규모의 무료 광고 프로그램이다. 프로젝트 설명에 따르면 Ad Grants 계정은 규칙이 더 엄격하며, 위반하면 계정이 정지될 수 있다. 이 도구는 다음 점검 기능을 제공한다.
- 광고와 사이트링크가 승인받은 소유 웹사이트로만 연결되도록 확인한다. 앱스토어, Google Play, YouTube, 소셜 링크는 차단하며
ads-agents platform grant-scrub-domains로 실행한다. ads-agents platform grant-compliance는 월간 클릭률(CTR) 5% 규칙, 품질평가점수 1~2인 키워드 금지, 캠페인마다 광고그룹 2개 이상과 사이트링크 2개 이상, 매월 의미 있는 전환 1회 이상, 전환 기반 스마트 자동 입찰을 점검한다.ADS_MAX_ACCOUNT_DAILY_BUDGET계정 전체 일일 한도 아래에서 월간 보조금에 맞춰 지출 속도를 조정한다.- 계정이 일시중지된 경우
ads-agents platform grant-reactivate가 수정 목록과 재활성화 요청서를 만든다. - 광고 문안은 게시 전에 브랜드·정책 게이트에서 점검한다. Google 자동 추천도 맹목적으로 적용하지 않는다.
일반 유료 Google Ads 계정에도 사용할 수 있다. 비영리단체는 Ad Grants 모드를 켜 추가 점검을 이용할 수 있다.
설치와 시작
Python 3.11 이상과 터미널이 필요하다. 저장소는 GitHub 프로젝트 페이지에서 확인할 수 있다. 아래 설치 절차는 프로젝트가 제시한 5분 빠른 시작이다.
git clone https://github.com/aipsyhelp/ai_ads_google.git && cd ai_ads_google
python3.11 -m venv .venv
source .venv/bin/activate # Windows: .venv\\Scripts\\activate
pip install -e ".[dev]"
Google 계정 정보 없이 로컬에서 먼저 시험할 수 있다. 예제 설정을 복사하고 에이전트 목록과 샘플 캠페인 계획을 확인한다.
python scripts/init_project.py --non-interactive # copies the example config (local, gitignored)
export PYTHONPATH=src # Windows PowerShell: $env:PYTHONPATH="src"
python -m ads_ai_agents.cli platform agents # list the 31 platform agents
python -m ads_ai_agents.cli controlled-live mode # confirm you are in READ_ONLY
python -m ads_ai_agents.cli plan samples/grant_search_campaign.example.json # 10-agent plan for a sample campaign
설치 후에는 같은 기능을 ads-agents … 명령으로 실행할 수 있다. Windows에서는 가상환경 경로와 PYTHONPATH 설정이 다르므로 위 명령의 주석을 참고한다.
자신의 계정을 연결하려면 ads-agents ui를 실행해 대시보드에서 설정하거나 python scripts/init_project.py로 대화형 설정 마법사를 시작한다. 마법사는 토큰, 계정 ID, 브랜드, 도메인을 묻고 서비스 계정 JSON 파일 경로를 받는다. 자격 증명을 설정한 다음 연결을 확인하고 읽기 전용 감사를 실행하는 명령은 다음과 같다.
ads-agents ui # easiest: fill in the dashboard at http://127.0.0.1:8765
# or, in the terminal:
python scripts/init_project.py # interactive wizard: tokens, account IDs, brand, domains
# Put your service-account JSON file into secrets/ (the wizard asks for its path)
python -m ads_ai_agents.cli ping # checks that your credentials work (read-only)
python -m ads_ai_agents.cli audit # full read-only account snapshot → reports/YYYY-MM-DD/
python -m ads_ai_agents.cli dashboard # KPI dashboard + tracking spec from the latest audit
ping은 자격 증명 작동 여부를 읽기 전용으로 확인한다. audit은 전체 계정 스냅샷을 reports/YYYY-MM-DD/에 저장한다. dashboard는 최근 감사 결과에서 KPI 대시보드와 추적 명세를 만든다. 전체 설정 안내는 docs/SETUP.md에 있다.
대시보드와 설정
ads-agents ui 또는 PYTHONPATH=src python -m ads_ai_agents.cli ui를 실행하면 http://127.0.0.1:8765/에서 로컬 웹 대시보드가 열린다. 대시보드는 127.0.0.1에서만 연결을 받고, 요청마다 실행별 토큰이 필요하다. 온라인에 호스팅되지 않으며 모든 인터페이스는 사용자 컴퓨터에서 작동한다.
대시보드에는 자동화 모드와 읽기 전용 연결 확인, 에이전트가 실제로 불러오는 설정을 보여주는 개요가 있다. 설정 화면에서 조직·사업체, 계정 및 자격 증명, 웹사이트·도메인, 지역 설정, 안전 설정과 자동화 모드, 계정 ID를 관리한다. Google Tags 화면에서는 Google Tag Manager(GTM)나 Google 태그 코드를 붙여 넣고 연결·계획·적용·검증 순서로 작업한다. READ_ONLY에서 적용은 실제 게시가 아닌 모의 실행이다. 실행 화면에서는 샘플 캠페인에 대한 10개 에이전트의 계획이나 계정 감사를 읽기 전용으로 실행한다. 보고서 화면은 efficiency_dashboard.json과 최근 감사 요약을 보여주며, 에이전트 화면은 41개 전체 목록을 보여준다.
ads-agents dashboard와 ads-agents ui는 서로 다른 기능이다. 전자는 보고서 생성 명령으로 efficiency_dashboard.json과 TRACKING.md를 reports/YYYY-MM-DD/에 쓴다. 후자는 설정과 보고서를 보여주는 웹 대시보드다.
조직 유형은 사업체 또는 비영리단체로 고를 수 있다. 조직·제품·서비스·활동을 설명하고 웹사이트를 입력할 수 있으며, 주요 제공 서비스나 제품은 선택 항목이다. 비영리단체는 여기서 Ad Grants 모드를 켤 수 있다. 조직 설명과 웹사이트는 계획 수립, 광고 소재 작성, 경쟁사 탐색에 활용된다.
Google Tags 설정에서는 GTM 또는 Google 태그 코드나 ID를 입력한다. 표시된 서비스 계정 이메일에 GTM 게시 권한을 부여해야 한다. 에이전트는 Consent Mode, GA4, Conversion Linker, 주요 이벤트, Ads 전환 태그 계획을 만들고, 사용자가 확인한 뒤 실시간 모드에서 새 GTM 버전으로 게시할 수 있다. READ_ONLY에서는 모의 실행만 한다. 웹사이트에서 아직 GTM 컨테이너를 불러오지 않는다면 컨테이너 스니펫을 한 번 설치하거나 CMS의 GTM 플러그인을 사용해야 한다. 그 뒤 태그 변경을 자동화할 수 있다.
비밀 정보는 대시보드에서 다시 표시되지 않는 쓰기 전용 방식으로 처리된다. 실시간 모드로 바꾸려면 ENABLE LIVE WRITES라는 문구를 직접 입력해야 한다. 설정은 .env, config/product_facts.json, config/tenant.json, config/account_ids.json 또는 secrets/에 저장되며 모두 Git에서 제외된다. 대시보드와 설정 마법사는 같은 파일을 사용한다. 자세한 항목별 설정은 docs/DASHBOARD.md를 참고한다.
계정 연결에 필요한 값과 저장 위치는 다음과 같다.
- 개발자 토큰:
.env의GOOGLE_ADS_DEVELOPER_TOKEN. Google Ads의 도구 메뉴에서 API Center를 통해 발급한다. 읽기 전용 사용에는 테스트 토큰도 가능하다. - 관리자(MCC) 계정 ID:
.env의GOOGLE_ADS_LOGIN_CUSTOMER_ID. 숫자만 입력하며 하이픈은 넣지 않는다. - 고객 계정 ID:
.env의GOOGLE_ADS_CUSTOMER_ID. 캠페인을 소유한 계정의 ID이며 숫자만 입력한다. - 서비스 계정 키:
secrets/*.json과.env의GOOGLE_ADS_SERVICE_ACCOUNT_JSON. 권장 인증 방식이며docs/TOKENS_AND_ACCESS.md에 안내가 있다. - 브랜드, 랜딩 페이지, 승인된 Grant 도메인:
config/product_facts.json.config/product_facts.example.json에서 복사한다. - 조직 유형·설명·웹사이트·주요 제공 내용과 Google 태그 ID:
config/product_facts.json의organization,main_offering,tracking항목. 대시보드에서 설정하는 방법이 가장 간단하다. - 시간대와 Grants 사용 여부:
config/tenant.json.config/tenant.example.json에서 복사한다. - 집중 대상 도시와 미지원 호스트: 선택 항목이다.
config/product_facts.json의geo.focus_cities,grant_destinations.unserved_hosts에 저장하며 도시별 규칙과 Grant 도메인 검사에 쓰인다. - 포트폴리오·예산·캠페인·소재 등 운영 스크립트용 리소스 ID: 선택 항목인
config/account_ids.json. 예제의 가짜 ID를 복사해 사용할 수 있으며,examples/ops/의 스크립트 일부와 일부 복구 계획 도구만 사용한다. - 안전 한도:
.env의ADS_MAX_BUDGET_CHANGE_PERCENT,ADS_REQUIRE_APPROVAL_ABOVE_PERCENT,ADS_BUDGET_COOLDOWN_DAYS,ADS_MAX_ACCOUNT_DAILY_BUDGET. 기본값은 각각 10%, 15%, 3일, 하루 329달러다. - 선택 알림:
.env의ALERT_EMAIL,SLACK_WEBHOOK_URL.
모든 설정 항목과 주석은 .env.example에 있다.
명령줄에서 할 수 있는 일
ads-agents ui: 설정, 보고서, 읽기 전용 실행, Google Tags 기능을 제공한다. GTM 게시에는 실시간 모드와 사용자 확인이 필요하다.ads-agents ping: 자격 증명을 확인한다. 읽기 작업이다.ads-agents audit: 전체 계정 감사를 실행해reports/YYYY-MM-DD/에 저장한다. 읽기 작업이다.ads-agents conversions audit: 전환 액션을 분류하고 추적 위험을 찾는다. 읽기 작업이다.ads-agents daily-run: 일일 정보 묶음을reports/daily/YYYY-MM-DD/에 저장한다. 읽기 작업이다.ads-agents dashboard: 최근 감사에서 효율 대시보드 JSON과 추적 명세를 만든다. 로컬 파일만 쓴다.ads-agents plan <campaign.json>: 캠페인 초안에 대한 10개 에이전트 계획을 만든다. Google Ads 계정은 건드리지 않는다.ads-agents platform agents: 플랫폼 에이전트 31개를 나열한다. 계정은 건드리지 않는다.ads-agents platform brief --funnel-csv samples/funnel_90d_template.csv: 모든 계층을 아우르는 CEO용 요약을 만든다. 설정에 따라 계정을 읽는다.ads-agents recommendations evaluate: Google 추천을 위험도에 따라 평가한다. 읽기 작업이다.ads-agents budget-plan: 예산 재배분을 시뮬레이션하는 섀도 모드로 실행한다. 읽기 작업이다.ads-agents controlled-live mode: 현재 안전 모드와 한도를 표시한다. 계정은 건드리지 않는다.
전체 목록은 ads-agents --help 또는 ads-agents <command> --help로 확인할 수 있다. 쓰기 작업이 가능한 명령에는 명시적인 --apply 옵션이 있으며, 이 옵션을 사용해도 실시간 모드가 필요하다.
데이터 보호와 안전 조건
설정과 자격 증명은 사용자 컴퓨터에 보관되며 Git에서 제외된다. .gitignore는 .env, secrets/, config/product_facts.json, config/tenant.json, var/, reports/와 *.pem, *.p12, *credentials*.json, *client_secret*.json, *service-account*.json 파일을 제외한다. 로그에서는 개발자 토큰과 개인 키를 가린다.
프로젝트 설명에 따르면 선택 기능을 사용자가 직접 켜지 않는 한 데이터는 다른 곳으로 전송되지 않는다. 예외로는 선택형 이메일·Slack 알림, 웹사이트 제목이나 GTM 스니펫을 한 번 가져오는 기능, Google Tags 화면에서 사용자가 확인하고 실시간 모드로 게시하는 GTM 작업이 있다. 마지막 작업은 Google Tag Manager API를 사용한다.
현재 모드는 다음 명령으로 확인할 수 있다.
python -m ads_ai_agents.cli controlled-live mode
실시간 모드를 켜기 전에 docs/SECURITY.md를 읽어야 한다. 프로젝트는 항상 READ_ONLY 모드에서 시작하라고 안내한다.
현재 상태와 한계
프로젝트는 0.1.0 알파이며 거친 부분이 있을 수 있다고 안내한다. 코드는 실제 Google Ad Grants 계정에서 실행된 프로덕션 설정에서 분리한 뒤 일반화한 것이다. 이 설명은 프로젝트의 자체 안내이며, 자료에는 독립적인 성능 평가가 제시돼 있지 않다.
프로젝트는 테스트 236개가 통과한다고 밝힌다. 여기에는 대시보드용 Playwright 브라우저 테스트 5개가 포함되며, Playwright나 Chromium이 설치되지 않으면 해당 테스트는 자동으로 건너뛴다. pyflakes 검사도 통과한다고 설명한다. 테스트 명령은 PYTHONPATH=src pytest -q다.
examples/ops/에는 과거의 일회성 운영 스크립트가 있다. 일부는 실행을 의도적으로 거부하도록 되어 있으므로 사용 전에 내용을 읽어야 한다. 키워드 사전과 광고 문안 묶음에는 비영리 웰빙 분야의 예시(영어·우크라이나어·독일어)가 포함된다. 자체 단체나 사업에 맞게 바꾸는 방법은 docs/EXAMPLE_VERTICAL.md에 있다.
ping에서 Google Ads 설정이 없다는 메시지가 나오면 .env에 GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_LOGIN_CUSTOMER_ID 또는 GOOGLE_ADS_CUSTOMER_ID가 빠졌을 수 있다. 설정 마법사를 다시 실행하거나 .env를 직접 편집하라고 안내한다. 권한·인증 오류가 나면 고객 ID에 하이픈 없이 숫자만 입력했는지, 서비스 계정이 Google Ads의 도구 메뉴와 API Center의 API 액세스에 추가됐는지, 서비스 계정을 소유한 Google Cloud 프로젝트에서 Google Ads API를 활성화했는지 확인해야 한다. 테스트 개발자 토큰은 테스트 계정에만 접근할 수 있으며 실제 계정에는 Basic 액세스를 신청해야 한다.
ModuleNotFoundError: No module named 'ads_ai_agents' 오류가 나면 가상환경을 활성화하고 export PYTHONPATH=src를 설정하거나 설치된 ads-agents 명령을 사용한다. 대시보드가 비어 있으면 먼저 자격 증명이 필요한 ads-agents audit을 실행한 뒤 ads-agents dashboard를 실행해야 한다. 모든 작업을 즉시 멈추려면 .env에서 ADS_AUTOMATION_MODE=READ_ONLY로 설정한다.
자료와 라이선스
저장소의 전체 안내는 docs/ARCHITECTURE.md, docs/AGENTS.md, docs/SETUP.md, docs/TOKENS_AND_ACCESS.md, docs/SECURITY.md에 있다. 기여 안내는 CONTRIBUTING.md에서 볼 수 있다. 기여자는 비밀 정보를 커밋하지 말고, 예제에는 일반적인 값만 사용하며, 문서와 CI에서는 읽기 전용 데모를 우선해야 한다. 테스트를 추가하거나 갱신하고 PR을 열기 전에 PYTHONPATH=src pytest -q를 실행하도록 안내한다.
프로젝트는 MIT 라이선스로 제공되며, 자료에는 2026년 Google Ads AI Automation 기여자 저작권으로 표시돼 있다. 애니메이션 아이콘은 Lucide를 사용하며 ISC 라이선스가 적용된다. 관련 라이선스는 LICENSE와 assets/visuals/LUCIDE_LICENSE.txt에서 확인할 수 있다.
댓글 (0)
로그인하면 이 기사에 내 생각을 남길 수 있어요