Async Operations

AdCP async operations guide: handling synchronous, asynchronous, and interactive (input-required) task types with polling, SSE streaming, and timeout strategies.

AdCP operations can take seconds, hours, or days. The server decides how to respond based on how long the operation will take and what’s blocking it.

The 30-second rule

Any AdCP task can return one of these statuses. The server chooses based on what it knows about the work involved:

Expected duration	Status	What the caller does
Under 30 seconds	completed / failed	Result is inline — done
Over 30 seconds, server actively processing	working	Out-of-band progress signal. Connection stays open, result arrives when ready. Caller just waits
Blocked on external dependency	submitted	Truly async — poll by task_id; push_notification_config can also deliver notifications when configured. Result may take hours or days
Blocked on human input	input-required	Caller provides the requested input to continue

working is not async. It’s a progress signal the server sends out-of-band (via MCP status notifications or SSE) while it continues processing. The caller holds the connection and receives the result when it’s ready — no polling, no webhooks. Think of it as “this is taking a moment, but I’m on it.”

submitted is async. The operation is blocked on something outside the server’s control — publisher approval, human review, third-party processing. The caller can always poll the AdCP task status surface with task_id. A configured webhook is an additional notification channel for background workflows, not a replacement for polling.

:::tip Webhooks for submitted operations Webhooks are recommended for background submitted operations — they work with any transport (MCP, A2A, REST) and handle operations that outlive a single session. For MCP/REST, the webhook channel is requested with push_notification_config on the task request. For A2A, it remains transport configuration at configuration.pushNotificationConfig, not a snake_case skill parameter. When a request includes a webhook channel and the server accepts the task by returning submitted, the server MUST deliver at least the terminal completion or failure notification to that channel. Intermediate progress notifications are optional unless another operation-specific contract requires them. If the server cannot honor the requested webhook channel, it MUST reject the request with a structured error instead of silently downgrading delivery. See Push Notifications.

Polling via the AdCP task polling surface is always valid for submitted tasks. In 3.x, that surface is legacy tasks/get, with optional get_task_status when the seller advertises the alias. Both names accept the same payload shape; multi-account callers SHOULD include account so sellers can scope task visibility to the authenticated account + principal pair. See the polling pattern below.

Transport-native tasks are not the AdCP lifecycle. MCP Tasks or A2A task updates may carry or stream an AdCP response, but the durable task state is the AdCP payload: task_id, status, webhook payloads, and AdCP polling/reconciliation. See MCP Guide. :::

Operation examples

Synchronous (instant)

Operation	Description
get_adcp_capabilities	Agent capability discovery
list_creative_formats	Format catalog
build_creative (library retrieval)	Resolving an existing creative_id

May need human input

Operation	Description
get_products	When brief is vague or needs clarification
create_media_buy	When approval is required
build_creative (generation)	When creative direction or asset selection is needed

May go async (submitted)

Operation	Description
create_media_buy	Publisher approval workflows
update_media_buy	Manual seller review for budget, targeting, or creative changes
get_products (brief / refine)	Bespoke curation that depends on upstream inventory queries or HITL review
get_signals (brief)	Semantic signal discovery that depends on slow provider queries or review
sync_creatives	Asset review and transcoding pipelines
build_creative (with review)	Human creative review before finalizing
sync_catalogs	Large feeds or feeds requiring content policy review
activate_signal	Platform deployment pipelines

These operations integrate with external systems or require human approval. Wholesale feed reads are the exception: get_products buying_mode: "wholesale" and get_signals discovery_mode: "wholesale" stay synchronous repair/reconciliation reads and report partial completion with incomplete[], not submitted.

Timeout Configuration

Set reasonable timeouts based on status:

const TIMEOUTS = {
  sync: 30_000,         // 30 seconds — most operations complete here
  working: 300_000,      // 5 minutes — server is actively processing
  interactive: 300_000,  // 5 minutes for human input
  submitted: 86_400_000  // 24 hours for external dependencies
};

function getTimeout(status) {
  if (status === 'submitted') return TIMEOUTS.submitted;
  if (status === 'working') return TIMEOUTS.working;
  if (status === 'input-required') return TIMEOUTS.interactive;
  return TIMEOUTS.sync;
}

working uses a connection timeout (how long to hold open), not a poll interval. The server sends progress out-of-band and delivers the result on the same connection. submitted uses a polling or webhook delivery window; a 30-second poll interval is a reasonable default even when webhooks are configured as the primary notification path.

Human-in-the-Loop Workflows

Design Principles

1. Optional by default - Approvals are configured per implementation
2. Clear messaging - Users understand what they’re approving
3. Timeout gracefully - Don’t block forever on human input
4. Audit trail - Track who approved what when

The human-in-the-loop patterns in async operations embody the Embedded Human Judgment framework — human judgment is embedded in system design, not bolted on afterward.

Approval Patterns

async function handleApprovalWorkflow(response) {
  if (response.status === 'input-required' && needsApproval(response)) {
    // Show approval UI with context
    const approval = await showApprovalUI({
      title: "Campaign Approval Required",
      message: response.message,
      details: response,  // Task fields are at top level
      approver: getCurrentUser()
    });

    // Send approval decision
    const decision = {
      approved: approval.approved,
      notes: approval.notes,
      approver_id: approval.approver_id,
      timestamp: new Date().toISOString()
    };

    return sendFollowUp(response.context_id, decision);
  }
}

