Add an Agent2Agent (A2A) agent as a connected agent (GitHub Copilot)

Use connected agents to let your primary agent delegate specific tasks to specialized agents. This article shows you how to connect a remote agent that's available over the Agent2Agent (A2A) protocol, so your primary agent can hand tasks off to it.

Note

Features in this article are used by agents or workflows powered by the GitHub Copilot harness.

Usage-based billing applies to using, building, testing, and evaluating agents. These actions might consume Copilot Credits. Learn more in Manage costs for agents powered by the GitHub Copilot harness.

The A2A protocol is an open standard for communication and collaboration between agents. Because it's an open standard, you can connect agents that are hosted outside Copilot Studio and built on other frameworks, as long as they implement A2A. Copilot Studio discovers the remote agent from its agent card, then uses the A2A protocol to delegate tasks to it at runtime.

You add every connected agent from the same Add a connected agent dialog. For an overview of connected agents and how routing works, see Connected agents overview. To connect another Copilot Studio agent, see Add a Copilot Studio agent as a connected agent. To connect a Microsoft Foundry agent, see Add a Foundry agent as a connected agent.

Prerequisites

  • An agent created with the GitHub Copilot harness to be the primary agent. See Create an agent (preview).
  • A remote agent that implements the Agent‑to‑Agent protocol and is reachable from Copilot Studio over the public internet.
  • The URL of the remote agent's agent card, typically https://<your-agent-host>/.well-known/agent-card.json.
  • The authentication details the remote agent requires, if any. Copilot Studio supports no authentication, API key, and OAuth 2.0.
  • For OAuth 2.0, permission to add a redirect URI to the app registration that the remote agent's identity provider uses. Copilot Studio generates the redirect URL during the wizard, and you must register it before you create the connection.

Note

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.

Add an Agent2Agent (A2A) agent

The wizard guides you through three or four steps, depending on the authentication method you choose:

  • If you choose None or API key: Connect to an A2A agent, Connect to the A2A agent, then Review and add.
  • If you choose OAuth 2.0: Connect to an A2A agent, Add redirect URL, Connect to the A2A agent, then Review and add.

  1. Sign in to Copilot Studio.

  2. Choose and open the agent you want to use as the primary agent.

  3. In the agent navigation bar, select the Build tab.

  4. In the components panel, select Connected agents to open the Add a connected agent dialog.

  5. In the dialog, select Add, and then select Add A2A agent.

  6. On the Connect to an A2A agent step, enter the details of the remote agent:

    • Agent card URL: the URL of the remote agent's agent card, for example https://agent.example.com/.well-known/agent-card.json. Copilot Studio reads the card to discover the agent's endpoint and capabilities.
    • Name: the name shown to the agent author. If the agent card includes a name, Copilot Studio fills this field for you.
    • Description: a clear description of when this A2A agent should be used, between 30 and 1,000 characters. If the agent card includes a description, Copilot Studio fills this field for you. The orchestrator uses this description to decide when to route a request to the agent, so make it specific and avoid overlap with your other tools and agents. Learn more in writing effective metadata.

    Note

    If the name and description aren't filled in automatically, the remote agent might not have an agent card, the card might be at a different URL than the one you entered, or Copilot Studio might not be able to reach it. Check the URL first, and try opening the agent card in your browser. If the card isn't available, enter a name and description manually.

  7. Under Authentication, select how Copilot Studio authenticates with the remote agent, and then complete the details for the method you chose:

    You can't continue until the authentication details are complete.

  8. Select Next.

  9. If you selected OAuth 2.0, the Add redirect URL step appears. Copilot Studio creates the connector for the A2A agent, and the platform generates a redirect URL for it. Register that URL with your identity provider before you create the connection:

    1. Wait for the Redirect URL field to fill in. The connector has to exist before the URL is generated.
    2. Select the copy button next to the field to copy the URL.
    3. In your OAuth app registration, add the URL as a redirect URI, and save the app registration.
    4. Select Next.

    Important

    If you don't register the redirect URL first, the first attempt to authorize the connection fails. The redirect URL is generated per connector, so it's specific to this A2A agent and can't be reused from another connector. If you need the URL again later, select the A2A agent under Connected agents in the components panel to reopen it.

  10. On the Connect to the A2A agent step, choose the connection this agent uses to reach the remote agent:

    • Select an existing connection from the list of available connections.
    • If no connection is available, create a new connection. If the remote agent uses API key authentication, you enter the API key value when you create the connection.

  11. Select Next.

  12. On the Review and add step, review the name, description, and agent card URL, and then select Add to agent.

  13. Confirm the connected agent appears under Connected agents in the components panel.

