Aller au contenu principal
OrbiAds logo — infrastructure AdOps IA pour Google Ad Manager OrbiAds
Série A2A · 4 / 4

Parler le standard AdCP avec un agent :
valider & prévisualiser un media buy

AdCP (Ad Context Protocol) est le standard d'achat. OrbiAds l'expose nativement : un agent acheteur envoie une requête create_media_buy, l'agent OrbiAds la valide puis la prévisualise en deal GAM — 100 % lecture seule.

OA
OrbiAds Engineering
Publié le 30 juin 2026 · Lecture 9 min

Dernier épisode. Jusqu'ici, nos agents lisaient Google Ad Manager. Ici, on parle le standard d'achat : AdCP (Ad Context Protocol). Un agent acheteur envoie une requête create_media_buy ; l'agent OrbiAds la valide puis la prévisualise en deal GAM, sans rien écrire.

AdCP est natif chez OrbiAds (ne hand-rollez rien)

Le réflexe à éviter : fabriquer un « brief JSON maison ». OrbiAds expose déjà une surface AdCP complète. Les outils vivent sous des tools parents (pattern parent → action) :

CapacitéAppelType
Discovery côté venteproducts → get_products_adcplecture
Valider un create_media_buydeals(action='adcp_validate')lecture
Traduire en DealSpec (sans exécuter)deals(action='adcp_preview')lecture
Exécuter de bout en boutdeals(action='adcp_create')écriture

La requête AdCP (create_media_buy)

Voici à quoi ressemble une demande d'achat envoyée par un agent acheteur :

sample_adcp_request.json
{
  "idempotency_key": "demo-mediabuy-0001-acme-q3",
  "account": { "account_id": "demo-buyer-seat-001", "sandbox": true },
  "brand": { "domain": "acme.com", "industries": ["retail"] },
  "start_time": "2026-09-01T00:00:00Z",
  "end_time": "2026-09-30T23:59:59Z",
  "packages": [
    {
      "package_id": "pkg-homepage-fr-1",
      "budget": 5000.0,
      "impressions": 1000000,
      "targeting_overlay": { "geo_countries": ["FR"], "language": ["fr"] }
    }
  ],
  "ext": {
    "orbiads_deal_type": "pg_guaranteed",
    "orbiads_buyer_account_id": "demo-authorized-buyer-seat"
  }
}

Le cas A2A : un gateway read-only

L'agent adcp_gateway reçoit la requête (d'un agent acheteur ou de l'utilisateur), puis : (1) check_credentials + network check, (2) deals(adcp_validate), (3) si valide, deals(adcp_preview), (4) un résumé lisible. Il n'appelle jamais adcp_create.

Agent AdCP : validate puis preview read-only
AdCP natif : l'agent valide la requête (deals(adcp_validate)) puis la prévisualise en deal GAM (deals(adcp_preview)) — read-only, rien n'est écrit. L'erreur actionnable ADCP_ADVERTISER_UNRESOLVED montre la traduction vers GAM en action.

Trois freins à connaître

  • Filtrage par nom, pas par action. Le tool_filter ne peut pas isoler une action : exposer deals expose aussi l'écriture. Garde-fous = le prompt (autoriser seulement validate/preview) + le confirmation_token d'OrbiAds.
  • Lookup d'annonceur réel. adcp_preview résout la marque dans GAM. Sans correspondance → ADCP_ADVERTISER_UNRESOLVED : fournir ext.orbiads_advertiser_company_id.
  • Choix du modèle. Un gros JSON AdCP imbriqué peut faire « coder » l'appel à certains modèles légers ; un modèle plus costaud fiabilise. C'est l'approche qu'on valide, le modèle reste un paramètre.

Conclusion de la série

En quatre épisodes : on a connecté un agent à GAM (OAuth), on l'a déployé et rendu découvrable en A2A, composé un cas métier multi-agents, et fait parler le standard AdCP. Le fil rouge : tout repose sur une connexion propre et des garde-fous (lecture seule, network check, confirmation_token). Le reste est de la composition.

Pour aller plus loin

Le code complet, prêt à cloner

Les 4 agents, le tutoriel pas à pas et les exemples — sur GitHub, sous licence MIT.

Voir le repo GitHub Revenir à l'article 1
FAQ

Questions fréquentes

Qu'est-ce qu'AdCP (Ad Context Protocol) ?

AdCP est un standard ouvert qui décrit, en JSON, une demande d'achat média (create_media_buy) qu'un agent acheteur envoie à un vendeur. OrbiAds le supporte nativement et le traduit en deals Google Ad Manager — inutile d'inventer un format de brief maison.

Quels outils AdCP OrbiAds expose-t-il ?

Sous le tool parent deals : adcp_validate (valide le payload contre le schéma v3, lecture seule), adcp_preview (traduit la requête en DealSpec sans exécuter, lecture seule), adcp_create (exécute de bout en bout, écriture). Côté vente, products → get_products_adcp fait la discovery des produits au format AdCP.

Comment garantir un agent AdCP en lecture seule ?

Le tool_filter de l'ADK filtre par nom de tool, pas par action — exposer deals expose donc aussi adcp_create (écriture). On s'appuie sur (a) l'instruction de l'agent qui n'autorise que adcp_validate/adcp_preview, et (b) le garde-fou d'OrbiAds : adcp_create refuse de s'exécuter sans confirmation_token issu d'un preview. Pour un read-only strict, il faudrait un scope serveur dédié.

Pourquoi le preview renvoie ADCP_ADVERTISER_UNRESOLVED ?

Parce que adcp_preview fait un vrai lookup d'annonceur dans GAM. Si la marque (brand.domain) ne correspond à aucun annonceur, il renvoie cette erreur actionnable : fournissez ext.orbiads_advertiser_company_id (l'ID GAM Company). C'est le comportement attendu, pas un bug.