> ## Documentation Index
> Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# クイックスタート

> 自分の役割を選びましょう——バイヤーは5分で AdCP エージェントを呼び出し、パブリッシャーとセラーは自前のエージェントを立ち上げます。

自分の役割を選びましょう。バイヤーは公開テストエージェントを5分で呼び出せます。パブリッシャーとセラーは、バイヤーが呼び出せるエージェントを立ち上げます。

<CardGroup cols={2}>
  <Card title="エージェントを呼び出す側" icon="plug">
    バイヤー側。このページの残りは公開テストエージェントの呼び出しを解説します——サインアップ不要、コピー&ペーストできる curl。
  </Card>

  <Card title="エージェントを構築する側" icon="server" href="/docs/building/by-layer/L4/build-an-agent">
    パブリッシャーまたはセラー側。バイヤーが呼び出せるエージェントを立ち上げます。
  </Card>
</CardGroup>

## セットアップ

公開テストトークンを使えばすぐに始められます——サインアップは不要です:

```bash theme={null}
export ADCP_AUTH_TOKEN="1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ"
export AGENT_URL="https://test-agent.adcontextprotocol.org/sales/mcp"
```

テストエージェントはパスルーティングされています: `/sales/mcp` はメディアバイのツール（このクイックスタートのパス）を提供し、兄弟 URL が他の専門領域を提供します——`/signals/mcp`、`/governance/mcp`、`/creative/mcp`、`/creative-builder/mcp`、`/brand/mcp`。テナントとツールの完全な一覧は [`/.well-known/adagents.json`](https://test-agent.adcontextprotocol.org/.well-known/adagents.json) を参照してください。

組織スコープで利用状況を追跡できる自分専用の API キーは、[AAO ダッシュボード](https://agenticadvertising.org/dashboard/api-keys)で作成できます。

## 1. プロダクトをディスカバリーする

MCP 上の AdCP は JSON-RPC 2.0 を使用します。トランスポートは [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) で、レスポンスは server-sent events として届きます。

```bash theme={null}
curl -X POST $AGENT_URL \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $ADCP_AUTH_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_products",
      "arguments": {
        "brief": "Video ads for pet food brand",
        "brand": { "domain": "premiumpetfoods.com" }
      }
    }
  }'
```

**レスポンス**（見やすさのため SSE エンベロープは省略）:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"products\":[{\"product_id\":\"pinnacle_news_video_premium\",\"name\":\"Pinnacle News Group video guaranteed\",\"channels\":[\"olv\",\"ctv\"],\"pricing_options\":[{\"pricing_option_id\":\"pinnacle_news_video_premium_pricing_0\",\"pricing_model\":\"cpm\",\"currency\":\"USD\",\"fixed_price\":15}],\"delivery_type\":\"guaranteed\"}, ...],\"sandbox\":true}"
      }
    ]
  }
}
```

**結果を取り出す**——AdCP のペイロードは `content[0].text` の中に JSON エンコードされています:

```javascript theme={null}
const response = /* parsed JSON-RPC response */;
const payload = JSON.parse(response.result.content[0].text);

console.log(payload.products[0].product_id);    // "pinnacle_news_video_premium"
console.log(payload.products[0].channels);      // ["olv", "ctv"]
console.log(payload.products[0].pricing_options[0].pricing_option_id); // "pinnacle_news_video_premium_pricing_0"
console.log(payload.products[0].pricing_options[0].fixed_price);       // 15
```

## 2. エラーを処理する

無効なツール名を送って、エラーがどのように見えるか確認します:

```bash theme={null}
curl -X POST $AGENT_URL \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $ADCP_AUTH_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "nonexistent_tool",
      "arguments": {}
    }
  }'
```

**レスポンス:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"code\":\"INVALID_REQUEST\",\"message\":\"Unknown tool: nonexistent_tool\"}"
      }
    ],
    "isError": true
  }
}
```

**処理する**——`isError` を確認してから、エラーペイロードをパースします:

```javascript theme={null}
const response = /* parsed JSON-RPC response */;

if (response.result.isError) {
  const err = JSON.parse(response.result.content[0].text);
  console.log(err.code);     // "INVALID_REQUEST"
  console.log(err.message);  // "Unknown tool: nonexistent_tool"
}
```

