# ADYou for AI agents — 에이전트가 광고를 만들고, 확인하고, 조정하는 법

> ADYou(애드유 · https://adyou.ai)는 온라인 광고 자율주행 서비스예요. 이 문서는 AI 에이전트(Claude Code · Claude Desktop · Cursor · 직접 만든 에이전트)가 사용자를 대신해 **「이렇게 광고해 줘」로 광고를 만들고**, **「광고 잘 되고 있어?」에 실제 숫자로 답하고**, **말로 고치고 시작·멈추는** 방법을 다 담았어요. 읽기(조회)는 자유롭게, 돈이 움직이는 일은 반드시 사람의 승낙을 거쳐요.

**English summary.** ADYou runs ads on Facebook/Instagram, Google Display, Google Search and YouTube from one sentence. Agents get three surfaces over the same cloud API: an MCP server (`npx -y adyou mcp`), a CLI (`adyou`), and a tiny SDK (`import { ADYou } from 'adyou/client'`). Read endpoints (`/api/agent/overview`, `/api/agent/ads/:id`, `/api/agent/report`) return both codes and plain-Korean text. All changes go through one conversational endpoint (`POST /api/studio`). Anything that moves money (start, change a running ad, restart) returns a confirmation card first; **only call approve after the human explicitly agrees — never self-approve.**

## 1. 한눈에 — 이렇게 물으면 이 도구

| 사용자가 하는 말 | MCP 도구 | CLI | SDK · REST |
|---|---|---|---|
| 「우리 카페 광고해 줘 · instagram.com/mycafe」 | `adyou_say` | `adyou "…"` | `say()` · `POST /api/studio` |
| 「더 따뜻한 느낌으로」「가격은 빼 줘」 | `adyou_say` | `adyou "…"` | `say(msg, { threadId })` |
| 「내일부터 한 달 30만원으로 시작해 줘」 | `adyou_say` → 확인 상자 → 사용자 승낙 → `adyou_say(confirmToken, userApproved=true)` | `adyou "…"` → Enter | `say()` → `approve()` |
| 「구글은 멈춰 줘」「전부 멈춰」「예산 50만원으로」 | `adyou_say` | `adyou "…"` | `say(msg, { threadId })` |
| 「광고 잘 되고 있어?」「얼마 썼어?」「ADYou가 뭘 바꿨어?」 | `adyou_overview` | `adyou status` | `overview()` · `GET /api/agent/overview` |
| 「그 광고 문구·이미지 보여 줘」「심사 통과했어?」「왜 예산이 바뀌었어?」 | `adyou_ad` | `adyou ad <이름>` | `ad(id)` · `GET /api/agent/ads/:id` |
| 「이번 주(달) 성과 정리해 줘」「어디가 제일 효율 좋아?」 | `adyou_cloud_report` | `adyou report --days 30` | `report(30)` · `GET /api/agent/report?days=30` |
| 「광고 목록」 | `adyou_overview` | `adyou ads` | `ads()` · `GET /api/agent/ads` |

숫자는 도구가 준 값을 그대로 옮기고 지어내지 않아요. 응답의 `summary`·`text`·`statusText`·`what`/`why` 는 사용자에게 그대로 읽어 줘도 되는 쉬운 한국어예요.

## 2. 설치와 연결(한 번)

```bash
npm i -g adyou        # 노드 20 이상
adyou login           # 브라우저가 열리고 코드가 맞는지 확인 → 「이 터미널 연결」 (비밀번호·키를 붙여 넣지 않아요)
adyou whoami          # 연결된 회사·광고비 잔액
```

- 계정이 없으면 승인 화면에서 이메일이나 구글 계정으로 바로 가입돼요(무료 · 광고를 시작하기 전까지 0원).
- 토큰은 `~/.adpilot/session.json`(0600)에 저장되고 `adyou logout` 으로 폐기해요. 토큰은 발급한 회사에 묶여요.
- 에이전트가 직접 로그인시킬 때: `adyou login --json` 은 `{ "next_action": "open_url_and_approve", "verifyUrl": "…", "userCode": "ABCD-EFGH" }` 를 먼저 찍어요 — 그 주소를 사용자에게 보여 주고 코드가 같은지 확인한 뒤 누르게 하세요.

### MCP 서버 등록

Claude Code:
```bash
claude mcp add adyou -- npx -y adyou mcp
```
Claude Desktop(`claude_desktop_config.json`) · Cursor(`~/.cursor/mcp.json`) · 그 밖의 MCP 클라이언트:
```json
{ "mcpServers": { "adyou": { "command": "npx", "args": ["-y", "adyou", "mcp"] } } }
```
MCP 서버는 같은 컴퓨터의 `adyou login` 세션을 써요(환경변수 `ADPILOT_HOME` 으로 세션 폴더, `ADYOU_API` 로 서버 주소를 바꿀 수 있어요).

클라우드 도구(ADYou 계정으로 집행 · 광고 계정·AI 키 불필요): `adyou_say` · `adyou_overview` · `adyou_ad` · `adyou_cloud_report`.
그 밖의 도구(`adyou_brief`·`adyou_creatives`·`adyou_build`·`adyou_launch`·`adyou_status`·`adyou_report` …)는 **내 광고 계정(메타·구글)을 이 컴퓨터에 직접 연결한** 개발자용 길이에요. 보통의 사용자에게는 클라우드 도구 넷이면 돼요.

## 3. 인증(REST)

```
Authorization: Bearer adyou_…
```
기기 코드 흐름(터미널·에이전트가 직접 받을 때):
1. `POST https://adyou.ai/api/cli/device` `{"label":"my-agent"}` → `{ deviceCode, userCode, verifyUrl, expiresIn, interval }`
2. 사용자가 `verifyUrl` 을 열어 코드를 확인하고 「이 터미널 연결」을 누른다.
3. `POST https://adyou.ai/api/cli/token` `{"deviceToken":"<deviceCode>"}` 를 `interval` 초마다 → `{ "status": "pending" }` 또는 `{ "status": "ok", "token": "adyou_…", "email", "workspace" }`(토큰은 한 번만 내려와요).
4. 폐기: `DELETE https://adyou.ai/api/cli/token` (같은 Authorization 헤더).

## 4. 조회 API(읽기 전용 · 아무것도 바꾸지 않아요)

### GET /api/agent/overview — 회사 전체 한눈에
```bash
curl -s https://adyou.ai/api/agent/overview -H "Authorization: Bearer $ADYOU_TOKEN"
```
```json
{
  "company": { "name": "온도 베이커리", "demo": false },
  "summary": "광고 1개가 나가고 있어요. 어제 ₩23,040을 써서 광고가 2,000번 보이고 16번 눌렸어요 (한 번 누르는 데 ₩1,440) · 목표 달성 2건. …",
  "counts": { "ads": 2, "running": 1, "waitingToStart": 0, "needsYou": 1 },
  "yesterday": { "spendKrw": 23040, "impressions": 2000, "clicks": 16, "conversions": 2, "clickRatePct": 0.8, "costPerClickKrw": 1440, "costPerGoalKrw": 11520 },
  "last7Days": { "spendKrw": 161280, "impressions": 14000, "clicks": 112, "conversions": 14, "clickRatePct": 0.8, "costPerClickKrw": 1440, "costPerGoalKrw": 11520 },
  "balance": { "adBalanceKrw": 122592, "creativeCreditKrw": 30000, "daysLeft": 9, "text": "광고비 잔액 ₩122,592 · 지금 속도로 약 9일치" },
  "billing": { "thisMonthAdSpendKrw": 161280, "thisMonthServiceFeeKrw": 16128, "note": "광고가 실제로 나간 만큼만 잔액에서 빠져요. …" },
  "ads": [{
    "id": "176f68fa-…", "name": "동네 필라테스", "site": "https://…",
    "status": "live", "statusText": "광고 나가는 중", "goal": "traffic", "goalText": "사이트 방문",
    "startedAt": "2026-11-15T11:01:28.386Z", "endDate": null,
    "budget": { "monthlyKrw": 400000, "dailyKrw": 13157, "spentThisMonthKrw": 161280, "usedThisMonthPct": 40 },
    "yesterday": { "…": "위와 같은 숫자 묶음" }, "last7Days": { "…": "위와 같은 숫자 묶음" },
    "media": [{ "medium": "google", "name": "구글 배너", "running": true, "adsOn": 1, "adsTotal": 1, "dailyBudgetKrw": 13151, "yesterday": { "…": "" }, "last7Days": { "…": "" }, "yesterdayBudgetUsedPct": 91 }],
    "review": { "blocked": 0, "limited": 0, "text": "문제 없이 나가고 있어요" },
    "notice": null,
    "summary": "동네 필라테스 — 광고 나가는 중. 최근 7일 동안 … 한 달 예산 ₩400,000 중 이번 달 ₩161,280 썼어요.",
    "links": { "ad": "https://adyou.ai/projects/176f68fa-…", "creatives": "…?tab=creatives", "performance": "…?tab=metrics", "changes": "…?tab=log" }
  }],
  "autopilot": { "days": 7, "checks": 168, "changes": 2, "lastCheckedAt": "2026-11-19T00:49:10.645Z",
    "recent": [{ "at": "2026-11-19T00:29:27.800Z", "ad": "동네 필라테스", "adId": "176f68fa-…", "what": "쉬고 있는 곳의 예산을 구글 배너 쪽으로 옮겼어요", "why": "페이스북·인스타그램이 멈춰 있어 그 몫 하루 ₩7,231을 …", "tag": "예산 늘림", "by": "ADYou 자동" }] },
  "savings": ["쉬고 있던 예산 하루 ₩7,231을 잘 나가는 곳으로 옮겼어요."],
  "todo": [{ "text": "광고비 잔액이 이틀치(₩26,314)보다 적어요. 모자라면 광고가 멈춰요.", "link": "https://adyou.ai/billing" }],
  "links": { "dashboard": "https://adyou.ai/dashboard", "performance": "https://adyou.ai/analytics", "billing": "https://adyou.ai/billing", "create": "https://adyou.ai/studio" },
  "howToAct": "…", "generatedAt": "2026-11-19T00:53:25.455Z"
}
```
- `status` 코드: `draft`(사이트 읽는 중) · `briefed`(읽은 내용 확인 필요) · `creatives`(광고 준비됨) · `planned`(예산 확인 필요) · `built`(시작 대기) · `live`(광고 나가는 중) · `paused`(멈춤) · `ended`(끝남). 사용자에게는 `statusText` 를 읽어 주세요.
- `media[].medium`: `meta`(페이스북·인스타그램) · `google`(구글 배너) · `google_search`(구글 검색) · `youtube`(유튜브).
- `autopilot`: ADYou 가 사람 손 없이 한 일. `checks` = 살펴본 횟수, `changes` = 실제로 고친 횟수, `recent[]` = 언제(`at`)·무엇을(`what`)·왜(`why`).
- `savings`: 기록에서 계산된 사실만(근거가 없으면 빈 배열). 숫자를 덧붙여 꾸미지 마세요.
- `notice.level`: `wait`(자동으로 다시 시도 · 할 일 없음) · `todo`(사용자가 할 일 있음 — `action`) · `help`(담당자가 확인).
- `?limit=N`(1~30) 으로 `autopilot.recent` 개수를 바꿔요.

### GET /api/agent/ads — 광고 목록만
`{ "ads": [ …위 ads 와 같은 모양… ], "counts": { … } }`

### GET /api/agent/ads/:id — 광고 하나 자세히
```bash
curl -s https://adyou.ai/api/agent/ads/176f68fa-7503-4cb4-9249-046e9f45dad6 -H "Authorization: Bearer $ADYOU_TOKEN"
```
overview 의 광고 한 건에 더해:
```json
{
  "about": { "whatItIs": "동네 필라테스 스튜디오", "offer": "퇴근길에 다니기 좋은 동네 필라테스, 첫 달 50% 할인", "audience": ["퇴근 후 운동 시작하려는 직장인"], "sellingPoints": ["퇴근길 30분 거리"], "tone": "친근하고 간결함" },
  "creatives": [{
    "name": "퇴근길 혜택 강조형", "angle": "퇴근 동선과 가격 혜택을 직접 전달한다",
    "headlines": ["퇴근길 30분 필라테스", "첫 달 50% 할인 중"], "bodies": ["퇴근길 30분이면 다녀올 수 있는 동네 필라테스예요. …"], "descriptions": ["…"],
    "images": [{ "url": "https://adyou.ai/api/assets/6d26b2c5-…", "width": 1200, "height": 628, "ratio": "16x9" }],
    "videos": [{ "url": "https://adyou.ai/api/assets/…", "width": 1080, "height": 1920, "seconds": 8 }],
    "running": true,
    "last30Days": { "spendKrw": 161280, "impressions": 14000, "clicks": 112, "conversions": 14, "clickRatePct": 0.8, "costPerClickKrw": 1440, "costPerGoalKrw": 11520 }
  }],
  "review": { "blocked": 0, "limited": 0, "text": "문제 없이 나가고 있어요", "ads": [{ "name": "퇴근길 혜택 강조형", "where": "구글 배너", "level": "ok", "levelText": "심사 통과 · 나가는 중", "reasons": [] }] },
  "autopilot": { "…": "이 광고만" }, "savings": ["…"],
  "changes": [{ "at": "2026-11-19T00:29:27.800Z", "what": "쉬고 있는 곳의 예산을 구글 배너 쪽으로 옮겼어요", "why": "…", "by": "ADYou 자동", "automatic": true }]
}
```
- `images[].url`·`videos[].url` 은 같은 Bearer 토큰으로 내려받아요(`curl -H "Authorization: Bearer …" <url> -o ad.png`). 사람에게 보여 줄 땐 `links.creatives` 를 주세요.
- `review.ads[].level`: `ok` · `review`(심사 중) · `limited`(일부에만 보임) · `blocked`(반려). 반려는 ADYou 가 문구를 고쳐 다시 올려요.
- 없는 id 는 `404 {"error":"…","code":"not_found"}`.

### GET /api/agent/report?days=7|30|90 — 기간 성과
```bash
curl -s "https://adyou.ai/api/agent/report?days=30" -H "Authorization: Bearer $ADYOU_TOKEN"
```
```json
{
  "days": 30, "since": "2026-10-21", "until": "2026-11-19",
  "text": "최근 30일 동안 ₩161,280을 써서 광고가 14,000번 보이고 112번 눌렸어요. 한 번 누르는 데 ₩1,440 들었어요. …",
  "lines": ["최근 30일 동안 …", "한 번 누르는 데 …"],
  "total": { "spendKrw": 161280, "impressions": 14000, "clicks": 112, "conversions": 14, "clickRatePct": 0.8, "costPerClickKrw": 1440, "costPerGoalKrw": 11520 },
  "previousPeriod": { "…": "직전 같은 길이 기간" }, "changePct": { "spend": null, "impressions": null, "clicks": null, "conversions": null },
  "byMedium": [{ "medium": "google", "name": "구글 배너", "spendKrw": 84000, "…": "" }],
  "byAd": [{ "id": "…", "name": "동네 필라테스", "status": "live", "statusText": "광고 나가는 중", "monthlyBudgetKrw": 400000, "link": "…", "…": "" }],
  "byCreative": [{ "adId": "…", "ad": "동네 필라테스", "name": "퇴근길 혜택 강조형", "where": "구글 배너", "…": "" }],
  "daily": [{ "date": "2026-11-18", "spendKrw": 23040, "impressions": 2000, "clicks": 16, "conversions": 2 }],
  "autopilot": { "…": "" }, "savings": ["…"]
}
```
`days` 는 7·30·90 중 하나로 맞춰져요. `changePct` 는 이전 기간 숫자가 없으면 `null`.

## 5. 만들기·고치기·시작·멈춤 — 대화 API 하나

모든 변경은 사용자의 말을 **그대로** 보내는 대화로 해요. 에이전트가 예산·날짜·매체를 따로 계산해 넣을 필요가 없어요(서버가 말에서 읽고, 모호하면 되물어요).

```bash
# ① 새 광고 — 첫 마디(가게 주소가 있으면 같이)
curl -s -X POST https://adyou.ai/api/studio -H "Authorization: Bearer $ADYOU_TOKEN" -H "content-type: application/json" \
  -d '{"message":"우리 카페 신메뉴를 동네 사람들에게 알리고 싶어요. instagram.com/mycafe","source":"cli"}'
# ② 이어서 말하기(고치기·시작 요청·질문) — 응답의 thread.id 로
curl -s -X POST https://adyou.ai/api/studio/$THREAD -H "Authorization: Bearer $ADYOU_TOKEN" -H "content-type: application/json" -d '{"message":"더 따뜻한 느낌으로"}'
# ③ 진행 상황(만드는 동안 2~3초마다) — after 는 마지막으로 받은 메시지 id
curl -s "https://adyou.ai/api/studio/$THREAD?after=12" -H "Authorization: Bearer $ADYOU_TOKEN"
# ④ 확인 상자 승인(사람이 승낙한 뒤에만) / 취소
curl -s -X POST https://adyou.ai/api/studio/$THREAD -H "Authorization: Bearer $ADYOU_TOKEN" -H "content-type: application/json" -d '{"confirm":"<pendingToken>"}'
curl -s -X POST https://adyou.ai/api/studio/$THREAD -H "Authorization: Bearer $ADYOU_TOKEN" -H "content-type: application/json" -d '{"cancel":true}'
# ⑤ 대화 목록
curl -s https://adyou.ai/api/studio -H "Authorization: Bearer $ADYOU_TOKEN"
```
응답(상태):
```json
{
  "thread": { "id": "b2599fd1-…", "title": "테라로사" },
  "messages": [{ "id": 13, "role": "assistant", "text": "광고를 만들었어요. …", "cards": [{ "type": "preview" }] }],
  "pendingToken": null,
  "stage": "preview",
  "project": { "id": "…", "name": "테라로사", "host": "terarosa.com", "concepts": [{ "name": "카페 신메뉴 출시", "headline": "테라로사 카페 신메뉴 나왔어요", "body": "…" }], "job": null, "error": null, "budgetMonthlyKrw": 300000, "dailyKrw": 9868, "startDate": null, "endDate": null, "media": ["meta", "google"] },
  "workspace": { "name": "내 가게", "balanceKrw": 0 }
}
```
- `stage`: `empty`(아직 광고 없음 — 가게 주소를 물어봐요) · `reading`(사이트 읽는 중 · 약 30초) · `making`(광고 이미지·문구 만드는 중 · 3~10분) · `preview`(미리보기 준비됨) · `registering`(광고 등록 중 · 1~3분) · `waiting`(잔액 충전 등 기다림) · `scheduled`(시작일 예약됨) · `ready`(등록 끝 · 아직 꺼져 있음) · `live`(나가는 중) · `paused`(멈춤) · `error`.
- `reading`·`making`·`registering` 동안에는 ③ 으로 기다려요. 사람에게 보여 줄 미리보기 주소는 `https://adyou.ai/studio/<thread.id>`.
- `cards[].type`: `preview` · `steps`(한 일 목록) · `link`(`href`·`label`) · `confirm`(아래) · `started`(승인한 조건).

### 대화 흐름
1. **만들기** — 「무엇을 누구에게」 + 가게 주소(홈페이지·인스타그램 프로필·스마트스토어·블로그). 주소가 없으면 ADYou 가 되물어요.
2. **미리보기** — `stage: "preview"`. 방향(`concepts`)마다 제목·본문. 사용자에게 `https://adyou.ai/studio/<id>` 를 보여 주세요.
3. **고치기** — 「더 고급스럽게」「가격은 빼 줘」「이미지 넣어 줘」. 다시 만드는 동안 `making`.
4. **시작 제안** — 「내일부터 2주 동안 한 달 50만원으로 인스타그램에 시작」 → `confirm` 카드와 `pendingToken`.
5. **승인** — 사용자가 상자를 보고 승낙하면 `{"confirm": pendingToken}`. 광고가 등록되고(예약일이면 그날) 시작돼요.
6. **운영 중** — 「구글은 멈춰 줘」「예산 80만원으로」「11월 말까지만」「다시 시작」. 조회는 4장의 API 로.

### 🔴 승인 규칙(반드시 지켜요)
- **돈이 움직이는 일 = 광고 시작 · 나가고 있는 광고의 변경 · 다시 시작**은 항상 「제안 → 승인」 두 단계예요. 서버가 보관한 토큰(`pendingToken`)과 맞아야만 실행되고, 건너뛰는 길은 없어요.
- `confirm` 카드: `{ "type": "confirm", "token": "…", "action": "start", "title": "11월 20일(금)부터 광고 시작", "rows": [["광고가 나갈 곳", "페이스북·인스타그램 · 구글 배너"], ["시작", "11월 20일(금) 0시부터"], ["하루 예산", "약 ₩9,868"], ["한 달 한도", "₩300,000 · 이 위로는 절대 안 나가요"]], "note": "…" }`
- 에이전트는 `title`·`rows`·`note` 를 **사용자에게 그대로 보여 주고**, 사용자가 명시적으로 「네, 시작해」라고 했을 때만 승인해요. 사용자가 처음 요청에서 조건을 다 말했더라도 상자를 한 번 보여 주세요. 에이전트가 스스로 승인하지 않아요.
- 다른 말을 보내면 앞의 제안은 버려져요. 제안은 30분 뒤 만료돼요. 틀리거나 만료된 토큰은 `409 stale_confirm` — 사용자에게 다시 요청하게 하세요.
- 멈춤·예약 취소는 확인 없이 바로 돼요(돈이 덜 나가는 방향).
- MCP `adyou_say` 는 `confirmToken` + `userApproved: true` 가 같이 와야만 승인하고, 「네」「진행해」 같은 말만 보내면 거절해요.

## 6. SDK(노드 20+ · 브라우저 · 엣지)

```ts
import { ADYou } from 'adyou/client'
const adyou = new ADYou({ token: process.env.ADYOU_TOKEN! })        // base 기본값 https://adyou.ai

const o = await adyou.overview()                                     // 「광고 잘 되고 있어?」
console.log(o.summary, o.autopilot.recent, o.savings)

const r = await adyou.say('우리 카페 신메뉴를 동네 사람들에게 알리고 싶어요. instagram.com/mycafe')   // 만드는 동안 기다려요(기본 4분)
console.log(r.reply, r.previewUrl)
const s = await adyou.say('내일부터 한 달 30만원으로 시작해 줘', { threadId: r.threadId })
if (s.confirm) {                                                     // 🔴 사람에게 s.confirm.title · rows 를 보여 주고 승낙을 받은 뒤에만
  await adyou.approve(s.threadId, s.confirm.token)                   // 거절이면 adyou.cancel(s.threadId)
}
const ad = await adyou.ad(o.ads[0].id)                               // 문구·이미지 주소·바뀐 내역
const rep = await adyou.report(30)                                   // 30일 성과
```
메서드: `overview()` · `ads()` · `ad(id)` · `report(days)` · `say(message, { threadId?, waitMs? })` · `approve(threadId, token)` · `cancel(threadId)` · `thread(id, after?)` · `asset(url)` · `logout()`. 실패는 `ADYouError { status, code, message }`.

## 7. CLI

```bash
adyou "우리 카페 신메뉴를 동네 사람들에게 알리고 싶어요. instagram.com/mycafe"   # 만들기(브라우저에 미리보기)
adyou "더 따뜻한 느낌으로"                                                        # 고치기
adyou "내일부터 한 달 30만원으로 시작"                                             # 확인 상자 → Enter
adyou status            # 광고 잘 되고 있는지 한눈에   (--json 원본)
adyou ads               # 광고 목록
adyou ad 카페           # 광고 하나 자세히(이름·주소 일부·id)
adyou report --days 30  # 기간 성과
adyou chat "…" --json   # 스크립트·에이전트용 JSON 출력 · --yes 는 확인을 건너뛰니 사람이 볼 땐 쓰지 마세요
```
`status`·`report` 는 이 컴퓨터에 내 광고 계정 프로젝트(BYO)가 있으면 예전처럼 그 프로젝트를 봐요. 그때 클라우드 현황은 `--cloud`.

## 8. ADYou 가 스스로 하는 일(자율주행)

광고를 시작하면 한 시간마다 성과를 가져와 살펴보고, 필요할 때만 고쳐요. 한 달 예산은 넘기지 않고, 한 일은 전부 이유와 함께 기록돼요(`autopilot.recent` · `changes`).
- **광고 끄기·바꾸기** — 이틀 넘게 나간 광고끼리 비교해 눈에 띄게 반응이 낮은 광고(눌린 적 없는 광고 포함)를 끄고, 그 자리에 새 이미지·문구를 만들어 넣어요. 광고가 나가는 곳마다 하나는 남겨요.
- **예산 옮기기** — 광고가 나가는 곳(페이스북·인스타그램 · 구글 배너 · 구글 검색 · 유튜브) 중 성과가 좋은 쪽으로 사흘에 한 번 하루 예산을 조금씩 옮기고, 멈춘 곳의 몫은 나가고 있는 곳이 써요.
- **보일 대상 다듬기** — 하루 한 번. 구글 검색은 실제 검색어를 읽어 관계없는 말을 빼고 잘 맞는 말을 더해요. 구글 배너는 실수로 눌리는 앱·사이트를 빼요.
- **반려된 광고 고치기** — 심사에서 반려되면 문구를 고쳐 다시 올려요.
- **잔액 지키기** — 광고비 잔액이 이틀치보다 적으면 멈추고, 충전하면 다시 시작해요.
- 시작 뒤 이틀은 숫자가 모일 때까지 지켜보기만 해요.
- 매일 아침 9시(한국 시간) 광고 리포트 메일, 매주 월요일 쉬운 말로 쓴 보고서.

## 9. 오류와 한도

| HTTP | code | 뜻 · 에이전트가 할 일 |
|---|---|---|
| 401 | `no_session` | 토큰이 없거나 폐기됨 → `adyou login` 을 다시 |
| 403 | `viewer_readonly` | 열람자 권한 — 조회만 가능 |
| 403 | `demo_readonly` | 체험 계정 — 변경 불가 |
| 403 | `suspended` | 회사 계정 정지 — support@adyou.ai |
| 404 | `not_found` | 그 id 의 광고·대화가 없음 → overview 로 id 확인 |
| 409 | `stale_confirm` | 확인 토큰이 틀리거나 30분 만료 → 사용자에게 다시 요청하게 |
| 429 | `creative_quota` | 광고 이미지·문구 만들기 횟수 한도(광고 하나 하루 6번 · 회사 하루 20번 · 충전한 적 없는 회사는 하루 3번) → 메시지의 「언제 다시 되는지」를 그대로 전달 |
| 429 | `rate_limited` | 너무 자주 보냄 → 잠시 뒤 다시 |

오류 본문은 항상 `{ "error": "사용자에게 보여 줄 한국어 문장", "code": "…" }`. `error` 는 그대로 전달해도 돼요.
- 조회 API 는 자주 불러도 되지만 숫자는 한 시간마다 바뀌니 분 단위로 되풀이할 필요는 없어요.
- 광고비는 사용자가 정한 한 달 예산 밖으로 나가지 않고, 회사마다 하루 광고비 한도가 있어요(넘는 시작 요청은 대화에서 이유를 알려 줘요).
- 못 하는 광고: 금융(대출·투자·보험·코인) · 의료·의약 · 정치 · 도박 · 담배 · 성인.

## 10. 더 읽기
- 기계가 읽는 명세: https://adyou.ai/api/openapi.json (OpenAPI 3.1)
- 서비스 요약: https://adyou.ai/llms.txt · 전문: https://adyou.ai/llms-full.txt
- 사람용 따라하기: https://adyou.ai/guide · 문의: support@adyou.ai
