Enable A2A communication with a Copilot Studio agent

By the end of this guide, A2A callers will be able to communicate with a Microsoft Copilot Studio agent through the gateway, with the gateway handling Direct Line protocol translation transparently.

An A2A proxy bridges a Copilot Studio agent, which communicates over the Microsoft Direct Line polling protocol, into the gateway’s A2A pipeline. The proxy synthesises an A2A agent card for the Copilot Studio agent and translates message/send calls into Direct Line activities transparently. For background on how the gateway processes A2A traffic, see A2A protocol.

Without an A2A proxy, a Copilot Studio agent cannot be addressed by A2A callers through the gateway. Callers must implement the Direct Line polling protocol directly, and the gateway cannot apply policy or observability to those interactions.

Use this guide when:

• You have a Copilot Studio agent published to a Direct Line channel.
• You want A2A callers to reach the agent through a governed gateway surface.

Prerequisites

• A running Agent Gateway instance with the dashboard accessible.
• Administrator role on the gateway.
• The copilot_integration feature flag enabled (on by default). Confirm it is toggled on under Settings → Admin → Feature Flags if the Proxies screen or the via A2A Proxy endpoint type is not visible.
• A Copilot Studio agent published to the Direct Line channel, with the Direct Line channel secret available. The agent must respond correctly in the Test your agent chat panel before proceeding. See Microsoft Copilot Studio documentation for setup guidance.
• An existing A2A surface, or permission to create one. See A2A surface starter.

Steps

Store the Direct Line secret

The proxy authenticates to Copilot Studio over the Direct Line channel. Before storing the secret in the gateway, configure authentication in Copilot Studio and retrieve the channel secret.

In Copilot Studio:

1. Open your agent and go to Settings → Security.
2. Under Authentication, select No Authentication and save.
3. On the same page, locate the Web Channel Security section, enable the Require secured access toggle, and copy the channel secret shown there.

In the Agent Gateway dashboard:

4. Navigate to Management → Secrets.
5. Select New Secret.
6. Fill in the fields:
   • Secret Name: a descriptive label, for example Copilot Direct Line Secret.
   • Secret Type: select Token.
   • Secret Value: paste the Direct Line channel secret you copied from Copilot Studio.
7. Select Save.

Important

Do not hardcode the secret value in any configuration, script, or source file. Rotate the secret through Management → Secrets rather than updating it directly in the proxy settings.

For details on secret types and storage, see Secrets reference.

Create the A2A proxy

1. Navigate to Proxies in the sidebar.
2. Select Add A2A Proxy.

The editor opens with three tabs: Overview, Backend, and Agent Card.

Overview tab

Fill in the proxy identity:

• Name: A descriptive label, for example Copilot HR Agent.
• Description: Optional context for other administrators.
• Status: Leave as Active.

Backend tab

The backend type is Copilot Direct Line and cannot be changed. Configure the connection fields:

Field	What to enter
Direct Line Secret	Select the secret you stored in Step 2.
Credential Mode	Select Generate Direct Line token to exchange the secret for a short-lived token on each request. Use Direct Line secret only when token generation is unavailable.
Direct Line Base URL	Leave blank to use the default Microsoft Direct Line endpoint.
Timeout seconds	Increase above the default if the Copilot Studio agent takes longer to produce a first activity. Accepts values from 1 to 120.
Poll interval ms	How often the proxy polls Direct Line for activity responses. The default is acceptable for most deployments. Accepts values from 100 to 5,000.
Max poll attempts	Maximum polling retries before the proxy returns a timeout. Accepts values from 1 to 240.

Agent Card tab

The proxy synthesises an A2A agent card for the Copilot Studio agent. By default, the card inherits the name and description of the exposing surface. Use the Card name override and Card description override fields only if the published card needs a different identity from the surface.

Under Verifiable identity, configure the Identity source:

• Set Identity source to Microsoft Entra agent identity and fill in:

  • Entra Agent ID: the agent ID from your Copilot Studio agent. Find it in Advanced → Metadata in Copilot Studio.
  • Client Tenant ID: the client tenant ID from the same Advanced → Metadata page in Copilot Studio.

  When these values match what Copilot Studio sends, the synthesised agent card and inbound Copilot calls both resolve to the same agent DID.

Select Create to save the proxy.

Attach the proxy to an A2A surface

The proxy is reachable to A2A callers only when targeted by a surface.

1. Open the A2A surface canvas for the surface that should route to the Copilot Studio agent.
2. Select the Managed Agent node to open its configuration panel.
3. Under Endpoint, set Endpoint Type to via A2A Proxy.
4. From the A2A Proxy dropdown, select the proxy you created in Step 3.
5. Select the save button (blue disk icon in the toolbar) or press Cmd+S / Ctrl+S.

The via A2A Proxy option appears in the Endpoint Type dropdown only when the copilot_integration feature flag is enabled and the surface protocol is A2A or AP2.

Confirm

Test 1: agent card is returned at the surface route

Replace GATEWAY_HOST and SURFACE_ROUTE with the values shown in the Channel Route banner of the Access Point panel.

curl -k https://GATEWAY_HOST/SURFACE_ROUTE/.well-known/agent-card.json

The -k flag disables TLS certificate verification. Use this for local testing only; remove it in production.

Expected: a JSON document containing the agent name, description, and at least one capability entry. The name should match the proxy name (or the Card name override if set).

Test 2: a message/send request returns an agent response

curl -k -X POST https://GATEWAY_HOST/SURFACE_ROUTE/message/send \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "id": 1,
    "params": {
      "message": {
        "messageId": "test-1",
        "role": "user",
        "parts": [{"kind": "text", "text": "Hello"}]
      }
    }
  }'

Expected: a JSON-RPC response where result.kind is message, result.role is agent, and result.parts contains the agent’s reply text. For example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "kind": "message",
    "messageId": "20e9d3d1-fa14-430f-8267-ebdf7f547c54",
    "role": "agent",
    "parts": [{"kind": "text", "text": "Hello, how can I help you today?"}]
  }
}

If the surface has authentication configured, include the required credentials in the request headers.

Troubleshooting

Next steps

• A2A surface starter: Build a full A2A surface to route traffic to the proxy.
• Configure per-caller Credential Delegation: Inject per-user OAuth tokens into outbound calls from the surface.

Related

• A2A protocol: How the gateway processes A2A traffic.
• Secrets reference: Secret types and how the gateway resolves them at runtime.
• Expose a REST API as MCP tools: The equivalent proxy pattern for MCP surfaces and REST backends.