Connect to an agent over the Agent2Agent (A2A) protocol - Microsoft Copilot Studio (original) (raw)

The Agent2Agent (A2A) protocol is an open standard for communication and collaboration between agents.

You can connect your custom agent to another agent that supports the A2A protocol. Copilot Studio uses the A2A protocol to orchestrate with this agent in response to a user request or a trigger.

What is the Agent2Agent (A2A) protocol?

The Agent‑to‑Agent (A2A) protocol defines a standard contract for agent communication. It enables an orchestrator or agent to:

Here's how the A2A protocol compares to a traditional HTTP connection for inter-agent communication:

Feature A2A protocol HTTP connector
Designed for agent workflows ✓ ✗
Supports multiturm interactions ✓ ✗
Provides rich contextual metadata ✓ Limited
Interoperable across frameworks ✓ Varies

By using A2A, Copilot Studio can delegate tasks to another agent, not just call APIs.

When to use A2A connections

Use an A2A connection when you want to integrate agents that already implement the Agent‑to‑Agent protocol. This approach works well for agents that are:

Use alternative integration patterns when appropriate:

Integration need Recommended approach
Connect to APIs or basic HTTP services Custom connectors / HTTP tools
Use MCP tools or resources MCP servers
Integrate agents built with Microsoft 365 Agents SDK Activity Protocol

You can combine multiple integration models within the same Copilot Studio agent.

