Class AgentClient

Per-agent client that maintains conversation context across calls

This wrapper provides a persistent conversation context for a single agent, making it easy to have multi-turn conversations and maintain state.

Constructors

constructor

new AgentClient(
agent: AgentConfig,
config?: SingleAgentClientConfig,
): AgentClient
Parameters
- agent: AgentConfig
- config: SingleAgentClientConfig = {}
Returns AgentClient
- Defined in src/lib/core/AgentClient.ts:64

Methods

handleWebhook

handleWebhook(
    payload: any,
    taskType: string,
    operationId: string,
    signature?: string,
    timestamp?: string | number,
): Promise<boolean>
Handle webhook from agent (async task completion or notifications)
Parameters
- payload: any
  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)
Returns Promise<boolean>
Whether webhook was handled successfully
- Defined in src/lib/core/AgentClient.ts:82

getWebhookUrl

getWebhookUrl(taskType: string, operationId: string): string
Generate webhook URL for a specific task and operation
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
- Defined in src/lib/core/AgentClient.ts:99

verifyWebhookSignature

verifyWebhookSignature(
    payload: any,
    signature: string,
    timestamp: string | number,
): boolean
Verify webhook signature using HMAC-SHA256 per AdCP PR #86 spec
Parameters
- payload: any
  Webhook payload object
- 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
- Defined in src/lib/core/AgentClient.ts:111

getProducts

getProducts(
    params: GetProductsRequest,
    inputHandler?: InputHandler,
    options?: TaskOptions,
): Promise<TaskResult<GetProductsResponse>>
Discover available advertising products
Parameters
- params: GetProductsRequest
- OptionalinputHandler: InputHandler
- Optionaloptions: TaskOptions
Returns Promise<TaskResult<GetProductsResponse>>
- Defined in src/lib/core/AgentClient.ts:120

listCreativeFormats

listCreativeFormats(
    params: ListCreativeFormatsRequest,
    inputHandler?: InputHandler,
    options?: TaskOptions,
): Promise<TaskResult<ListCreativeFormatsResponse>>
List available creative formats
Parameters
- params: ListCreativeFormatsRequest
- OptionalinputHandler: InputHandler
- Optionaloptions: TaskOptions
Returns Promise<TaskResult<ListCreativeFormatsResponse>>
- Defined in src/lib/core/AgentClient.ts:140

createMediaBuy

createMediaBuy(
    params: CreateMediaBuyRequest,
    inputHandler?: InputHandler,
    options?: TaskOptions,
): Promise<TaskResult<CreateMediaBuyResponse>>
Create a new media buy
Parameters
- params: CreateMediaBuyRequest
- OptionalinputHandler: InputHandler
- Optionaloptions: TaskOptions
Returns Promise<TaskResult<CreateMediaBuyResponse>>
- Defined in src/lib/core/AgentClient.ts:160

updateMediaBuy

updateMediaBuy(
    params: UpdateMediaBuyRequest,
    inputHandler?: InputHandler,
    options?: TaskOptions,
): Promise<TaskResult<UpdateMediaBuyResponse>>
Update an existing media buy
Parameters
- params: UpdateMediaBuyRequest
- OptionalinputHandler: InputHandler
- Optionaloptions: TaskOptions
Returns Promise<TaskResult<UpdateMediaBuyResponse>>
- Defined in src/lib/core/AgentClient.ts:180

syncCreatives

syncCreatives(
    params: SyncCreativesRequest,
    inputHandler?: InputHandler,
    options?: TaskOptions,
): Promise<TaskResult<SyncCreativesResponse>>
Sync creative assets
Parameters
- params: SyncCreativesRequest
- OptionalinputHandler: InputHandler
- Optionaloptions: TaskOptions
Returns Promise<TaskResult<SyncCreativesResponse>>
- Defined in src/lib/core/AgentClient.ts:200

listCreatives

