Add a Foundry 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 existing Microsoft Foundry agent 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.

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 remote agent over the Agent2Agent (A2A) protocol, see Add an A2A agent as a connected agent. To connect an agent built with the Microsoft 365 Agents SDK, see Add a Microsoft 365 Agents SDK 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 existing Foundry agent created in a project in the Microsoft Foundry portal, with the Activity protocol enabled and the agent's Agent ID available. Foundry agents don't have the Activity protocol enabled by default. See Enable the Activity protocol on your Foundry agent.
  • The Azure AI Project endpoint URL for the project that hosts the Foundry agent.
  • Permission to access the Foundry project. The connection authenticates with your Microsoft Entra ID user login.

Note

You can only connect to agents created in the current Microsoft Foundry portal. Connecting to an agent created in the previous portal returns a 404 - Version not found error.

Add a Foundry agent

  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 Foundry agent.

  6. On the Connect to Azure AI Foundry step, choose the connection this agent uses to reach Microsoft Foundry:

    • Select an existing connection from the Connection list.
    • If no connection is available, select Create new connection and continue to the next step.

  7. If you're creating a new connection, enter the connection details, and then select Create:

    • Display name (optional): a name that helps you identify this connection later.
    • Authentication Type: Microsoft Entra ID User Login. This value is set for you.
    • Azure AI Project Endpoint: the endpoint URL of the Foundry project that hosts the agent.

  8. Back on the Connect to Azure AI Foundry step, confirm your connection is selected, and then select Next.

  9. On the Review and add step, enter the details of the Foundry agent you want to connect, and then select Add to agent:

    • Name: the name shown to the agent author.
    • Description: a clear description of when this Foundry agent should be used. 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. For more information, see writing effective metadata.
    • Agent ID: the ID of the Foundry agent you want to connect to.

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

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.

Enable the Activity protocol on your Foundry agent

Copilot Studio communicates with a connected Foundry agent by using the Activity protocol. Foundry agents don't have this protocol enabled by default, so you must enable it before your primary agent can exchange messages with the Foundry agent. If the Activity protocol isn't enabled, you can still add the connection, but calling the Foundry agent fails.

You can enable the Activity protocol in either of the following ways:

  • Publish the Foundry agent to Microsoft 365 or Microsoft Teams. When you publish a prompt agent to Microsoft 365 or Teams, the Activity protocol and the required BotServiceRbac authorization scheme are enabled automatically. Choose this option if you already plan to publish the agent to those channels.

  • Enable it manually with a REST API call. If you don't publish the agent to Microsoft 365 or Teams, call the Foundry Agents - Update agent REST API to add the activity protocol and the BotServiceRbac authorization scheme to the agent.

For more information about configuring and sharing your Foundry agent, see Configure and share your Microsoft Foundry agent.

Enable the Activity protocol with a REST API call

Call the Foundry Agents - Update agent REST API. Replace {{endpoint}}, {{agent_name}}, and {{token}} with the endpoint, agent name, and access token for your Foundry project.

Important

Keep responses and Entra in the lists. Removing them breaks chatting with the agent from the Foundry portal or SDK.

PATCH {{endpoint}}/agents/{{agent_name}}?api-version=v1
Authorization: Bearer {{token}}
Content-Type: application/merge-patch+json
Foundry-Features: AgentEndpoints=V1Preview

{
    "agent_endpoint": {
        "protocols": [
            "responses",
            "activity"
        ],
        "authorization_schemes": [
            {
                "type": "Entra",
                "isolation_key_source": {
                    "kind": "Entra"
                }
            },
            {
                "type": "BotServiceRbac"
            }
        ]
    }
}

How the orchestrator routes to the Foundry agent

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

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

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

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

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

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

  • Last updated on