Class ADCPMultiAgentClient

Main multi-agent AdCP client providing unified access to multiple advertising protocol agents.

This is the primary entry point for the @adcp/client library. It provides flexible access patterns for working with one or multiple AdCP agents (MCP or A2A protocols).

Key Features

Single agent access via agent(id) - for individual operations
Multi-agent access via agents([ids]) - for parallel execution across specific agents
Broadcast access via allAgents() - for parallel execution across all configured agents
Auto-configuration via static factory methods (fromConfig(), fromEnv(), fromFile())
Full type safety - all AdCP request/response types are strongly typed
Protocol agnostic - works seamlessly with both MCP and A2A agents

Basic Usage

Example: Single agent operation

const client = new ADCPMultiAgentClient([
  { id: 'agent1', agent_uri: 'https://agent1.com', protocol: 'mcp' },
  { id: 'agent2', agent_uri: 'https://agent2.com', protocol: 'a2a' }
]);

// Execute operation on single agent
const result = await client.agent('agent1').getProducts({
  brief: 'Coffee brands for premium audience'
});

if (result.status === 'completed') {
  console.log('Products:', result.data.products);
}

Example: Multi-agent parallel execution

// Execute across specific agents
const results = await client.agents(['agent1', 'agent2']).getProducts({
  brief: 'Coffee brands'
});

// Execute across all agents
const allResults = await client.allAgents().getProducts({
  brief: 'Coffee brands'
});

// Process results from all agents
allResults.forEach((result, i) => {
  console.log(`Agent ${client.agentIds[i]}: ${result.status}`);
  if (result.status === 'completed') {
    console.log(`  Products: ${result.data.products.length}`);
  }
});

Example: Auto-configuration from environment

// Load agents from environment variables or config files
const client = ADCPMultiAgentClient.fromConfig();

// Or from environment only
const client = ADCPMultiAgentClient.fromEnv();

// Or from specific file
const client = ADCPMultiAgentClient.fromFile('./my-agents.json');

Available Operations

All standard AdCP operations are available:

getProducts() - Discover advertising products
listCreativeFormats() - Get supported creative formats
createMediaBuy() - Create new media buy
updateMediaBuy() - Update existing media buy
syncCreatives() - Upload/sync creative assets
listCreatives() - List creative assets
getMediaBuyDelivery() - Get delivery performance
listAuthorizedProperties() - Get authorized properties
getSignals() - Get audience signals
activateSignal() - Activate audience signals
providePerformanceFeedback() - Send performance feedback

See

AgentClient for single-agent operations
AgentCollection for multi-agent parallel operations
SingleAgentClientConfig for configuration options

Constructors

constructor

new ADCPMultiAgentClient(
agentConfigs?: AgentConfig[],
config?: SingleAgentClientConfig,
): ADCPMultiAgentClient
Parameters
- agentConfigs: AgentConfig[] = []
- config: SingleAgentClientConfig = {}
Returns ADCPMultiAgentClient
- Defined in src/lib/core/ADCPMultiAgentClient.ts:372

Accessors

agentCount

get agentCount(): number
Get count of configured agents

Returns number
- Defined in src/lib/core/ADCPMultiAgentClient.ts:711

Methods

`Static`fromConfig

fromConfig(config?: SingleAgentClientConfig): ADCPMultiAgentClient
Create client by auto-discovering agent configuration

Automatically loads agents from:
1. Environment variables (SALES_AGENTS_CONFIG, ADCP_AGENTS_CONFIG, etc.)
2. Config files (adcp.config.json, adcp.json, .adcp.json, agents.json)
Parameters
- Optionalconfig: SingleAgentClientConfig
  Optional client configuration
Returns ADCPMultiAgentClient
ADCPMultiAgentClient instance with discovered agents
Example
```
// Simplest possible setup - auto-discovers configuration
const client = ADCPMultiAgentClient.fromConfig();

// Use with options
const client = ADCPMultiAgentClient.fromConfig({
  debug: true,
  defaultTimeout: 60000
});
```
- Defined in src/lib/core/ADCPMultiAgentClient.ts:405

`Static`fromEnv