Common Approval Triggers

• Budget thresholds: Campaigns over $100K
• New advertisers: First-time buyers
• Policy-sensitive content: Certain industries or topics
• Manual inventory: Premium placements requiring publisher approval

Progress Tracking

Progress Updates

Long-running operations may provide progress information:

{
  "status": "working",
  "message": "Processing creative assets...",
  "task_id": "task-456",
  "progress": 45,
  "step": "transcoding_video",
  "steps_completed": ["upload", "validation"],
  "steps_remaining": ["transcoding_video", "thumbnail_generation", "cdn_distribution"]
}

Displaying Progress

function displayProgress(response) {
  if (response.progress !== undefined) {
    updateProgressBar(response.progress);
  }

  if (response.step) {
    updateStatusText(`Step: ${response.step}`);
  }

  if (response.steps_completed) {
    updateStepsList(response.steps_completed, response.steps_remaining);
  }

  // Always show the message
  updateMessage(response.message);
}

Protocol-Agnostic Patterns

These patterns work with both MCP and A2A.

Product Discovery with Clarification

async function discoverProducts(brief) {
  let response = await adcp.send({
    task: 'get_products',
    brief: brief
  });

  // Handle clarification loop
  while (response.status === 'input-required') {
    const moreInfo = await promptUser(response.message);
    response = await adcp.send({
      context_id: response.context_id,
      additional_info: moreInfo
    });
  }

  if (response.status === 'completed') {
    return response.products;  // Task fields are at top level
  } else if (response.status === 'failed') {
    throw new Error(response.message);
  }
}

Campaign Creation with Approval

async function createCampaign(packages, budget) {
  let response = await adcp.send({
    task: 'create_media_buy',
    packages: packages,
    total_budget: budget
  });

  // Handle approval if needed
  if (response.status === 'input-required') {
    const approved = await getApproval(response.message);
    if (!approved) {
      throw new Error('Campaign creation not approved');
    }

    response = await adcp.send({
      context_id: response.context_id,
      approved: true
    });
  }

  // 'working' means the server is actively processing — result will arrive
  // 'submitted' means blocked on external dependency — poll by task_id;
  // a webhook may also deliver completion if configured.
  if (response.status === 'submitted') {
    response = await pollForResult(response.task_id);
  }

  if (response.status === 'completed') {
    return response.media_buy_id;  // Task fields are at top level
  } else {
    throw new Error(response.message);
  }
}

Polling for submitted Operations

Polling is always valid for submitted operations. A webhook may also deliver completion when configured, but callers can still reconcile through the task polling surface. Don’t poll for working — the server delivers the result on the open connection.

async function pollForResult(taskId, options = {}) {
  const { maxWait = 86_400_000, pollInterval = 30_000 } = options;
  const startTime = Date.now();

  while (true) {
    if (Date.now() - startTime > maxWait) {
      throw new Error('Operation timed out');
    }

    await sleep(pollInterval);

    const response = await adcp.call('get_task_status', {
      task_id: taskId,
      include_result: true
    });

    if (['completed', 'failed', 'canceled'].includes(response.status)) {
      return response;
    }
  }
}

Asynchronous-First Design

Store State Persistently

Don’t rely on in-memory state for async operations:

class AsyncOperationTracker {
  constructor(db) {
    this.db = db;
  }

  async startOperation(taskId, operationType, request) {
    await this.db.operations.insert({
      task_id: taskId,
      type: operationType,
      status: 'submitted',
      request: request,
      created_at: new Date(),
      updated_at: new Date()
    });
  }

  async updateStatus(taskId, status, result = null) {
    await this.db.operations.update(
      { task_id: taskId },
      {
        status: status,
        result: result,
        updated_at: new Date()
      }
    );
  }

  async getPendingOperations() {
    return this.db.operations.find({
      status: { $in: ['submitted', 'working', 'input-required'] }
    });
  }
}

Handle Restarts Gracefully

Resume tracking after orchestrator restarts:

async function onStartup() {
  const tracker = new AsyncOperationTracker(db);
  const pending = await tracker.getPendingOperations();

  for (const operation of pending) {
    // Check current status on server
    const response = await adcp.call('get_task_status', {
      task_id: operation.task_id,
      include_result: true
    });

    // Update local state
    await tracker.updateStatus(operation.task_id, response.status, response);

    // Resume polling if still pending
    if (['submitted', 'working'].includes(response.status)) {
      startPolling(operation.task_id);
    }
  }
}

Best Practices

1. Design async first - Assume any operation could take time
2. Persist state - Don’t rely on in-memory tracking
3. Handle restarts - Resume tracking on startup
4. Implement timeouts - Don’t wait forever
5. Show progress - Keep users informed
6. Support cancellation - Let users cancel long operations
7. Audit trail - Log all status transitions

Next Steps

• Webhooks: See Webhooks for push notifications instead of polling
• Task Lifecycle: See Task Lifecycle for status handling details
• Orchestrator Design: See Orchestrator Design for production patterns