Implementation Patterns

AdCP implementation patterns: task lifecycle, async operations, webhooks, error handling, security, and orchestrator design for production advertising systems.

This section covers patterns and best practices for building robust, production-ready systems that integrate with AdCP.

Core Patterns

Task Lifecycle

Status values, state transitions, and polling patterns. The foundation for handling any AdCP operation.

Async Operations

Handling sync, async, and interactive operations. Timeouts, progress tracking, and completion handling.

Webhooks

Push notification architecture, reliability patterns, circuit breakers, and idempotent handlers.

Error Handling

Error categories, standard error codes, recovery strategies, and retry logic.

System Design

Security

Security considerations for AdCP integrations. Webhook verification, replay prevention, and access control.

Orchestrator Design

State machine design, operation tracking, persistence patterns, and reconciliation.

Who This Section Is For

This section is primarily for orchestrator builders - developers building systems that:

• Manage multiple AdCP operations concurrently
• Need to survive restarts and recover state
• Handle long-running operations (hours to days)
• Require high reliability and auditability

If you’re building a simple integration that makes occasional AdCP calls, the Integration section may be sufficient.

Key Design Principles

1. Asynchronous First

AdCP operations may take seconds, hours, or days. Design all operations as async:

• Store operation state persistently
• Handle orchestrator restarts gracefully
• Implement proper timeout handling

2. Status-Driven Logic

Every response includes a status field. Build your logic around status values:

switch (response.status) {
  case 'completed': return processResults(response);
  case 'working': return pollForUpdates(response.task_id);
  case 'input-required': return promptUser(response.message);
  case 'failed': return handleError(response);
}

3. Webhooks + Polling

Never rely solely on webhooks:

• Configure webhooks for immediate notification
• Implement polling as backup
• Use circuit breakers for reliability

4. Idempotent Operations

Make all operations idempotent:

• Check for existing operations before creating new ones
• Handle duplicate webhook deliveries gracefully
• Use event IDs for deduplication

Reading Order

For comprehensive understanding, read in this order:

1. Task Lifecycle - Understand status values and transitions
2. Async Operations - Handle different operation types
3. Webhooks - Implement push notifications reliably
4. Error Handling - Handle failures gracefully
5. Orchestrator Design - Put it all together

Next Steps

• Start with basics: Task Lifecycle
• Building webhooks: Webhooks
• Complete architecture: Orchestrator Design