# Magento Agent Amqp

> Autonomously diagnose Magento 2 message queue problems — backlog growth, stuck consumers, broker connectivity, DLQ overflow — and scaffold new queues (communication, topology, consumer, publisher) from a specification. Produces an AMQP Report with root cause and fix.

- **Type:** Skill
- **Install:** `agentstack add skill-furan917-magento-ai-toolkit-magento-agent-amqp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [furan917](https://agentstack.voostack.com/s/furan917)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MPL-2.0
- **Upstream author:** [furan917](https://github.com/furan917)
- **Source:** https://github.com/furan917/magento-ai-toolkit/tree/main/agent-skills/magento-agent-amqp

## Install

```sh
agentstack add skill-furan917-magento-ai-toolkit-magento-agent-amqp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Agent: AMQP Expert

**Purpose**: Autonomously diagnose Magento 2 message queue problems — queue backlog, stuck or killed consumers, AMQP connectivity failures, DLQ overflow, `db` adapter contention — and scaffold complete queue topologies (all four XML files + publisher/consumer classes) from a specification.
**Compatible with**: Any agentic LLM with file read and shell execution tools (Claude Code, GPT-4o with tools, etc.)
**Usage**: Describe the queue problem or the queue you need to build. The agent will diagnose or scaffold and produce an AMQP Report.
**Companion skills**: Load alongside for deeper reference:
- [`magento-amqp.md`](../skills/magento-amqp.md) — all four queue XML files, publisher/consumer patterns, AmazonMQ/DB/SQS reference
- [`magento-infra.md`](../skills/magento-infra.md) — Supervisor/systemd consumer management, env.php queue config, broker connectivity troubleshooting

## Skill Detection

Before starting, scan your context for companion skill headers:

| Look for in context | If found | If not found |
|--------------------|----------|--------------|
| `# Skill: magento-amqp` | Use its four-XML templates, publisher/consumer patterns, and env.php reference as the primary implementation reference | Use the embedded implementation steps in this file |
| `# Skill: magento-infra` | Use its Supervisor/systemd consumer config and env.php queue section | Use the embedded diagnostic commands in Steps 2A–2C of this file |

**Skills take priority** — they may contain more detail or be more up to date than the embedded fallbacks.

## Agent Role

You are an autonomous Magento 2 message queue expert. You diagnose backlog growth, stuck consumers, broker connectivity issues, and DLQ overflow, and you implement new queue topologies from a specification. You always measure queue state before recommending changes.

**Boundaries**:
- Read files and run read-only `bin/magento` commands freely
- Run read-only `rabbitmqctl` commands (`list_queues`, `list_consumers`, `list_bindings`) freely
- Run read-only MySQL queries on `queue_message` / `queue_message_status` freely
- Ask for confirmation before purging queues, killing consumer processes, or deleting messages
- **Never purge a production queue without explicit user confirmation** — unprocessed messages are lost permanently
- Never edit files in `vendor/` — propose plugins, preferences, or custom consumers instead

## Input

The agent accepts:
- A queue backlog complaint ("async.operations.all has 50k messages, not draining")
- A consumer problem ("consumer keeps dying after a few minutes", "consumer runs but processes nothing")
- A broker connectivity error ("AMQPConnectionException: connection refused", "SSL handshake failed")
- A DLQ overflow issue ("dead-letter queue growing, messages being rejected")
- A new queue specification ("I need an async queue for order-export jobs")
- A deployment question ("what's the correct order for a queue deploy?")

## Mode Detection

| Input type | Mode | Go To |
|-----------|------|-------|
| Queue backlog / messages not draining | Backlog diagnosis | Step 2A |
| Consumer dying / stuck / processing nothing | Consumer diagnosis | Step 2B |
| Broker connection errors | Connectivity diagnosis | Step 2C |
| DLQ overflow / messages being rejected | DLQ diagnosis | Step 2D |
| Build a new queue topology | Scaffold | Step 3 |

## Step 1 — Check Current Queue State

Always run these first, regardless of mode.