fromEnv(config?: SingleAgentClientConfig): ADCPMultiAgentClient
Create client from environment variables only
Parameters
- Optionalconfig: SingleAgentClientConfig
  Optional client configuration
Returns ADCPMultiAgentClient
ADCPMultiAgentClient instance with environment-loaded agents
Example
```
// Load agents from SALES_AGENTS_CONFIG environment variable
const client = ADCPMultiAgentClient.fromEnv();
```
- Defined in src/lib/core/ADCPMultiAgentClient.ts:431

`Static`fromFile

fromFile(
configPath?: string,
config?: SingleAgentClientConfig,
): ADCPMultiAgentClient
Create client from a specific config file
Parameters
- OptionalconfigPath: string
  Path to configuration file
- Optionalconfig: SingleAgentClientConfig
  Optional client configuration
Returns ADCPMultiAgentClient
ADCPMultiAgentClient instance with file-loaded agents
Example
```
// Load from specific file
const client = ADCPMultiAgentClient.fromFile('./my-agents.json');

// Load from default locations
const client = ADCPMultiAgentClient.fromFile();
```
- Defined in src/lib/core/ADCPMultiAgentClient.ts:459

`Static`simple

simple(
    agentUrl: string,
    options?: {
        agentId?: string;
        agentName?: string;
        protocol?: "mcp" | "a2a";
        requiresAuth?: boolean;
        authTokenEnv?: string;
        debug?: boolean;
        timeout?: number;
    },
): ADCPMultiAgentClient
Create a simple client with minimal configuration
Parameters
- agentUrl: string
  Single agent URL
- options: {
      agentId?: string;
      agentName?: string;
      protocol?: "mcp" | "a2a";
      requiresAuth?: boolean;
      authTokenEnv?: string;
      debug?: boolean;
      timeout?: number;
  } = {}
  Optional agent and client configuration
Returns ADCPMultiAgentClient
ADCPMultiAgentClient instance with single agent
Example
```
// Simplest possible setup for single agent
const client = ADCPMultiAgentClient.simple('https://my-agent.example.com');

// With options
const client = ADCPMultiAgentClient.simple('https://my-agent.example.com', {
  agentName: 'My Agent',
  protocol: 'mcp',
  requiresAuth: true,
  debug: true
});
```
- Defined in src/lib/core/ADCPMultiAgentClient.ts:492

agent

agent(agentId: string): AgentClient
Get a single agent client for individual operations.

This is the primary method for executing operations on a specific agent. Returns an AgentClient instance that provides all AdCP operations.
Parameters
- agentId: string
  The unique identifier of the agent to retrieve
Returns AgentClient
Agent client instance for the specified agent
Throws
If agent ID is not found in configuration
Example
```
const client = new ADCPMultiAgentClient([
  { id: 'sales_agent', agent_uri: 'https://sales.example.com', protocol: 'a2a' }
]);

// Get specific agent and execute operation
const agent = client.agent('sales_agent');
const result = await agent.getProducts({ brief: 'Premium coffee brands' });
```
See
AgentClient for available operations
- Defined in src/lib/core/ADCPMultiAgentClient.ts:556

agents

agents(agentIds: string[]): AgentCollection
Get multiple specific agents for parallel operations.

Returns an AgentCollection that executes operations across the specified agents in parallel using Promise.all(). Useful when you want to query specific agents simultaneously and compare results.
Parameters
- agentIds: string[]
  Array of agent IDs to include in the collection
Returns AgentCollection
Agent collection for parallel operations across specified agents
Throws
If any agent ID is not found in configuration
Example
```
// Execute across specific agents
const results = await client.agents(['sales_agent_1', 'sales_agent_2']).getProducts({
  brief: 'Premium coffee brands'
});

// Process parallel results
results.forEach((result, i) => {
  if (result.status === 'completed') {
    console.log(`Agent ${i + 1}: ${result.data.products.length} products`);
  }
});
```
See
AgentCollection for available parallel operations
- Defined in src/lib/core/ADCPMultiAgentClient.ts:594

allAgents

allAgents(): AgentCollection

Get all configured agents for broadcast operations.

Returns an AgentCollection containing all agents in the client configuration. Executes operations across all agents in parallel, useful for market research, price comparison, or discovering capabilities across your entire agent network.

Returns AgentCollection

