Connect to an A2A agent endpoint from Foundry Agent Service

Connect your Foundry agent to a remote Agent2Agent (A2A) endpoint. Configure connections, authentication, and use SDK integration to call external A2A agents.

Items marked (preview) in this article are currently in public preview. This preview is provided without a service-level agreement, and we don’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

For information on optimizing tool usage, see best practices.

You can extend the capabilities of your Microsoft Foundry agent by connecting to a remote Agent2Agent (A2A) endpoint that supports the A2A protocol. The A2A tool enables agent-to-agent communication, making it easier to share context between Foundry-model-powered agents and external agent endpoints through a standardized protocol. This guide shows you how to configure a connection and call a remote A2A endpoint from your Foundry Agent Service agent.

This article covers how to call a remote A2A endpoint from your Foundry agent. If you want to expose your own agent as an A2A endpoint that other agents can call, see Host an A2A-compatible agent endpoint later in this article.

Connecting agents via the A2A tool versus a multi-agent workflow:

• Using the A2A tool: When Agent A calls Agent B through the A2A tool, Agent B’s answer goes back to Agent A. Agent A then summarizes the answer and generates a response for the user. Agent A keeps control and continues to handle future user input.
• Using a multi-agent workflow: When Agent A calls Agent B through a workflow or other multi-agent orchestration, Agent B takes full responsibility for answering the user. Agent A is out of the loop. Agent B handles all subsequent user input. For more information, see Build a workflow in Microsoft Foundry.

Migrating from agent.as_tool or Connected Agents? The Connected Agents tool from the previous (classic) Agents API isn’t available in the new Foundry Agent Service. To use one Foundry agent from another, choose one of the following replacements:

• A2A tool (this article): Call any A2A-compatible endpoint from your agent. To call another Foundry agent this way, expose that agent as an A2A endpoint by following Host an A2A-compatible agent endpoint later in this article, then connect to it from your calling agent.
• Workflows: Orchestrate multiple Foundry agents declaratively in a sequential, group chat, or human-in-the-loop pattern. See Build a workflow in Microsoft Foundry.

For the full mapping of classic tools to their replacements in the new API, see Agent tool availability in the migration guide.

Usage support

The following table shows SDK and setup support.

Microsoft Foundry support	Python SDK	C# SDK	JavaScript SDK	Java SDK	REST API	Basic agent setup	Standard agent setup
✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️

Prerequisites

• An Azure subscription with an active Foundry project.
• A model deployment (for example, gpt-4.1-mini) in your Foundry project.
• Required Azure role: On the Foundry resource, Contributor or Owner for management and Foundry User for building an agent.

The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

• SDK installation:
  • Python (GA): pip install "azure-ai-projects>=2.0.0"
  • C#: Azure.AI.Projects NuGet package
  • TypeScript (GA): @azure/ai-projects npm package
  • Java: com.azure:azure-ai-agents:2.0.0 Maven dependency