主なエラーコード: `INVALID_REQUEST`（不正な入力）、`RATE_LIMITED`（バックオフしてリトライ）、`UNAUTHORIZED`（認証情報を確認）。

## 3. メディアバイを（冪等に）作成する

ステップ1のプロダクト ID を使ってキャンペーンを作成します。すべての変更を伴うリクエストは `idempotency_key`——リトライを安全にするクライアント生成の UUID v4——を必ず含めなければなりません。同じキーを同じペイロードで送ると、セラーは重複した購入を作成する代わりに元の結果を返します:

```bash theme={null}
export IDEMPOTENCY_KEY="$(uuidgen | tr '[:upper:]' '[:lower:]')"

curl -X POST $AGENT_URL \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $ADCP_AUTH_TOKEN" \
  -d "{
    \"jsonrpc\": \"2.0\",
    \"id\": 1,
    \"method\": \"tools/call\",
    \"params\": {
      \"name\": \"create_media_buy\",
      \"arguments\": {
        \"idempotency_key\": \"$IDEMPOTENCY_KEY\",
        \"account\": { \"account_id\": \"test_account\" },
        \"brand\": { \"domain\": \"premiumpetfoods.com\" },
        \"start_time\": \"asap\",
        \"end_time\": \"2026-04-30T00:00:00Z\",
        \"packages\": [{
          \"product_id\": \"pinnacle_news_video_premium\",
          \"budget\": 5000,
          \"pricing_option_id\": \"pinnacle_news_video_premium_pricing_0\"
        }]
      }
    }
  }"
```

同じリクエスト（同じキー、同じペイロード）を再送すると、セラーは `replayed: true` を付けて元のレスポンスを返します。同じキーを異なるペイロードで送ると `IDEMPOTENCY_CONFLICT` になります。セラーの有効期間は `get_adcp_capabilities` で確認できます:

```json theme={null}
{ "idempotency": { "supported": true, "replay_ttl_seconds": 86400 } }
```

`IDEMPOTENCY_CONFLICT`、`IDEMPOTENCY_EXPIRED`、および AdCP Verified エージェント向けの UUID v4 ガイダンスを含む完全なリトライモデルは、[セキュリティガイド](/docs/building/by-layer/L1/security)を参照してください。

**レスポンス**（ID は呼び出しごとに異なります）:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"media_buy_id\":\"mb_f4139524\",\"status\":\"active\",\"revision\":1,\"packages\":[{\"package_id\":\"pkg_3df649f0\",\"product_id\":\"pinnacle_news_video_premium\",\"budget\":5000,\"pricing_option_id\":\"pinnacle_news_video_premium_pricing_0\"}],\"valid_actions\":[\"pause\",\"cancel\",\"update_budget\",\"update_dates\",\"update_packages\",\"add_packages\",\"sync_creatives\"],\"sandbox\":true}"
      }
    ]
  }
}
```

**結果を取り出す:**

```javascript theme={null}
const response = /* parsed JSON-RPC response */;
const buy = JSON.parse(response.result.content[0].text);

