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

    Class AgentClient

    Index

    Constructors

    constructor

    Methods

    getAdcpVersion fromMCPClient handleWebhook verifyWebhookSignature getProducts listCreativeFormats createMediaBuy updateMediaBuy syncCreatives listCreatives getMediaBuys getMediaBuyDelivery providePerformanceFeedback getSignals activateSignal getAdcpCapabilities getCapabilities getIdempotencyReplayTtlSeconds requireSupportedMajor requireV3 previewCreative buildCreative listAccounts syncAccounts syncAudiences createPropertyList getPropertyList updatePropertyList listPropertyLists deletePropertyList listContentStandards getContentStandards calibrateContent validateContentDelivery siGetOffering siInitiateSession siSendMessage siTerminateSession continueConversation getHistory clearContext resetContext getContextId getPendingTaskId setContextId getAgent getAgentId getAgentName getProtocol getCanonicalUrl resolveCanonicalUrl isSameAgent isSameAgentResolved getResolvedAgent getAgentInfo hasActiveConversation getActiveTasks executeTask listTasks getTaskInfo onTaskUpdate onTaskEvents getWebhookUrl registerWebhook unregisterWebhook

    Constructors

    Methods

    • Create an AgentClient backed by a pre-connected MCP Client instead of an HTTP endpoint. Useful for in-process compliance testing without spinning up a loopback HTTP server.

      MCP only. This factory wraps an MCP Client from @modelcontextprotocol/sdk. There is no equivalent in-process bridge for A2A today — for A2A agents, run them on a loopback HTTP server and use the standard AgentClient constructor with the agent's agent_uri.

      What this gives you over dispatchTestRequest: All client-side pipeline stages still apply — idempotency key auto-injection, request/response schema validation hooks, governance middleware, and the typed TaskResult<T> discriminated-union response shape. None of these apply when calling dispatchTestRequest() directly.

      Usage:

      import { Client } from '@modelcontextprotocol/sdk/client/index.js';
      import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
      import { AgentClient } from '@adcp/sdk';

      const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
      const mcpClient = new Client({ name: 'test', version: '1.0.0' });
      await Promise.all([
        mcpClient.connect(clientTransport),
        adcpServer.connect(serverTransport),
      ]);

      const agent = AgentClient.fromMCPClient(mcpClient, {
        validation: { requests: 'strict' },
      });
      const result = await agent.createMediaBuy({ ... });

      Unsupported methods on in-process instances: resolveCanonicalUrl, getWebhookUrl, registerWebhook, unregisterWebhook — these require HTTP and will throw Error with a descriptive message. Use getAgentId() / getAgentName() for identification instead.

      Parameters

      • mcpClient: Client

        An already-connected MCP Client (see example above).

      • config: InProcessAgentClientConfig = {}

        Optional narrowed config. HTTP-only fields are excluded.

      Returns AgentClient

    • Handle webhook from agent (async task completion or notifications)

      Parameters

      • payload: MCPWebhookPayload | Task | TaskStatusUpdateEvent

        Webhook payload from agent

      • 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

        Optional signature for verification (X-ADCP-Signature)

      • Optionaltimestamp: string | number

        Optional timestamp for verification (X-ADCP-Timestamp)

      • OptionalrawBody: string

      Returns Promise<boolean>

      Whether webhook was handled successfully

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

      Prefer passing the raw HTTP body string for correct cross-language interop. Passing a parsed object still works but re-serializes with JSON.stringify, which may not match the sender's byte representation.

      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

    • Return the seller's declared adcp.idempotency.replay_ttl_seconds, or throw when a v3 seller omits the (required) declaration.

      Returns undefined for v2 agents — v2 pre-dates the idempotency envelope.

      Returns Promise<number | undefined>

    • Assert that the seller's capabilities corroborate this client's pinned AdCP major (per getAdcpVersion()). Throws VersionUnsupportedError otherwise. Set ADCP_ALLOW_V2=1 to bypass.

      Parameters

      • taskType: string = 'request'

      Returns Promise<void>

    • Continue the conversation with a natural language message

      Type Parameters

      • T = any

      Parameters

      • message: string

        Natural language message to send to the agent

      • OptionalinputHandler: InputHandler

        Handler for any clarification requests

      • Optionaloptions: TaskOptions

      Returns Promise<TaskResult<T>>

      const agent = multiClient.agent('my-agent');
      await agent.getProducts({ brief: 'Tech products' });

      // Continue the conversation
      const refined = await agent.continueConversation(
        'Focus only on laptops under $1000'
      );

    • Clear the conversation context (start fresh).

      Equivalent to resetContext() — clears both the retained contextId and any pending server-side taskId, and drops cached history.

      Returns void

    • Reset conversation state. Call with no args to start a fresh conversation; pass a seed to rehydrate a persisted session id (e.g., across a process restart).

      Always clears the retained pending-task handle — a persisted contextId places the next send into the same server-side session, but any old taskId is stale.

      Parameters

      • Optionalseed: string

      Returns void

    • Get the pending server-side taskId from the last non-terminal response, if any. Populated when the server returned input-required / working / submitted / auth-required; cleared when the task reaches a terminal state.

      Persist this alongside getContextId() if you need to resume a specific task (not just a conversation) across a process restart.

      Returns string | undefined

    • Get the canonical base URL for this agent

      Returns the canonical URL if already resolved, or computes it synchronously. For guaranteed canonical URL (especially for A2A), use resolveCanonicalUrl() first.

      Returns string

    • Resolve and return the canonical base URL for this agent

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

      Not supported on in-process instances (created via fromMCPClient). Use getAgentId() / getAgentName() for identification instead.

      Returns Promise<string>

    • Get agent information including capabilities

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

    • Get detailed information about a specific task

      Parameters

      • taskId: string

      Returns Promise<TaskInfo | null>

    • Subscribe to task notifications for this agent

      Parameters

      • callback: (task: TaskInfo) => void

      Returns () => void

    • Subscribe to all task events

      Parameters

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

      Returns () => void

    • Generate webhook URL for a specific task and operation.

      Not supported on in-process instances (created via fromMCPClient). In-process clients have no HTTP listener to receive webhook callbacks.

      Parameters

      • taskType: string
      • operationId: string

      Returns string

    • Register webhook for task notifications.

      Not supported on in-process instances (created via fromMCPClient).

      Parameters

      • webhookUrl: string
      • OptionaltaskTypes: string[]

      Returns Promise<void>

    • Unregister webhook notifications.

      Not supported on in-process instances (created via fromMCPClient).

      Returns Promise<void>

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods
    getAdcpVersionfromMCPClienthandleWebhookverifyWebhookSignaturegetProductslistCreativeFormatscreateMediaBuyupdateMediaBuysyncCreativeslistCreativesgetMediaBuysgetMediaBuyDeliveryprovidePerformanceFeedbackgetSignalsactivateSignalgetAdcpCapabilitiesgetCapabilitiesgetIdempotencyReplayTtlSecondsrequireSupportedMajorrequireV3previewCreativebuildCreativelistAccountssyncAccountssyncAudiencescreatePropertyListgetPropertyListupdatePropertyListlistPropertyListsdeletePropertyListlistContentStandardsgetContentStandardscalibrateContentvalidateContentDeliverysiGetOfferingsiInitiateSessionsiSendMessagesiTerminateSessioncontinueConversationgetHistoryclearContextresetContextgetContextIdgetPendingTaskIdsetContextIdgetAgentgetAgentIdgetAgentNamegetProtocolgetCanonicalUrlresolveCanonicalUrlisSameAgentisSameAgentResolvedgetResolvedAgentgetAgentInfohasActiveConversationgetActiveTasksexecuteTasklistTasksgetTaskInfoonTaskUpdateonTaskEventsgetWebhookUrlregisterWebhookunregisterWebhook