A PPC agent asks an advertising API to create a campaign. The request reaches the platform, the platform accepts it, and the network connection drops before the response comes back. This failure can be easy to miss in automated PPC campaigns because a retry looks like routine recovery even after the provider completed the first write.

What should the agent do next?

If it simply retries the write, it may create a second campaign. Creating campaigns in a paused state limits the immediate spend risk, but it does not remove the operational damage: duplicate objects, duplicate review work, conflicting names, and uncertainty about which campaign is authoritative.

This is an idempotency problem. Any agent that can mutate an ad account needs to solve it before it is trusted with retries.

Why do paid media AI agents need idempotency?

For PPC automation, idempotency means that repeated delivery of the same approved intent produces one logical result.

That definition contains four important constraints:

1. The same approved operation must not create two resources.
2. A genuinely different operation must not be incorrectly deduplicated.
3. A retry should return the original result when it is already known.
4. If the outcome is uncertain, the system must reconcile state instead of guessing.

The last constraint matters most. A timeout does not mean failure. It means the caller does not know whether the write succeeded.

How should an agent identify an approved operation?

The first building block is an idempotency key generated before execution. Scope it to the tenant, actor, and tool so two customers or two operations cannot collide.

scope = tenant_id + actor_id + tool_name + idempotency_key

The key alone is not enough. Store a canonical hash of the request payload with it. If a caller reuses the same key with different parameters, reject the request rather than silently returning an unrelated result.

type OperationRecord = {
  scope: string;
  requestHash: string;
  status:
    | "CLAIMED"
    | "EXECUTING"
    | "SUCCEEDED"
    | "FAILED_RETRYABLE"
    | "FAILED_FINAL"
    | "UNKNOWN";
  providerResourceId?: string;
  result?: unknown;
  lastError?: string;
};

Canonicalization must be deterministic. Sort object keys, normalize equivalent values, and exclude fields that should not change the logical identity of the request. Hashing raw JSON without canonicalization will eventually treat the same intent as two different operations.

Why must the operation be claimed atomically?

Two workers can receive the same request at nearly the same time. A read followed by an insert is therefore unsafe: both workers may observe that no record exists and both may execute the write.

Use a uniqueness constraint and claim the operation in one transaction.

create unique index operations_scope_unique
on operations (tenant_id, actor_id, tool_name, idempotency_key);

A simplified execution path looks like this:

async function executeIdempotently(input: ToolInput, ctx: Context) {
  const scope = makeScope(ctx, input.idempotencyKey);
  const requestHash = hash(canonicalize(input.parameters));

  const record = await claimOrLoad(scope, requestHash);

  if (record.requestHash !== requestHash) {
    throw new Error("IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_INPUT");
  }

  if (record.status === "SUCCEEDED") {
    return record.result;
  }

  if (record.status === "EXECUTING" || record.status === "UNKNOWN") {
    return reconcileBeforeRetry(record, input);
  }

  await markExecuting(record);

  try {
    const result = await callAdvertisingPlatform(input);
    await markSucceeded(record, result.resourceId, result);
    return result;
  } catch (error) {
    await classifyAndPersistFailure(record, error);
    throw error;
  }
}

The database record is not just a cache. It is the state machine that decides whether another external write is allowed.

What should happen after an ambiguous timeout?

Errors need semantic classification. A validation error returned before the platform accepts a request can be final. A rate limit may be retryable. A connection timeout after request transmission is ambiguous.

Do not map every exception to FAILED_RETRYABLE.

For an ambiguous outcome:

1. Mark the operation UNKNOWN.
2. Block another write for the same operation.
3. Query the advertising platform for evidence of the first result.
4. Bind the discovered resource ID to the operation record.
5. Retry the write only when the system has evidence that the first attempt did not succeed.

Reconciliation is easiest when the provider accepts its own idempotency key or returns a request ID that can be queried later. When it does not, create a recoverable correlation signal. Depending on the API, that may be a deterministic external ID, a unique label, or a name suffix derived from the operation ID.

Resource names alone are a weak fallback. They may be editable, truncated, or non-unique. Prefer a provider-supported identifier whenever one exists.

How should human approval bind to the write?

Idempotency prevents duplicate execution. It does not prove that the execution was authorized.

For consequential ad operations, approval should reference both the stable operation ID and the canonical request hash:

approval = sign(operation_id, request_hash, approver, expires_at)

If the budget, targeting, creative, or destination URL changes after approval, the hash changes and the approval no longer matches. The agent must present the modified plan for review again.

This closes a subtle gap: without payload binding, a system can approve one campaign plan and execute a materially different one under the same human confirmation.

For updates to existing resources, add an optimistic-concurrency check such as an entity version, revision number, or provider ETag. Idempotency answers “have I already run this operation?” Concurrency control answers “am I modifying the version the reviewer actually saw?”

What should retry observability capture?

Operational logs should let an engineer reconstruct the full lifecycle without exposing credentials or sensitive ad data.

Record at least:

• Operation ID and scoped idempotency key
• Tool name and request hash
• Approval identity and approval timestamp
• State transitions with timestamps
• Provider request ID and resource ID
• Retry count and backoff decision
• Reconciliation queries and their outcome
• Final result classification

Alert on operations that remain EXECUTING or UNKNOWN beyond a reasonable recovery window. Those states are not ordinary failures; they are unresolved external-side-effect risk.

Which failure boundaries should be tested?

The most valuable tests interrupt execution at each boundary:

1. Before the provider receives the request
2. After the provider receives it but before it responds
3. After the response arrives but before the result is persisted
4. After persistence but before the caller receives the response
5. While two workers race to claim the same operation
6. When the same key is reused with different input
7. When reconciliation finds zero, one, or multiple candidate resources

The pass condition is not simply “the retry succeeds.” It is “one logical operation maps to one authoritative advertising resource, and every uncertain outcome is recoverable.”

A practical review checklist

Before enabling retryable write tools for an AI ad agent, verify that:

• Every write accepts or derives a stable idempotency key.
• The key is scoped and protected by a database uniqueness constraint.
• The canonical payload hash is stored and checked on reuse.
• Ambiguous outcomes enter an UNKNOWN state instead of retrying blindly.
• A provider-native request ID or durable correlation signal supports reconciliation.
• Human approval is bound to the exact operation payload.
• Updates use concurrency controls where the provider supports them.
• Logs expose state transitions without exposing secrets.
• Fault-injection tests cover every network and persistence boundary.

Where does this pattern fit in Adspirer?

Adspirer's developer program exposes read-only plugin tooling to contributors, avoiding external-write risk at that extension boundary. Product workflows that can act on paid media use a stricter human-approval and paused-review model. The Adspirer documentation covers setup across supported AI clients and ad platforms.

This article describes a general control pattern rather than claiming a specific internal implementation. Approval determines whether an operation may run; idempotency ensures one approved intent cannot become two campaign builds because a network retry was handled badly.

Disclosure: This article is published by the Adspirer team and links to our product, developer program, and documentation.