AdCP — sync_governance

Sync governance agent endpoints to specific accounts. The seller persists these agents and calls them via check_governance during media buy lifecycle events. Each account entry pairs an account reference with the governance agents for that account, supporting both explicit accounts (account_id) and implicit accounts (brand + operator). This uses replace semantics — each call replaces any previously registered agents on the specified accounts. Accounts not included in the request keep their existing configuration. Response Time: ~1s. Request Schema: /schemas/3.0.19/account/sync-governance-request.json Response Schema: /schemas/3.0.19/account/sync-governance-response.json

Quick Start

Sync a budget governance agent to an explicit account:

import { testAgent } from "@adcp/client/testing";
import { SyncGovernanceResponseSchema } from "@adcp/client";

const result = await testAgent.syncGovernance({
  accounts: [
    {
      account: { account_id: "acct-social-001" },
      governance_agents: [
        {
          url: "https://governance.pinnacle-media.com/budget",
          authentication: {
            schemes: ["Bearer"],
            credentials: "gov-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          },
          categories: ["budget_authority"]
        }
      ]
    }
  ]
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = SyncGovernanceResponseSchema.parse(result.data);

if ("errors" in validated && validated.errors) {
  throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}

for (const entry of validated.accounts) {
  if (entry.status === "synced") {
    console.log(`${JSON.stringify(entry.account)}: ${entry.governance_agents.length} agents registered`);
  } else {
    console.log(`${JSON.stringify(entry.account)}: failed — ${JSON.stringify(entry.errors)}`);
  }
}

import asyncio
from adcp.testing import test_agent

async def main():
    result = await test_agent.simple.sync_governance(
        accounts=[
            {
                "account": {"account_id": "acct-social-001"},
                "governance_agents": [
                    {
                        "url": "https://governance.pinnacle-media.com/budget",
                        "authentication": {
                            "schemes": ["Bearer"],
                            "credentials": "gov-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
                        },
                        "categories": ["budget_authority"]
                    }
                ]
            }
        ]
    )

    if hasattr(result, 'errors') and result.errors:
        raise Exception(f"Operation failed: {result.errors}")

    for entry in result.accounts:
        if entry.status == "synced":
            print(f"{entry.account}: {len(entry.governance_agents)} agents registered")
        else:
            print(f"{entry.account}: failed — {entry.errors}")

asyncio.run(main())

Request Parameters

Parameter	Type	Required	Description
`accounts`	array	Yes	Per-account governance agent entries. Each pairs an account reference with governance agents for that account.

Each account entry:

Field	Type	Required	Description
`account`	object	Yes	Account reference: `{account_id}` for explicit accounts or `{brand, operator}` for implicit accounts.
`governance_agents`	array	Yes	Governance agent endpoints for this account (1–10 per account).

Each governance agent:

Field	Type	Required	Description
`url`	string	Yes	HTTPS endpoint URL for the governance agent.
`authentication`	object	Yes	Credentials the seller presents when calling this agent. Contains `schemes` (array with one auth scheme) and `credentials` (token, min 32 characters).
`categories`	array	No	Governance categories this agent handles (e.g., `["budget_authority", "geo_compliance"]`). When omitted, the agent handles all categories. Max 20 categories, each max 64 characters.

Response

Success response: Returns an accounts array with per-account results. Individual entries may fail even when the operation succeeds.

Field	Description
`account`	Account reference, echoed from request.
`status`	`"synced"` or `"failed"`.
`governance_agents`	Governance agents now active on this account. Reflects persisted state. Only present when `status: "synced"`.
`errors`	Per-account errors. Only present when `status: "failed"`.

Error response: errors array with operation-level errors (auth failure, service unavailable). No accounts array is present.

Authorization

The seller MUST verify that the authenticated agent has authority over each referenced account before persisting governance agents. Requests referencing accounts the agent does not own MUST return a failed status with an error for those entries.

Common Scenarios

Different governance agents per account

import { testAgent } from "@adcp/client/testing";
import { SyncGovernanceResponseSchema } from "@adcp/client";

const result = await testAgent.syncGovernance({
  accounts: [
    {
      account: { account_id: "acct-social-001" },
      governance_agents: [
        {
          url: "https://governance.pinnacle-media.com/budget",
          authentication: {
            schemes: ["Bearer"],
            credentials: "gov-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          },
          categories: ["budget_authority"]
        }
      ]
    },
    {
      account: { account_id: "acct-social-002" },
      governance_agents: [
        {
          url: "https://governance.pinnacle-media.com/compliance",
          authentication: {
            schemes: ["Bearer"],
            credentials: "gov-token-yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
          },
          categories: ["geo_compliance"]
        }
      ]
    }
  ]
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = SyncGovernanceResponseSchema.parse(result.data);

if ("errors" in validated && validated.errors) {
  throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}

for (const entry of validated.accounts) {
  console.log(`${JSON.stringify(entry.account)}: ${entry.status}`);
}

import asyncio
from adcp.testing import test_agent

async def main():
    result = await test_agent.simple.sync_governance(
        accounts=[
            {
                "account": {"account_id": "acct-social-001"},
                "governance_agents": [
                    {
                        "url": "https://governance.pinnacle-media.com/budget",
                        "authentication": {
                            "schemes": ["Bearer"],
                            "credentials": "gov-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
                        },
                        "categories": ["budget_authority"]
                    }
                ]
            },
            {
                "account": {"account_id": "acct-social-002"},
                "governance_agents": [
                    {
                        "url": "https://governance.pinnacle-media.com/compliance",
                        "authentication": {
                            "schemes": ["Bearer"],
                            "credentials": "gov-token-yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
                        },
                        "categories": ["geo_compliance"]
                    }
                ]
            }
        ]
    )

    if hasattr(result, 'errors') and result.errors:
        raise Exception(f"Operation failed: {result.errors}")

    for entry in result.accounts:
        print(f"{entry.account}: {entry.status}")

asyncio.run(main())

Implicit accounts (brand + operator)

{
  "$schema": "https://adcontextprotocol.org/schemas/3.0.19/account/sync-governance-request.json",
  "idempotency_key": "e5b9f2c3-1234-48a0-1234-56789012345e",
  "accounts": [
    {
      "account": {
        "brand": { "domain": "nova-brands.com", "brand_id": "spark" },
        "operator": "pinnacle-media.com"
      },
      "governance_agents": [
        {
          "url": "https://governance.pinnacle-media.com/compliance",
          "authentication": {
            "schemes": ["Bearer"],
            "credentials": "gov-token-yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
          },
          "categories": ["geo_compliance", "strategic_alignment"]
        }
      ]
    }
  ]
}

Rotate governance agent credentials

Call sync_governance again with updated authentication. Replace semantics means the new credentials overwrite the previous configuration.

Error Handling

Error Code	Description	Resolution
`ACCOUNT_NOT_FOUND`	Referenced account does not exist or is not accessible	Verify account reference via `list_accounts` or `sync_accounts`
`UNAUTHORIZED`	Agent does not have authority over the referenced account	Check that you are authenticated as an agent with access to this account

Next Steps

list_accounts — Discover accounts and their current governance agents
sync_accounts — Provision or link advertiser accounts
check_governance — How sellers call governance agents during media buy events
Accounts and agents — Account models, billing, and trust

Getting Started

Building with AdCP

Protocol

FAQ

Trust & Security

Reference

Certification

sync_governance

Quick Start

Request Parameters

Response

Authorization

Common Scenarios

Different governance agents per account

Implicit accounts (brand + operator)

Rotate governance agent credentials

Error Handling

Next Steps

​Quick Start

​Request Parameters

​Response

​Authorization

​Common Scenarios

​Different governance agents per account

​Implicit accounts (brand + operator)

​Rotate governance agent credentials

​Error Handling

​Next Steps

Quick Start

Request Parameters

Response

Authorization

Common Scenarios

Different governance agents per account

Implicit accounts (brand + operator)

Rotate governance agent credentials

Error Handling

Next Steps