Connect an agent available over the Agent2Agent (A2A) protocol (preview)

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:

• Send tasks to external agents.
• Provide rich, structured metadata.
• Receive agent responses in a predictable format.

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

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:

• Built on external frameworks.
• Hosted outside Copilot Studio.
• Equipped with their own domain‑specific reasoning or workflows.

Use alternative integration patterns when appropriate:

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.

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

• Run a sample A2A-enabled agent locally or use an existing A2A agent you already have.
• Expose the agent securely over HTTPS by using Dev Tunnels or another hosting option.
• Connect the external agent to a Copilot Studio agent through an A2A connection.
• Validate the connection by invoking the agent from Copilot Studio with a natural language task such as: "Which plant needs more light-a tomato plant or a strawberry plant?"

After configuring the connection, you see:

• A successful A2A connection established from Copilot Studio.
• Activity logs from the external agent confirming it received and processed the delegated task.
• The complete A2A payload, including the other metadata Copilot Studio sends with each request.

Prerequisites

To follow the sample scenario, you need:

• An Azure OpenAI resource with:
  • Endpoint URL
  • Deployment name
  • API key
• .NET 10 SDK or higher
• A Copilot Studio environment with permissions to:
  • Edit agents
  • Configure connections
• A method to expose the local agent publicly:
  • Dev Tunnels (recommended for development)
  • Or a hosted environment such as Azure App Service or container

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/A2ASamples/Simple_A2A_Agent

Set the required Azure OpenAI settings:

• AZURE_OPENAI_ENDPOINT: Your Azure OpenAI endpoint URL
• AZURE_OPENAI_DEPLOYMENT_NAME: Name of your Azure OpenAI deployment
• AZURE_OPENAI_API_KEY: Your Azure OpenAI API key

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

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.

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:

• A received A2A task.
• The natural language prompt.
• The generated response returned to Copilot Studio.

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:

• A unique contextId
• Message IDs
• Locale information
• Full chat history, not just the latest user utterance
• Message content parts (text, tool calls, or other metadata)

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:

• Add new skills or domain knowledge to your A2A agent.
• Use metadata from the A2A payload to implement routing and personalization logic.
• Add authentication to secure your A2A endpoint and update Copilot Studio settings accordingly.
• Connect other A2A-enabled agents by using the same configuration approach.

Key takeaways

• Copilot Studio can orchestrate external agents by using the A2A protocol.
• A2A enables mult-agent workflows with rich contextual metadata.
• The sample agent demonstrates the full round trip: Copilot Studio -> A2A agent -> Copilot Studio.
• A2A messages include detailed metadata that supports context-aware agent behavior.

Related information

• Explore multi-agent orchestration patterns
• Architecting agent solutions: Multi-agent patterns