@adcp/client API Reference

Complete TypeScript API documentation for the @adcp/client library - the official client for the Ad Context Protocol (AdCP).

Overview

The @adcp/client library provides a comprehensive, type-safe interface for interacting with AdCP agents supporting both MCP (Model Context Protocol) and A2A (Agent-to-Agent) protocols. Whether you're working with a single agent or orchestrating operations across multiple agents, this library provides the tools you need.

Quick Start

import { ADCPMultiAgentClient } from '@adcp/client';

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

// Execute operation
const result = await client.agent('agent1').getProducts({
  brief: 'Premium coffee brands for millennial audience'
});

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

Core Concepts

🎯 Client Classes

The library provides flexible client patterns for different use cases:

• ADCPMultiAgentClient - Main entry point supporting single and multi-agent operations
• AgentClient - Individual agent operations with full AdCP method support
• AgentCollection - Parallel operations across multiple agents

📦 Request/Response Types

All AdCP operations have strongly-typed request and response interfaces:

Product Discovery:

• GetProductsRequest / GetProductsResponse
• ListCreativeFormatsRequest / ListCreativeFormatsResponse

Media Buy Lifecycle:

• CreateMediaBuyRequest / CreateMediaBuyResponse
• UpdateMediaBuyRequest / UpdateMediaBuyResponse
• SyncCreativesRequest / SyncCreativesResponse

Targeting & Signals:

• GetSignalsRequest / GetSignalsResponse
• ActivateSignalRequest / ActivateSignalResponse

View all request/response types →

🔄 Task Results

All operations return a TaskResult<T> with status tracking:

type TaskStatus = 'completed' | 'submitted' | 'needs_input' | 'failed' | 'aborted';

interface TaskResult<T> {
  status: TaskStatus;
  data?: T;              // Present when status === 'completed'
  error?: Error;         // Present when status === 'failed'
  needs_input?: {...};   // Present when status === 'needs_input'
  submitted?: {...};     // Present when status === 'submitted'
}
Copy

🔐 Configuration

Multiple ways to configure agents:

// 1. Direct construction
const client = new ADCPMultiAgentClient([...agents]);

// 2. Auto-discover from environment/config
const client = ADCPMultiAgentClient.fromConfig();

// 3. Environment variables only
const client = ADCPMultiAgentClient.fromEnv();

// 4. Specific config file
const client = ADCPMultiAgentClient.fromFile('./agents.json');

// 5. Simple single-agent setup
const client = ADCPMultiAgentClient.simple('https://agent.example.com');
Copy

See ConfigurationManager for configuration file formats and environment variable names.

Usage Patterns

Single Agent Operations

// Get agent and execute
const agent = client.agent('sales_agent');
const products = await agent.getProducts({ brief: 'Coffee brands' });

// Continue conversation if clarification needed
if (products.status === 'needs_input') {
  const refined = await agent.continueConversation('Premium brands only');
}
Copy

Multi-Agent Parallel Execution

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

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

// Process results
allResults.forEach((result, i) => {
  if (result.status === 'completed') {
    console.log(`Agent ${i}: ${result.data.products.length} products`);
  }
});
Copy

Property Discovery (AdCP v2.2.0+)

Build agent registries by discovering what properties agents can sell:

import { PropertyCrawler, getPropertyIndex } from '@adcp/client';

// Crawl agents
const crawler = new PropertyCrawler();
await crawler.crawlAgents([
  { agent_url: 'https://agent1.com' },
  { agent_url: 'https://agent2.com' }
]);

// Query index
const index = getPropertyIndex();
const matches = index.findAgentsForProperty('domain', 'cnn.com');
Copy

See PropertyCrawler and PropertyIndex for details.

Error Handling

The library provides specific error types for different failure modes:

• ADCPError - Base error class
• ProtocolError - Protocol-level failures
• TaskTimeoutError - Operation timeouts
• AgentNotFoundError - Invalid agent ID
• ValidationError - Schema validation failures

import { isADCPError, isErrorOfType, TaskTimeoutError } from '@adcp/client';

try {
  const result = await agent.getProducts(params);
} catch (error) {
  if (isErrorOfType(error, TaskTimeoutError)) {
    console.error('Operation timed out');
  } else if (isADCPError(error)) {
    console.error('AdCP error:', error.message);
  }
}
Copy

Type Safety

All types are automatically generated from the AdCP JSON schemas, ensuring perfect alignment with the protocol specification:

import type {
  GetProductsRequest,
  GetProductsResponse,
  BrandManifest,
  Product,
  Format
} from '@adcp/client';

// Full IntelliSense support
const request: GetProductsRequest = {
  brand_manifest: { name: 'Acme Corp' },
  brief: 'Coffee products'
};
Copy

Validation

Runtime validation using Zod schemas:

import {
  GetProductsRequestSchema,
  GetProductsResponseSchema
} from '@adcp/client';

// Validate request
const validRequest = GetProductsRequestSchema.parse(requestData);

// Validate response
const validResponse = GetProductsResponseSchema.parse(responseData);
Copy

See schemas.generated for all available Zod schemas.

Advanced Features

Async Handlers & Webhooks

Handle asynchronous operations with automatic webhook management:

const client = new ADCPMultiAgentClient(agents, {
  webhookUrlTemplate: 'https://myapp.com/webhook/{task_type}/{agent_id}/{operation_id}',
  handlers: {
    onGetProductsStatusChange: (response, metadata) => {
      console.log(`Status: ${metadata.status}`);
      if (metadata.status === 'completed') {
        saveProducts(response.products);
      }
    }
  }
});
Copy

See AsyncHandler for webhook configuration.

Creative Agent Integration

Work with creative generation agents:

import { CreativeAgentClient, STANDARD_CREATIVE_AGENTS } from '@adcp/client';

const creativeClient = new CreativeAgentClient({
  agents: STANDARD_CREATIVE_AGENTS
});

const creative = await creativeClient.generateCreative({
  format: 'banner_300x250',
  brand_manifest: { name: 'Acme' },
  targeting: { demographics: { age_ranges: ['25-34'] } }
});
Copy

See CreativeAgentClient for details.

Protocol Support

The library seamlessly supports both protocols:

• MCP (Model Context Protocol) - SSE-based streaming protocol
• A2A (Agent-to-Agent) - REST-based protocol

Protocol is specified per-agent in configuration. All operations work identically regardless of protocol.

Version Information

Check library and protocol versions:

import {
  LIBRARY_VERSION,
  ADCP_VERSION,
  isCompatibleWith
} from '@adcp/client';

console.log(`Library: ${LIBRARY_VERSION}`);
console.log(`AdCP Protocol: ${ADCP_VERSION}`);

if (isCompatibleWith('2.4.0')) {
  console.log('Compatible with AdCP 2.4.0');
}
Copy

Additional Resources

• Main README: Getting Started Guide
• Protocol Spec: AdCP Specification
• Full Documentation: docs.adcontextprotocol.org
• npm Package: @adcp/client
• GitHub: adcontextprotocol/adcp-client

Browse the API

Use the navigation below to explore all classes, interfaces, types, and utilities in the library.

---

📚 Generated from source code with TypeDoc • View on GitHub