Agent collection for parallel operations across all configured agents

Example

const client = new ADCPMultiAgentClient([
  { id: 'agent1', agent_uri: 'https://agent1.com', protocol: 'a2a' },
  { id: 'agent2', agent_uri: 'https://agent2.com', protocol: 'mcp' },
  { id: 'agent3', agent_uri: 'https://agent3.com', protocol: 'a2a' }
]);

// Query all agents simultaneously
const allResults = await client.allAgents().getProducts({
  brief: 'Premium coffee brands'
});

// Find best options across all agents
const successfulResults = allResults.filter(r => r.status === 'completed');
console.log(`Got products from ${successfulResults.length} agents`);

See

AgentCollection for available parallel operations

addAgent

addAgent(agentConfig: AgentConfig): void
Add an agent to the client
Parameters
- agentConfig: AgentConfig
  Agent configuration to add
Returns void
Throws
Error if agent ID already exists
- Defined in src/lib/core/ADCPMultiAgentClient.ts:654

removeAgent

removeAgent(agentId: string): boolean
Remove an agent from the client
Parameters
- agentId: string
  ID of agent to remove
Returns boolean
True if agent was removed, false if not found
- Defined in src/lib/core/ADCPMultiAgentClient.ts:668

getAgent

getAgent(agentId: string): AgentClient
Get individual agent client by ID
Parameters
- agentId: string
  ID of agent to retrieve
Returns AgentClient
AgentClient instance

Throws
Error if agent not found
- Defined in src/lib/core/ADCPMultiAgentClient.ts:679

hasAgent

hasAgent(agentId: string): boolean
Check if an agent exists
Parameters
- agentId: string
Returns boolean
- Defined in src/lib/core/ADCPMultiAgentClient.ts:690

getAgentIds

getAgentIds(): string[]
Get all configured agent IDs

Returns string[]
- Defined in src/lib/core/ADCPMultiAgentClient.ts:697

getAgentConfigs

getAgentConfigs(): AgentConfig[]
Get all agent configurations

Returns AgentConfig[]
- Defined in src/lib/core/ADCPMultiAgentClient.ts:704

getAgentsByProtocol

getAgentsByProtocol(protocol: "mcp" | "a2a"): AgentCollection
Filter agents by protocol
Parameters
- protocol: "mcp" | "a2a"
Returns AgentCollection
- Defined in src/lib/core/ADCPMultiAgentClient.ts:720

findAgentsForTask

findAgentsForTask(taskName: string): AgentCollection
Find agents that support a specific task This is a placeholder - in a full implementation, you'd query agent capabilities
Parameters
- taskName: string
Returns AgentCollection
- Defined in src/lib/core/ADCPMultiAgentClient.ts:732

getAllActiveTasks

getAllActiveTasks(): TaskState[]
Get all active tasks across all agents

Returns TaskState[]
- Defined in src/lib/core/ADCPMultiAgentClient.ts:740

listAllTasks

listAllTasks(): Promise<TaskInfo[]>
Get all tasks from all agents with detailed information

Returns Promise<TaskInfo[]>
Promise resolving to array of all tasks across agents
Example
```
const allTasks = await client.listAllTasks();
console.log(`Total active tasks: ${allTasks.length}`);
```
- Defined in src/lib/core/ADCPMultiAgentClient.ts:761

listTasksForAgents

listTasksForAgents(agentIds: string[]): Promise<TaskInfo[]>
Get tasks for specific agents
Parameters
- agentIds: string[]
  Array of agent IDs to get tasks for
Returns Promise<TaskInfo[]>
Promise resolving to array of tasks from specified agents
- Defined in src/lib/core/ADCPMultiAgentClient.ts:773

getTaskInfo

getTaskInfo(taskId: string): Promise<null | TaskInfo>
Get task information by ID from any agent
Parameters
- taskId: string
  ID of the task to find
Returns Promise<null | TaskInfo>
Promise resolving to task information or null if not found
- Defined in src/lib/core/ADCPMultiAgentClient.ts:788

onTaskEvents

