Documentation Index
Fetch the complete documentation index at: https://docs.adcontextprotocol.org/llms.txt
Use this file to discover all available pages before exploring further.
Sync the governance agent endpoint for specific accounts. The seller persists the agent and calls it via check_governance during media buy lifecycle events. Each account entry pairs an account reference with exactly one governance agent, supporting both explicit accounts (account_id) and implicit accounts (brand + operator).
An account binds to one governance agent that owns the full lifecycle. Authorization, delivery monitoring, and compliance are phases of the same evaluation against one plan, not specialisms held by separate authorities; specialist review (legal, brand safety, category) composes inside the governance agent rather than across multiple registrations. governance_agents is an array with maxItems: 1 because the array shape is the shape 3.0 shipped with — the constraint is load-bearing and not a staging post toward loosening. The envelope’s governance_context is singular below this layer; relaxing the cap would require a coordinated wire-shape change that is not planned. See One governance agent per account.
This uses replace semantics — each call replaces any previously registered agent on the specified accounts. Accounts not included in the request keep their existing configuration.
Response Time: ~1s.
Request Schema: /schemas/v3/account/sync-governance-request.json
Response Schema: /schemas/v3/account/sync-governance-response.json
Quick Start
Sync the governance agent for an explicit account:
import { testAgent } from "@adcp/sdk/testing";
import { SyncGovernanceResponseSchema } from "@adcp/sdk";
const result = await testAgent.syncGovernance({
accounts: [
{
account: { account_id: "acct-social-001" },
governance_agents: [
{
url: "https://governance.pinnacle-media.com",
authentication: {
schemes: ["Bearer"],
credentials: "gov-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
]
}
]
});
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} agent 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. |
| 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 endpoint for this account. Array with exactly one entry (minItems: 1, maxItems: 1). |
| 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). |
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". |
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
A single sync_governance call can register a distinct agent per account — each account still binds to exactly one agent, but accounts on the same call need not share it.
import { testAgent } from "@adcp/sdk/testing";
import { SyncGovernanceResponseSchema } from "@adcp/sdk";
const result = await testAgent.syncGovernance({
accounts: [
{
account: { account_id: "acct-social-001" },
governance_agents: [
{
url: "https://governance.pinnacle-media.com",
authentication: {
schemes: ["Bearer"],
credentials: "gov-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
]
},
{
account: { account_id: "acct-social-002" },
governance_agents: [
{
url: "https://governance.acme-buyer.com",
authentication: {
schemes: ["Bearer"],
credentials: "gov-token-yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
}
}
]
}
]
});
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)
{
"$schema": "https://adcontextprotocol.org/schemas/v3/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",
"authentication": {
"schemes": ["Bearer"],
"credentials": "gov-token-yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
}
}
]
}
]
}
Rotate governance agent credentials
Call sync_governance again with updated authentication. Replace semantics means the new credentials overwrite the previous configuration.
Migrating from pre-3.1 multi-agent registration
Earlier drafts of 3.0 allowed up to 10 governance agents per account with per-agent categories. 3.1 constrains governance_agents to exactly one entry and removes categories. Buyers that registered more than one agent against the previous shape MUST collapse to a single agent on their next sync_governance call; the seller’s persisted state is replaced. The new request schema rejects more than one agent outright, so no “mixed-mode” window exists.
Buyer-side collapse decision. Which of the previously-registered agents becomes the single agent is a buyer-internal decision — the protocol does not rank or recommend. Typical paths: (a) keep the agent with the broadest policy coverage (usually the budget/spend-authority agent) and fold specialist logic (legal, brand safety, regulatory review) into it as internal workflow; (b) deploy a new “front-door” governance agent that fans out to the previous specialists internally, and register only that agent; (c) keep the agent that was always the de facto governance surface and fold the others’ specialist review into it as internal workflow without re-registering them. Surface the internal decomposition to auditors via categories_evaluated and findings[].details on check responses so the audit trail retains what each internal reviewer contributed.
Seller-side. Sellers MAY, on first boot under the new schema, collapse previously-persisted multi-agent state to the first entry (ordered by original sync position) and log the migration to their audit trail. Sellers SHOULD surface a clear error to buyers whose next sync_governance call attempts to re-register multiple agents, pointing at this migration guidance.
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