Connect your agent to another agent over the A2A protocol

  1. Go to the Agents page for your main agent and select Add an agent.
  2. Select Connect to an external agent > Agent2Agent.
  3. Enter your A2A agent's endpoint URL. The endpoint URL should be the endpoint for communication with the agent and not the URL for the agent card.
    Once you enter your endpoint URL, if your agent has a valid agent card on the standard .well-known URL, Copilot Studio automatically pulls the name and description for your agent from the card and populates them into the form for you.
    Note
    If a name and description aren't automatically populated for your agent, it's possible that your agent doesn't have an agent card, the card is located on a different URL than the expected one, or there's a problem communicating with the card. First, check that your agent's endpoint is correct. If it is, you can manually enter an appropriate name and description for your SDK agent. The description should describe the purpose of your agent, so that your main agent can understand when the second agent should be used. Learn more about writing effective metadata. You can also try to navigate to your agent's card in your browser (located at your agent's endpoint + /.well-known/agent.json).
  4. Select the appropriate authentication method, depending on how your SDK agent is configured, from the Authentication dropdown. The options are:
    • None: Select this option if your agent doesn't require authentication or if you're using the sample agent provided in this documentation, which doesn't have authentication enabled.
    • API key: Select this option if your agent requires an API key for authentication. You need to provide the name of the header where the API key should be included or the query parameter.
    • OAuth 2.0: Select this option if your agent uses OAuth 2.0 for authentication. You need to provide the client ID, client secret, authorization URL, token URL, and refresh URL.
      If you select an authentication type other than None, you must also complete the other authentication details.
  5. Select Create.
  6. Select the desired connection from the list of available connections or create a new connection between your A2A agent and your Copilot Studio agent.
  7. Select Add and configure.

Note

You're responsible to carefully review and test connected agents in the context of your specific use cases, and make all appropriate decisions and customizations. When you connect to agents outside of Copilot Studio, you're responsible for the use of such agents. Considerations include ensuring:

A2A connection sample

In this quickstart, you configure an A2A-enabled agent and connect it to a Copilot Studio agent. When you complete the steps, you

After configuring the connection, you see:

Prerequisites

To follow the sample scenario, you need:

If you already have an A2A-enabled agent, go to Create the A2A connection in Copilot Studio.

Step 1: Clone and configure the sample A2A agent

Clone the sample A2A agent repository:

git clone https://github.com/microsoft/CopilotStudioSamples.git
cd CopilotStudioSamples/extensibility/a2a/Simple-A2A-Sample

Set the required Azure OpenAI settings:

You can configure these settings either as environment variables or by saving them into appsettings.json or appsettings.Development.json.

Option A: Configure as environment variables

$env:AZURE_OPENAI_ENDPOINT="https://YOUR-RESOURCE.openai.azure.com"
$env:AZURE_OPENAI_DEPLOYMENT_NAME="YOUR-DEPLOYMENT"
$env:AZURE_OPENAI_API_KEY="YOUR-KEY"

Option B: Configure in appsettings.json

{  
    "AzureOpenAI": {    
        "Endpoint": "https://YOUR-RESOURCE.openai.azure.com",
        "DeploymentName": "YOUR-DEPLOYMENT",
        "ApiKey": "YOUR-KEY"  
    }
}

Step 2: Build, run, and expose the agent

Restore and build dependencies:

dotnet restore
dotnet build

Run the agent:

dotnet run

The console displays the local A2A endpoint URL.

Expose the endpoint

Note

For production scenarios, deploy the agent as a secure web app or containerized service by using proper authentication. Use Dev Tunnels only for local development and demonstration purposes.

If you're using Visual Studio Code and plan to expose the endpoint by using Dev Tunnels, expose a new dev tunnel port. Choose the A2A port displayed in the console. Right-click and make the port public; otherwise, it isn't visible online.

Dev Tunnels gives you a public URL, such as: https://xyz123-9000.dev.tunnels.ms/. Take note of this URL as the base endpoint so you can use it when configuring the A2A connection in Copilot Studio.

Step 3: Create the A2A connection in Copilot Studio

After the A2A agent is publicly accessible, create the A2A connection inside Copilot Studio.

  1. Open Copilot Studio and select your primary agent.
  2. Select Agents.
  3. Select Add agent, and then choose A2A agent.
  4. Enter the required configuration values:
    • Name: A descriptive name, such as Botanical Agent.
    • Endpoint URL: Use the public Dev Tunnel URL followed by the A2A message endpoint, for example: https://xyz123-5073.dev.tunnels.ms/a2a/botanical/v1/message:stream
    • Authentication: Select None if you're using the sample agent (no authentication enforced).
  5. Select Save to validate and establish the connection.

When the configuration is valid, Copilot Studio confirms the A2A agent is connected successfully.

Tip

Because A2A connections use the custom connector infrastructure, you can also use them to connect to A2A agents running on-premises or within a virtual network.

Step 4: Send a task from Copilot Studio to the A2A agent

After you create the connection, verify the integration by sending a task.

  1. Open your main agent in Copilot Studio and go to the Test canvas.
  2. Enter a prompt that should be delegated to the A2A agent. For example: "Which plant needs more light—a tomato plant or a strawberry plant?"
  3. The agent orchestrator evaluates the user input and delegates the task to the A2A agent.
  4. The external agent processes the request and returns a response, which appears in the test chat.

In the external agent's logs, you see:

Step 5: Inspect the A2A payload and metadata

A2A messages include structured metadata that provides extra context. This metadata can help the agent adapt responses, manage routing, or maintain continuity across user turns.

A typical A2A message payload includes:

Example payload excerpt:

{
"method": "message/send",
"params": {
 "message": {
   "contextId": "ee1e68ee-75fc-42bb-83d7-25fd26e559c3",
   "metadata": {
     "copilotstudio.microsoft.com/a2a/chathistory": [
       {
         "From": "agent",
         "Locale": "en-US",
         "Text": "Hello, I'm A2A Agent Demo...",
         "Timestamp": "2025-11-26T23:19:28.764Z"
       },
       {
         "From": "user",
         "Locale": "en-US",
         "Text": "Which plant needs more sunlight...",
         "Timestamp": "2025-11-26T23:20:21.484Z"
       }
     ]
   }
 }
}
}

You can use this metadata for any downstream logic your A2A agent implements.

Next steps

After you establish the basic A2A connection, you can:

Key takeaways