Merge branch 'latest' into W-21162798-Combine-overviews-for-agent-network/agent-fabric-ie

Author: IsaacEldridge

modules/ROOT/pages/af-project-files.adoc

@@ -342,6 +342,9 @@ tools:
         name: talent-pool-mcp         # Exchange asset ID of MCP server. By default, the groupId for this asset is the same as that in exchange.json.
       allowed:                        # Allowlist specific tools
         - TalentPoolMcpServer.match_email_to_address
+      headersToPropagate: 
+        - Authorization
+        - X-Correlation-Id           # Optional. Header names to forward when invoking this tool.
   - mcp:
       ref:
         name: slack-mcp
@@ -358,6 +361,7 @@ The `tools` element has these properties.
 |`mcp.ref` |The reference to the MCP server that is available to this broker. |String |See <<mcp-servers-section,MCP Servers>> |Yes
 |`mcp.connection.ref` |Connection reference. |String |See <<connections-section,Connections>> |No
 |`mcp.allowed` |Filters the list of tools advertised by the MCP server to only those in this list. Mutually exclusive with 'denied'. |Array of strings |Array of tool name strings |No
+|`mcp.headersToPropagate` |The names of the request headers to propagate when the broker invokes this tool. |Array of strings |Array of header name strings |No
 |===
 
 [[links-section]]
@@ -376,6 +380,9 @@ links:
       ref:
         name: hr-agent        # Exchange asset ID of the linked agent. By default, the groupId for this asset is the same as that in exchange.json.
         namespace:            # Optional. If the asset was defined in a different business group, set the corresponding groupId here.
+      headersToPropagate: 
+        - Authorization
+        - X-Correlation-Id   # Optional. Header names to forward when invoking this agent.
   - agent:
       ref:
         name: badging-agent
@@ -415,6 +422,7 @@ The `links` element has these properties.
 |`links[].agent.ref.name` |Exchange asset ID of the linked agent. This references the `assetId` that the agent has in Anypoint Exchange, not the human-friendly name.|String|Asset ID string (for example, "hr-agent", "crm-agent"). By default, the groupId for this asset is the same as that in exchange.json|Yes
 |`links[].agent.ref.namespace` |Business group ID (groupId) where the asset is defined. Use this when the asset was defined in a different business group than the current one.|String|Group ID string. To find the groupId, look in the `dependencies` section in `exchange.json`|No
 |`links[].agent.connection.ref` |Connection reference.|String|See <<connections-section,Connections>>. This references a connection defined in the `connections` section|No
+|`links[].agent.headersToPropagate` |The names of the request headers to propagate when the broker invokes this agent.|Array of strings|Array of header name strings |No
 |===
 
 
@@ -779,7 +787,7 @@ The `connections` element has these properties.
 |`spec` |Connection specification. Properties vary by connection kind. |Object |Object with spec properties (See <<spec-section,Spec>>) |Yes
 |`spec.url` |The URL for the connection endpoint. |String |Valid URL string |Yes (for agent and llm), No (for mcp)
 |`spec.authentication` |Authentication configuration for the connection. |Object |Authentication object (See <<authentication-types,Authentication types>>) |No
-|`spec.authentication.kind` |The type of authentication. |String |`basic`, `oauth2-client-credentials`, `apikey-client-credentials`, `apiKey` |Yes (when authentication is specified)
+|`spec.authentication.kind` |The type of authentication. |String |`basic`, `oauth2-client-credentials`, `apikey-client-credentials`, `apiKey`, `in-task-authorization-code`, and `oauth2-obo` |Yes (when authentication is specified)
 |`spec.authentication.username` |The username for basic authentication. |String |Any string value |Yes (for basic auth)
 |`spec.authentication.password` |The password for basic authentication. |String |Any string value |Yes (for basic auth)
 |`spec.authentication.headerName` |The name of the header in which to set the key. If not specified, 'Authorization' is set by default. |String |Any string value |No
@@ -864,7 +872,7 @@ Both agents and MCP servers support the same authentication types with custom he
 [source,yaml]
 ----
 authentication:
-  Kind: basic
+  kind: basic
   username: "username"
   password: "password"
 ----
@@ -879,6 +887,18 @@ kind: basic
   headerName: X-API-Authorization  # Custom header instead of default "Authorization"
 ----
 
+The `basic` authentication has these properties.
+
+[cols="1,2,1,2,1",options="header"]
+|===
+|Parameter |Description |Type |Valid Values |Required
+
+|`kind` |Authentication type. |String |`basic` |Yes
+|`username` |The username for authentication. |String |Any string |Yes
+|`password` |The password for authentication. |String |Any string |Yes
+|`headerName` |The name of the header in which to set the credentials. If not specified, `Authorization` is used. |String |Any string |No
+|===
+
 [[oauth-client-credentials]]
 ==== OAuth 2.0 Client Credentials
 
@@ -888,10 +908,29 @@ authentication:
   kind: oauth2-client-credentials
   clientId: "client_id"
   clientSecret: "client_secret"