onTaskEvents(
    callbacks: {
        onTaskCreated?: (task: TaskInfo) => void;
        onTaskUpdated?: (task: TaskInfo) => void;
        onTaskCompleted?: (task: TaskInfo) => void;
        onTaskFailed?: (task: TaskInfo, error: string) => void;
    },
): () => void
Subscribe to task events from all agents
Parameters
- callbacks: {
      onTaskCreated?: (task: TaskInfo) => void;
      onTaskUpdated?: (task: TaskInfo) => void;
      onTaskCompleted?: (task: TaskInfo) => void;
      onTaskFailed?: (task: TaskInfo, error: string) => void;
  }
  Event callbacks for different task events
Returns () => void
Unsubscribe function that removes all subscriptions
Example
```
const unsubscribe = client.onTaskEvents({
  onTaskCompleted: (task) => {
    console.log(`Task ${task.taskName} completed!`);
  },
  onTaskFailed: (task, error) => {
    console.error(`Task ${task.taskName} failed:`, error);
  }
});
```
- Defined in src/lib/core/ADCPMultiAgentClient.ts:816

onAnyTaskUpdate

onAnyTaskUpdate(callback: (task: TaskInfo) => void): () => void
Subscribe to task updates from all agents
Parameters
- callback: (task: TaskInfo) => void
  Function to call when any task status changes
Returns () => void
Unsubscribe function
- Defined in src/lib/core/ADCPMultiAgentClient.ts:840

registerWebhooksForAll

registerWebhooksForAll(webhookUrl: string, taskTypes?: string[]): Promise<void>
Register webhooks for all agents
Parameters
- webhookUrl: string
  Base webhook URL (will append agent ID)
- OptionaltaskTypes: string[]
  Optional array of task types to watch
Returns Promise<void>
- Defined in src/lib/core/ADCPMultiAgentClient.ts:859

unregisterAllWebhooks

unregisterAllWebhooks(): Promise<void>
Unregister webhooks for all agents

Returns Promise<void>
- Defined in src/lib/core/ADCPMultiAgentClient.ts:869

getTaskCountsByStatus

getTaskCountsByStatus(): Promise<Record<string, number>>
Get count of active tasks by status

Returns Promise<Record<string, number>>
Promise resolving to object with counts by status
Example
```
const counts = await client.getTaskCountsByStatus();
console.log(`Working: ${counts.working}, Completed: ${counts.completed}`);
```
- Defined in src/lib/core/ADCPMultiAgentClient.ts:885

getWebhookUrl

getWebhookUrl(agentId: string, taskType: string, operationId: string): string
Generate webhook URL for a specific agent, task type, and operation
Parameters
- agentId: string
  ID of the agent
- taskType: string
  Type of task (e.g., 'get_products', 'media_buy_delivery')
- operationId: string
  Operation ID for this request
Returns string
Full webhook URL with macros replaced
Example
```
const webhookUrl = client.getWebhookUrl('agent1', 'sync_creatives', 'op_123');
// Returns: https://myapp.com/webhook/sync_creatives/agent1/op_123
```
- Defined in src/lib/core/ADCPMultiAgentClient.ts:912

handleWebhook

handleWebhook(
    payload: any,
    signature?: string,
    timestamp?: string | number,
    taskType?: string,
): Promise<boolean>
Handle webhook from any agent (async task completion or notifications)

Automatically routes webhook to the correct agent based on agent_id in payload.
Parameters
- payload: any
  Webhook payload from agent (must contain agent_id or operation_id)
- Optionalsignature: string
  Optional signature for verification (X-ADCP-Signature)
- Optionaltimestamp: string | number
  Optional timestamp for verification (X-ADCP-Timestamp)
- OptionaltaskType: string
Returns Promise<boolean>
Whether webhook was handled successfully
Example
```
app.post('/webhook', async (req, res) => {
  const signature = req.headers['x-adcp-signature'];
  const timestamp = req.headers['x-adcp-timestamp'];

  try {
    const handled = await client.handleWebhook(req.body, signature, timestamp);
    res.status(200).json({ received: handled });
  } catch (error) {
    res.status(401).json({ error: error.message });
  }
});
```
- Defined in src/lib/core/ADCPMultiAgentClient.ts:942

createCreativeAgent

createCreativeAgent(
    agentUrl: string,
    protocol?: "mcp" | "a2a",
    authToken?: string,
): CreativeAgentClient
Create a creative agent client
Parameters
- agentUrl: string
  URL of the creative agent
