@adcp/sdk API Reference - v7.9.0
    Preparing search index...

    Class SingleAgentClient

    Index

    Constructors

    constructor

    Methods

    getAdcpVersion handleWebhook getWebhookUrl createWebhookHandler verifyWebhookSignature getProducts listCreativeFormats createMediaBuy updateMediaBuy syncCreatives listCreatives previewCreative getMediaBuys getMediaBuyDelivery providePerformanceFeedback getSignals activateSignal syncPlans getPlanAuditLogs reportGovernanceOutcome getAdcpCapabilities buildCreative listAccounts syncAccounts syncAudiences createPropertyList getPropertyList updatePropertyList listPropertyLists deletePropertyList listContentStandards getContentStandards calibrateContent validateContentDelivery siGetOffering siInitiateSession siSendMessage siTerminateSession executeTask resumeDeferredTask continueConversation getConversationHistory clearConversationHistory getAgent getResolvedAgent getAgentId getAgentName getProtocol getCanonicalUrl resolveCanonicalUrl isSameAgent isSameAgentResolved getActiveTasks listTasks getTaskInfo onTaskUpdate onTaskEvents registerWebhook unregisterWebhook getAgentInfo getCapabilities detectServerVersion isSyntheticV2 supportsVersion getIdempotencyReplayTtlSeconds supports require refreshCapabilities requireSupportedMajor requireV3 discoverCreativeFormats

    Constructors

    Methods

    • Returns the AdCP protocol version this client is configured to speak.

      Defaults to ADCP_VERSION (the GA version the SDK ships against) unless overridden via new SingleAgentClient(agent, { adcpVersion }).

      Plumbing surface — Stage 2 of the multi-version refactor exposes the configured value but does not yet vary validator/schema selection by version. Wire-shape adapters key off this method in subsequent stages.

      Returns string

    • Handle webhook from agent (async task status updates and completions)

      Accepts webhook payloads from both MCP and A2A protocols:

      1. MCP: MCPWebhookPayload envelope with AdCP data in .result field
      2. A2A: Native Task/TaskStatusUpdateEvent with AdCP data in either:
        • status.message.parts[].data (for status updates)
        • artifacts (for task completion, per A2A spec)

      The method normalizes both formats so handlers receive the unwrapped AdCP response data (AdCPAsyncResponseData), not the raw protocol structure.

      Parameters

      • payload: MCPWebhookPayload | Task | TaskStatusUpdateEvent

        Protocol-specific webhook payload (MCPWebhookPayload | Task | TaskStatusUpdateEvent)

      • taskType: string

        Task type (e.g create_media_buy) from url param or url part of the webhook delivery

      • operationId: string

        Operation id (e.g used for client app to track the operation) from the param or url part of the webhook delivery

      • Optionalsignature: string

        X-ADCP-Signature header (format: "sha256=...")

      • Optionaltimestamp: string | number

        X-ADCP-Timestamp header (Unix timestamp)

      • OptionalrawBody: string

      Returns Promise<boolean>

      Whether webhook was handled successfully

      app.post('/webhook/:taskType', async (req, res) => {
        const signature = req.headers['x-adcp-signature'];
        const timestamp = req.headers['x-adcp-timestamp'];

        try {
          const handled = await client.handleWebhook(req.body, signature, timestamp, req.params.taskType);
          res.status(200).json({ received: handled });
        } catch (error) {
          res.status(401).json({ error: error.message });
        }
      });

    • Generate webhook URL using macro substitution

      Parameters

      • taskType: string

        Type of task (e.g., 'get_products', 'media_buy_delivery')

      • operationId: string

        Operation ID for this request

      Returns string

      Full webhook URL with macros replaced

      // With template: "https://myapp.com/webhook/{task_type}/{agent_id}/{operation_id}"
      const webhookUrl = client.getWebhookUrl('sync_creatives', 'op_123');
      // Returns: https://myapp.com/webhook/sync_creatives/agent_x/op_123

      // With template: "https://myapp.com/webhook?agent={agent_id}&op={operation_id}"
      const webhookUrl = client.getWebhookUrl('sync_creatives', 'op_123');
      // Returns: https://myapp.com/webhook?agent=agent_x&op=op_123

    • Create an HTTP webhook handler that automatically verifies signatures

      This helper creates a standard HTTP handler (Express/Next.js/etc.) that:

      • Extracts X-ADCP-Signature and X-ADCP-Timestamp headers
      • Verifies HMAC signature (if webhookSecret configured)
      • Validates timestamp freshness
      • Calls handleWebhook() with proper error handling

      Returns (
          req: {
              headers: Record<string, string | undefined>;
              body: unknown;
              params?: Record<string, string>;
          },
          res: {
              status: (code: number) => { json: (body: unknown) => void };
              json?: unknown;
              writeHead: (code: number, headers: Record<string, string>) => void;
              end: (body: string) => void;
          },
      ) => Promise<void>

      HTTP handler function compatible with Express, Next.js, etc.

      const client = new ADCPClient(agent, {
        webhookSecret: 'your-secret-key',
        handlers: {
          onSyncCreativesStatusChange: async (result) => {
            console.log('Creative synced:', result);
          }
        }
      });

      app.post('/webhook', client.createWebhookHandler());

      export default client.createWebhookHandler();

    • Verify webhook signature using HMAC-SHA256 per AdCP spec.

      HMAC is computed over the raw HTTP body bytes — the exact bytes received on the wire, before JSON parsing. This ensures cross-language interop since different JSON serializers may produce different byte representations of the same logical payload.

      For backward compatibility, a parsed object is still accepted but will be re-serialized with JSON.stringify, which may not match the sender's bytes. Always prefer passing the raw body string.

      Signature format: sha256={hex_signature} Message format: {timestamp}.{raw_body}

      Parameters

      • rawBodyOrPayload: unknown

        Raw HTTP body string (preferred) or parsed payload object (deprecated)

      • signature: string

        X-ADCP-Signature header value (format: "sha256=...")

      • timestamp: string | number

        X-ADCP-Timestamp header value (Unix timestamp)

      Returns boolean

      true if signature is valid

    • Report a governance outcome for an async task that has resolved.

      Use this when a task returned status 'submitted' or 'working' and later resolves via polling or webhooks. The checkId is available on the original TaskResult at result.governance.checkId.

      Parameters

      • checkId: string
      • outcome: OutcomeType
      • OptionalgovernanceContext: string
      • OptionalsellerResponse: Record<string, unknown>
      • Optionalerror: { code?: string; message: string }

      Returns Promise<GovernanceOutcome | undefined>

    • Execute any task by name with type safety

      Type Parameters

      • T = any

      Parameters

      • taskName: string

        Name of the task to execute

      • params: any

        Task parameters

      • OptionalinputHandler: InputHandler

        Handler for clarification requests

      • Optionaloptions: TaskOptions

        Task execution options

      Returns Promise<TaskResult<T>>

      const result = await client.executeTask(
        'get_products',
        { brief: 'Coffee brands' },
        handler
      );

    • Resume a deferred task using its token

      Type Parameters

      • T = any

      Parameters

      • token: string

        Deferred task token

      • inputHandler: InputHandler

        Handler to provide the missing input

      Returns Promise<TaskResult<T>>

      try {
        await client.createMediaBuy(params, handler);
      } catch (error) {
        if (error instanceof DeferredTaskError) {
          // Get human input and resume
          const result = await client.resumeDeferredTask(
            error.token,
            (context) => humanProvidedValue
          );
        }
      }

    • Continue an existing conversation with the agent

      Type Parameters

      • T = any

      Parameters

      • message: string

        Message to send to the agent

      • contextId: string

        Conversation context ID to continue

      • OptionalinputHandler: InputHandler

        Handler for any clarification requests

      Returns Promise<TaskResult<T>>

      const agent = new ADCPClient(config);
      const initial = await agent.getProducts({ brief: 'Tech products' });

      // Continue the conversation — use the server-returned contextId, not
      // the client-minted correlation taskId.
      const refined = await agent.continueConversation(
        'Focus only on laptops under $1000',
        initial.metadata.contextId!
      );

    • Get the agent configuration with normalized protocol

      Returns the agent config with:

      • Protocol normalized (e.g., .well-known URLs switch to A2A)
      • If canonical URL has been resolved, agent_uri will be the canonical URL

      For guaranteed canonical URL, use getResolvedAgent() instead.

      Returns AgentConfig

    • Get the fully resolved agent configuration

      This async method ensures the agent config has the canonical URL resolved:

      • For A2A: Fetches the agent card and uses its 'url' field
      • For MCP: Performs endpoint discovery

      Returns Promise<AgentConfig>

      Promise resolving to agent config with canonical URL

    • Get the canonical base URL for this agent

      Returns the canonical URL if already resolved, or computes it synchronously from the configured URL. For the most accurate canonical URL (especially for A2A where the agent card contains the authoritative URL), use resolveCanonicalUrl() first.

      The canonical URL is:

      • For A2A: The 'url' field from the agent card (if resolved), or base URL with the well-known agent card path stripped
      • For MCP: The discovered endpoint with /mcp stripped

      Returns string

      The canonical base URL (synchronous, may not be fully resolved)

    • Resolve and return the canonical base URL for this agent

      This async method ensures the canonical URL is properly resolved:

      • For A2A: Fetches the agent card and uses its 'url' field
      • For MCP: Performs endpoint discovery and strips /mcp suffix

      The result is cached, so subsequent calls are fast.

      Returns Promise<string>

      Promise resolving to the canonical base URL

    • Check if this agent is the same as another agent

      Compares agents by their canonical base URLs. Two agents are considered the same if they have the same canonical URL, regardless of:

      • Protocol (MCP vs A2A)
      • URL format (with/without /mcp, with/without well-known agent card path)
      • Trailing slashes

      Parameters

      Returns boolean

      true if agents have the same canonical URL

    • Async version of isSameAgent that resolves canonical URLs first

      This provides more accurate comparison for A2A agents since it fetches the agent card to get the authoritative canonical URL.

      Parameters

      Returns Promise<boolean>

      Promise resolving to true if agents have the same canonical URL

    • List all tasks for this agent with detailed information

      Returns Promise<TaskInfo[]>

      Promise resolving to array of task information

      const tasks = await client.listTasks();
      tasks.forEach(task => {
        console.log(`${task.taskName}: ${task.status}`);
      });

    • Get detailed information about a specific task

      Parameters

      • taskId: string

        ID of the task to get information for

      Returns Promise<TaskInfo | null>

      Promise resolving to task information

    • Subscribe to task notifications for this agent

      Parameters

      • callback: (task: TaskInfo) => void

        Function to call when task status changes

      Returns () => void

      Unsubscribe function

      const unsubscribe = client.onTaskUpdate((task) => {
        console.log(`Task ${task.taskName} is now ${task.status}`);
        if (task.status === 'completed') {
          // Handle completion
        }
      });

      // Later, stop listening
      unsubscribe();

    • Subscribe to all task events (create, update, complete, error)

      Parameters

      • callbacks: {
            onTaskCreated?: (task: TaskInfo) => void;
            onTaskUpdated?: (task: TaskInfo) => void;
            onTaskCompleted?: (task: TaskInfo) => void;
            onTaskFailed?: (task: TaskInfo, error: string) => void;
        }

        Event callbacks for different task events

      Returns () => void

      Unsubscribe function

    • Register webhook URL for receiving task notifications

      Parameters

      • webhookUrl: string

        URL to receive webhook notifications

      • OptionaltaskTypes: string[]

        Optional array of task types to watch (defaults to all)

      Returns Promise<void>

      await client.registerWebhook('https://myapp.com/webhook', ['create_media_buy']);

    • Get comprehensive agent information including name, description, and available tools/skills

      Works with both MCP (tools) and A2A (skills) protocols to discover what the agent can do.

      Auth resolution: this method forwards agent.headers as customHeaders to the MCP transport so header-only auth (HTTP Basic via gateways like Apigee/Kong, x-api-key, custom tenant routing) reaches the precheck path. The invariant — basic-auth credentials live entirely on headers.Authorization; do not also set auth_token — is documented at docs/guides/BASIC-AUTH.md. See #1864 for the failure mode if it's violated.

      Returns Promise<
          {
              name: string;
              description?: string;
              protocol: "mcp"
              | "a2a";
              url: string;
              tools: {
                  name: string;
                  description?: string;
                  inputSchema?: Record<string, unknown>;
                  parameters?: string[];
              }[];
          },
      >

      Promise resolving to agent information including tools

      const client = new ADCPClient(agentConfig);
      const info = await client.getAgentInfo();

      console.log(`${info.name}: ${info.description}`);
      console.log(`Supports ${info.tools.length} tools`);

      info.tools.forEach(tool => {
        console.log(`  - ${tool.name}: ${tool.description}`);
      });

    • Get agent capabilities, including AdCP version support

      For v3 servers, calls get_adcp_capabilities tool. For v2 servers, builds synthetic capabilities from available tools.

      Returns Promise<AdcpCapabilities>

      Promise resolving to normalized capabilities object

      const capabilities = await client.getCapabilities();

      console.log(`Server version: ${capabilities.version}`);
      console.log(`Protocols: ${capabilities.protocols.join(', ')}`);

      if (capabilities.features.propertyListFiltering) {
        // Use v3 property list features
      }

    • Whether the seller's capabilities are synthesized from tools/list with no authoritative get_adcp_capabilities response — i.e. the dispatcher routes through the v2 adapter and idempotency-TTL is unknown. Use this to gate retry behavior for sellers whose retry safety can't be derived from declared capabilities (lower attempt caps, longer backoff, or fall back to natural-key recovery).

      Returns false for declared v2 sellers, declared v3 sellers, and synthetic v3 sellers (which advertise the v3 discovery tool even when the call itself failed).

      Caveat for synthetic v3: the predicate returns false, but TTL is still unknown for those sellers — getIdempotencyReplayTtlSeconds() throws until the agent's capabilities endpoint is fixed (issue #1217). Retry-policy consumers that need a complete "TTL unknown" gate should additionally check getCapabilities()._synthetic.

      Returns Promise<boolean>

    • Check if server supports a specific AdCP major version

      Parameters

      • version: 2 | 3

      Returns Promise<boolean>

    • Return the seller's declared adcp.idempotency.replay_ttl_seconds.

      BYOK callers use this to compare the age of persisted keys against the seller's replay window — past the window, the safe recovery is a natural-key lookup rather than reusing the key.

      Fails closed when the seller is v3 but does not declare the field: the spec makes the declaration REQUIRED, and silently defaulting to 24h would mislead buyers about retry safety. Callers on v2 servers get undefined instead of a throw — v2 pre-dates the idempotency envelope.

      Returns Promise<number | undefined>

    • Check if the seller supports a feature.

      Feature names resolve as follows:

      • Protocol names ('media_buy', 'signals', etc.) check supported_protocols
      • 'ext:' checks extensions_supported
      • 'targeting.' checks media_buy.execution.targeting
      • Other names check media_buy.features (e.g., 'audience_targeting', 'conversion_tracking')

      Absent features return false.

      Parameters

      • feature: string

      Returns Promise<boolean>

    • Require that the seller supports all listed features. Throws FeatureUnsupportedError if any are missing.

      Call this before making feature-dependent task calls to fail fast with an actionable error message.

      Parameters

      • ...features: string[]

      Returns Promise<void>

    • Assert that the seller's capabilities corroborate the major this client is pinned to (per getAdcpVersion()).

      A self-reported version: 'v3' is not enough — a hostile or misconfigured seller can just string-claim the version. For sellers that return an authoritative get_adcp_capabilities response, the guard requires:

      1. capabilities.majorVersions.includes(<this client's major>)
      2. capabilities.idempotency.replayTtlSeconds present (spec-required for real major-3+ sellers)

      Sellers whose capabilities are synthesized from tools/list (no authoritative get_adcp_capabilities response) are treated as v2: a compliant v3 seller would declare itself, so absence of a declaration is taken as evidence of v2. The dispatcher routes the request through the v2 wire-shape adapter. A one-time warning surfaces the routing decision so adopters can audit it; retry-safety (idempotency TTL) is unknown for these sellers and BYOK callers should treat them as such.

      Per-client allowV2: true or, when that's undefined, ADCP_ALLOW_V2=1 in the environment bypasses the guard entirely.

      Throws VersionUnsupportedError with the specific reason on failure.

      Parameters

      • taskType: string = 'request'

      Returns Promise<void>

    • Deprecated alias for requireSupportedMajor. Original name from the AdCP v2/v3 split; the function generalized in Stage 3 to check the client's per-instance major instead of hardcoded 3, and requireV3 stopped reflecting what the function actually does.

      Parameters

      • taskType: string = 'request'

      Returns Promise<void>

      Use requireSupportedMajor() instead.

    • Query a creative agent to discover available creative formats

      This is a static utility method that allows you to query any creative agent (like creative.adcontextprotocol.org) to discover what formats are available before creating a media buy.

      Parameters

      Returns Promise<Format[]>

      Promise resolving to the list of available formats

      // Discover formats from the standard creative agent
      const formats = await SingleAgentClient.discoverCreativeFormats(
        'https://creative.adcontextprotocol.org/mcp'
      );

      // Find a specific format
      const banner = formats.find(f => f.format_id.id === 'display_300x250_image');

      // Use the format in a media buy
      await salesAgent.createMediaBuy({
        packages: [{
          format_ids: [{
            agent_url: banner.format_id.agent_url,
            id: banner.format_id.id
          }]
        }]
      });

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods
    getAdcpVersionhandleWebhookgetWebhookUrlcreateWebhookHandlerverifyWebhookSignaturegetProductslistCreativeFormatscreateMediaBuyupdateMediaBuysyncCreativeslistCreativespreviewCreativegetMediaBuysgetMediaBuyDeliveryprovidePerformanceFeedbackgetSignalsactivateSignalsyncPlansgetPlanAuditLogsreportGovernanceOutcomegetAdcpCapabilitiesbuildCreativelistAccountssyncAccountssyncAudiencescreatePropertyListgetPropertyListupdatePropertyListlistPropertyListsdeletePropertyListlistContentStandardsgetContentStandardscalibrateContentvalidateContentDeliverysiGetOfferingsiInitiateSessionsiSendMessagesiTerminateSessionexecuteTaskresumeDeferredTaskcontinueConversationgetConversationHistoryclearConversationHistorygetAgentgetResolvedAgentgetAgentIdgetAgentNamegetProtocolgetCanonicalUrlresolveCanonicalUrlisSameAgentisSameAgentResolvedgetActiveTaskslistTasksgetTaskInfoonTaskUpdateonTaskEventsregisterWebhookunregisterWebhookgetAgentInfogetCapabilitiesdetectServerVersionisSyntheticV2supportsVersiongetIdempotencyReplayTtlSecondssupportsrequirerefreshCapabilitiesrequireSupportedMajorrequireV3discoverCreativeFormats