Add a Microsoft 365 Agents SDK 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 an agent built with the Microsoft 365 Agents SDK, 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.

An agent built with the Microsoft 365 Agents SDK exposes a messaging endpoint that speaks the Activity protocol. You connect it by entering that endpoint directly. Unlike an A2A agent, an SDK agent doesn't publish an agent card, so Copilot Studio can't discover its name and description for you. You supply those details yourself.

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. To connect a remote agent over the Agent2Agent (A2A) protocol, see Add an A2A agent as a connected agent.

Prerequisites

  • An agent created with the GitHub Copilot harness to be the primary agent. See Create an agent (preview).
  • An agent built with the Microsoft 365 Agents SDK, deployed and reachable from Copilot Studio.
  • The agent's messaging endpoint URL, typically https://<your-agent-host>/api/messages. The URL must be an absolute http or https URL.
  • The authentication details the SDK agent requires, if any. Copilot Studio supports no authentication, API key, and OAuth 2.0.

Add a Microsoft 365 Agents SDK agent

The wizard takes you through three steps: Connect to a Microsoft 365 Agents SDK agent, Connect to the Microsoft 365 Agents SDK 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 Microsoft 365 Agents SDK agent.

  6. On the Connect to a Microsoft 365 Agents SDK agent step, enter the details of the agent:

    • Messaging endpoint URL: the Activity protocol endpoint of your SDK agent, for example https://agent.example.com/api/messages.
    • Name: the name shown to the agent author, up to 30 characters.
    • Description: a clear description of when this SDK agent should be used, between 30 and 1,000 characters. 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.

  7. Under Authentication, select how Copilot Studio authenticates with the SDK 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. On the Connect to the Microsoft 365 Agents SDK agent step, Copilot Studio creates the connector for the agent. Then choose the connection this agent uses to reach the SDK agent:

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

    If the connector can't be created, select Retry.

  10. Select Next.

  11. On the Review and add step, review the name, description, and messaging endpoint URL, and then select Add to agent.

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

If you go back and change the messaging endpoint URL on the Connect to a Microsoft 365 Agents SDK agent step, Copilot Studio discards the connector that was built from the previous URL. You have to 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 SDK 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 SDK 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 SDK agent's identity provider for you. Enter the Authorization URL and the Token URL.

  • Manual: use an app registration you already created with the SDK 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 SDK 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.

How the orchestrator routes to the SDK agent

After you add the SDK 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 SDK 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 SDK agent:

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

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

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

  4. Send a message outside the SDK agent's domain to confirm that 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
The messaging endpoint URL is rejected The URL must be an absolute http or https URL that points at the agent's Activity protocol endpoint, such as https://agent.example.com/api/messages.
Next stays unavailable on the connect step The name, description, and messaging endpoint URL are all required, and the description must be at least 30 characters. Incomplete authentication details also block the step.
Creating the connector fails Select Retry. If it keeps failing, check that the messaging endpoint URL is correct and that your environment allows custom connectors.
The connection you created no longer works after you edited the wizard Changing the messaging endpoint URL discards the connector built from the previous URL. Choose a connection again.
  • Last updated on