> ## 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.

# 呼び出し元を構築する

> AdCP バイヤーとデマンドサイドアプリケーションのためのクライアント側ガイド。SDK をインストール、エージェントのケイパビリティを発見、呼び出し、非同期レスポンスとエラーを処理、レポートを取り込む。数か月ではなく数週間のハンドラーグルー。

**バイ側** — DSP、プランニングツール、エージェンティッククライアント、またはプラン、購入、レポートのために AdCP エージェントを呼ぶ任意のアプリケーション — を構築しているなら、ここから始めてください。呼び出し元側の L0–L3 は、エージェント側が要求する [3〜4 人月のビルド](/docs/building/cross-cutting/sdk-stack#why-sdks-matter-more-in-adcp-than-in-eg-http) ではなく、数週間のハンドラーグルーです。あなたの言語のフルスタック SDK が L0–L3 を運びます。あなたは呼び出しロジック、レスポンス処理、そしてアプリケーションがデータで何をするかを書きます。

<Note>
  **仕様レベルのリファレンス対ビルド形式ガイド。** このページはビルドを順に案内します。ワイヤーレベルの不変条件 — すべての変更呼び出しに適用されるすべてのルール — は [AdCP エージェントの呼び出し](/docs/protocol/calling-an-agent) にあります。本番に行く前に一度読んでください。ワイヤー形状エラーをデバッグするときはいつでも参照してください。
</Note>

<Tip>
  **ライブエージェントに対して試す。** AAO は `https://test-agent.adcontextprotocol.org` でパブリックテストエージェントを、ドメインごとのエンドポイント — `/sales/mcp`、`/creative/mcp`、`/signals/mcp`、`/governance/mcp` — で実行します。クライアントを一致するエンドポイントに向けると `getAdcpCapabilities()` が認証なしで機能します。実際のセラーに向ける前にインストールを検証するために使ってください。
</Tip>

## SDK をインストール

サーバープリミティブを出荷する同じ SDK が呼び出しクライアントも出荷します。1 つをインストールすれば両方を持ちます。

<Tabs>
  <Tab title="JavaScript/TypeScript">
    ```bash theme={null}
    npm install @adcp/sdk
    ```

    ```typescript theme={null}
    import { createSingleAgentClient } from '@adcp/sdk';

    const client = createSingleAgentClient({
      id: 'sales',
      name: 'Sales agent',
      agent_uri: 'https://sales.example.com/mcp',
      protocol: 'mcp',
    });
    ```

    マルチエージェントファンアウト（1 つのクライアントが並列で多くのセラーを駆動）には、代わりに `ADCPMultiAgentClient` を使います — 同じ呼び出しサーフェス、エージェント id でインデックス化。

    * [NPM Package](https://www.npmjs.com/package/@adcp/sdk)
    * [GitHub Repository](https://github.com/adcontextprotocol/adcp-client)
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install adcp
    ```

    ```python theme={null}
    from adcp import ADCPClient, AgentConfig, Protocol

    client = ADCPClient(AgentConfig(
        id="sales",
        agent_uri="https://sales.example.com/mcp",
        protocol=Protocol.MCP,
    ))
    ```

    * [PyPI Package](https://pypi.org/project/adcp/)
    * [GitHub Repository](https://github.com/adcontextprotocol/adcp-client-python)
  </Tab>

  <Tab title="Go">
    ```bash theme={null}
    go get github.com/adcontextprotocol/adcp-go/adcp
    ```

    Go 呼び出しサーフェスは活発に開発中です。現在のカバレッジについては [adcp-go README](https://github.com/adcontextprotocol/adcp-go) を参照。
  </Tab>
</Tabs>

## 認証する

ほとんどのエージェントは、`get_adcp_capabilities` を超えた何かに応答する前に認証情報を要求します。SDK は構築時に認証を受け入れます:

<Tabs>
  <Tab title="Bearer / API key">
    ```typescript theme={null}
    const client = createSingleAgentClient({
      id: 'sales',
      name: 'Sales agent',
      agent_uri: 'https://sales.example.com/mcp',
      protocol: 'mcp',
      auth_token: process.env.ADCP_API_KEY,
    });
    ```
  </Tab>

  <Tab title="Signed requests (RFC 9421)">
    ```typescript theme={null}
    const client = createSingleAgentClient({
      id: 'sales',
      name: 'Sales agent',
      agent_uri: 'https://sales.example.com/mcp',
      protocol: 'mcp',
      signing: { keyId: 'your-key-id', privateKey: /* PEM or KMS handle */ },
    });
    ```
  </Tab>
</Tabs>

最初の呼び出しが 401 / `AUTH_REQUIRED` を返す場合、認証情報がエージェントに到達していません — リクエストペイロードではなくコンストラクターオプションを確認してください。完全な認証情報モデルについては [L1 セキュリティ実装プロファイル](/docs/building/by-layer/L1/security) を参照。

## 最初の呼び出し: エージェントを発見する

手動でツールを呼ぶ前に、エージェントに何をサポートするか尋ねます。

```typescript theme={null}
const capabilities = await client.getAdcpCapabilities();
// → { supported_protocols: [...], adcp_versions: [...], features: {...} }
```

`get_adcp_capabilities` はエージェントのプロトコルカバレッジ、AdCP バージョン範囲、機能フラグを返します。呼び出しをゲートするのに使ってください — `media_buy` が `supported_protocols` にないなら、このエージェントに対して `create_media_buy` を呼ばないでください。完全なレスポンス形状については [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities) リファレンスを参照。

ディスカバリーチェーンの残り（エージェントカード、`tools/list`、`get_schema`）については、[エージェントの呼び出しのディスカバリーチェーンセクション](/docs/protocol/calling-an-agent#discovery-chain) を参照。

## 呼び出しをする

クライアントの型付きメソッドは AdCP ツールに対応します。SDK は送信前にリクエストをバンドルされたスキーマに対して検証し、レスポンスを型付き値にパースします。

```typescript theme={null}
const products = await client.getProducts({
  brief: 'Video campaign for pet owners, 18–34, US, $50K monthly',
});

const buy = await client.createMediaBuy({
  idempotency_key: crypto.randomUUID(),
  account: { brand: { domain: 'acme.com' }, operator: 'sales.example' },
  packages: [/* … */],
});
```

最初の呼び出しで知っておく価値のある 2 つのこと:

* **論理操作ごとに新しい `idempotency_key` を生成。** リトライで同じキー → サーバーは同じレスポンスをリプレイ。失敗後の新しいキーは重複したバイを作る。[冪等性ルール](/docs/protocol/calling-an-agent#idempotency-replay-vs-new-operation) を参照。
* **`account` は判別された `oneOf`。** 1 つのバリアント（`sync_accounts` / `list_accounts` からの `{account_id}`、または自然キーとしての `{brand, operator}` — `brand.domain` はバイヤーのブランドドメイン、`operator` はセラーエージェントのデプロイホスト名または brand.json 識別子）を選び、その必須フィールドのみを送る。それらをマージすると両方で失敗。[`account` は `oneOf`](/docs/protocol/calling-an-agent#account-is-oneof--pick-exactly-one-variant) を参照。

## 3 つのレスポンス形状を扱う

すべての変更ツールは 3 つの形状の 1 つを返します。それらを明示的に扱ってください。

```typescript theme={null}
const response = await client.createMediaBuy({/* … */});

if ('errors' in response) {
  // Error: don't retry without fixing — read response.adcp_error.issues[]
  // for correctable failures (validation, oneOf, etc.)
} else if (response.status === 'submitted') {
  // Async: the work is queued, NOT done. The completion payload arrives
  // later — either via webhook (preferred) or by polling the AdCP task.
} else {
  // Sync success: response carries the completion payload directly.
  // (e.g., response.media_buy_id, response.packages)
}
```

SDK は非同期完了のため webhook に導きます。構築時に `webhookUrlTemplate` とステータス変更ハンドラーを設定します。SDK はインバウンド webhook をセラーの JWKS に対して検証し、同期レスポンスが運ぶのと同じ `result` 形状であなたのハンドラーを発火します — 下の [Webhook を受信する](#receive-webhooks) を参照。

webhook を使う代わりにポーリングしなければならない場合（例: ワンショットスクリプト内）、AdCP ポーリングサーフェスを呼びます: セラーがアドバタイズするとき `get_task_status`、そうでなければ 3.x のレガシー AdCP `tasks/get`。[エージェントの呼び出しの非同期レスポンスセクション](/docs/protocol/calling-an-agent#async-responses-status-submitted-means-queued) にワイヤーコントラクトがあります。

## エラーから回復する

レスポンスに `adcp_error` を見たら、`issues[]` を読み `recovery` に基づいて行動します:

```typescript theme={null}
const { code, recovery, issues } = response.adcp_error;

switch (recovery) {
  case 'correctable':
    // Buyer-side fix. Patch the JSON pointers from issues[], resend with
    // the SAME idempotency_key (fresh key = new operation).
    break;
  case 'transient':
    // Retry with the SAME idempotency_key. Same key on retry replays the
    // cached response if the work landed.
    break;
  case 'terminal':
    // Human action required. Don't retry.
    break;
}
```

`issues[]` は実行可能な部分です: 各エントリは JSON Pointer（`pointer`）、Ajv キーワード（`required`、`oneOf`、`enum` など）、そして — `oneOf` 失敗については — 各バリアントの必須フィールドをリストする `variants[]` 配列を持ちます。完全なエンベロープとリカバリーセマンティクスについては [エラーリカバリーセクション](/docs/protocol/calling-an-agent#error-recovery--read-issues) を参照。

## Webhook を受信する

非同期タスクについては、ポーリングまたは webhook 登録のいずれかができます。webhook は `include_result: true` を伴う AdCP タスクポーリングと同じ `result` ペイロードを配信します。SDK は、セラーの brand.json 経由で鍵を解決し、リプレイウィンドウを強制し、[webhook エラータクソノミー](/docs/building/by-layer/L1/security#webhook-error-taxonomy) の構造化エラーをサーフェスする RFC 9421 webhook 検証者（`@adcp/sdk/signing/server` の `createWebhookVerifier`）を出荷します。

マルチエージェントクライアントを `webhookUrlTemplate` とステータス変更ハンドラーで配線する（[@adcp/sdk README](https://github.com/adcontextprotocol/adcp-client#readme) 準拠）と、インバウンド webhook が検証され自動的にハンドラーにディスパッチされます — あなたの HTTP ルートはリクエストをクライアントに渡す 1 行です。

配線方法にかかわらずエンドポイントが満たさなければならないワイヤーレベルの要件（カバードコンポーネント、`content-digest` 強制、重複排除の規律）については、[L3 — Webhooks](/docs/building/by-layer/L3/webhooks#signature-verification) を参照。

## レポートを取り込む

レポートは読み取り専用で、他のすべてと同じ呼び出し/レスポンス形状に従います。所有するバイの配信を引き、ウィンドウ付きケイデンスで反復します:

```typescript theme={null}
const delivery = await client.getMediaBuyDelivery({
  media_buy_ids: ['mb_123', 'mb_456'],
  window: { start: '2026-05-01T00:00:00Z', end: '2026-05-02T00:00:00Z' },
});
```

パフォーマンス webhook をサポートするセラーについては、上に示した同じ webhook レシーバー経由でデルタを受け取ります。そうでなければレポートニーズに応じた任意のケイデンスでポーリングします。呼び出し元 L4 — 最適化、ペーシングアラート、アトリビューション結合、ダッシュボード — は型付き `delivery` オブジェクトの上のあなたのアプリケーションコードです。

## 書かずに済んだもの

呼び出し元側の L0–L3 が数週間のハンドラーグルーなのは、SDK が既に次を出荷したからです:

* **L0** — 型付きリクエストビルダー、レスポンスパーサー、バンドルされたスキーマに対するスキーマ検証。
* **L1** — アウトバウンド RFC 9421 署名（呼び出しごと）、インバウンド webhook 検証、鍵ローテーション。
* **L2** — エージェントレジストリルックアップ、エージェントカード公開、認証情報合成。
* **L3** — 非同期タスクポーリング、webhook レシーバー、冪等性キー生成ヘルパー、エラーリカバリー分類。

[SDK スタックリファレンス](/docs/building/cross-cutting/sdk-stack) が各層を分解します。[サーバー対クライアント比較表](/docs/building/cross-cutting/sdk-stack#server-vs-client-at-each-layer) がコスト非対称性の並列ビューです。

## 次は

* **[エージェントの呼び出し](/docs/protocol/calling-an-agent)** — 正準ワイヤーコントラクトリファレンス。本番に行く前に一度読む。
* **[Schemas](/docs/building/by-layer/L0/schemas)** — スキーマバンドル、型生成、バージョンピン留め。
* **[Webhooks](/docs/building/by-layer/L3/webhooks)** — プッシュ通知、署名、リトライ、信頼性パターン。
* **[Error handling](/docs/building/by-layer/L3/error-handling)** — エラーカテゴリー、コード、リカバリー分類。
* **[エージェントを検証する](/docs/building/verification/validate-your-agent)** — 呼び出し元側のワイヤー適合性のストーリーボードも存在する。呼び出しが機能したら実行する。

プロトコルごとのタスクリファレンス:

* [メディアバイタスクリファレンス](/docs/media-buy/task-reference/index)
* [クリエイティブタスクリファレンス](/docs/creative/task-reference)
* [シグナルタスクリファレンス](/docs/signals/tasks/get_signals)
* [ブランドプロトコルタスク](/docs/brand-protocol)