sync_governance

sync_governance syncs governance agent endpoints to specific accounts. The seller persists these agents and calls them via check_governance during media buy lifecycle events.

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/latest/account/sync-governance-request.json Response Schema: /schemas/latest/account/sync-governance-response.json

Quick Start

Sync a budget governance agent to an explicit account:

JavaScript

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)}`);
  }
}

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

JavaScript

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}`);
}

Implicit accounts (brand + operator)

Request

{
  "$schema": "https://adcontextprotocol.org/schemas/latest/account/sync-governance-request.json",
  "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