listCreatives(
    params: ListCreativesRequest,
    inputHandler?: InputHandler,
    options?: TaskOptions,
): Promise<TaskResult<ListCreativesResponse>>
List creative assets
Parameters
- params: ListCreativesRequest
- OptionalinputHandler: InputHandler
- Optionaloptions: TaskOptions
Returns Promise<TaskResult<ListCreativesResponse>>
- Defined in src/lib/core/AgentClient.ts:220

getMediaBuyDelivery

getMediaBuyDelivery(
    params: GetMediaBuyDeliveryRequest,
    inputHandler?: InputHandler,
    options?: TaskOptions,
): Promise<TaskResult<GetMediaBuyDeliveryResponse>>
Get media buy delivery information
Parameters
- params: GetMediaBuyDeliveryRequest
- OptionalinputHandler: InputHandler
- Optionaloptions: TaskOptions
Returns Promise<TaskResult<GetMediaBuyDeliveryResponse>>
- Defined in src/lib/core/AgentClient.ts:240

providePerformanceFeedback

providePerformanceFeedback(
    params: ProvidePerformanceFeedbackRequest,
    inputHandler?: InputHandler,
    options?: TaskOptions,
): Promise<TaskResult<ProvidePerformanceFeedbackResponse>>
Provide performance feedback
Parameters
- params: ProvidePerformanceFeedbackRequest
- OptionalinputHandler: InputHandler
- Optionaloptions: TaskOptions
Returns Promise<TaskResult<ProvidePerformanceFeedbackResponse>>
- Defined in src/lib/core/AgentClient.ts:260

getSignals

getSignals(
    params: GetSignalsRequest,
    inputHandler?: InputHandler,
    options?: TaskOptions,
): Promise<TaskResult<GetSignalsResponse>>
Get audience signals
Parameters
- params: GetSignalsRequest
- OptionalinputHandler: InputHandler
- Optionaloptions: TaskOptions
Returns Promise<TaskResult<GetSignalsResponse>>
- Defined in src/lib/core/AgentClient.ts:282

activateSignal

activateSignal(
    params: ActivateSignalRequest,
    inputHandler?: InputHandler,
    options?: TaskOptions,
): Promise<TaskResult<ActivateSignalResponse>>
Activate audience signals
Parameters
- params: ActivateSignalRequest
- OptionalinputHandler: InputHandler
- Optionaloptions: TaskOptions
Returns Promise<TaskResult<ActivateSignalResponse>>
- Defined in src/lib/core/AgentClient.ts:299

getAdcpCapabilities

getAdcpCapabilities(
    params: GetAdCPCapabilitiesRequest,
    inputHandler?: InputHandler,
    options?: TaskOptions,
): Promise<TaskResult<GetAdCPCapabilitiesResponse>>
Get AdCP capabilities (v3 tool call)
Parameters
- params: GetAdCPCapabilitiesRequest
- OptionalinputHandler: InputHandler
- Optionaloptions: TaskOptions
Returns Promise<TaskResult<GetAdCPCapabilitiesResponse>>
- Defined in src/lib/core/AgentClient.ts:321

getCapabilities

getCapabilities(): Promise<AdcpCapabilities>
Get normalized capabilities with v2/v3 fallback

For v3 servers: calls get_adcp_capabilities tool For v2 servers: builds synthetic capabilities from tool list

Returns Promise<AdcpCapabilities>
- Defined in src/lib/core/AgentClient.ts:344

continueConversation

continueConversation<T = any>(
    message: string,
    inputHandler?: InputHandler,
    options?: TaskOptions,
): Promise<TaskResult<T>>
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>>
Example
```
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'
);
```
- Defined in src/lib/core/AgentClient.ts:367

getHistory

getHistory(): undefined | Message[]
Get the full conversation history

Returns undefined | Message[]
- Defined in src/lib/core/AgentClient.ts:388

clearContext

clearContext(): void
Clear the conversation context (start fresh)

Returns void
- Defined in src/lib/core/AgentClient.ts:398