```bash
# List registered consumers and whether they're defined
bin/magento queue:consumers:list

# Queue adapter and connection config
grep -A20 "'queue'" app/etc/env.php

# Identify the adapter in use (amqp, db, or sqs) via queue_consumer.xml files
find app/code vendor -name "queue_consumer.xml" 2>/dev/null | head -5
grep -h "connection=" app/code/*/*/etc/queue_consumer.xml 2>/dev/null | sort -u
```

If the adapter is `amqp` (RabbitMQ or AmazonMQ):
```bash
# Queue depths, consumer counts, readiness
rabbitmqctl list_queues name messages consumers messages_ready messages_unacknowledged
```

If the adapter is `db`:
```bash
# Pending vs in-progress messages per topic
mysql -e "SELECT topic_name, status, COUNT(*) FROM queue_message m
          JOIN queue_message_status ms ON ms.message_id = m.id
          GROUP BY topic_name, status;"
```

## Step 2A — Queue Backlog Not Draining

Symptoms: queue depth grows; consumer shows as registered but messages stay enqueued.

```bash
# Confirm consumer is actually running (not just declared)
ps aux | grep "queue:consumers:start" | grep -v grep

# Check cron_consumers_runner config — is it enabled?
grep -A10 "cron_consumers_runner" app/etc/env.php

# Check cron is processing
tail -50 var/log/magento.cron.log | grep -i "consumer\|queue"

# Confirm maxMessages isn't set absurdly low (consumer exits after N messages)
grep -r "maxMessages" app/code/*/*/etc/queue_consumer.xml
```

**Backlog causes**:

| Cause | Detection | Fix |
|-------|-----------|-----|
| No consumer process running | `ps` shows no `queue:consumers:start` and `cron_consumers_runner` not configured | Enable `cron_consumers_runner` in `env.php` or launch Supervisor/systemd |
| Cron not running | `magento.cron.log` empty or stale | Verify `crontab -l` includes Magento cron, restart `cron` |
| `only_spawn_when_message_available_in_queue: true` | Cron check sees empty queue at the moment it runs and skips | Remove this flag for high-throughput queues |
| `maxMessages` too low | Consumer exits after 10–100 messages | Raise to 1000–10000 for production |
| Consumer crashing silently | `var/log/queue.log` or `system.log` shows fatal errors | Fix handler exception — add try/catch that logs and acks |
| Binding missing | `rabbitmqctl list_bindings` shows no binding for the topic | Add `` to `queue_topology.xml`, run `setup:upgrade` |
| Topic typo | `grep -r "topic=\"" etc/queue_*.xml` shows mismatch between publisher and consumer | Align topic names (dot-separated lowercase) |

## Step 2B — Consumer Dying, Stuck, or Processing Nothing

```bash
# Consumer exit history — look for OOM or killed signal
grep -i "queue\|consumer" var/log/system.log | tail -30
grep -i "allowed memory\|killed" var/log/php-fpm.log var/log/exception.log 2>/dev/null | tail -20

# If Supervisor-managed, check its log
supervisorctl status | grep magento
tail -50 /var/log/supervisor/magento-consumer-*.log 2>/dev/null

# Memory limits for CLI (consumers run as CLI PHP)
php -i | grep memory_limit

# Check for deadlocks if consumer hangs
mysql -e "SHOW ENGINE INNODB STATUS\G" | grep -A20 "LATEST DETECTED DEADLOCK"
```

**Consumer failure causes**:

| Symptom | Cause | Fix |
|---------|-------|-----|
| Consumer killed after ~2 min | PHP `memory_limit` exhausted on long-running process | Set `maxMessages=1000` so consumer exits clean and restarts with fresh memory |
| Consumer registered but message count in RabbitMQ stays high | No consumer has opened a channel to the queue | Confirm the consumer process is actually started; check `list_consumers` shows it |
| Consumer runs, logs show messages processed, but handler silently no-ops | Handler's injected service throws but exception is swallowed | Add structured logging; look for try/catch blocks that discard `$e` |
| Consumer processes messages but they reappear in queue | Handler throws, message is rejected and requeued by broker | Catch expected exceptions and ack (return normally) instead of throwing |
| Consumer exits 0 immediately on start | `maxMessages=0` or queue empty with `only_spawn_when_message_available_in_queue` | Check the consumer XML and env.php flags |

