キャンペーン要件に基づき、自然言語のブリーフまたは構造化フィルターで利用可能な広告プロダクトを検索します。
Authentication : 任意(認証なしの場合は結果が制限されます)
Response Time : 約 60 秒(バックエンド連携を伴う推論)
Request Schema : /schemas/v2/media-buy/get-products-request.json
Response Schema : /schemas/v2/media-buy/get-products-response.json
クイックスタート
自然言語のブリーフでプロダクトを検索:
import { testAgent } from '@adcp/client/testing' ;
import { GetProductsResponseSchema } from '@adcp/client' ;
const result = await testAgent . getProducts ({
brief: 'Premium athletic footwear with innovative cushioning' ,
brand_manifest: {
name: 'Nike' ,
url: 'https://nike.com'
}
});
if ( ! result . success ) {
throw new Error ( `Request failed: ${ result . error } ` );
}
// Validate response against schema
const validated = GetProductsResponseSchema . parse ( result . data );
console . log ( `Found ${ validated . products . length } products` );
// Access validated product fields
for ( const product of validated . products ) {
console . log ( `- ${ product . name } ( ${ product . delivery_type } )` );
console . log ( ` Formats: ${ product . format_ids . map ( f => f . id ). join ( ', ' ) } ` );
}
構造化フィルターの利用
ブリーフの代わりに(または併用して)構造化フィルターを使うこともできます。
import { testAgent } from '@adcp/client/testing' ;
const result = await testAgent . getProducts ({
brand_manifest: {
name: 'Nike' ,
url: 'https://nike.com'
},
filters: {
format_types: [ 'video' ],
delivery_type: 'guaranteed' ,
standard_formats_only: true
}
});
if ( result . success && result . data ) {
console . log ( `Found ${ result . data . products . length } guaranteed video products` );
}
リクエストパラメーター
Parameter Type Required Description briefstring No キャンペーン要件の自然言語説明。プロポーザルのリファイン時は “ドイツ語話者に重きを置いて” のような指示も記述可。 proposal_idstring No リファイン対象のプロポーザル ID。ブリーフと併用した場合、ブリーフを指示として解釈し更新されたプロポーザルを返す。 brand_manifestBrandManifest | string No ブランド情報(インラインまたは URL)。Brand Manifest 参照 filtersFilters No 構造化フィルター(後述) property_listPropertyListRef No [AdCP 3.0] 絞り込みに用いるプロパティリスト参照。Property Lists 参照
Filters オブジェクト
Parameter Type Description delivery_typestring "guaranteed" または "non_guaranteed" でフィルタリングis_fixed_priceboolean 固定価格かオークションかでフィルタリング format_typesstring[] フォーマット種別でフィルタリング(例: ["video", "display"]) format_idsFormatID[] 特定のフォーマット ID でフィルタリング standard_formats_onlyboolean IAB 標準フォーマットを受け付けるプロダクトのみ返す min_exposuresinteger 計測妥当性に必要な最小エクスポージャ数 start_datestring 可用性確認のための開始日 (ISO 8601, YYYY-MM-DD) end_datestring 可用性確認のための終了日 (ISO 8601, YYYY-MM-DD) budget_rangeobject 適切なプロダクトを絞る予算レンジ(下記 Budget Range 参照) countriesstring[] ISO 3166-1 alpha-2 コードで国を指定(大文字/小文字は不問。例: ["US", "CA", "GB"]) channelsstring[] 広告チャンネルでフィルタリング(例: ["display", "ctv", "social", "streaming_audio"])。Media Channel Taxonomy 参照
Budget Range オブジェクト
Parameter Type Required Description currencystring Yes ISO 4217 通貨コード(例: "USD", "EUR", "GBP") minnumber No* 最低予算額 maxnumber No* 最高予算額
*At least one of min or max must be specified.
レスポンス
products 配列と、必要に応じて proposals を返します。
Products 配列
Field Type Description product_idstring プロダクトの一意 ID namestring 人が読めるプロダクト名 descriptionstring プロダクトの詳細説明 publisher_propertiesPublisherProperty[] パブリッシャーごとのエントリ。publisher_domain と property_ids または property_tags を含む format_idsFormatID[] サポートするクリエイティブフォーマット ID delivery_typestring "guaranteed" または "non_guaranteed"delivery_measurementDeliveryMeasurement 配信の計測方法(インプレッション、ビュー等) pricing_optionsPricingOption[] 利用可能な価格モデル(CPM、CPCV など) brief_relevancestring ブリーフに合致する理由(ブリーフ提供時)
Proposals 配列(任意)
パブリッシャーはプロダクトと併せてプロポーザル(予算配分付きの構造化メディアプラン)を返すことがあります。詳細は Proposals を参照。
Field Type Description proposal_idstring このプロポーザルを実行/リファインするための一意 ID namestring メディアプランの人が読める名称 allocationsProductAllocation[] プロダクト間の予算配分(合計 100% 必須) total_budget_guidanceobject 最小/推奨/最大の予算ガイダンス(任意) brief_alignmentstring キャンペーンブリーフへの対応内容 expires_atstring プロポーザルの有効期限 (ISO 8601)
レスポンスメタデータ
Field Type Description property_list_appliedboolean [AdCP 3.0] 提供された property_list に基づきフィルタした場合 true。未指定または非対応なら省略/false。
完全なフィールドはスキーマを参照 : get-products-response.json
よくあるシナリオ
スタンダードカタログの探索
import { testAgent } from '@adcp/client/testing' ;
// ブリーフなし = リーチ最大化のための標準カタログ
const result = await testAgent . getProducts ({
brand_manifest: {
name: 'Nike' ,
url: 'https://nike.com'
},
filters: {
delivery_type: 'non_guaranteed'
}
});
if ( result . success && result . data ) {
console . log ( `Found ${ result . data . products . length } standard catalog products` );
}
マルチフォーマット探索
import { testAgent } from '@adcp/client/testing' ;
// video と display の両方をサポートするプロダクトを探す
const result = await testAgent . getProducts ({
brief: 'Brand awareness campaign with video and display' ,
brand_manifest: {
name: 'Nike' ,
url: 'https://nike.com'
},
filters: {
format_types: [ 'video' , 'display' ]
}
});
if ( result . success && result . data ) {
console . log ( `Found ${ result . data . products . length } products supporting video and display` );
}
予算と日付でのフィルタリング
import { testAgent } from '@adcp/client/testing' ;
// 指定国とチャンネルで、予算と期間に収まるプロダクトを探す
const result = await testAgent . getProducts ({
brief: 'Q2 campaign for athletic footwear in North America' ,
brand_manifest: {
name: 'Nike' ,
url: 'https://nike.com'
},
filters: {
start_date: '2025-04-01' ,
end_date: '2025-06-30' ,
budget_range: {
min: 50000 ,
max: 100000 ,
currency: 'USD'
},
countries: [ 'US' , 'CA' ],
channels: [ 'display' , 'ctv' , 'podcast' ],
delivery_type: 'guaranteed'
}
});
if ( result . success && result . data ) {
console . log ( `Found ${ result . data . products . length } products for Q2 within budget` );
}
プロパティタグの解決
import { testAgent } from '@adcp/client/testing' ;
// property_tags を持つプロダクトを取得
const result = await testAgent . getProducts ({
brief: 'Sports content' ,
brand_manifest: {
name: 'Nike' ,
url: 'https://nike.com'
}
});
if ( result . success && result . data ) {
// publisher_properties に property_tags がある場合は大規模ネットワークを意味する
// エージェントのポートフォリオは get_adcp_capabilities で確認する
const productsWithTags = result . data . products . filter ( p =>
p . publisher_properties ?. some ( pub => pub . property_tags && pub . property_tags . length > 0 )
);
console . log ( ` ${ productsWithTags . length } products use property tags (large networks)` );
}
保証配信のプロダクト
import { testAgent } from '@adcp/client/testing' ;
// Find guaranteed delivery products for measurement
const result = await testAgent . getProducts ({
brief: 'Guaranteed delivery for lift study' ,
brand_manifest: {
name: 'Nike' ,
url: 'https://nike.com'
},
filters: {
delivery_type: 'guaranteed' ,
min_exposures: 100000
}
});
if ( result . success && result . data ) {
console . log ( `Found ${ result . data . products . length } guaranteed products with 100k+ exposures` );
}
標準フォーマットのみ
import { testAgent } from '@adcp/client/testing' ;
// IAB 標準フォーマットのみ受け付けるプロダクトを探す
const result = await testAgent . getProducts ({
brand_manifest: {
name: 'Nike' ,
url: 'https://nike.com'
},
filters: {
standard_formats_only: true
}
});
if ( result . success && result . data ) {
console . log ( `Found ${ result . data . products . length } products with standard formats only` );
}
プロパティリストでのフィルタリング
AdCP 3.0 - プロパティリストでのフィルタリングにはガバナンスエージェントの対応が必要です。
承認済みリストのプロパティで利用できるプロダクトだけに絞ります。
JavaScript
Python test=false
import { testAgent } from '@adcp/client/testing' ;
// Filter products by property list from governance agent
const result = await testAgent . getProducts ({
brief: 'Brand-safe inventory for family brand' ,
brand_manifest: {
name: 'Nike' ,
url: 'https://nike.com'
},
property_list: {
agent_url: 'https://governance.example.com' ,
list_id: 'pl_brand_safe_2024'
}
});
if ( result . success && result . data ) {
// フィルタが適用されたか確認
if ( result . data . property_list_applied ) {
console . log ( `Found ${ result . data . products . length } products on approved properties` );
} else {
console . log ( 'Agent does not support property list filtering' );
console . log ( `Found ${ result . data . products . length } products (unfiltered)` );
}
}
Note : If property_list_applied is absent or false, the sales agent did not filter products. This can happen if:
The agent doesn’t support property governance features
The agent couldn’t access the property list
The property list had no effect on the available inventory
See Property Governance for more on property lists.
Error Handling
Error Code Description Resolution AUTH_REQUIREDAuthentication needed for full catalog Provide credentials via auth header INVALID_REQUESTBrief too long or malformed filters Check request parameters POLICY_VIOLATIONCategory blocked for advertiser See policy response message for details
Authentication Comparison
See the difference between authenticated and unauthenticated access:
import { testAgent , testAgentNoAuth } from '@adcp/client/testing' ;
// WITH authentication - full catalog with pricing
const fullCatalog = await testAgent . getProducts ({
brief: 'Premium CTV inventory for brand awareness' ,
brand_manifest: {
name: 'Nike' ,
url: 'https://nike.com'
}
});
if ( ! fullCatalog . success ) {
throw new Error ( `Failed to get products: ${ fullCatalog . error } ` );
}
console . log ( `With auth: ${ fullCatalog . data . products . length } products` );
console . log ( `First product pricing: ${ fullCatalog . data . products [ 0 ]. pricing_options . length } options` );
// WITHOUT authentication - limited public catalog
const publicCatalog = await testAgentNoAuth . getProducts ({
brief: 'Premium CTV inventory for brand awareness' ,
brand_manifest: {
name: 'Nike' ,
url: 'https://nike.com'
}
});
if ( ! publicCatalog . success ) {
throw new Error ( `Failed to get products: ${ publicCatalog . error } ` );
}
console . log ( `Without auth: ${ publicCatalog . data . products . length } products` );
console . log ( `First product pricing: ${ publicCatalog . data . products [ 0 ]. pricing_options ?. length || 0 } options` );
Key Differences:
Product Count : Authenticated access returns more products, including private/custom offerings
Pricing Information : Only authenticated requests receive detailed pricing options (CPM, CPCV, etc.)
Targeting Details : Custom targeting capabilities may be restricted to authenticated users
Rate Limits : Unauthenticated requests have lower rate limits
Authentication Behavior
Without credentials : Returns limited catalog (standard catalog products), no pricing, no custom offerings
With credentials : Returns complete catalog with pricing and custom products
See Authentication Guide for details.
Asynchronous Operations
Most product searches complete immediately, but some scenarios require asynchronous processing. When this happens, you’ll receive a status other than completed and can track progress through webhooks or polling.
When Search Runs Asynchronously
Product search may require async processing in these situations:
Complex searches : Searching across multiple inventory sources or custom curation
Needs clarification : Your brief is vague and the system needs more information
Custom products : Bespoke product packages that require human review
Async Status Flow
即時完了(最も一般的) POST /api/mcp/call_tool
{
"name" : "get_products" ,
"arguments" : {
"brief" : "CTV inventory for sports audience" ,
"brand_manifest" : { "name" : "Nike" , "url" : "https://nike.com" }
}
}
Response ( 200 OK):
{
"status" : "completed" ,
"message" : "Found 3 products matching your requirements" ,
"data" : {
"products" : [ ... ]
}
}
Needs Clarification When the brief is unclear, the system asks for more details: Response ( 200 OK):
{
"status" : "input-required" ,
"message" : "I need a bit more information. What's your budget range and campaign duration?" ,
"task_id" : "task_789" ,
"context_id" : "ctx_123" ,
"data" : {
"reason" : "CLARIFICATION_NEEDED" ,
"partial_results" : [],
"suggestions" : [ "$50K-$100K" , "1 month" , "Q1 2024" ]
}
}
Continue the conversation with the same context_id: POST /api/mcp/continue
{
"context_id" : "ctx_123" ,
"message" : "Budget is $75K for a 3-week campaign in March"
}
Response ( 200 OK):
{
"status" : "completed" ,
"message" : "Perfect! Found 5 products within your budget" ,
"data" : {
"products" : [ ... ]
}
}
Complex Search (With Webhook) For searches requiring deep inventory analysis, configure a webhook: POST /api/mcp/call_tool
{
"name" : "get_products" ,
"arguments" : {
"brief" : "Premium inventory across all formats for luxury automotive brand" ,
"brand_manifest" : { "name" : "Porsche" , "url" : "https://porsche.com" },
"pushNotificationConfig" : {
"url" : "https://buyer.com/webhooks/adcp/get_products" ,
"authentication" : {
"schemes" : [ "Bearer" ],
"credentials" : "secret_token_32_chars"
}
}
}
}
Response ( 200 OK):
{
"status" : "working" ,
"message" : "Searching premium inventory across display, video, and audio" ,
"task_id" : "task_456" ,
"context_id" : "ctx_123" ,
"data" : {
"percentage" : 10 ,
"current_step" : "searching_inventory"
}
}
// Later, webhook POST to https://buyer.com/webhooks/adcp/get_products
{
"task_id" : "task_456" ,
"task_type" : "get_products" ,
"status" : "completed" ,
"timestamp" : "2025-01-22T10:30:00Z" ,
"message" : "Found 12 premium products across all formats" ,
"result" : {
"products" : [ ... ]
}
}
POST /api/a 2 a
{
"message" : {
"role" : "user" ,
"parts" : [{
"kind" : "data" ,
"data" : {
"skill" : "get_products" ,
"parameters" : {
"brief" : "CTV inventory for sports audience" ,
"brand_manifest" : { "name" : "Nike" , "url" : "https://nike.com" }
}
}
}]
}
}
Response ( 200 OK):
{
"id" : "task_123" ,
"contextId" : "ctx_456" ,
"artifact" : {
"kind" : "data" ,
"data" : {
"products" : [ ... ]
}
},
"status" : {
"state" : "completed" ,
"message" : {
"role" : "agent" ,
"parts" : [{ "text" : "Found 3 products matching your requirements" }]
}
}
}
追加確認が必要な場合 確認が必要な場合、SSE でリアルタイム更新を受け取ります。 // Initial response
{
"id" : "task_789" ,
"contextId" : "ctx_123" ,
"status" : {
"state" : "input-required" ,
"message" : {
"role" : "agent" ,
"parts" : [
{ "text" : "I need a bit more information. What's your budget range and campaign duration?" },
{
"data" : {
"reason" : "CLARIFICATION_NEEDED" ,
"suggestions" : [ "$50K-$100K" , "1 month" , "Q1 2024" ]
}
}
]
}
}
}
// 追いメッセージを送る
POST /api/a 2 a
{
"contextId" : "ctx_123" ,
"message" : {
"role" : "user" ,
"parts" : [{ "text" : "Budget is $75K for a 3-week campaign in March" }]
}
}
// SSE 更新: タスク完了
{
"id" : "task_789" ,
"contextId" : "ctx_123" ,
"artifact" : {
"kind" : "data" ,
"data" : { "products" : [ ... ] }
},
"status" : {
"state" : "completed" ,
"message" : {
"role" : "agent" ,
"parts" : [{ "text" : "Perfect! Found 5 products within your budget" }]
}
}
}
複雑な検索(Webhook 併用) 長時間かかる検索ではプッシュ通知を設定します。 POST /api/a 2 a
{
"message" : {
"role" : "user" ,
"parts" : [{
"kind" : "data" ,
"data" : {
"skill" : "get_products" ,
"parameters" : {
"brief" : "Premium inventory across all formats for luxury automotive brand" ,
"brand_manifest" : { "name" : "Porsche" , "url" : "https://porsche.com" }
}
}
}]
},
"pushNotificationConfig" : {
"url" : "https://buyer.com/webhooks/a2a/get_products" ,
"authentication" : {
"schemes" : [ "bearer" ],
"credentials" : "secret_token_32_chars"
}
}
}
Response ( 200 OK):
{
"id" : "task_456" ,
"contextId" : "ctx_789" ,
"status" : {
"state" : "working" ,
"message" : {
"role" : "agent" ,
"parts" : [
{ "text" : "Searching premium inventory across display, video, and audio" },
{
"data" : {
"percentage" : 10 ,
"current_step" : "searching_inventory"
}
}
]
}
}
}
// 後で https://buyer.com/webhooks/a2a/get_products に Webhook POST が届く
{
"id" : "task_456" ,
"contextId" : "ctx_789" ,
"artifact" : {
"kind" : "data" ,
"data" : {
"products" : [ ... ]
}
},
"status" : {
"state" : "completed" ,
"message" : {
"role" : "agent" ,
"parts" : [
{ "text" : "Found 12 premium products across all formats" },
{
"data" : {
"products" : [ ... ]
}
}
]
},
"timestamp" : "2025-01-22T10:30:00Z"
}
}
ステータス概要
Status 発生タイミング 対応 completed検索が正常完了 プロダクト結果を処理 input-requiredブリーフに追加確認が必要 質問に回答して続行 working複数ソースを検索中 Webhook を待つかポーリング submittedカスタムキュレーションがキュー入り Webhook 通知を待つ failed検索を完了できなかった エラーメッセージを確認しブリーフ調整
Note: 完全なステータス一覧は Task Lifecycle を参照。
ほとんどの検索は即時完了します。 非同期処理が必要なのは複雑なケースや追加入力が必要な場合のみです。
次のステップ
プロダクトを見つけたら:
選択肢を確認 : プロダクト、価格、ターゲティング能力を比較
メディアバイ作成 : create_media_buy でキャンペーンを実行
クリエイティブ準備 : list_creative_formats で要件を確認
アセットアップロード : sync_creatives でアセットを提供
さらに学ぶ