Agent-to-agent collaboration just became much easier to build in Microsoft Foundry. The A2A Tool and incoming A2A endpoints support A2A protocol version 1.0, which is generally available. The earlier a2a_preview tool type and protocol version 0.3 remain available in preview for existing integrations. Hosted Agents can also consume A2A tools through Foundry Toolboxes exposed over MCP.
If you have been following earlier previews, A2A Endpoints were previously known as the A2A API head. The idea is simple:
- A2A Endpoint: expose a Foundry agent so an external agent can discover and invoke it.
- A2A Tool: let a Foundry agent invoke another A2A-compatible agent.
- Hosted Agents: use the A2A Tool through a Foundry Toolbox exposed as an MCP endpoint.
Together, these capabilities make it possible to build multi-agent systems where agents can specialize, publish their skills, and securely collaborate across service boundaries.
Why this matters
Until now, many multi-agent patterns required custom APIs, one-off adapters, or orchestration logic tightly coupled to a specific framework. A2A gives us a standardized protocol for agent-to-agent communication.
That means one agent can ask another agent for help without needing to know its implementation details. The caller discovers the remote agent’s capabilities through an agent card, sends a task through the A2A protocol, and receives a response it can incorporate into the conversation.
For Foundry-hosted A2A endpoints, discovery is authenticated. The agent-card URLs and protocol endpoint require Microsoft Entra ID authentication and are not publicly accessible.
For example:
- A support agent can call a billing agent.
- A research agent can call a data-analysis agent.
- A Foundry-hosted enterprise agent can call a specialized agent running outside Foundry.
- A Hosted Agent can call a Foundry Toolbox that wraps an A2A connection.
Architecture 1: External agent calls a Foundry agent through an A2A Endpoint
In this pattern, a Foundry agent is exposed as an A2A endpoint. An external agent discovers the agent card and invokes it using the A2A protocol.
The Foundry agent processes the request using its configured models, instructions, tools, and enterprise data sources, and then returns the response to the calling agent.
A Foundry prompt agent must support the Responses protocol before it can be exposed through an incoming A2A endpoint.
The Foundry agent exposes an A2A base URL in the following format:
https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/a2a
The version-specific agent-card URLs follow these patterns:
https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/a2a/agentCard/v1.0
https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/a2a/agentCard/v0.3
For new integrations, target A2A protocol v1.0, which is GA. Foundry also supports v0.3 for existing preview integrations, but v1.0 is the recommended path forward.
Foundry serves both protocol versions through the same A2A base path. The caller selects the version through agent-card negotiation, the A2A-Version header, or the a2a-version query parameter. Production clients should explicitly negotiate or request version 1.0 rather than relying on the default behavior.
Foundry’s incoming A2A v1.0 endpoint uses JSON-RPC. Incoming A2A v0.3 supports JSON-RPC and HTTP+JSON, but v0.3 remains in preview. Only text modality is supported, and streaming responses are not supported.
Architecture 2: Foundry agent calls another agent using the A2A Tool
The reverse pattern is just as important. A Foundry agent can use the A2A Tool to call another A2A-compatible endpoint.
A RemoteA2A project connection stores the remote A2A base URL and its authentication configuration. The A2A Tool references the connection and specifies the A2A protocol version to use.
Foundry resolves the default agent-card path automatically and negotiates the A2A protocol version. You do not need to configure send_credentials_for_agent_card for a Foundry agent target.
First, set the active Foundry project. Then create the RemoteA2A connection.
PROJECT_ENDPOINT=”https://{account}.services.ai.azure.com/api/projects/{project}”
azd ai project set “$PROJECT_ENDPOINT”
azd ai connection create my-a2a-connection \
–kind remote-a2a \
–target “https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/a2a” \
–auth-type agentic-identity \
–audience “https://ai.azure.com”
The target Foundry project or agent must grant the calling agent identity the Foundry Agent Consumer role, or another role that contains the required endpoint permissions. When assigning the role, use the calling identity’s Microsoft Entra object or principal ID, not its application or client ID.
A role assignment can be created at either the target project scope or the individual agent scope:
az role assignment create \
–assignee-object-id “{calling-agent-principal-object-id}” \
–assignee-principal-type “ServicePrincipal” \
–role “eed3b665-ab3a-47b6-8f48-c9382fb1dad6” \
–scope “{target-project-or-agent-resource-id}”
Agent identities and managed identities are represented as service principals in Microsoft Entra ID, which is why ServicePrincipal is used as the principal type.
Architecture 3: Hosted Agent uses A2A through a Foundry Toolbox
Hosted Agents can use A2A by attaching a Foundry Toolbox. The toolbox contains an A2A Toolbox Tool and exposes it through an MCP-compatible endpoint.
The complete interaction flow is:
- The Hosted Agent connects to the Foundry Toolbox over MCP.
- The Hosted Agent authenticates to the toolbox using Microsoft Entra ID.
- The toolbox invokes its configured A2A Toolbox Tool.
- The A2A Toolbox Tool references a RemoteA2A project connection.
- The RemoteA2A connection identifies the destination and downstream authentication configuration.
- The toolbox invokes the remote agent through the A2A protocol.
- The result is returned to the Hosted Agent through the toolbox’s MCP endpoint.
This creates a two-hop architecture: Hosted Agent to Foundry Toolbox over MCP, followed by Foundry Toolbox to the remote agent over A2A.
The toolbox MCP endpoint used by the Hosted Agent follows this format:
https://{account}.services.ai.azure.com/api/projects/{project}/toolboxes/{toolbox-name}/versions/{version}/mcp?api-version=v1
A version-specific toolbox endpoint can also be used when the Hosted Agent must remain pinned to an immutable toolbox version.
The Hosted Agent authenticates to the toolbox using Microsoft Entra ID and the following scope:
https://ai.azure.com/.default
The Hosted Agent authenticates to the Foundry Toolbox MCP endpoint using Microsoft Entra ID. For direct token acquisition, use the https://ai.azure.com/.default scope.
Downstream credentials, secrets, managed identity settings, and OAuth configuration should remain in the RemoteA2A project connection rather than being embedded in the Hosted Agent’s code.
Authentication is the design decision
The most important architecture choice is authentication. A2A supports different patterns depending on whether the calling agent should act as itself or on behalf of the user.
RemoteA2A connection authentication options
| Auth type | Use when |
|---|---|
| none | The remote endpoint does not require auth. Rare for production. |
| custom-keys | The endpoint expects an API key, PAT, bearer token, or custom header. |
| oauth2 |
Each user authorizes access through an OAuth 2.0 consent flow. Use this when the downstream action must preserve the user’s individual permissions. |
| user-entra-token | The user’s Microsoft Entra identity should flow to the remote service. |
| project-managed-identity | All agents in the project should share the project identity. |
| agentic-identity |
For service-to-service calls using an agent identity, service principal, or managed identity, use as the role-assignment principal type. |
For incoming A2A Endpoints on Foundry agents, authentication is stricter:
- Incoming A2A requires Microsoft Entra ID authentication.
- Key-based and unauthenticated incoming access are not supported.
- The caller must have Foundry Agent Consumer or another role that grants endpoint access.
- Access can be granted at the project scope or individual agent scope.
- Calls can use either on-behalf-of user identity or a service identity such as an agent identity, service principal, or managed identity.
Use OAuth or user identity passthrough when the remote action must respect each user’s permissions.
What you configure
To expose a Foundry agent as an A2A Endpoint, you configure two things:
- An agent card, describing the agent’s capabilities.
- The A2A protocol on the agent endpoint.
The relevant portion of the agent PATCH request body looks like this:
{ “agent_card”: { “description”: “A specialist agent that answers questions about invoices.”, “version”: “1.0”, “skills”: [ { “id”: “invoice-lookup”, “name”: “Invoice lookup”, “description”: “Finds and summarizes invoice status.” } ] }, “agent_endpoint”: { “protocol_configuration”: { “responses”: {}, “a2a”: {} } } }
Agent cards for prompt agents in Foundry can also be configured directly in the portal. Then another agent can call it via Tools using the agents A2A endpoint.
Agent card configuration for a Foundry agent
Final thoughts
A2A Endpoints and the A2A Tool make Foundry agents composable. Instead of building one large agent that knows everything, you can build focused agents that publish capabilities and collaborate securely.
Use A2A Endpoints when you want other agents to call your Foundry agent. Use the A2A Tool when your Foundry agent needs to call another agent. For Hosted Agents, use a Foundry Toolbox to bring A2A into the hosted runtime cleanly.
Learn more:
- A2A authentication: https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/agent-to-agent-authentication
- A2A Tool: https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/agent-to-agent
- A2A Endpoint: https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/enable-agent-to-agent-endpoint