---
schema_version: "1"
id: dcd7271d192c98077e66c5694e037253aa0e22d025d8630ee93622c986522240
title: A2A v1 Agent Card Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/latest/policies-included-a2a-v1-agent-card.md
canonical_url: https://docs.mulesoft.com/gateway/latest/policies-included-a2a-v1-agent-card
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 9a3cc043c64129107ff0f3c84a91e9d67906c04cae0c7ab2fe66435338ee08e1
description: MuleSoft Documentation Site
release: "1.14"
latest: true
---
---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy
---

# A2A v1 Agent Card Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>A2A v1 Agent Card</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Rewrites interface URLs in the A2A v1.0 agent card to match the gateway’s public address</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>A2A</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/a2a-v1-agent-card-release-notes">A2A v1 Agent Card Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

## Summary

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 handles the following response formats:

- Bare card response (`GET /.well-known/agent-card.json` or `GET /extendedAgentCard`)

- JSON-RPC envelope responses (`GetExtendedAgentCard`)

- Server-Sent Events (SSE) streams (`SendStreamingMessage`, `SubscribeToTask`)

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](https://docs.mulesoft.com/gateway/latest/managed-view-api-metrics).

## Configuring Policy Parameters

### Omni Gateway Local Mode

The A2A v1 Agent Card policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th><th>Required</th><th>Default Value</th><th>Example</th></tr></thead><tbody><tr><td><div><div><p>Consumer URL</p></div></div></td><td><div><div><p>The base gateway URL injected into the agent card’s <code>supportedInterfaces[]</code> entries. Each binding’s final URL is the Consumer URL joined with its Interface Paths value (or the bare Consumer URL when no path is set).</p></div><div><p>When undefined, the gateway resolves its public consumer URL from the Anypoint platform.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Resolved from platform</p></div></div></td><td><div><div><p><code>https://gateway.public.example.com/agent/</code></p></div></div></td></tr><tr><td><div><div><p>Agent Card Path</p></div></div></td><td><div><div><p>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.</p></div><div><p>Configure this when the gateway publishes the card under a custom sub-path.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>/.well-known/agent-card.json</code></p></div></div></td><td><div><div><p><code>/agents/finance/.well-known/agent-card.json</code></p></div></div></td></tr><tr><td><div><div><p>Interface Paths - JSON-RPC Path</p></div></div></td><td><div><div><p>Path appended to Consumer URL for interfaces with <code>protocolBinding</code> of <code>JSONRPC</code>.</p></div><div><p>When undefined, the binding uses the bare Consumer URL.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>(bare Consumer URL)</p></div></div></td><td><div><div><p><code>/jsonrpc</code></p></div></div></td></tr><tr><td><div><div><p>Interface Paths - gRPC Path</p></div></div></td><td><div><div><p>Path appended to Consumer URL for interfaces with <code>protocolBinding</code> of <code>GRPC</code>.</p></div><div><p>When undefined, the binding uses the bare Consumer URL.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>(bare Consumer URL)</p></div></div></td><td><div><div><p><code>/grpc</code></p></div></div></td></tr><tr><td><div><div><p>Interface Paths - HTTP+JSON Path</p></div></div></td><td><div><div><p>Path appended to Consumer URL for interfaces with <code>protocolBinding</code> of <code>HTTP+JSON</code>.</p></div><div><p>When undefined, the binding uses the bare Consumer URL.</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>(bare Consumer URL)</p></div></div></td><td><div><div><p><code>/rest</code></p></div></div></td></tr></tbody></table>

## Examples

### Basic Configuration

This example applies the policy with default settings (agent card at `/.well-known/agent-card.json`,
consumer URL resolved from platform).

```yaml
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
```

### Override Consumer URL

This example overrides the consumer URL when running behind a CDN or reverse proxy that the Anypoint
platform doesn’t see.

```yaml
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/"
```

### Custom Card Path

This example matches a custom card path when your agent is mounted under a tenant prefix.

```yaml
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"
```

### Per-Transport Paths

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.

```yaml
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"
```