Getting started Community Training Tutorials Documentation APIs, AI & Tools
Consumer URL
Policy Name |
A2A v1 Agent Card |
Summary |
Rewrites interface URLs in the A2A v1.0 agent card to match the gateway’s public address |
Category |
A2A |
First Omni Gateway version available |
v1.13.0 |
Release Notes |
|
Returned Status Codes |
No return codes exist for this policy. |
The Agent-to-Agent (A2A) v1 Agent Card Policy rewrites the interface URLs inside an A2A v1.0 agent card so that clients reach the agent through Omni Gateway rather than connecting directly to backend services. This ensures that all client requests are routed through Omni Gateway, enabling it to enforce security and access controls.
The policy rewrites the url field for every supported interface (JSONRPC, GRPC, HTTP+JSON) in the supportedInterfaces[] array of the agent card response. Custom protocol bindings aren’t edited.
The policy rewrites URLs in the following agent card response formats:
Bare card response (GET /.well-known/agent-card.json or GET /extendedAgentCard)
JSON-RPC envelope responses (GetExtendedAgentCard)
The policy doesn’t rewrite Server-Sent Events (SSE) streams (SendStreamingMessage, SubscribeToTask). For these streams, the policy only reads the events to record whether the call succeeded.
The A2A v1 Agent Card policy also enables the Total Agent Calls metric that tracks the total successful and unsuccessful calls made to the agent. To view Total Agent Calls, see Viewing Key Metrics in API Manager for Managed Omni Gateway.
The A2A v1 Agent Card policy always buffers the full request body, because it needs the body to determine the A2A method. Responses are handled as follows:
JSON responses: The policy buffers the full response body. It rewrites the URLs in agent card responses and uses other responses only to record metrics.
Unary gRPC responses: The policy buffers the full response body. It rewrites the URLs in GetExtendedAgentCard responses.
Streaming gRPC responses: The policy processes the response chunk by chunk and doesn’t buffer the full stream.
SSE responses: The policy reads the stream one event at a time to record metrics and doesn’t buffer the full stream.
Buffered payloads count toward the Omni Gateway payload limit, which is 1 MB by default. To change the limit on a self-managed Omni Gateway, set the FLEX_DOWNSTREAM_CONNECTION_BUFFER_LIMIT_BYTES environment variable. In Connected Mode, you can also set Global connection buffer limit in Runtime Manager. For more information, see Configure Global and Routing Settings in Runtime Manager. For more information about the limit, see Omni Gateway Limits and Performance Metrics.
When you apply the policy from the UI, the following parameters are displayed:
| Parameter | Description | Required | Default Value | Example |
|---|---|---|---|---|
Consumer URL |
The base gateway URL injected into the agent card’s When undefined, the gateway resolves its public consumer URL from the Anypoint platform. |
No |
Resolved from platform |
|
Agent Card Path |
The suffix path where the well-known agent card is published. The match is case-insensitive and suffix-based, so the configured path resolves under any tenant prefix. Configure this when the gateway publishes the card under a custom sub-path. |
No |
|
|
Interface Paths - JSON-RPC Path |
Path appended to Consumer URL for interfaces with When undefined, the binding uses the bare Consumer URL. |
No |
(bare Consumer URL) |
|
Interface Paths - gRPC Path |
Path appended to Consumer URL for interfaces with When undefined, the binding uses the bare Consumer URL. |
No |
(bare Consumer URL) |
|
Interface Paths - HTTP+JSON Path |
Path appended to Consumer URL for interfaces with When undefined, the binding uses the bare Consumer URL. |
No |
(bare Consumer URL) |
|
This example applies the policy with default settings (agent card at /.well-known/agent-card.json, consumer URL resolved from platform).
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
name: a2a-v1-agent-card
spec:
targetRef:
kind: ApiInstance
name: my-a2a-agent
policyRef:
name: a-two-a-v1-agent-card-flex
namespace: default
This example overrides the consumer URL when running behind a CDN or reverse proxy that the Anypoint platform doesn’t see.
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
name: a2a-v1-agent-card
spec:
targetRef:
kind: ApiInstance
name: my-a2a-agent
policyRef:
name: a-two-a-v1-agent-card-flex
namespace: default
config:
consumerUrl: "https://gateway.public.example.com/agent/"
This example matches a custom card path when your agent is mounted under a tenant prefix.
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
name: a2a-v1-agent-card
spec:
targetRef:
kind: ApiInstance
name: my-a2a-agent
policyRef:
name: a-two-a-v1-agent-card-flex
namespace: default
config:
cardPath: "/agents/finance/.well-known/agent-card.json"
This example gives each transport its own sub-path under the gateway. The final URL for each binding is the Consumer URL joined with its path.
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
name: a2a-v1-agent-card
spec:
targetRef:
kind: ApiInstance
name: my-a2a-agent
policyRef:
name: a-two-a-v1-agent-card-flex
namespace: default
config:
consumerUrl: "https://gateway.public.example.com/agent/"
interfacePaths:
jsonRpc: "/jsonrpc"
grpc: "/grpc"
httpJson: "/rest"