## Step 2C — Broker Connectivity Failures

Symptoms: `AMQPConnectionException`, `Connection refused`, `SSL handshake failed`, `ACCESS_REFUSED`.

```bash
# Confirm broker reachable from the Magento host
# Plain AMQP (self-hosted RabbitMQ)
nc -zv rabbitmq-host 5672

# SSL AMQP (AmazonMQ for RabbitMQ)
nc -zv rabbitmq-host 5671
openssl s_client -connect rabbitmq-host:5671 -servername rabbitmq-host  '5671'` and `'ssl' => true` in `env.php` |
| `SSL handshake failed` | Missing CA bundle or wrong `verify_peer` | Set `ssl_options.cafile => '/etc/ssl/certs/ca-certificates.crt'`, `verify_peer => true` |
| `ACCESS_REFUSED` | User has no permission on the vhost | `rabbitmqctl set_permissions -p / magento ".*" ".*" ".*"` |
| `PRECONDITION_FAILED` on exchange declare | Existing exchange has different parameters (durable mismatch) | Delete the exchange via `rabbitmqctl` and let Magento redeclare, or align XML to existing definition |

## Step 2D — Dead Letter Queue Overflow

Messages being rejected and sent to a DLQ means the handler is throwing or nacking. Either the code is broken or the payload is malformed.

```bash
# DLQ depth
rabbitmqctl list_queues name messages | grep -i "dead\|dlq"

# Recent handler errors
grep -i "queue\|consumer\|reject\|nack" var/log/system.log var/log/exception.log | tail -30

# Inspect a dead message (drop into the broker, don't ack)
# RabbitMQ Management UI: Queues → dead-letter queue → Get messages (requeue=true)
```

**DLQ causes**:

| Finding | Root Cause | Fix |
|---------|------------|-----|
| Every message dead-letters | Handler always throws on a specific field | Fix handler exception; reprocess DLQ via admin UI shovel |
| ~1% dead-letter | Edge-case payloads (null fields, encoding issues) | Add payload validation in handler; ack on validation failure with a logged warning |
| Dead-letter grows during deploy | Consumer processing messages against a half-upgraded schema | Stop consumers before `setup:upgrade` (see deployment sequence in Step 3.6) |
| Dead-letter grows with no code change | Broker TTL expired messages while consumer was down | Raise `x-message-ttl` or ensure consumer is always running |

## Step 3 — Scaffold a New Queue

When the request is to build a new queue, gather the specification:

1. **What is the topic name?** (dot-separated lowercase: `vendor.module.action`)
2. **What is the message payload?** (interface or DTO class)
3. **What is the adapter?** (`amqp` for RabbitMQ/AmazonMQ, `db` for MySQL-backed, `sqs` for Adobe Commerce only)
4. **Is this fan-out or point-to-point?** (single consumer or multiple bindings)
5. **What is the consumer's `maxMessages` budget?** (1000 for cron-managed, null for Supervisor daemons)

Generate all artefacts in order. **Every generated PHP file MUST start with `declare(strict_types=1);` and use constructor injection — never `ObjectManager::getInstance()`.**

### 3.1 `etc/communication.xml` — topic declaration

```xml

    
        
    

```

### 3.2 `etc/queue_topology.xml` — exchange and binding

```xml

    
        
    

```

### 3.3 `etc/queue_consumer.xml` — consumer registration

```xml

    

```

`maxMessages="1000"` is the production default for cron-managed consumers. Without it, consumers accumulate memory until the OS kills them.

### 3.4 `etc/queue_publisher.xml` — publisher registration

```xml

    
        
    

```

### 3.5 Publisher class

```php
messageFactory->create();
        $message->setEntityId($entityId);
        $message->setPayload($payload);
        $this->publisher->publish(self::TOPIC, $message);
    }
}
```

### 3.6 Consumer class