If you go back and change the authentication settings on the Connect to an A2A agent step, Copilot Studio discards the connector that was built from the previous settings. You have to register a new redirect URL and choose a connection again.

Note

You're responsible for carefully reviewing and testing connected agents in the context of your specific use cases, and making 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:

  • Data flows, data handling, and data sharing between agents are appropriate for your use case and meet relevant requirements and laws.
  • Agents meet appropriate quality, reliability, security, and trustworthiness standards.
  • Appropriate permissions, boundaries, and approvals are provisioned, if prudent for your use case.
  • Proper observability, identity and traceability, and human oversight functions are in place.

Configure API key authentication

When you select API key, choose where Copilot Studio sends the key by selecting a Parameter type:

  • Header: the key is sent as a request header. In Header name, enter the name of the header the remote agent expects, such as x-api-key.
  • Query string: the key is sent as a query string parameter. In Parameter label, enter the name of the query string parameter the remote agent expects.

You enter the API key value itself when you create the connection, not in this step. That way the key is stored with the connection and isn't visible in the agent configuration.

Configure OAuth 2.0 authentication

When you select OAuth 2.0, choose a Configuration type:

  • Dynamic: Copilot Studio registers a client with the remote agent's identity provider for you. Enter the Authorization URL and the Token URL.

  • Manual: use an app registration you already created with the remote agent's identity provider. Enter the following values:

    • Client ID: the client ID of your app registration.
    • Client secret: the client secret of your app registration.
    • Authorization URL: the identity provider's authorization endpoint.
    • Token URL: the identity provider's token endpoint.
    • Refresh token URL: the endpoint used to refresh access tokens.
    • Scopes (optional): the scopes to request, separated by spaces.

Use Dynamic when the remote agent's identity provider supports dynamic client registration. Use Manual when you need to control the app registration, for example when your identity provider requires preregistered redirect URIs or consent.

Either configuration type requires you to register a redirect URL with your identity provider. After you select Next, Copilot Studio creates the connector and shows the generated redirect URL on the Add redirect URL step.

Find the redirect URL later

If you close the wizard or lose the redirect URL, you can view it again at any time:

  1. On the Build tab, select the A2A agent under Connected agents in the components panel.

  2. In the Edit A2A agent dialog, copy the value in the Redirect URL field.

The Redirect URL field appears only for A2A agents that use OAuth 2.0.

How the orchestrator routes to the A2A agent

After you add the A2A agent, the orchestration runtime automatically determines when to delegate to it. The routing decision is based on:

  • The connected agent's name and description
  • The user's message and conversation context
  • Your primary agent's instructions

Tip

Write a clear, specific description for the A2A agent so the orchestrator can accurately determine when to route requests to it. Avoid overlapping descriptions between connected agents.

Test delegation

After you add the A2A agent:

  1. In the agent navigation bar, select the Preview tab.

  2. Send a message that matches the A2A agent's domain.

  3. Verify that the response comes from the A2A agent and is appropriate.

  4. Send a message outside the A2A agent's domain to confirm your primary agent handles it.

If you need to change the name or description later, edit the connected agent from the components panel. See Manage connected agents in an agent.

Troubleshoot the connection

Problem What to check
Authorizing the connection fails with a redirect URI error The redirect URL that Copilot Studio generated isn't registered with your identity provider. Copy the URL from the Edit A2A agent dialog, add it to your app registration, and then authorize the connection again.
The Redirect URL field stays empty in the wizard The connector is still being created. If the step shows an error instead, select Retry.
The name and description don't fill in from the agent card Check that the agent card URL is correct and that Copilot Studio can reach the card. Enter the name and description manually if the card isn't available.
The connection you created no longer works after you edited the wizard Changing the authentication settings discards the connector built from the previous settings. Register the new redirect URL and choose a connection again.
  • Last updated on