-  tokenUrl: "https://oauth.provider.com/token"
+  token:
+    url: "https://oauth.provider.com/token"
+    bodyEncoding: form
+    timeout: 300
   scopes: ["read", "write"]             # Optional
 ----
 
+The `oauth2-client-credentials` authentication has these properties.
+
+[cols="1,2,1,2,1",options="header"]
+|===
+|Parameter |Description |Type |Valid Values |Required
+
+|`kind` |Authentication type. |String |`oauth2-client-credentials` |Yes
+|`clientId` |The client ID. |String |Any string |Yes
+|`clientSecret` |The client secret. |String |Any string |Yes
+|`token` |Configuration for fetching the token. |Object |Object with token properties |Yes
+|`token.url` |The URL of the token provider. |String |Valid URL |Yes
+|`token.timeout` |Time in seconds to wait for the service to return the token. |Number |Any number |No
+|`token.bodyEncoding` |The encoding format for the token request body. |String |`form`, `json` |No
+|`scopes` |An array of scopes to request. |Array |Array of scope strings |No
+|===
+
 [[anypoint-client-credentials]]
 ==== Anypoint Client Credentials
 
@@ -903,6 +942,17 @@ authentication:
   clientSecret: "client_secret"
 ----
 
+The `apikey-client-credentials` authentication has these properties.
+
+[cols="1,2,1,2,1",options="header"]
+|===
+|Parameter |Description |Type |Valid Values |Required
+
+|`kind` |Authentication type. |String |`apikey-client-credentials` |Yes
+|`clientId` |The client ID. |Object |Object with `value` and optional `name` (default header name is `client_id`) |Yes
+|`clientSecret` |The client secret. |Object |Object with `value` and optional `name` (default header name is `client_secret`) |Yes
+|===
+
 [[api-key]]
 ==== API Key Authentication
 
@@ -924,6 +974,112 @@ authentication:
   headerName: X-Custom-Auth-Token  # Custom header name
 ----
 
