AI agent dead-letter queues: recover messages after failure
AI agent dead-letter queues keep a failed message from becoming a vanished message. When a channel event cannot be processed or delivered safely, preserve it outside the normal flow with its context and failure reason. An operator can then inspect, correct, and deliberately retry it. That is safer than an automatic retry loop that duplicates a reply, drops the original request, or repeats a broken tool call.
This matters most when an agent works through chat channels. A message can arrive as the Gateway restarts, a provider can time out after work has started, or a destination can reject a reply. The user still expects one accountable outcome. A dead-letter queue gives the system somewhere specific to put the exception instead of leaving it half-processed in logs.
OpenClaw’s v2026.7.2-beta.7 release notes describe shared ingress draining and dead-letter recovery for accepted channel messages across Telegram, Signal, Slack, QQBot, Twitch, Synology Chat, Tlon, IRC, and Zalo User. It is a beta release, so treat it as a release signal rather than a promise about every deployment. The operating lesson is useful either way: accepted work needs a durable recovery path.
In this guide
- What AI agent dead-letter queues do
- The recovery record to keep
- When to retry, repair, or escalate
- How to test the failure path
What AI agent dead-letter queues do
A dead-letter queue, or DLQ, is a separate holding place for messages a system could not process. AWS defines a DLQ as a queue for messages that cannot be processed because of errors. The important property is separation: the broken item is no longer blocking ordinary traffic, but it has not been discarded.
For an AI agent, the failed unit may be more than a plain message. It can include the incoming chat event, the selected session, a channel account, a request ID, a tool result, and the attempted response. That extra context is what makes recovery possible without guessing which conversation the agent was serving.
| Failure | Bad response | DLQ response |
|---|---|---|
| Gateway restarts during message intake | The event disappears or is processed twice | Preserve the accepted event and recover it after startup |
| Provider times out after tools run | Retry blindly and risk repeated side effects | Hold the run for review with the tool history and request ID |
| Channel rejects a reply | Log an error with no owner | Record the delivery failure, target, and retry decision |
| Malformed or unauthorized input | Keep retrying an invalid request | Quarantine it with the rejection reason and escalation path |
A DLQ is not an alternative name for retries. Retries suit a transient problem with a known limit, such as a temporary network failure. A DLQ starts when the system should stop guessing. It makes the failure visible and separates recovery from normal message processing.
For the broader runtime picture, how OpenClaw works is a useful starting point: a channel message, session, tool call, and final delivery are different stages. A recovery record must let an operator identify which stage failed.
The recovery record to keep
The record needs enough evidence to answer two questions: what happened, and is replay safe? Do not only store an error string. That forces the next person to reconstruct the incident from unrelated logs.
At a minimum, keep:
- Message identity: a stable event or request ID, received time, channel, account, and conversation or session reference.
- Processing state: whether the agent had only accepted the request, selected a model, called a tool, generated a draft, or attempted delivery.
- Failure class: timeout, malformed input, permission denial, unavailable destination, duplicate detection, or an unknown system error.
- Side-effect evidence: tool-call IDs, external action IDs, and any delivery attempt. This is the check against replaying an email, purchase, or destructive operation twice.
- Recovery owner: the person or team responsible for deciding whether to retry, edit, discard, or escalate.
Microsoft’s Service Bus DLQ guidance makes the same operational point: failed messages remain available for inspection until an application explicitly retrieves and completes them. The queue is not self-healing. Someone or something with a defined policy still has to decide what happens next.
That policy belongs beside access controls. If a replay can trigger an external send or a write action, require the same approval standard as the original action. OpenClaw safety guidance is relevant here: an agent should have only the access its job needs, and consequential actions need an accountable boundary.
When to retry, repair, or escalate
A simple recovery policy keeps a DLQ from becoming an archive of ignored failures.
| Situation | Default action | Why |
|---|---|---|
| Short, confirmed provider outage | Retry with a bounded count and backoff | The request remains valid and no side effect completed |
| Channel token, routing, or permission issue | Repair configuration, then replay once | Repeating the same request will not fix authorization |
| Tool may have changed an external system | Pause for human review | A second call can duplicate the effect |
| Malformed, unsafe, or out-of-scope input | Reject and retain the audit record | Retry would only create more noise |
| Unknown failure after a restart | Inspect the session, trace, and prior delivery state | The safe action depends on what already completed |
The key distinction is whether the failed event is idempotent. A status lookup can often run again. A message send, ticket update, or payment action needs proof that the first attempt did not already succeed. Amazon SQS documents redrive policies for moving repeatedly unprocessed messages aside; apply the same caution to agent work, where the payload may carry real-world side effects.
OpenClaw’s multi-channel message delivery guide covers the companion problem: keeping responses attached to the intended conversation. A recovery path must preserve that target as well. A correct replay sent to the wrong channel is still an operational failure.
How to test the failure path
Test the DLQ before the first production incident. The happy path does not reveal whether messages remain recoverable after a restart or whether replay produces duplicates.
Run a small, controlled test suite:
- Send a harmless request with a unique marker, then interrupt the Gateway during intake.
- Confirm that the system records one accepted event, not zero and not two.
- Restore the service and inspect the recovery record before replaying it.
- Replay once and verify that the final reply appears in the original conversation.
- Repeat the test with a simulated provider timeout after a read-only tool call.
- Run one case where the tool would write or send externally, and verify that recovery pauses for approval rather than repeating automatically.
Keep the evidence from these tests: event IDs, logs, session IDs, delivery IDs, and the operator decision. It is the shortest way to distinguish a useful recovery mechanism from a queue that merely moves failures out of sight.
If a Gateway enters a restart loop, first stop the loop and repair the service. Then decide what to recover. The AI agent crash-loop repair guide explains why a stable repair state is better than endless restarts. A DLQ gives that repair state work to resume in a controlled order.
FAQ
What is an AI agent dead-letter queue?
An AI agent dead-letter queue is a separate recovery path for messages or tasks that could not be processed safely. It keeps the original context and failure information available so an operator or recovery workflow can decide whether to retry, repair, reject, or escalate.
Should every failed AI agent task go to a dead-letter queue?
No. Use bounded retries for known transient failures where replay is safe. Use a DLQ when retries are exhausted, the failure is ambiguous, the request may have caused a side effect, or the item needs a human decision.
Can a dead-letter queue prevent duplicate replies?
It can help, but only if the recovery record includes a stable message ID and delivery state. Before replaying, check whether the original response or external action already completed. A queue without idempotency checks can preserve and repeat the same mistake.
What should an operator inspect before replaying an agent message?
Inspect the original event, conversation target, failure reason, prior tool calls, external action IDs, and delivery status. If the run may have changed an external system, require explicit approval before replaying it.
Sources: OpenClaw v2026.7.2-beta.7 release notes · AWS: what is a dead-letter queue? · Amazon SQS dead-letter queue guidance · Microsoft Service Bus dead-letter queue guidance