Timeout Is Not Failure: The State Your AI Agent Is Missing

In the realm of AI agents, a timeout in an HTTP request or browser tool call often signals failure. However, recording this as a 'failed' state can leave the agent blind to the true outcome. Network timeouts don't necessarily indicate a server-side failure; they simply mean the connection was closed before the client received any response.

Recording a 'succeeded' state in such cases leads to false certainty, as the server may have processed the mutation, only for an intermediate proxy to timeout later, resulting in a duplicate artifact. The missing state here is 'outcome_unknown' - a crucial operational status that stops automatic retries, records the unconfirmed mutation, and hands off execution to an explicit reconciliation loop.

To address this, a concrete state machine can be implemented that distinguishes between pre-send failures and post-send ambiguities. Pre-send failures are situations like DNS lookup failures, missing credentials, or connection refusals before any bytes are sent. These are safe to retry as the action hasn't changed the world. Post-send ambiguities, however, occur after bytes have crossed the wire.

The server might have committed the mutation and crashed during response serialization, or an intermediate proxy might have timed out while the backend worker finished the job.

The proposed state machine has four states: 'planned', 'submitted', 'outcome_unknown', and 'succeeded'. After an action is planned, it's submitted and bytes are sent. The action then transitions to 'submitted', awaiting a response. If the response is received successfully, it moves to 'succeeded'. If the network drops or times out, it moves to 'outcome_unknown'. From this state, the agent can either retry (if it's safe to do so), be reviewed manually, or be suspended.

Idempotency keys are used in payment engineering for distributed consensus. If the server supports idempotency keys, then replaying the request with the same key ensures the action is idempotent. However, many web APIs and browser-driven surfaces lack native idempotency keys. In such cases, the caller must manage idempotency. This is done by computing a normalized intent fingerprint before sending the request.

If outcome_unknown is triggered, the agent reads back resources created by the agent's account within a specific timestamp window and matches them to the intent fingerprint.

The audit trail of each action is crucial for debugging and post-mortem analysis. It includes the operation ID, operation type, current state, intent fingerprint, and state history. This provides a full picture of how the action reached its final state, ensuring transparency and reliability in the system.