IBM MQ Agent

The IBM® MQ Agent is a separately downloadable IBM MQ component that provides an AI agent to help you explore your configuration, check the status of objects, and diagnose problems with your IBM MQ system.

Overview

The IBM MQ Agent is designed to help you understand how your IBM MQ queue managers are configured, lead real-time diagnostic investigation, and provide general information about IBM MQ concepts and terms. For example, in a system that is running well, messages flow freely from producers to consumers and should not spend a long time queued in the system. However, some issues can cause messages to build up on a queue. If queues fill up, applications can no longer put messages to the affected queues. Where messages are not flowing correctly, applications might not be able to get messages for processing. The IBM MQ Agent can help you identify and understand the cause of the message build-up (and other problems) so that you can get your messages moving again.

Note: The IBM MQ Agent can query and reason about your system based on queue manager state. The IBM MQ Agent cannot process or run commands such as IBM MQ script (MQSC) commands.

The IBM MQ Agent is a container-based offering that includes the following items:

Configuration for the agent to connect to (and interact with) up to twenty queue managers, which can be running anywhere in your estate.
A Model Context Protocol (MCP) server that hosts a suite of tools for gathering information from your IBM MQ queue managers.
An agent runtime that you interact with, which uses AI models, and tools that are hosted by the MCP server, to answer your questions.

You manage your entitlement to use the IBM MQ Agent as an extension of the entitlement that you purchase for IBM MQ Advanced or IBM Cloud Pak® for Integration. For more information, see Support and entitlement for the IBM MQ Agent.

After you install the IBM MQ Agent and complete the configuration, you can use the chat assistant to ask the IBM MQ Agent questions about your IBM MQ installation and environment. To answer your questions, the IBM MQ Agent has capabilities that are designed around core queue manager concepts. For example:

Queue manager: configuration and status
Channels: client, server, sender, receiver, status, and related diagnostics
Queues: local, remote, transmission, model queues, status, and related diagnostics
Listeners: listener status and related diagnostics
Clustering: clustering objects, status, and related diagnostics
Applications: application connectivity status and related diagnostics
Message build-up: analysis of queue managers to identify message build-up and recommend remedial actions
Documentation: context enhanced search and next-step planning by using IBM MQ documentation

A screenshot of the welcome page, with the following text: "The IBM MQ Agent chat assistant uses generative Al. Output may not be accurate, and IBM has no responsibility for any such Output. IBM warranties and support do not apply to such Output; it is used at Licensee's risk. Welcome to the MQ Agent chat. I'm here to help you, ask me what I can do." — Figure 1. Chat assistant welcome page

Use cases

The agent uses conversation context and conversation history to select which of its capabilities can help you analyze your IBM MQ configuration and diagnose problems. Here are some examples of the type of question and problem determination that the IBM MQ Agent can help you with:

Questions about IBM MQ objects and status

Report cluster memberships of a queue manager
Report IBM MQ versions and platforms in your queue manager estate
Show the queues that are available on a queue manager or set of queue managers
Identify queues that have a current depth of more than 100 messages (for example)
Identify queues on queue managers where messages haven't been processed for more than 30 minutes (for example)
Identify queues with no connected consuming applications
Report queues with a specified attribute, for example list shared queues on a queue manager
Show channels that are in a retry state
Show all running listeners on a queue manager or set of queue managers
Identify where an application is connected

Problem determination

Diagnose why a channel is in a stopped state
Understand why messages were delivered to a dead letter queue
Search error logs to help diagnose problems that are related to channels
Understand which ports listeners are running on
Identify and diagnose general message build-up problems
Diagnose slow message flow over a network
Understand why messages are building up

Intelligent insights and next step planning

Explain an IBM MQ concept
Reason about configuration issues
Predict future outcomes based on real-time status
Help you plan your next steps to resolve a problem

Examples

Here are some examples of general questions and instructions that you might ask the IBM MQ Agent:

What queue managers can you see?
What version are my queue managers?
Do I have message build up?
What is the problem with <queue name> on <queue manager name>?
Diagnose <queue name> on <queue manager name>
Why are messages building up on <queue name> on <queue manager name>?
Is there a problem with the dead letter queue on <queue manager name>?

Here is an example of a conversation that you might have with the IBM MQ Agent:

User: What queue managers are available?

Agent: The available queue managers are:

-  QM1
-  QM2
-  QM3

User: What MQ versions are those queue managers on?

Agent: Here's the MQ version information for the queue managers you asked about:

-  QM1: 9.4.5.0
-  QM2: 9.4.5.0
-  QM3: 9.4.3.0

User: What's the deepest queue on QM1?

Agent: The deepest queue on the QM1 queue manager is queue4, with a current depth of 5,000 messages. Other queues have lower depths, with the next highest being important at 4,950 messages. Some queues (like model, alias, or remote queues) don't have depth values.

User: Why is this queue built up?

Agent: The queue queue4 on queue manager QM1 is built up because there are no applications consuming or producing messages from it. Here are the key details:

The queue is enabled for getting messages, but there are no active consumers (IPPROCS = 0).
There are also no active producers (OPPROCS = 0), so no new messages are being added.
The queue is currently at 100% capacity, with 5000 messages (the maximum allowed).
No messages have been consumed from the queue, and the last time a message was added was 29 days ago.

In short, the queue is full because messages are not being processed or removed, and no new messages are being added either.

User: How should I fix this problem?

Agent: To fix the problem with queue qm4 on queue manager QM1, you'll need to address the lack of message consumers. Here's what I found:

The queue is completely full (5000/5000 messages) because:

There are no applications consuming messages from it (IPPROCS = 0)
Messages have been accumulating for 29 days without being processed
While the queue is enabled for getting messages, nothing is actually retrieving them

To resolve this:

You'll need to either:
- Start an application that should be consuming messages from this queue, or
- Clear out the existing messages if they're no longer needed
For immediate relief, you could:
- Increase the queue's maximum depth temporarily
- Manually clear some messages to prevent further buildup

The root cause appears to be that whatever application should be processing these messages isn't running or isn't properly connected to this queue.

User: How do I increase the queue depth?

Agent: To increase the queue depth for queue queue4 on queue manager QM1, you'll need to modify the MAXDEPTH parameter. Here's how to do it:

First, determine the new value for MAXDEPTH based on your expected message volume and available storage.
Use the ALTER QUEUE command to update the queue depth. For your specific queue, the command would be:
```
ALTER QLOCAL ('queue4')
MAXDEPTH(new_value)
```
Replace new_value with your desired maximum depth.