AdCP — Async Operations

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 — configure a webhook via `push_notification_config`. 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 should configure a webhook and move on. :::tip Webhooks for submitted operations Webhooks are the recommended approach for submitted operations — they work with any transport (MCP, A2A, REST) and handle operations that outlive a single session. See Push Notifications. Polling via the AdCP task polling surface works as a simpler alternative or backup. In 3.x, that surface is legacy tasks/get, with optional get_task_status when the seller advertises the alias. 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
`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.

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 webhook delivery window — if you’re also polling as backup, use a 30-second interval.

Human-in-the-Loop Workflows

Design Principles

Optional by default - Approvals are configured per implementation
Clear messaging - Users understand what they’re approving
Timeout gracefully - Don’t block forever on human input
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 — need webhook or polling
  if (response.status === 'submitted') {
    // Poll as backup (webhook is preferred — see Push Notifications)
    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 a backup for submitted operations when webhooks aren’t configured or as a fallback. 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

Design async first - Assume any operation could take time
Persist state - Don’t rely on in-memory tracking
Handle restarts - Resume tracking on startup
Implement timeouts - Don’t wait forever
Show progress - Keep users informed
Support cancellation - Let users cancel long operations
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

Getting Started

Building with AdCP

Protocol

FAQ

Trust & Security

Reference

Certification

Async Operations

The 30-second rule

Operation examples

Synchronous (instant)

May need human input

May go async (`submitted`)

Timeout Configuration

Human-in-the-Loop Workflows

Design Principles

Approval Patterns

Common Approval Triggers

Progress Tracking

Progress Updates

Displaying Progress

Protocol-Agnostic Patterns

Product Discovery with Clarification

Campaign Creation with Approval

Polling for `submitted` Operations

Asynchronous-First Design

Store State Persistently

Handle Restarts Gracefully

Best Practices

Next Steps

​The 30-second rule

​Operation examples

​Synchronous (instant)

​May need human input

​May go async (submitted)

​Timeout Configuration

​Human-in-the-Loop Workflows

​Design Principles

​Approval Patterns

​Common Approval Triggers

​Progress Tracking

​Progress Updates

​Displaying Progress

​Protocol-Agnostic Patterns

​Product Discovery with Clarification

​Campaign Creation with Approval

​Polling for submitted Operations

​Asynchronous-First Design

​Store State Persistently

​Handle Restarts Gracefully

​Best Practices

​Next Steps

The 30-second rule

Operation examples

Synchronous (instant)

May need human input

May go async (`submitted`)

Timeout Configuration

Human-in-the-Loop Workflows

Design Principles

Approval Patterns

Common Approval Triggers

Progress Tracking

Progress Updates

Displaying Progress

Protocol-Agnostic Patterns

Product Discovery with Clarification

Campaign Creation with Approval

Polling for `submitted` Operations

Asynchronous-First Design

Store State Persistently

Handle Restarts Gracefully

Best Practices

Next Steps