+The `apiKey` authentication has these properties.
+
+[cols="1,2,1,2,1",options="header"]
+|===
+|Parameter |Description |Type |Valid Values |Required
+
+|`kind` |Authentication type. |String |`apiKey` |Yes
+|`apiKey` |The value of the API key. |String |Any string |Yes
+|`headerName` |The name of the header in which to set the key. If not specified, `Authorization` is used. |String |Any string |No
+|===
+
+[[in-task-auth]]
+==== In-Task Authorization Code
+
+Use `in-task authorization code` when the connection needs secondary credentials obtained during a task using the OAuth 2.0 Authorization Code flow. OAuth2 tokens are extracted from message data and injected into the `Authorization` header for upstream calls. This supports step-up or in-task authentication (for example, when a user must re-authenticate for a sensitive action). For more information about the associated policy, see xref:gateway::policies-outbound-a2a-intask-authorization-code.adoc[].
+
+[source,yaml]
+----
+authentication:
+  kind: in-task-authorization-code
+  secondaryAuthProvider: providerName
+  authorizationEndpoint: https://oauth.provider.com/authorize
+  tokenEndpoint: https://oauth.provider.com/token
+  scopes: Read
+  redirectUri: https://oauth.provider.com/callback
+  responseType: code
+  tokenAudience: https://api.example.com/agents/my-agent
+  codeChallengeMethod: S256
+  bodyEncoding: form
+  challengeResponseStatusCode: 200 #Optional, Status code for challenge response. Default: 200.
+  tokenTimeout: 300  #Optional. Timeout in seconds for token requests. Default: 300.
+----
+
+The `in-task-authorization-code` authentication has these properties.
+
+[cols="1,2,1,2,1",options="header"]
+|===
+|Parameter |Description |Type |Valid Values |Required
+
+|`kind` |Authentication type. |String |`in-task-authorization-code` |Yes
+|`authorizationEndpoint` |OAuth2 authorization endpoint URL. Used to generate the authentication challenge. |String |Valid URL |Yes
+|`tokenEndpoint` |OAuth2 token endpoint URL. Used to generate the authentication challenge. |String |Valid URL |Yes
+|`scopes` |OAuth2 scopes required for step-up authentication. |String |Space- or comma-separated scope list (for example, `openid profile email`) |Yes
+|`redirectUri` |OAuth2 redirect URI the client uses in the authorization flow. |String |Valid URI |Yes
+|`secondaryAuthProvider` |Name of the IdP (for example, `okta`, `auth0`). Informational only, for the authentication card. |String |Any string |No
+|`responseType` |OAuth2 response type. |String |Typically `code`. Default: `code` |No
+|`codeChallengeMethod` |PKCE code challenge method. |String |Typically `S256`. Default: `S256` |No
+|`tokenAudience` |Intended recipient of the token (for example, `agent1` or API URL). |String |Any string |No
+|`bodyEncoding` |Encoding for the token request body. |String |`form`, `json`. Default: `form` |No
+|`tokenTimeout` |Timeout in seconds for token requests. |Integer |Positive integer. Default: 300 |No
+|`challengeResponseStatusCode` |HTTP status code returned for auth-required challenge responses. Typically 200 for JSON-RPC compatibility. |Integer |HTTP status code. Default: 200 |No
+|===
+
+
+[[obo-credential-injection]]
+==== OAuth 2.0 OBO Credential Injection
+
+This authentication type supports OAuth 2.0 Token Exchange and Microsoft Entra ID On-Behalf-Of protocols. For more information about the associated policy, see xref:gateway::policies-outbound-oauth-obo.adoc[].
+
+Using OAuth 2.0 Token Exchange:
+
+[source,yaml]
+----
+authentication:
+  kind: oauth2-obo
+  flow: oauth2-token-exchange
+  tokenEndpoint: https://oauth.provider.com/token
+  clientId: clientId
+  clientSecret: clientSecret
+  targetType: audience
+  targetValue: https://api.example.com/agents/my-agent
+  scope: Read #optional, OAuth 2.0 scope to request. Required for Microsoft Entra OBO (for example, api://downstream-client-id/.default). Optional for OAuth 2.0 Token Exchange (RFC 8693).
+  timeout: 5000 #optional, Timeout for token exchange requests in milliseconds. Default: 10000.
+----
+
+Using Microsoft Entra ID On-Behalf-Of:
+
+[source,yaml]
+----
+authentication:
+  kind: oauth2-obo
+  flow: microsoft-entra-obo
+  tokenEndpoint: https://oauth.provider.com/token
+  clientId: clientId
+  clientSecret: clientSecret
+  scope: api://downstream-client-id/.default
+  timeout: 5000 #optional, Timeout for token exchange requests in milliseconds. Default: 10000.
+----
+
+The `oauth2-obo` authentication has these properties.
+
+[cols="1,2,1,2,1",options="header"]
+|===
+|Parameter |Description |Type |Valid Values |Required
+
+|`kind` |Authentication type. |String |`oauth2-obo` |Yes
+|`flow` |Token exchange flow type. |String |`oauth2-token-exchange`, `microsoft-entra-obo` |Yes
+|`clientId` |OAuth2 client ID for token exchange. |String |Any string |Yes
+|`clientSecret` |OAuth2 client secret for token exchange. |String |Any string |Yes
+|`tokenEndpoint` |OAuth2 token endpoint URL for token exchange. |String |Valid URL |Yes
+|`targetType` |Parameter type for specifying the target service (audience for logical name, resource for physical URI). Used for OAuth 2.0 Token Exchange. |String |`audience`, `resource`. Default: `audience` |No
+|`targetValue` |Target audience URI or resource URI for the exchanged token. Required for OAuth 2.0 Token Exchange. |String |Valid URI |Required when using `oauth2-token-exchange` with a target
+|`scope` |OAuth scope to request. Required for Microsoft Entra OBO (e.g. `api://downstream-client-id/.default`). Optional for OAuth 2.0 Token Exchange. |String |Any string |Required for `microsoft-entra-obo`
+|`timeout` |Timeout for token exchange requests in milliseconds. |Integer |Positive integer. Default: 10000 |No
+|===
+
 [[exchange-json-file-element]]
 == exchange.json File Element
 

modules/ROOT/pages/af-troubleshoot-agent-networks.adoc

@@ -17,39 +17,23 @@ Enable logging and log levels from CloudHub 2.0 or Runtime Fabric:
 * xref:runtime-fabric::deploy-to-runtime-fabric.adoc#configure-logging-and-log-levels[Runtime Fabric]
 . Set the log level to Debug for these classes:
 +
-* `com.mulesoft.modules.agent.broker`
-* `org.mule.service.http.impl.service.HttpMessageLogger`
+* `com.mulesoft.modules.agent.broker` (For agent broker)
+* `INSECURE-LOGGING` (For content that can potentially contain sensitive information, such as LLM reasoning, and inputs and outputs from agents and assets defined in `tools` and `links`)
 
 [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.
+`INSECURE-LOGGING` is very likely to contain sensitive information, such as personally identifiable information (PII). Make sure to disable it after troubleshooting is completed.
 
 [[enable-message-logging]]
 == Enable Message Logging Policy
 
-Use API Manager or manually edit the agent network file to add a message logging policy. 
+Edit `agent-network.yaml` to set message logging for MCP servers and agents. 
 
-=== Using API Manager
-
-. 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]`.
-* 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 instance you want to log, add the following inside `policies`:
+Message logging uses the xref:gateway::policies-included-message-logging.adoc[Flex Gateway Message Logging policy]. In the `connection` section of the agent or MCP server instance you want to log, add the following logging policy inside `policies`:
 
 [source,yaml]
 ----
 
-  policies: ## add the following inside the policy setting
+policies: ## add the following inside the policy setting
     - ref:
         name: message-logging
         namespace: business_group_UUID
@@ -83,14 +67,6 @@ If Anypoint Monitoring isn't showing traces for agents and MCP servers, check th
 * 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.