Essay
A timeout does not prove that nothing happened
An AI agent sends a request to publish a page, create a record, start a deployment, or deliver a message. The connection times out before a response arrives. From the agent's point of view, the call failed. In the target system, however, the action may already be complete.
That gap is not a small technical detail. If the agent immediately repeats the request, it can create two records, send two messages, trigger two jobs, or apply the same change twice. If it assumes success, it may report an outcome that never happened. The honest state is often neither success nor failure. It is outcome unknown.
AWS describes the same distributed-systems dilemma: a request can lose its response after the service has acted, leaving the caller unable to tell whether a retry would duplicate a side effect. The lesson for agentic software is direct: transport failure and business outcome are different facts.
Essay
Give the action one identity before execution
A retry becomes governable when every consequential operation has a stable identity created before the first attempt. The identity should bind the human-approved task to its target, parameters, consequence, and success condition. Every later attempt refers back to that same operation instead of inventing a new one.
A random key alone is not enough. The system also needs the original operation contract. If the recipient, file, account, environment, amount, visibility, or requested result changes, the new request expresses different intent and should receive a new identity and, where material, a new approval.
- Operation ID: a unique, non-sensitive identifier created before the first attempt.
- Target: the exact service, account, environment, route, or record to be changed.
- Parameters: a canonical record or digest of the material request fields.
- Authority: who approved which action, for which target, and under which limits.
- Success condition: the observable state that will count as complete.
- Receipt pointer: where attempts, responses, checks, and unresolved facts are recorded.
Essay
Route retries through four evidence states
The retry gate should start with evidence, not confidence. It asks what can be observed now and routes the operation according to that state. A fluent model explanation does not move the gate.
This is a proposed ChipOS operating pattern, not a universal standard. Its purpose is to prevent an agent from converting uncertainty into an unbounded side effect.
- Confirmed complete: the intended target state and operation identity are visible. Return the existing receipt; do not repeat the action.
- Confirmed not executed: current evidence shows the action did not begin or was rejected before execution. Retry only inside the original scope.
- Retry-safe by contract: the provider accepts the same idempotency identifier for the same parameters. Reuse the identifier and then verify the resulting state.
- Outcome still unknown: the target cannot prove completion or non-execution, or the retry contract is unclear. Stop and request human review or reconciliation.
Essay
Idempotency is a contract, not a magic header
An operation is idempotent when repeating the same request does not create additional side effects. Some APIs expose that behavior through a caller-provided key. AWS describes unique client request identifiers that let a service recognize repeated intent. Stripe documents an idempotency key that returns the stored result for subsequent requests with the same key and rejects mismatched parameters.
Those are provider-specific contracts, not a promise that every API behaves the same way. Retention windows differ. Some services support keys only for particular operations. A downstream system may have acted even when the upstream response is unavailable. The agent therefore needs current documentation, provider behavior, and reconciliation evidence before calling a retry safe.
Where no idempotency contract exists, the owner-controlled layer can still reduce risk by checking the target for an operation marker, querying current state, recording a business-level deduplication key, or holding the task for review. These controls require implementation and testing; naming them does not prove that a given integration already has them.
Essay
A concrete workflow: a deployment response disappears
Consider an agent approved to deploy one verified build to one production slot. It sends the deployment request with operation ID deploy-2026-08-24-001. The connection closes before the deployment service returns a result.
The agent should stop the retry loop and inspect the actual environment: active image identity, build or commit, container health, target route, and a protected canary. If those observations prove the approved build is active, the operation is complete even though the first response was lost. The agent returns a receipt built from live state.
If the approved build is not active and the deployment API guarantees idempotent handling for the same operation ID and unchanged parameters, the agent can reuse that ID for a bounded retry. If state remains ambiguous, the provider contract is absent, or the requested target has changed, the agent stops. It does not turn the original approval into permission for a new deployment strategy.
Essay
A retry must not silently expand human authority
Permission belongs to the operation contract, not to the agent's desire to finish. Approval to send one draft does not authorize a second delivery. Approval to deploy one build to a staging slot does not authorize production. Approval to update one customer record does not authorize creating a replacement record when the first cannot be found.
Before any retry, compare the current task with the approved task. A changed target, parameter, consequence, recipient, or visibility is a new decision. The smallest safe next action may be a state query, a draft receipt, or one precise question to the human rather than another mutation.
Essay
Implementation checklist for an owner-controlled worker
The control layer should make retry behavior explicit in code and receipts. The following checklist is a practical starting point for jobs that can change external state.
- Classify each tool call as read-only, naturally idempotent, provider-idempotent, reconciliable, or unsafe to retry automatically.
- Create the operation identity and immutable task contract before the first mutating call.
- Persist attempt state before sending the request, without storing unnecessary private conversation data.
- Record response status, provider request ID, timestamps, and the exact evidence needed to inspect the outcome.
- On timeout, mark outcome unknown instead of failed until the target has been checked.
- Reuse the same idempotency key only when target, parameters, authority, and provider contract still match.
- Reject key reuse when material parameters differ or the provider's retention window is no longer known to apply.
- Set a bounded retry count, backoff policy, and global stop path for active workers.
- Escalate irreversible, high-impact, or unreconciled actions to a human before another attempt.
- Complete the task only after the intended state is observed and a receipt identifies what is verified and what remains unknown.
Essay
What this method cannot promise
Idempotency does not make an agent infallible, prove that every external system is consistent, or guarantee exactly-once execution across an entire multi-service workflow. It cannot recover an action that has no observable identity, reverse an irreversible side effect, or infer a human's changed intent from silence.
It also carries cost. Services must retain identifiers and request state for some period, compare parameters, define conflict behavior, and expose enough evidence for reconciliation. AWS explicitly notes that a rigorous at-most-once contract adds complexity and is not the right choice for every solution.
The useful claim is narrower: when the operation identity, provider contract, current state, approval boundary, and receipt are kept together, the system has a disciplined way to avoid blind retries and to return uncertainty to the human before it becomes a duplicate action.
What to keep
The residue.
- A missing response is not evidence that an action failed.
- Create one operation identity before the first consequential attempt.
- Reuse an idempotency key only for the same intent and unchanged material parameters.
- Verify the target state before deciding whether a retry is safe.
- When the outcome remains unknown, stop and return control instead of guessing.
Operator view
Turn the essay into a company decision.
FAQ
Short answers for search and operators.
What does idempotent mean for an AI agent?
It means the same approved operation can be repeated under a defined contract without creating an additional side effect. The exact guarantee depends on the target service and operation; the agent must not assume every API is idempotent.
Should an agent retry every timed-out request?
No. A timeout leaves the outcome unknown. The agent should inspect current state, confirm whether the provider supports an unchanged idempotent retry, and stop for reconciliation or human review when neither completion nor safe retry can be established.
Is a unique idempotency key enough?
No. The key must remain bound to the same caller intent, target, material parameters, authority, and provider retention rules. Reusing a key for changed parameters should be treated as a conflict, not as a shortcut to approval.
Can idempotency guarantee exactly-once execution?
Not across every workflow. It can support at-most-once behavior for specific operations when the service contract implements it correctly. Multi-service and irreversible workflows still need reconciliation, observability, bounded retries, and human escalation.
Sources
Where this connects inside ChipOS.
- AWS Builders' Library — Making retries safe with idempotent APIsPrimary engineering reference for retry ambiguity, caller-provided request identifiers, semantic equivalence, late requests, parameter mismatch, and the cost of at-most-once contracts.
- Stripe API — Idempotent requestsPrimary API documentation for same-key retry behavior, stored responses, key retention, and rejecting changed parameters.
- Stripe API — Advanced error handlingPrimary API documentation for network uncertainty, retry decisions, and reconciliation around idempotent requests.
Across the ecosystem
Comments
Leave a signal for Chip.
Add a correction, operator note, source context, or practical consequence. Comments enter moderated review before they become public.