Interface SingleAgentClientConfig

Configuration for SingleAgentClient (and multi-agent client)

interface SingleAgentClientConfig {
    maxHistorySize?: number;
    persistConversations?: boolean;
    workingTimeout?: number;
    defaultMaxClarifications?: number;
    adcpVersion?:
        | "3.0"
        | string & {}
        | "v3"
        | "3.1.1"
        | "v2.5"
        | "v2.6"
        | "3.0.0-beta.1"
        | "3.0-beta.1"
        | "3.0-beta"
        | "3.0.0-beta.3"
        | "3.0-beta.3"
        | "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"
        | "3.0.12"
        | "3.1.0"
        | "3.1";
    wireAdcpVersion?: | "3.0"
    | string & {}
    | "v3"
    | "3.1.1"
    | "v2.5"
    | "v2.6"
    | "3.0.0-beta.1"
    | "3.0-beta.1"
    | "3.0-beta"
    | "3.0.0-beta.3"
    | "3.0-beta.3"
    | "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"
    | "3.0.12"
    | "3.1.0"
    | "3.1";
    versionEnvelope?: VersionEnvelopeMode;
    debug?: boolean;
    userAgent?: string;
    headers?: Record<string, string>;
    onActivity?: (activity: Activity) => void | Promise<void>;
    onTransportActivity?: TransportActivityHandler;
    handlers?: AsyncHandlerConfig;
    webhookSecret?: string;
    webhookUrlTemplate?: WebhookUrlTemplate;
    reportingWebhookFrequency?: "hourly" | "daily" | "monthly";
    validateFeatures?: boolean;
    requireV3ForMutations?: boolean;
    allowV2?: boolean;
    validation?: {
        requests?: ValidationMode;
        responses?: ValidationMode;
        strictSchemaValidation?: boolean;
        logSchemaViolations?: boolean;
        filterInvalidProducts?: boolean;
        rejectProductsWithoutPricingOptions?: boolean;
        productPropertyPolicy?: false | ClientProductPropertyPolicy;
    };
    governance?: GovernanceConfig;
    transport?: TransportOptions;
}

Hierarchy (View Summary)

ConversationConfig
- SingleAgentClientConfig
  - CreativeAgentClientConfig

Properties

`Optional`maxHistorySize

maxHistorySize?: number

Maximum messages to keep in history

`Optional`persistConversations

persistConversations?: boolean

Whether to persist conversations

`Optional`workingTimeout

workingTimeout?: number

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

`Optional`defaultMaxClarifications

defaultMaxClarifications?: number

Default max clarifications

`Optional`adcpVersion

adcpVersion?:
    | "3.0"
    | string & {}
    | "v3"
    | "3.1.1"
    | "v2.5"
    | "v2.6"
    | "3.0.0-beta.1"
    | "3.0-beta.1"
    | "3.0-beta"
    | "3.0.0-beta.3"
    | "3.0-beta.3"
    | "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"
    | "3.0.12"
    | "3.1.0"
    | "3.1"

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.

`Optional`wireAdcpVersion

wireAdcpVersion?:
    | "3.0"
    | string & {}
    | "v3"
    | "3.1.1"
    | "v2.5"
    | "v2.6"
    | "3.0.0-beta.1"
    | "3.0-beta.1"
    | "3.0-beta"
    | "3.0.0-beta.3"
    | "3.0-beta.3"
    | "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"
    | "3.0.12"
    | "3.1.0"
    | "3.1"

Optional wire-only AdCP version envelope override. Request/response validation still uses adcpVersion; protocol envelopes use this value.

`Optional`versionEnvelope

versionEnvelope?: VersionEnvelopeMode

Controls emission of AdCP version envelope fields. Defaults to auto. none is primarily for conformance harnesses that need to send a request exactly as authored, without SDK-managed version fields.

`Optional`debug

debug?: boolean

Enable debug logging

`Optional`userAgent

userAgent?: string

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

`Optional`headers

headers?: Record<string, string>

Additional headers to include in requests

`Optional`onActivity

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

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

`Optional`onTransportActivity

onTransportActivity?: TransportActivityHandler

Transport-level diagnostics callback for outbound HTTP requests.

Receives sanitized request/response/failure events from the SDK's protocol fetch layer. Header maps are allowlisted/redacted and URLs have credentials, query strings, and fragments stripped before emission.

`Optional`handlers

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.

`Optional`webhookSecret

webhookSecret?: string

Webhook secret for signature verification (recommended for production)

`Optional`webhookUrlTemplate

webhookUrlTemplate?: WebhookUrlTemplate

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

