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

    Interface SingleAgentClientConfig

    Configuration for SingleAgentClient (and multi-agent client)

    interface SingleAgentClientConfig {
        maxHistorySize?: number;
        persistConversations?: boolean;
        workingTimeout?: number;
        defaultMaxClarifications?: number;
        adcpVersion?:
            | "v3"
            | "3.0.12"
            | "v2.5"
            | "v2.6"
            | "3.0.0-beta.1"
            | "3.0.0-beta.3"
            | "3.1.0-beta.1"
            | "3.0.0"
            | "3.0.1"
            | "3.0.2"
            | "3.0.3"
            | "3.0.4"
            | "3.0.5"
            | "3.0.6"
            | "3.0.7"
            | "3.0.8"
            | "3.0.9"
            | "3.0.10"
            | "3.0.11"
            | string & {};
        debug?: boolean;
        userAgent?: string;
        headers?: Record<string, string>;
        onActivity?: (activity: Activity) => void | Promise<void>;
        handlers?: AsyncHandlerConfig;
        webhookSecret?: string;
        webhookUrlTemplate?: string;
        reportingWebhookFrequency?: "hourly" | "daily" | "monthly";
        validateFeatures?: boolean;
        requireV3ForMutations?: boolean;
        allowV2?: boolean;
        validation?: {
            requests?: ValidationMode;
            responses?: ValidationMode;
            strictSchemaValidation?: boolean;
            logSchemaViolations?: boolean;
            filterInvalidProducts?: boolean;
        };
        governance?: GovernanceConfig;
        transport?: TransportOptions;
    }

    Hierarchy (View Summary)

    Index

    Properties

    maxHistorySize? persistConversations? workingTimeout? defaultMaxClarifications? adcpVersion? debug? userAgent? headers? onActivity? handlers? webhookSecret? webhookUrlTemplate? reportingWebhookFrequency? validateFeatures? requireV3ForMutations? allowV2? validation? governance? transport?

    Properties

    maxHistorySize?: number

    Maximum messages to keep in history

    persistConversations?: boolean

    Whether to persist conversations

    workingTimeout?: number

    Timeout for 'working' status (max 120s per PR #78)

    defaultMaxClarifications?: number

    Default max clarifications

    adcpVersion?:
        | "v3"
        | "3.0.12"
        | "v2.5"
        | "v2.6"
        | "3.0.0-beta.1"
        | "3.0.0-beta.3"
        | "3.1.0-beta.1"
        | "3.0.0"
        | "3.0.1"
        | "3.0.2"
        | "3.0.3"
        | "3.0.4"
        | "3.0.5"
        | "3.0.6"
        | "3.0.7"
        | "3.0.8"
        | "3.0.9"
        | "3.0.10"
        | "3.0.11"
        | string & {}

    AdCP protocol version this client speaks to agents. Defaults to ADCP_VERSION — the GA version the SDK ships against. Override to pin to an older stable (e.g., '3.0.0') or opt into a beta channel ('3.1.0-beta.1') once that registry ships.

    Stage 2 plumbs the option through and validates it at construction time; cross-major pins (e.g. '4.0.0-beta.1' while the SDK ships against major 3) throw ConfigurationError. Stage 3 wires per-instance schema/validator selection off this field.

    Typed as AdcpVersion | (string & {}) so editors autocomplete canonical values from COMPATIBLE_ADCP_VERSIONS while still accepting forward-compatible strings.

    debug?: boolean

    Enable debug logging

    userAgent?: string

    Custom User-Agent header sent with all outbound protocol requests. Overridden by per-agent headers['User-Agent'] if set.

    headers?: Record<string, string>

    Additional headers to include in requests

    onActivity?: (activity: Activity) => void | Promise<void>

    Activity callback for observability (logging, UI updates, etc)

    handlers?: AsyncHandlerConfig

    Task completion handlers — called for both sync responses and webhook completions.

    For at-least-once webhook delivery, set handlers.webhookDedup to drop duplicate retries by idempotency_key. See docs/guides/PUSH-NOTIFICATION-CONFIG.md#deduplication.

    webhookSecret?: string

    Webhook secret for signature verification (recommended for production)

    webhookUrlTemplate?: string

    Webhook URL template with macro substitution

    Available macros:

    • {agent_id} - Agent ID
    • {task_type} - Task type (e.g., sync_creatives, media_buy_delivery)
    • {operation_id} - Operation ID
    Path-based: "https://myapp.com/webhook/{task_type}/{agent_id}/{operation_id}"
    Query string: "https://myapp.com/webhook?agent={agent_id}&op={operation_id}&type={task_type}"
    Custom: "https://myapp.com/api/v1/adcp/{agent_id}?operation={operation_id}"
    reportingWebhookFrequency?: "hourly" | "daily" | "monthly"

    Reporting webhook frequency

    'daily'
    validateFeatures?: boolean

    Validate that the seller supports required features before each task call. When true, tasks like syncAudiences will fail fast with FeatureUnsupportedError if the seller hasn't declared audience_targeting support.

    true
    requireV3ForMutations?: boolean

    Gate mutating-task dispatch on the seller's declared major version. When the seller returns an authoritative get_adcp_capabilities response, the guard requires:

    1. major_versions includes 3
    2. adcp.idempotency.replay_ttl_seconds is declared (spec-required)

    Sellers whose capabilities are synthesized from tools/list (no authoritative get_adcp_capabilities response) route through the v2 adapter with a one-time warning — a compliant v3 seller would declare itself, so absence of a declaration is read as v2. Adopters who need a hard "definitely-v3" gate should validate (await client.getCapabilities())._synthetic === false directly.

    Throws VersionUnsupportedError before the request is sent when the guard rejects. Bypass with allowV2 or — process-wide as a fallback — ADCP_ALLOW_V2=1.

    false
    allowV2?: boolean

    Per-client bypass for the v3 guard. When true, the guard is off regardless of the ADCP_ALLOW_V2 env var. When undefined, the env var is consulted as a fallback. Set explicitly in multi-tenant deployments so one tenant's override can't silently disable safety for another.

    validation?: {
        requests?: ValidationMode;
        responses?: ValidationMode;
        strictSchemaValidation?: boolean;
        logSchemaViolations?: boolean;
        filterInvalidProducts?: boolean;
    }

    Runtime schema validation options

    Type Declaration

    • Optionalrequests?: ValidationMode

      Validate outgoing requests against the bundled AdCP JSON schema before dispatch. Catches field-name drift at call-time instead of at storyboard-time.

      • strict: throw ValidationError with a JSON Pointer to the bad field
      • warn: log to debug logs and continue
      • off: skip the validator entirely (no overhead)

      strict in dev/test, warn in production

    • Optionalresponses?: ValidationMode

      Validate incoming responses against the bundled AdCP JSON schema.

      • strict: fail the task with VALIDATION_ERROR
      • warn: log to debug logs and surface the task as successful
      • off: skip the validator entirely

      Overrides strictSchemaValidation when set.

      strict in dev/test, warn in production

    • OptionalstrictSchemaValidation?: boolean

      Legacy: fail tasks when response schema validation fails (default: true). Superseded by responses above — retained for backward compat. false maps to responses: 'warn' when responses isn't set.

      true
    • OptionallogSchemaViolations?: boolean

      Log all schema validation violations to debug logs (default: true)

      true
    • OptionalfilterInvalidProducts?: boolean

      Filter out invalid products from get_products responses instead of rejecting the entire response (default: false)

      When true: Each product in a get_products response is validated individually. Valid products are kept, invalid products are dropped, and the response is returned as long as it passes full schema validation after filtering. When false: The entire response is rejected if any product fails validation.

      Only applies to get_products — all other tool responses use standard validation.

      false
    governance?: GovernanceConfig

    Governance configuration for buyer-side campaign governance

    transport?: TransportOptions

    Transport-level safeguards. Applies to every call this client dispatches unless overridden at call time.

    Set maxResponseBytes when crawling untrusted agents (registries, federated discovery layers) to prevent a hostile vendor from buffering a large reply before any application-layer schema validation runs.

    Settings

    Member Visibility

    On This Page

    Properties