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.

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 through a standardized protocol, allowing your Foundry agent to exchange context and collaborate with external agents.

This article shows you how to configure an A2A connection and call a remote A2A endpoint from your Foundry Agent Service 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.

When your Foundry agent calls a remote agent through the A2A tool, the remote agent processes the request and returns a response. Your Foundry agent uses that response to generate an answer for the user and continues to manage the conversation.

To learn more on optimizing tool usage, see best practices.

Consider adding this tool using a toolbox. By using a toolbox, you are able to reuse the tool across agents and runtimes, as well as centralizing credential management, versioning, and policy enforcement through a managed MCP endpoint. See the toolbox quickstart.

Migrating from agent.as_tool or Connected Agents?

The Connected Agents tool from the classic Agents API isn’t available in the new Foundry Agent Service. To connect one agent to another, use one of the following approaches:

• A2A tool (this article): Connect to any A2A-compatible endpoint, including another Foundry agent exposed as an A2A endpoint. See Host an A2A-compatible agent endpoint to set up the Foundry agent as an endpoint.
• Workflows: Orchestrate multiple Foundry agents declaratively using sequential, group chat, or human-in-the-loop patterns. See Build a workflow in Microsoft Foundry.

For a complete mapping of classic agent tools to their replacements in the new API, see Agent tool availability.

Prerequisites

• An Azure subscription with an active Foundry project.
• A model deployment (for example, gpt-4.1-mini) in your Foundry project.
• Required Azure roles on the Foundry project:
  • Foundry Project Manager to create the A2A project connection.
  • Foundry User to create and test the 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: Node.js 22 or later and the @azure/ai-projects npm package. The A2A tool is in preview.
  • 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.
• For a Foundry agent target, use its A2A base path, enable incoming A2A, and grant the calling identity the Foundry Agent Consumer role or higher on the target project. For the role requirement, see Configure authentication for incoming requests.
• Foundry agent targets support A2A protocol versions 1.0 and 0.3. Version 1.0 uses JSON-RPC. Only text modality is supported, and streaming responses aren’t supported. For details, see A2A limitations.

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
✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️

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.

If you’re connecting to a Foundry agent as the target, set the connection target to the target agent’s A2A base path, https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/a2a, and use the audience https://ai.azure.com. Don’t set an agent card path. Foundry resolves the default agent card path automatically and negotiates the A2A protocol version for you. You also don’t need to set the optional send_credentials_for_agent_card field, because Foundry doesn’t require the agent card fetch to carry separate credentials. However, the target agent must have incoming A2A enabled; see Enable incoming A2A on a Foundry agent.

For other endpoints, if the endpoint requires authentication to read its agent card, set send_credentials_for_agent_card to true in the A2A tool definition. Otherwise, Agent Service fetches the agent card anonymously by default. For more information, see Credentials for the agent card request.

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.

Add an A2A tool to a toolbox with the Azure Developer CLI

Create a remote-a2a connection for the remote agent, then reference it from a minimal toolbox YAML.

Step 1. Create the connection

Pick the auth variant you need:

# No auth
azd ai connection create my-a2a-conn \
  --kind remote-a2a \
  --target https://your-remote-agent.azurecontainerapps.io \
  --auth-type none

# Custom-keys header
# Set A2A_AUTHORIZATION_HEADER in your shell without committing its value.
azd ai connection create my-a2a-conn \
  --kind remote-a2a \
  --target https://your-remote-agent.azurecontainerapps.io \
  --auth-type custom-keys \
  --custom-key "Authorization=$A2A_AUTHORIZATION_HEADER"

# OAuth — bring your own app registration
azd ai connection create my-a2a-conn \
  --kind remote-a2a \
  --target https://your-remote-agent.azurecontainerapps.io \
  --auth-type oauth2 \
  --authorization-url https://auth.example.com/authorize \
  --token-url https://auth.example.com/token \
  --client-id <oauth-client-id> \
  --client-secret <oauth-client-secret> \
  --scopes "<scope1> <scope2>"

# User Entra token (managed user identity passthrough)
azd ai connection create my-a2a-conn \
  --kind remote-a2a \
  --target https://your-remote-agent.azurecontainerapps.io \
  --auth-type user-entra-token \
  --audience "<entra-audience>"

# Project managed identity
azd ai connection create my-a2a-conn \
  --kind remote-a2a \
  --target https://your-remote-agent.azurecontainerapps.io \
  --auth-type project-managed-identity \
  --audience "<entra-audience>"

# Agentic identity
azd ai connection create my-a2a-conn \
  --kind remote-a2a \
  --target https://your-remote-agent.azurecontainerapps.io \
  --auth-type agentic-identity \
  --audience "<entra-audience>"

--auth-type	Additional flags
none	—
custom-keys	--custom-key "Header=Value" (repeatable)
oauth2	--authorization-url, --token-url, --client-id, --client-secret, --scopes
user-entra-token	--audience <entra-audience>
project-managed-identity	--audience <entra-audience> (optional)
agentic-identity	--audience <entra-audience>

Step 2. Define the toolbox

# my-toolbox.yaml
description: Agent-to-Agent toolbox
connections:
  - name: my-a2a-conn

Step 3. Create the toolbox

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

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
• Best practices for tools
• Microsoft Foundry REST API reference