Skip to main content
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