getContextId

getContextId(): undefined | string
Get the current conversation context ID

Returns undefined | string
- Defined in src/lib/core/AgentClient.ts:408

setContextId

setContextId(contextId: string): void
Set a specific conversation context ID
Parameters
- contextId: string
Returns void
- Defined in src/lib/core/AgentClient.ts:415

getAgent

getAgent(): AgentConfig
Get the agent configuration

Returns AgentConfig
- Defined in src/lib/core/AgentClient.ts:424

getAgentId

getAgentId(): string
Get the agent ID

Returns string
- Defined in src/lib/core/AgentClient.ts:431

getAgentName

getAgentName(): string
Get the agent name

Returns string
- Defined in src/lib/core/AgentClient.ts:438

getProtocol

getProtocol(): "mcp" | "a2a"
Get the agent protocol

Returns "mcp" | "a2a"
- Defined in src/lib/core/AgentClient.ts:445

getCanonicalUrl

getCanonicalUrl(): string
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
- Defined in src/lib/core/AgentClient.ts:455

resolveCanonicalUrl

resolveCanonicalUrl(): Promise<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

Returns Promise<string>
- Defined in src/lib/core/AgentClient.ts:465

isSameAgent

isSameAgent(other: AgentConfig | AgentClient): boolean
Check if this agent is the same as another agent by canonical URL
Parameters
- other: AgentConfig | AgentClient
Returns boolean
- Defined in src/lib/core/AgentClient.ts:472

isSameAgentResolved

isSameAgentResolved(other: AgentConfig | AgentClient): Promise<boolean>
Async version that resolves canonical URLs first for more accurate comparison
Parameters
- other: AgentConfig | AgentClient
Returns Promise<boolean>
- Defined in src/lib/core/AgentClient.ts:483

getResolvedAgent

getResolvedAgent(): Promise<AgentConfig>
Get the fully resolved agent configuration with canonical URL

Returns Promise<AgentConfig>
- Defined in src/lib/core/AgentClient.ts:497

getAgentInfo

getAgentInfo(): Promise<
    {
        name: string;
        description?: string;
        protocol: "mcp"
        | "a2a";
        url: string;
        tools: {
            name: string;
            description?: string;
            inputSchema?: any;
            parameters?: string[];
        }[];
    },
>
Get agent information including capabilities

Returns Promise<
    {
        name: string;
        description?: string;
        protocol: "mcp"
        | "a2a";
        url: string;
        tools: {
            name: string;
            description?: string;
            inputSchema?: any;
            parameters?: string[];
        }[];
    },
>
- Defined in src/lib/core/AgentClient.ts:504

hasActiveConversation

hasActiveConversation(): boolean
Check if there's an active conversation

Returns boolean
- Defined in src/lib/core/AgentClient.ts:511

getActiveTasks

getActiveTasks(): TaskState[]
Get active tasks for this agent

Returns TaskState[]
- Defined in src/lib/core/AgentClient.ts:518

executeTask

executeTask<K extends keyof TaskResponseTypeMap>(
    taskName: K,
    params: any,
    inputHandler?: InputHandler,
    options?: TaskOptions,
): Promise<TaskResult<TaskResponseTypeMap[K]>>
Execute any ADCP task by name with full type safety
Type Parameters
- K extends keyof TaskResponseTypeMap
Parameters
- taskName: K
- params: any
- OptionalinputHandler: InputHandler
- Optionaloptions: TaskOptions
Returns Promise<TaskResult<TaskResponseTypeMap[K]>>
Example
```
// ✅ TYPE-SAFE: Automatic response type inference
const result = await agent.executeTask('get_products', params);
// result is TaskResult<GetProductsResponse> - no casting needed!

// ✅ CUSTOM TYPES: For non-standard tasks
const customResult = await agent.executeTask<MyCustomResponse>('custom_task', params);
```
- Defined in src/lib/core/AgentClient.ts:537
executeTask<T = any>(
    taskName: string,
    params: any,
    inputHandler?: InputHandler,
    options?: TaskOptions,
): Promise<TaskResult<T>>
Execute any task by name with custom response type
Type Parameters
- T = any
Parameters
- taskName: string
- params: any
- OptionalinputHandler: InputHandler
- Optionaloptions: TaskOptions
Returns Promise<TaskResult<T>>
- Defined in src/lib/core/AgentClient.ts:547