console.log(buy.media_buy_id);     // "mb_f4139524"
console.log(buy.status);           // "active"
console.log(buy.packages[0].budget); // 5000
console.log(buy.valid_actions);    // ["pause", "cancel", "update_budget", ...]
```

## 4. プッシュ通知（署名付き Webhook）

本番のエージェントは長時間実行される操作について Webhook を送信します。AdCP 3.0 は、**エージェント間リクエストで使われるものと同じ RFC 9421 HTTP Message Signatures プロファイル**で Webhook に署名します——一つのベリファイア、一つの JWKS、一つのトラストサーフェス。共有 HMAC シークレットはありません。

エージェントにあなたの Webhook エンドポイントを指定し、あなたの JWKS を公開します。エージェントは自分が信頼する鍵で各 POST に署名します。あなたはエージェントの JWKS を取得し、ペイロードに基づいて動作する前に署名を検証します:

```json theme={null}
{
  "name": "create_media_buy",
  "arguments": {
    "idempotency_key": "5c4c6f29-...",
    "account": { "account_id": "your_account" },
    "brand": { "domain": "premiumpetfoods.com" },
    "push_notification_config": {
      "url": "https://you.example.com/webhooks/adcp",
      "authentication": {
        "schemes": ["HTTP_MESSAGE_SIGNATURES"]
      }
    }
  }
}
```

操作が完了すると、エージェントはあなたの URL へ署名付きリクエストを POST します。ペイロードは自身の `idempotency_key` を持つため、受信側はリトライを重複排除できます:

```json theme={null}
{
  "task_id": "task_456",
  "idempotency_key": "webhook_evt_8f2a...",
  "task_type": "create_media_buy",
  "status": "completed",
  "timestamp": "2026-04-22T10:30:00Z",
  "result": {
    "media_buy_id": "mb_12345",
    "packages": [{ "package_id": "pkg_001" }]
  }
}
```

ペイロードを信頼する前に署名を検証します——`keyid` をセラーオペレーターの `brand.json` の `agents[].jwks_uri` 経由で解決し、パブリッシャーの `adagents.json` の `signing_keys[]` ピンがあれば適用し、AdCP の Webhook ベリファイアチェックリストを実行し、未知の鍵・期限切れの日付・一致しないダイジェストを型付きの `webhook_signature_*` 理由コードで拒否します:

```typescript theme={null}
app.post('/webhooks/adcp/*', async (req, res) => {
  try {
    await verifyAdcpWebhookSignature(req, {
      sellerAgentUrl: req.sellerContext.agentUrl,
      requiredTag: 'adcp/webhook-signing/v1',
      allowedAlgs: ['ed25519', 'ecdsa-p256-sha256'],
    });
  } catch (err) {
    return res.status(401)
      .setHeader('WWW-Authenticate', `Signature error="${err.code}"`)
      .end();
  }

  const { idempotency_key } = req.body;
  if (await seen(idempotency_key)) return res.status(200).end();
  await process(req.body);
  res.status(200).end();
});
```

必須ヘッダー、対象コンポーネント、nonce と date のウィンドウ、コンプライアンスランナーが実行するネガティブベクトルスイートを含む完全な検証プロファイルは、[セキュリティガイド](/docs/building/by-layer/L1/security)と [Webhook ガイド](/docs/building/by-layer/L3/webhooks)を参照してください。

## クライアントライブラリを使う

上記の例は分かりやすさのために生の HTTP を使っています。実際には、SSE のパース、リトライ、認証を処理してくれる AdCP クライアントライブラリを使用します:

```bash theme={null}
npm install @adcp/sdk  # JavaScript/TypeScript
pip install adcp          # Python
```

```javascript theme={null}
import { ADCPMultiAgentClient } from '@adcp/sdk';

const client = new ADCPMultiAgentClient([{
  id: 'test',
  name: 'Test Agent',
  agent_uri: 'https://test-agent.adcontextprotocol.org/sales/mcp',
  protocol: 'mcp',
  auth_token: process.env.ADCP_AUTH_TOKEN,
}]);

const result = await client.agent('test').getProducts({
  brief: 'Video ads for pet food brand',
  brand: { domain: 'premiumpetfoods.com' },
});

console.log(result.data.products);
```

## 次のステップ

* **[エージェントを構築する](/docs/building/by-layer/L4/build-an-agent)** — skill ファイルを使って、コーディングエージェントでストーリーボード準拠のエージェントを生成する
* **[エージェントを検証する](/docs/building/verification/validate-your-agent)** — ストーリーボードとコンプライアンスチェックでエージェントをテストする
* **[コンプライアンスカタログ](/docs/building/verification/compliance-catalog)** — エージェントが主張できるドメインと専門領域、および各主張を検証するストーリーボード
* **[MCP インテグレーションガイド](/docs/building/by-layer/L0/mcp-guide)** — トランスポート、セッション、認証の詳細
* **[A2A インテグレーションガイド](/docs/building/by-layer/L0/a2a-guide)** — ストリーミング、アーティファクト、プッシュ通知
* **[メディアバイのライフサイクル](/docs/media-buy/media-buys/lifecycle)** — 状態機械、順序付けられたフロー、保証付き取引の IO パス、クリエイティブ同期のタイミング
* **[タスクリファレンス](/docs/media-buy/task-reference)** — テスト可能な例を備えた利用可能なすべてのタスク
* **[エラーハンドリング](/docs/building/operating/transport-errors)** — エラーコード、リカバリー戦略
* **[認証](/docs/building/by-layer/L2/authentication)** — 本番の認証情報のセットアップ