- protocol: "mcp" | "a2a" = 'mcp'
  Protocol to use (defaults to 'mcp')
- OptionalauthToken: string
  Optional authentication token
Returns CreativeAgentClient
CreativeAgentClient instance
Example
```
// Use standard creative agent
const creativeAgent = client.createCreativeAgent(
  'https://creative.adcontextprotocol.org/mcp'
);

// List formats
const formats = await creativeAgent.listFormats();
```
- Defined in src/lib/core/ADCPMultiAgentClient.ts:1007

getStandardCreativeAgent

getStandardCreativeAgent(protocol?: "mcp" | "a2a"): CreativeAgentClient
Get the standard AdCP creative agent
Parameters
- protocol: "mcp" | "a2a" = 'mcp'
  Protocol to use (defaults to 'mcp')
Returns CreativeAgentClient
CreativeAgentClient instance for standard agent
Example
```
const creativeAgent = client.getStandardCreativeAgent();
const formats = await creativeAgent.listFormats();
```
- Defined in src/lib/core/ADCPMultiAgentClient.ts:1028

discoverFormats

discoverFormats(): Promise<CreativeFormat[]>
Discover creative formats from standard creative agent

Convenience method to quickly get formats from the standard AdCP creative agent

Returns Promise<CreativeFormat[]>
Promise resolving to array of creative formats
Example
```
const formats = await client.discoverFormats();

// Find specific format
const banner = formats.find(f => f.format_id.id === 'display_300x250_image');
```
- Defined in src/lib/core/ADCPMultiAgentClient.ts:1050

findFormatsByType

findFormatsByType(
    type:
        | "video"
        | "audio"
        | "dooh"
        | "native"
        | "display"
        | "rich_media"
        | "universal",
): Promise<CreativeFormat[]>
Find creative formats by type
Parameters
- type: "video" | "audio" | "dooh" | "native" | "display" | "rich_media" | "universal"
  Format type to filter by
Returns Promise<CreativeFormat[]>
Promise resolving to matching formats
Example
```
const videoFormats = await client.findFormatsByType('video');
const displayFormats = await client.findFormatsByType('display');
```
- Defined in src/lib/core/ADCPMultiAgentClient.ts:1067

findFormatsByDimensions

findFormatsByDimensions(
width: number,
height: number,
): Promise<CreativeFormat[]>
Find creative formats by dimensions
Parameters
- width: number
  Width in pixels
- height: number
  Height in pixels
Returns Promise<CreativeFormat[]>
Promise resolving to matching formats
Example
```
// Find all 300x250 formats
const mediumRectangles = await client.findFormatsByDimensions(300, 250);
```
- Defined in src/lib/core/ADCPMultiAgentClient.ts:1087

Class ADCPMultiAgentClient

Key Features

Basic Usage

Example: Single agent operation

Example: Multi-agent parallel execution

Example: Auto-configuration from environment

Available Operations

See

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns ADCPMultiAgentClient

Accessors

agentCount

Returns number

Methods

StaticfromConfig

Parameters

Returns ADCPMultiAgentClient

Example

StaticfromEnv

Parameters

Returns ADCPMultiAgentClient

Example

StaticfromFile

Parameters

Returns ADCPMultiAgentClient

Example

Staticsimple

Parameters

Returns ADCPMultiAgentClient

Example

agent

Parameters

Returns AgentClient

Throws

Example

See

agents

Parameters

Returns AgentCollection

Throws

Example

See

allAgents

Returns AgentCollection

Example

See

addAgent

Parameters

Returns void

Throws

removeAgent

Parameters

Returns boolean

getAgent

Parameters

Returns AgentClient

Throws

hasAgent

Parameters

Returns boolean

getAgentIds

Returns string[]

getAgentConfigs

Returns AgentConfig[]

getAgentsByProtocol

Parameters

Returns AgentCollection

findAgentsForTask

Parameters

Returns AgentCollection

getAllActiveTasks

Returns TaskState[]

listAllTasks

Returns Promise<TaskInfo[]>

`Static`fromConfig

`Static`fromEnv

`Static`fromFile

`Static`simple