listTasks

listTasks(): Promise<TaskInfo[]>
List all tasks for this agent

Returns Promise<TaskInfo[]>
- Defined in src/lib/core/AgentClient.ts:577

getTaskInfo

getTaskInfo(taskId: string): Promise<null | TaskInfo>
Get detailed information about a specific task
Parameters
- taskId: string
Returns Promise<null | TaskInfo>
- Defined in src/lib/core/AgentClient.ts:584

onTaskUpdate

onTaskUpdate(callback: (task: TaskInfo) => void): () => void
Subscribe to task notifications for this agent
Parameters
- callback: (task: TaskInfo) => void
Returns () => void
- Defined in src/lib/core/AgentClient.ts:591

onTaskEvents

onTaskEvents(
    callbacks: {
        onTaskCreated?: (task: TaskInfo) => void;
        onTaskUpdated?: (task: TaskInfo) => void;
        onTaskCompleted?: (task: TaskInfo) => void;
        onTaskFailed?: (task: TaskInfo, error: string) => void;
    },
): () => 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
- Defined in src/lib/core/AgentClient.ts:598

registerWebhook

registerWebhook(webhookUrl: string, taskTypes?: string[]): Promise<void>
Register webhook for task notifications
Parameters
- webhookUrl: string
- OptionaltaskTypes: string[]
Returns Promise<void>
- Defined in src/lib/core/AgentClient.ts:610

unregisterWebhook

unregisterWebhook(): Promise<void>
Unregister webhook notifications

Returns Promise<void>
- Defined in src/lib/core/AgentClient.ts:617

Class AgentClient

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns AgentClient

Methods

handleWebhook

Parameters

Returns Promise<boolean>

getWebhookUrl

Parameters

Returns string

verifyWebhookSignature

Parameters

Returns boolean

getProducts

Parameters

Returns Promise<TaskResult<GetProductsResponse>>

listCreativeFormats

Parameters

Returns Promise<TaskResult<ListCreativeFormatsResponse>>

createMediaBuy

Parameters

Returns Promise<TaskResult<CreateMediaBuyResponse>>

updateMediaBuy

Parameters

Returns Promise<TaskResult<UpdateMediaBuyResponse>>

syncCreatives

Parameters

Returns Promise<TaskResult<SyncCreativesResponse>>

listCreatives

Parameters

Returns Promise<TaskResult<ListCreativesResponse>>

getMediaBuyDelivery

Parameters

Returns Promise<TaskResult<GetMediaBuyDeliveryResponse>>

providePerformanceFeedback

Parameters

Returns Promise<TaskResult<ProvidePerformanceFeedbackResponse>>

getSignals

Parameters

Returns Promise<TaskResult<GetSignalsResponse>>

activateSignal

Parameters

Returns Promise<TaskResult<ActivateSignalResponse>>

getAdcpCapabilities

Parameters

Returns Promise<TaskResult<GetAdCPCapabilitiesResponse>>

getCapabilities

Returns Promise<AdcpCapabilities>

continueConversation

Type Parameters

Parameters

Returns Promise<TaskResult<T>>

Example

getHistory

Returns undefined | Message[]

clearContext

Returns void

getContextId

Returns undefined | string

setContextId

Parameters

Returns void

getAgent

Returns AgentConfig

getAgentId

Returns string

getAgentName

Returns string

getProtocol

Returns "mcp" | "a2a"

getCanonicalUrl

Returns string

resolveCanonicalUrl

Returns Promise<string>

isSameAgent

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