From d7e174b5307547a04d7e5c43a20be7ac70a38d53 Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Thu, 29 Jan 2026 16:10:24 -0800 Subject: [PATCH 1/6] Add troubleshooting guide for agent networks in 'af-troubleshoot-agent-networks.adoc' This new document provides detailed steps for resolving common agent network errors, enabling logging, and configuring message logging policies. It also addresses specific issues such as deployment targets, HTTP errors, and monitoring traces, enhancing overall support for users managing agent networks. --- .../pages/af-troubleshoot-agent-networks.adoc | 116 ++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 modules/ROOT/pages/af-troubleshoot-agent-networks.adoc diff --git a/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc b/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc new file mode 100644 index 000000000..e1277a52e --- /dev/null +++ b/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc @@ -0,0 +1,116 @@ += Troubleshoot Agent Networks + +Resolve common agent network errors and connectivity issues by enabling verbose logging, message logging policies, and distributed tracing. + +[NOTE] +You can use Agent Visualizer to xref:agent-visualizer::troubleshoot-agent-network.adoc[view metrics, logs, and traces] for your agents and MCP servers in your network + +== Enable Logging to Debug Agent Brokers + +You can enable logging and log levels from CloudHub 2.0 or Runtime Fabric. + +1. In Runtime Manager, navigate to the application for the agent broker. +2. Choose one of these options to configure logging: ++ +* xref:cloudhub-2::ch2-manage-app-logs.adoc#configure-log-levels-and-categories[CloudHub 2.0] +* xref:runtime-fabric::deploy-to-runtime-fabric.adoc#configure-logging-and-log-levels[Runtime Fabric] +3. Set the log level to Debug for these classes: ++ +* `com.mulesoft.modules.agent.broker` +* `org.mule.service.http.impl.service.HttpMessageLogger` + +[IMPORTANT] +HTTP wire logging displays HTTP headers and payload in plain text. Avoid leaving it enabled indefinitely or unsupervised, as it can negatively impact API performance. + +[[enable-message-logging]] +== Enable Message Logging Policy + +Use API Manager or manually edit to the agent network file to add a message logging policy. + +=== Using API Manager + +. In API Manage, select the API, agent, or MCP server for which you want to apply the policy. +. Follow the steps in xref:gateway::flex-managed-message-log.adoc#configure-message-logging-in-connected-mode[Configure Message Logging in Connected Mode] and add these settings: ++ +* In the Messages field, enter `#[attributes]`. +* Select the checkboxes for **Before Calling API** and **After Calling API**. +. Click **Save**. + +Afterward, you should see a Message Log option for the API, agent, or MCP server. + +[NOTE] +If you redeploy the network, this policy is deleted. + +=== Using the Agent Network File + +In the `connection` section of the API, agent, or MCP server you want to log, add the following inside `policies`: + +[source,yaml] +---- + + policies: ## add the following inside the policy setting + - ref: + name: message-logging + namespace: business_group_UUID + configuration: + loggingConfiguration: + - itemName: "Payload" + itemData: + message: "#[payload]" + firstSection: true + secondSection: true + level: "INFO" + - itemName: "Headers" + itemData: + message: "#[attributes]" + firstSection: true + secondSection: true + level: "INFO" +---- + +[NOTE] +On non-US control planes, the value for the `namespace` parameter can change. In Exchange, check the group in the policy API Gateway Message Logging Policy Template. + +== Troubleshooting Common Errors and Issues + +Use the steps in this section to diagnose and fix common problems in agent networks. + +=== Issue: No Agent Network Commands in Anypoint Code Builder + +If you installed Anypoint Code Builder successfully, but you don’t see agent network commands in the interface, verify that you have the latest version of the Anypoint Extension Pack. Then, restart VS Code. + +=== Issue: No Agent Network Deployment Targets + +If you attempt to deploy an agent network, but you don’t see any deployment targets in Anypoint Code Builder or Anypoint CLI, then you need to set up your target deployment space and set up gateways. For instructions, see xref:anypoint-code-builder::af-get-started.adoc[Get Started with Agent Networks]. + +=== Error: "Cannot complete task due to issue accessing reasoning engine" + +This is a generic error that the broker issues when the LLM fails. To troubleshoot this error, <> on the LLM instance, and then review the logs to determine the cause of the error. + +=== Error: "HTTP error 404: Agent card not found at /.well-known/agent-card.json" + +You can encounter this error in two different scenarios: + +. The agent card URL is incorrect. In this case: ++ +* Check that the URL you set on the connection ends with a `/`. +* Use a browser or Postman to ping the URL you configured prefixed with `.well-known/agent-card.json`, for example, https://ping-id-agent-url/pingid/.well-known/agent-card.json +. The A2A agent is not configured to use A2A protocol version 0.3.0. In this case: ++ +* If you created the agent with MuleSoft, verify that you are using the A2A connector version 0.4.0 or later. +* If you are using an external agent, verify that it uses the A2A protocol version 0.3.0. + +=== Issue: Agent Visualizer Shows Disconnected Nodes + +If Agent Visualizer shows disconnected nodes with no edges, delete the `extensions` from the `spec.capabilities` section in `agent-network.yaml`. + +== Issue: Traces Not Shown + +If Anypoint Monitoring isn't showing traces for agents and MCP servers, check these settings: + +* In API Manager, verify you've enabled the tracing policy for all brokers and agents. +* In the managed Flex Gateways, verify that you've enabled Distributed Tracing for ingress and egress. + +== Issue: Null Response from Broker + +If your agent network broker returns a null response, restart the broker. From 686d70ce76fc8d8d862631cdb5016790944dac16 Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Thu, 29 Jan 2026 16:10:37 -0800 Subject: [PATCH 2/6] Remove 'af-troubleshoot-anypoint-code-builder.adoc' as it is no longer needed for troubleshooting Anypoint Code Builder issues. --- .../ROOT/pages/af-troubleshoot-anypoint-code-builder.adoc | 5 ----- 1 file changed, 5 deletions(-) delete mode 100644 modules/ROOT/pages/af-troubleshoot-anypoint-code-builder.adoc diff --git a/modules/ROOT/pages/af-troubleshoot-anypoint-code-builder.adoc b/modules/ROOT/pages/af-troubleshoot-anypoint-code-builder.adoc deleted file mode 100644 index d9e3c44b3..000000000 --- a/modules/ROOT/pages/af-troubleshoot-anypoint-code-builder.adoc +++ /dev/null @@ -1,5 +0,0 @@ -= Troubleshoot Anypoint Code Builder - -* If you installed Anypoint Code Builder successfully, but you don't see agent network commands in the interface, verify that you have the latest version of the Anypoint Extension Pack. Then, restart VS Code. - -* If you attempt to deploy an agent network, but you don't see any deployment targets in Anypoint Code Builder or Anypoint CLI, then you need to set up your target deployment space and set up gateways. For instructions, see xref:af-get-started.adoc[]. From 0501dc5c47f37e8cace260909472e6b528873253 Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Thu, 29 Jan 2026 16:17:57 -0800 Subject: [PATCH 3/6] Update navigation and add page alias for troubleshooting agent networks Changed the navigation link from 'af-troubleshoot-anypoint-code-builder.adoc' to 'af-troubleshoot-agent-networks.adoc' for better clarity. Added a page alias in 'af-troubleshoot-agent-networks.adoc' to maintain accessibility for users familiar with the previous document name. --- modules/ROOT/nav.adoc | 2 +- modules/ROOT/pages/af-troubleshoot-agent-networks.adoc | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 810faf242..496cb475f 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -49,7 +49,7 @@ ** xref:af-define-your-agent-network-specification.adoc[] ** xref:af-publish-agent-network-assets.adoc[] ** xref:af-deploy-agent-network-targets.adoc[] -** xref:af-troubleshoot-anypoint-code-builder.adoc[] +** xref:af-troubleshoot-agent-networks.adoc[] ** xref:af-build-agent-networks-in-a-ci-cd-environment.adoc[] ** xref:af-project-files.adoc[] * xref:ai-enabling-api-project-topic-center.adoc[] diff --git a/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc b/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc index e1277a52e..a380a08c0 100644 --- a/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc +++ b/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc @@ -1,4 +1,5 @@ = Troubleshoot Agent Networks +:page-aliases: af-troubleshoot-anypoint-code-builder.adoc Resolve common agent network errors and connectivity issues by enabling verbose logging, message logging policies, and distributed tracing. From 827f0e99d9ea8257dd92ef6a3d4a58619c5892aa Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Fri, 30 Jan 2026 10:39:24 -0800 Subject: [PATCH 4/6] Enhance troubleshooting guide in 'af-troubleshoot-agent-networks.adoc' by adding new common issues and resolutions. Updated section titles for clarity and reorganized content to improve readability. This includes specific troubleshooting steps for traces not shown, disconnected nodes, and null responses from brokers. --- .../pages/af-troubleshoot-agent-networks.adoc | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc b/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc index a380a08c0..f9bedd2bf 100644 --- a/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc +++ b/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc @@ -72,10 +72,25 @@ In the `connection` section of the API, agent, or MCP server you want to log, ad [NOTE] On non-US control planes, the value for the `namespace` parameter can change. In Exchange, check the group in the policy API Gateway Message Logging Policy Template. -== Troubleshooting Common Errors and Issues +== Troubleshooting Common Issues and Errors Use the steps in this section to diagnose and fix common problems in agent networks. +=== Issue: Traces Not Shown + +If Anypoint Monitoring isn't showing traces for agents and MCP servers, check these settings: + +* In API Manager, verify you've enabled the tracing policy for all brokers and agents. +* In the managed Flex Gateways, verify that you've enabled Distributed Tracing for ingress and egress. + +=== Issue: Agent Visualizer Shows Disconnected Nodes + +If Agent Visualizer shows disconnected nodes with no edges, delete the `extensions` from the `spec.capabilities` section in `agent-network.yaml`. + +=== Issue: Null Response from Broker + +If your agent network broker returns a null response, restart the broker. + === Issue: No Agent Network Commands in Anypoint Code Builder If you installed Anypoint Code Builder successfully, but you don’t see agent network commands in the interface, verify that you have the latest version of the Anypoint Extension Pack. Then, restart VS Code. @@ -99,19 +114,4 @@ You can encounter this error in two different scenarios: . The A2A agent is not configured to use A2A protocol version 0.3.0. In this case: + * If you created the agent with MuleSoft, verify that you are using the A2A connector version 0.4.0 or later. -* If you are using an external agent, verify that it uses the A2A protocol version 0.3.0. - -=== Issue: Agent Visualizer Shows Disconnected Nodes - -If Agent Visualizer shows disconnected nodes with no edges, delete the `extensions` from the `spec.capabilities` section in `agent-network.yaml`. - -== Issue: Traces Not Shown - -If Anypoint Monitoring isn't showing traces for agents and MCP servers, check these settings: - -* In API Manager, verify you've enabled the tracing policy for all brokers and agents. -* In the managed Flex Gateways, verify that you've enabled Distributed Tracing for ingress and egress. - -== Issue: Null Response from Broker - -If your agent network broker returns a null response, restart the broker. +* If you are using an external agent, verify that it uses the A2A protocol version 0.3.0. \ No newline at end of file From 6ea4026a14c57107797b7295d03558e80e175733 Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Fri, 30 Jan 2026 11:21:00 -0800 Subject: [PATCH 5/6] Apply suggestions from peer review Co-authored-by: glenn-rodgers-sf <115032644+glenn-rodgers-sf@users.noreply.github.com> --- modules/ROOT/pages/af-troubleshoot-agent-networks.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc b/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc index f9bedd2bf..283bcf563 100644 --- a/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc +++ b/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc @@ -4,11 +4,11 @@ Resolve common agent network errors and connectivity issues by enabling verbose logging, message logging policies, and distributed tracing. [NOTE] -You can use Agent Visualizer to xref:agent-visualizer::troubleshoot-agent-network.adoc[view metrics, logs, and traces] for your agents and MCP servers in your network +Use Agent Visualizer to xref:agent-visualizer::troubleshoot-agent-network.adoc[view metrics, logs, and traces] for your agents and MCP servers in your network == Enable Logging to Debug Agent Brokers -You can enable logging and log levels from CloudHub 2.0 or Runtime Fabric. +Enable logging and log levels from CloudHub 2.0 or Runtime Fabric: 1. In Runtime Manager, navigate to the application for the agent broker. 2. Choose one of these options to configure logging: @@ -26,11 +26,11 @@ HTTP wire logging displays HTTP headers and payload in plain text. Avoid leaving [[enable-message-logging]] == Enable Message Logging Policy -Use API Manager or manually edit to the agent network file to add a message logging policy. +Use API Manager or manually edit the agent network file to add a message logging policy. === Using API Manager -. In API Manage, select the API, agent, or MCP server for which you want to apply the policy. +. In API Manager, select the API, agent, or MCP server instance for which you want to apply the policy. . Follow the steps in xref:gateway::flex-managed-message-log.adoc#configure-message-logging-in-connected-mode[Configure Message Logging in Connected Mode] and add these settings: + * In the Messages field, enter `#[attributes]`. @@ -44,7 +44,7 @@ If you redeploy the network, this policy is deleted. === Using the Agent Network File -In the `connection` section of the API, agent, or MCP server you want to log, add the following inside `policies`: +In the `connection` section of the API, agent, or MCP server instance you want to log, add the following inside `policies`: [source,yaml] ---- From b36a3257ca5f9acd4597363bf09baedd941fffd4 Mon Sep 17 00:00:00 2001 From: Isaac Eldridge Date: Fri, 30 Jan 2026 11:22:30 -0800 Subject: [PATCH 6/6] Refine logging configuration instructions in 'af-troubleshoot-agent-networks.adoc' for clarity. Adjusted formatting and improved readability of steps for enabling logging and setting log levels. --- modules/ROOT/pages/af-troubleshoot-agent-networks.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc b/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc index 283bcf563..a79853200 100644 --- a/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc +++ b/modules/ROOT/pages/af-troubleshoot-agent-networks.adoc @@ -10,12 +10,12 @@ Use Agent Visualizer to xref:agent-visualizer::troubleshoot-agent-network.adoc[v Enable logging and log levels from CloudHub 2.0 or Runtime Fabric: -1. In Runtime Manager, navigate to the application for the agent broker. -2. Choose one of these options to configure logging: +. In Runtime Manager, navigate to the application for the agent broker. +. Choose one of these options to configure logging: + * xref:cloudhub-2::ch2-manage-app-logs.adoc#configure-log-levels-and-categories[CloudHub 2.0] * xref:runtime-fabric::deploy-to-runtime-fabric.adoc#configure-logging-and-log-levels[Runtime Fabric] -3. Set the log level to Debug for these classes: +. Set the log level to Debug for these classes: + * `com.mulesoft.modules.agent.broker` * `org.mule.service.http.impl.service.HttpMessageLogger`