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,
    signature?: string,
    timestamp?: string | number,
    taskType?: string,
): Promise<boolean>
Handle webhook from agent (async task completion or notifications)
Parameters
- payload: any
  Webhook payload from agent
- Optionalsignature: string
  Optional signature for verification (X-ADCP-Signature)
- Optionaltimestamp: string | number
  Optional timestamp for verification (X-ADCP-Timestamp)
- OptionaltaskType: string
  Task type from URL path (e.g., 'create_media_buy')
Returns Promise<boolean>
Whether webhook was handled successfully
- Defined in src/lib/core/AgentClient.ts:80

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:96

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:108

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:117

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:137

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:157

updateMediaBuy

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

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:197

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:217

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:237

listAuthorizedProperties

listAuthorizedProperties(
    params: ListAuthorizedPropertiesRequest,
    inputHandler?: InputHandler,
    options?: TaskOptions,
): Promise<TaskResult<ListAuthorizedPropertiesResponse>>
List authorized properties
Parameters
- params: ListAuthorizedPropertiesRequest
- OptionalinputHandler: InputHandler
- Optionaloptions: TaskOptions
Returns Promise<TaskResult<ListAuthorizedPropertiesResponse>>
- Defined in src/lib/core/AgentClient.ts:257

providePerformanceFeedback

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

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:299

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:316

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:352

getHistory

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

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

clearContext

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

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

getContextId

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

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

setContextId

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

getAgent

getAgent(): AgentConfig
Get the agent configuration

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

getAgentId

getAgentId(): string
Get the agent ID

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

getAgentName

getAgentName(): string
Get the agent name

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

getProtocol

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

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

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:437

hasActiveConversation

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

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

getActiveTasks

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

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

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:470
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:480

listTasks

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

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

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:517

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:524

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:531

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:543

unregisterWebhook

unregisterWebhook(): Promise<void>
Unregister webhook notifications

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

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

listAuthorizedProperties

Parameters

Returns Promise<TaskResult<ListAuthorizedPropertiesResponse>>

providePerformanceFeedback

Parameters

Returns Promise<TaskResult<ProvidePerformanceFeedbackResponse>>

getSignals

Parameters

Returns Promise<TaskResult<GetSignalsResponse>>

activateSignal

Parameters

Returns Promise<TaskResult<ActivateSignalResponse>>

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"

getAgentInfo

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

hasActiveConversation

Returns boolean

getActiveTasks

Returns TaskState[]

executeTask

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