• Values to update in code:
  • Project endpoint URL (for example, https://<resource>.ai.azure.com/api/projects/<project>).
  • Model deployment name (for example, gpt-4.1-mini).
  • A2A connection name (created in the Foundry portal).
  • A2A base URI (optional, only needed for non-RemoteA2A connections).
• An A2A connection configured in your Foundry project. For connection setup and REST examples, see Create an A2A connection.

Create an A2A connection

Create a project connection for your A2A endpoint so you can store authentication securely and reuse it across agent versions.

For details about supported authentication approaches, see Agent2Agent (A2A) authentication.

Create the connection in the Foundry portal

1. Sign in to Microsoft Foundry. Make sure the New Foundry toggle is on. These steps refer to Foundry (new).

1. Select Tools.
2. Select Connect tool.
3. Select the Custom tab.
4. Select Agent2Agent (A2A), and then select Create.
5. Enter a Name and an A2A Agent Endpoint.
6. Under Authentication, select an authentication method. For key-based authentication, set the credential name (for example, x-api-key) and the corresponding secret value.

Get the connection identifier for code

Use your connection name in code. Your code uses this name to retrieve the full connection ID at runtime:

• Python/C#/TypeScript: Call project.connections.get(connection_name) to get the connection object, then access connection.id.
• REST API: Include the connection ID in the project_connection_id field of the A2A tool definition.

Code example

Troubleshooting

Issue	Cause	Resolution
Agent doesn’t invoke the A2A tool	Agent definition doesn’t include A2A tool configuration	Confirm your agent definition includes the A2A tool and that you configured the connection. If you’re using responses, confirm you’re not forcing a different tool.
Agent doesn’t invoke the A2A tool	Prompt doesn’t require remote agent	Update your prompt to require calling the remote agent, or remove conflicting tool choice settings.
Authentication failures (401 or 403)	Connection authentication type mismatch	Confirm the connection’s authentication type matches your endpoint requirements. For key-based auth, confirm the credential name matches what the endpoint expects (x-api-key or Authorization).
SDK sample can’t find the connection	Connection name mismatch	Confirm the connection name in code matches the connection name in Foundry.
Network or TLS errors	Endpoint unreachable or invalid certificate	Confirm the endpoint is publicly reachable and uses a valid TLS certificate. Check firewall rules and proxy settings.
Remote agent returns unexpected response	Response format incompatibility	Confirm the remote agent follows A2A protocol specifications. Check that response content types match expected formats.
Connection timeout	Remote agent slow to respond	Increase timeout settings or verify the remote agent’s performance. Consider implementing retry logic with exponential backoff.
Missing A2A tool in response	Tool not enabled for the agent	Recreate the agent with the A2A tool explicitly enabled, and verify the connection is active and properly configured.

Host an A2A-compatible agent endpoint

You can expose your Foundry agent as an A2A endpoint directly by enabling the A2A protocol on the agent. For step-by-step instructions, see Enable incoming A2A on a Foundry agent.

If your agent is deployed outside of Agent Service, or if you need a custom hosting approach, use one of the following alternatives.

Option 1: Register a custom A2A agent in Foundry Control Plane

If you already have an agent deployed outside of Agent Service that supports the A2A protocol, register it in Foundry Control Plane for centralized management, observability, and governance.

1. Deploy your A2A-compatible agent to any reachable endpoint.
2. Register the agent in Foundry Control Plane, and select A2A as the protocol.
3. Foundry generates a proxy URL and discovers your agent card at /.well-known/agent-card.json.

After registration, other agents can connect to your agent through the proxy URL. Foundry provides access control and monitoring through the AI gateway.

For authentication setup, see Agent2Agent (A2A) authentication.

Option 2: Build a custom A2A server that wraps a Foundry agent

Build a lightweight A2A server that delegates to your Foundry agent through the Responses API:

1. Create an A2A server by using the official A2A SDK for your language (Python, .NET, or JavaScript).
2. Implement the server to call your Foundry agent through the Responses API.
3. Serve an agent card at /.well-known/agent-card.json that describes your agent’s capabilities.
4. Deploy the server and register it in Foundry Control Plane.

For more information about the A2A protocol requirements for servers, see the A2A specification.

Considerations for using non-Microsoft services

You’re subject to the terms between you and the service provider when you use connected non-Microsoft services and servers (“non-Microsoft services”). Under your agreement governing use of Microsoft Online services, non-Microsoft services are non-Microsoft Products. When you connect to a non-Microsoft service, you pass some of your data (such as prompt content) to the non-Microsoft services, or your application might receive data from the non-Microsoft services. You’re responsible for your use of non-Microsoft services and data, along with any charges associated with that use.

Third parties, not Microsoft, create the non-Microsoft services, including A2A agent endpoints, that you decide to use with the A2A tool described in this article. Microsoft didn’t test or verify these A2A agent endpoints. Microsoft has no responsibility to you or others in relation to your use of any non-Microsoft services.

Carefully review and track the A2A agent endpoints you add to Foundry Agent Service. Rely on endpoints hosted by trusted service providers themselves rather than proxies.

The A2A tool allows you to pass custom headers, such as authentication keys or schemas, that an A2A agent endpoint might need. Review all data that you share with non-Microsoft services, including A2A agent endpoints, and log the data for auditing purposes. Be aware of non-Microsoft practices for retention and location of data.

Related content

• Agent2Agent (A2A) authentication
• Register and manage custom agents
• Build a workflow in Microsoft Foundry
• Best practices for tools
• Foundry project REST API (preview)