Example

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}"

`Optional`reportingWebhookFrequency

reportingWebhookFrequency?: "hourly" | "daily" | "monthly"

Reporting webhook frequency

Default

'daily'

`Optional`validateFeatures

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.

Default

true

`Optional`requireV3ForMutations

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:

major_versions includes 3
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.

Default

false

`Optional`allowV2

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.

`Optional`validation

validation?: {
    requests?: ValidationMode;
    responses?: ValidationMode;
    strictSchemaValidation?: boolean;
    logSchemaViolations?: boolean;
    filterInvalidProducts?: boolean;
    rejectProductsWithoutPricingOptions?: boolean;
    productPropertyPolicy?: false | ClientProductPropertyPolicy;
}

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)
Default
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.
Default
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.
Default
```
true
```
OptionallogSchemaViolations?: boolean
Log all schema validation violations to debug logs (default: true)
Default
```
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.
Default
```
false
```
OptionalrejectProductsWithoutPricingOptions?: boolean
Reject products that arrive without a usable pricing_options[] array from completed get_products responses (default: true).

pricing_options is a required, non-empty field in AdCP 3.1 — a product that advertises no pricing model is non-transactable, so the SDK drops it from the product list before callers and completion handlers see it. This runs on every completion path (sync, polling, track, webhook) and is independent of the response validation mode, so unpriced products are removed even under responses: 'warn' | 'off'. The rejection is recorded in result.metadata.productPricingPolicy and a product_missing_pricing_options debug-log notice.

Set to false to pass products through untouched (e.g. when the caller deliberately inspects malformed seller responses).
Default
```
true
```
OptionalproductPropertyPolicy?: false | ClientProductPropertyPolicy
Buyer-side property policy applied to completed get_products responses before completion handlers and callers receive the product list. A request-level property_list is enforced automatically by default; set this to false only when the caller deliberately wants to trust seller-side filtering without SDK verification.

Use this for brand/block-list rules such as excluding ladbible.com; domain matching normalizes www. aliases, so www.ladbible.com violates an exclusion for ladbible.com.

`Optional`governance

governance?: GovernanceConfig

Governance configuration for buyer-side campaign governance

`Optional`transport

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. Set requestTimeoutMs to override the default 60s cap on A2A agent-card discovery; use 0 to disable the SDK-imposed discovery timeout.

Interface SingleAgentClientConfig

Hierarchy (View Summary)

Index

Properties

Properties

OptionalmaxHistorySize

OptionalpersistConversations

OptionalworkingTimeout

OptionaldefaultMaxClarifications

OptionaladcpVersion

OptionalwireAdcpVersion

OptionalversionEnvelope

Optionaldebug

OptionaluserAgent

Optionalheaders

OptionalonActivity

OptionalonTransportActivity

Optionalhandlers

OptionalwebhookSecret

OptionalwebhookUrlTemplate

Example

OptionalreportingWebhookFrequency

Default

OptionalvalidateFeatures

Default

OptionalrequireV3ForMutations

Default

OptionalallowV2

Optionalvalidation

Type Declaration

Optionalrequests?: ValidationMode

Default

Optionalresponses?: ValidationMode

Default

OptionalstrictSchemaValidation?: boolean

Default

OptionallogSchemaViolations?: boolean

Default

OptionalfilterInvalidProducts?: boolean

Default

OptionalrejectProductsWithoutPricingOptions?: boolean

Default

OptionalproductPropertyPolicy?: false | ClientProductPropertyPolicy

Optionalgovernance

Optionaltransport

Settings

On This Page

`Optional`maxHistorySize

`Optional`persistConversations

`Optional`workingTimeout

`Optional`defaultMaxClarifications

`Optional`adcpVersion

`Optional`wireAdcpVersion

`Optional`versionEnvelope

`Optional`debug

`Optional`userAgent

`Optional`headers

`Optional`onActivity

`Optional`onTransportActivity

`Optional`handlers

`Optional`webhookSecret

`Optional`webhookUrlTemplate

`Optional`reportingWebhookFrequency

`Optional`validateFeatures

`Optional`requireV3ForMutations

`Optional`allowV2

`Optional`validation

`Optional`requests?: ValidationMode

`Optional`responses?: ValidationMode

`Optional`strictSchemaValidation?: boolean

`Optional`logSchemaViolations?: boolean

`Optional`filterInvalidProducts?: boolean

`Optional`rejectProductsWithoutPricingOptions?: boolean

`Optional`productPropertyPolicy?: false | ClientProductPropertyPolicy

`Optional`governance

`Optional`transport