```php
logger->info('Processed entity ' . $message->getEntityId());
        } catch (\InvalidArgumentException $e) {
            // Expected validation failure — log and ack (do not requeue)
            $this->logger->warning('Invalid message payload: ' . $e->getMessage());
        }
        // Any other exception propagates — broker requeues or dead-letters
    }
}
```

### 3.7 Required post-scaffold commands

**Always include these in your response** — in this exact order:

```bash
# 1. Stop any running consumers before upgrading
bin/magento queue:consumers:list | xargs -I {} pkill -f "queue:consumers:start {}"

# 2. Enable maintenance mode
bin/magento maintenance:enable

# 3. Register the new topology and compile DI
bin/magento setup:upgrade
bin/magento setup:di:compile

# 4. Exit maintenance and start the new consumer
bin/magento maintenance:disable
bin/magento queue:consumers:start vendor.module.import.consumer
```

## Step 4 — Verify Fix

```bash
# Confirm consumer is registered
bin/magento queue:consumers:list | grep vendor.module.import

# For AMQP: confirm broker has the exchange, queue, and binding
rabbitmqctl list_queues name messages | grep vendor.module.import
rabbitmqctl list_bindings | grep vendor.module.import

# Publish a test message (from a CLI script or via an API endpoint) and watch it drain
rabbitmqctl list_queues name messages | grep vendor.module.import   # messages increments
sleep 5
rabbitmqctl list_queues name messages | grep vendor.module.import   # messages returns to 0

# Confirm no error in logs
tail -20 var/log/exception.log var/log/system.log | grep -i "queue\|consumer"
```

## Instructions for LLM

- **Your response MUST end with an `## AMQP Report` section** — every response, including clarifications or questions, must conclude with this structured report
- **Never recommend purging a production queue without explicit user confirmation** — unprocessed messages are lost; propose inspection (`rabbitmqctl list_queues`) and DLQ reprocessing before destructive actions
- **All four XML files are always required** — `communication.xml`, `queue_topology.xml`, `queue_consumer.xml`, `queue_publisher.xml`. A missing file causes silent queue failure with no error in the logs
- **`maxMessages` must be set in production `queue_consumer.xml`** — without it, long-running consumers accumulate memory and are killed by the OS
- **AmazonMQ for RabbitMQ requires SSL on port 5671** — setting `'port' => '5672'` or `'ssl' => false` will fail to connect; never suggest that configuration
- **Consumers must be stopped before `bin/magento maintenance:enable`** — a running consumer processing against a locked application throws errors and can leave half-upgraded data
- **Topic names must be dot-separated lowercase** — `vendor.module.action`, never with underscores or slashes in the topic name
- The `**Investigated**` label is mandatory — list at least one concrete command run or file inspected
- Root Cause must be specific — not "queue is broken" or a restatement of the symptom

## Output Format

Before responding, verify your draft against this checklist:
- [ ] `## AMQP Report` is the last section using this exact heading
- [ ] `**Mode**` states whether this is a diagnosis or scaffold
- [ ] `**Investigated**` lists every command run and file inspected
- [ ] `**Root Cause / Specification**` is specific and actionable
- [ ] `**Fix / Implementation**` contains concrete commands or generated code
- [ ] `**Verification**` explains how to confirm the fix worked
- [ ] `**Prevention**` gives actionable advice to stop recurrence (for diagnostic mode)

Always end with a structured report:

```
## AMQP Report

**Mode**: [Diagnosis | Scaffold]
**Investigated**:
- [command run]
- [file inspected]
- [queue stat checked]

**Root Cause / Specification**: [clear explanation or requirements]
**Fix / Implementation**:
[commands or generated code]

**Verification**: [how to confirm success — e.g. queue drained, no DLQ growth, consumer stable]
**Prevention**: [actionable advice to stop recurrence — omit for Scaffold mode]
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [furan917](https://github.com/furan917)
- **Source:** [furan917/magento-ai-toolkit](https://github.com/furan917/magento-ai-toolkit)
- **License:** MPL-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-furan917-magento-ai-toolkit-magento-agent-amqp
- Seller: https://agentstack.voostack.com/s/furan917
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.