Enable incoming A2A on a Foundry agent

You can expose your Foundry Agent Service agent as an Agent2Agent (A2A) endpoint so that other agents can discover and call it through the A2A protocol. When incoming A2A is enabled, Foundry publishes an agent card for your agent and accepts inbound A2A requests from external callers. Foundry Agent Service supports generally available A2A protocol version 1.0 and preview version 0.3. New integrations should target version 1.0. For details about how clients select a version, see A2A protocol versions.

Items marked preview in this article are currently in preview. This preview is provided without a service-level agreement, and Microsoft doesn’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.

Supported agent types

Incoming A2A requires the responses protocol. Prompt agents support the responses protocol by default, and you can expose them as A2A endpoints.

This article covers how to expose your agent as an A2A endpoint that other agents can call. If you want your agent to call a remote A2A endpoint, see Connect to an A2A agent endpoint from Foundry Agent Service.

Prerequisites

An Azure subscription with an active Foundry project.
A deployed prompt agent in Foundry Agent Service.
Required Azure role: Foundry User or higher on the Foundry project.

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.

Enable incoming A2A

Enabling incoming A2A requires two things: an agent card that describes your agent’s capabilities, and the A2A protocol enabled on the agent endpoint. You can set both in a single PATCH call. This feature isn’t available in the Foundry portal yet—use the REST API or Python SDK.

Enabling incoming A2A isn’t yet configurable in the Foundry portal. Use the REST API or Python SDK.

Set up variables for your project:

BASE_URL="https://{account}.services.ai.azure.com/api/projects/{project}"
AGENT_NAME="your-agent-name"
TOKEN=$(az account get-access-token --resource https://ai.azure.com \
  --query accessToken -o tsv)

Send a PATCH request to configure the agent card and enable the A2A protocol:

curl -X PATCH "$BASE_URL/agents/$AGENT_NAME?api-version=v1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_card": {
      "description": "A helpful assistant that answers questions",
      "version": "1.0",
      "skills": [
        {
          "id": "general-qa",
          "name": "General Q&A",
          "description": "Answers general questions"
        }
      ]
    },
    "agent_endpoint": {
      "protocol_configuration": {
        "responses": {},
        "a2a": {}
      }
    }
  }'

Update the agent_card fields to describe your agent’s actual capabilities. The agent card is what other agents see when they discover your A2A endpoint.

Set up variables for your project:

$BASE_URL = "https://{account}.services.ai.azure.com/api/projects/{project}"
$AGENT_NAME = "your-agent-name"
$TOKEN = az account get-access-token --resource https://ai.azure.com `
  --query accessToken -o tsv

Send a PATCH request to configure the agent card and enable the A2A protocol:

$body = @{
    agent_card = @{
        description = "A helpful assistant that answers questions"
        version = "1.0"
        skills = @(
            @{
                id = "general-qa"
                name = "General Q&A"
                description = "Answers general questions"
            }
        )
    }
    agent_endpoint = @{
        protocol_configuration = @{
            responses = @{}
            a2a = @{}
        }
    }
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Method Patch `
  -Uri "$BASE_URL/agents/$AGENT_NAME`?api-version=v1" `
  -Headers @{ Authorization = "Bearer $TOKEN" } `
  -ContentType "application/json" `
  -Body $body

Update the agent_card fields to describe your agent’s actual capabilities. The agent card is what other agents see when they discover your A2A endpoint.

Install the required package:

pip install "azure-ai-projects>=2.5.0"

Use the update_details method to add the agent card and A2A protocol to your agent’s endpoint:

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    A2AProtocolConfiguration, AgentCard, AgentCardSkill, AgentEndpointConfig,
    ProtocolConfiguration, ResponsesProtocolConfiguration,
)
# Create the project client.
project = AIProjectClient(
    endpoint="your_project_endpoint",
    credential=DefaultAzureCredential(),
)
# Add the agent card and enable the A2A protocol.
patched_agent = project.agents.update_details(
    agent_name="your_agent_name",
    agent_endpoint=AgentEndpointConfig(
        protocol_configuration=ProtocolConfiguration(
            responses=ResponsesProtocolConfiguration(),
            a2a=A2AProtocolConfiguration(),
        ),
    ),
    agent_card=AgentCard(
        version="1.0",
        description="A helpful assistant that answers questions.",
        skills=[AgentCardSkill(
            id="general-qa", name="General Q&A",
            description="Answers general questions.",
        )],
    ),
)
print(f"Enabled incoming A2A for agent: {patched_agent.name}")

Install the prerelease package with dotnet add package Azure.AI.Projects.Agents --prerelease and dotnet add package Azure.Identity. Use PatchAgent to add the agent card and enable the responses and A2A protocols in one call:

using System;
using Azure.AI.Projects.Agents;
using Azure.Identity;

AgentAdministrationClient agentsClient = new(
    endpoint: new Uri("your_project_endpoint"),
    tokenProvider: new DefaultAzureCredential());

var patchOptions = new PatchAgentOptions
{
    AgentEndpoint = new AgentEndpointConfiguration
    {
        ProtocolConfiguration = new ProtocolConfiguration
        {
            Responses = new ResponsesProtocolConfiguration(),
            A2a = new A2AProtocolConfiguration(),
        },
    },
    AgentCard = new AgentCard(version: "1.0", skills: new[]
    {
        new AgentCardSkill(id: "general-qa", name: "General Q&A")
        {
            Description = "Answers general questions.",
        }
    })
    {
        Description = "A helpful assistant that answers questions.",
    },
};
var patched = agentsClient.PatchAgent("your_agent_name", patchOptions);
Console.WriteLine($"Enabled incoming A2A for agent: {patched.Value.Name}");

Install the required package:

npm install @azure/ai-projects @azure/identity

import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

const project = new AIProjectClient(
  "your_project_endpoint",
  new DefaultAzureCredential(),
);

// Add the agent card and enable the A2A protocol.
const patchedAgent = await project.agents.patchAgentObject(
  "your_agent_name",
  {
    agentEndpoint: {
      protocol_configuration: {
        responses: {},
        a2a: {},
      },
    },
    agentCard: {
      version: "1.0",
      description: "A helpful assistant that answers questions.",
      skills: [
        {
          id: "general-qa",
          name: "General Q&A",
          description: "Answers general questions.",
        },
      ],
    },
  },
);
console.log(`Enabled incoming A2A for agent: ${patchedAgent.name}`);

Reference: AIProjectClient

A2A protocol versions

Foundry serves both A2A protocol versions on the same base path (…/endpoint/protocols/a2a). Calling agents select a version in one of three ways:

Agent card discovery (recommended)—Fetch the version-specific agent card. Foundry publishes the v1.0 card at …/agentCard/v1.0 and the v0.3 card at …/agentCard/v0.3. Each card declares its protocolVersion, and most A2A client SDKs use that field to negotiate the version automatically for subsequent requests.
HTTP header—Set A2A-Version: 1.0 (or A2A-Version: 0.3) on the request.
Query string—Append ?a2a-version=1.0 (or ?a2a-version=0.3) to the request URL.

If you provide a version in both the A2A-Version header and the a2a-version query string, the values must match. If the values differ, Foundry returns HTTP 400 with the version-ambiguous problem type or the JSON-RPC VERSION_AMBIGUOUS reason. Remove one version selector or make the values identical.

If a request doesn’t specify a version through the A2A-Version header or a2a-version query string, Foundry serves preview A2A v0.3 by default, in accordance with the A2A specification. For production integrations, explicitly select generally available v1.0 by setting the header, setting the query string, or having your client fetch the v1.0 agent card so the SDK negotiates v1.0 automatically.

The following table summarizes the supported versions:

Version	Status	Recommended for
1.0	Generally available (GA)	New integrations
0.3	Preview	Existing integrations that already target v0.3

Understand A2A task and context retention

Foundry retains A2A tasks and contexts for 60 days from their most recent write. Each new write to a task or context resets its 60-day retention period.

Verify the agent card

After you enable incoming A2A, your agent exposes the following URLs that calling agents use:

A2A base path—The root URL for A2A protocol interactions with your agent: https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/a2a
Agent card URL (v1.0, recommended)—The discovery endpoint that calling agents use to retrieve your agent’s v1.0 card: https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/a2a/agentCard/v1.0
Agent card URL (v0.3)—The discovery endpoint for the v0.3 card. Use this URL for clients that target A2A v0.3: https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/a2a/agentCard/v0.3

You author your agent card once (in the agent_card PATCH body shown earlier), and Foundry projects the same content into both the v1.0 and v0.3 card shapes.

All A2A URLs require Microsoft Entra ID authentication. Anonymous access to the agent card isn’t supported. The calling identity must have the Foundry Agent Consumer role or another Foundry role that grants endpoint access on the Foundry project or agent.

To confirm your agent card is configured correctly, fetch the v1.0 card directly:

    curl -X GET "$BASE_URL/agents/$AGENT_NAME/endpoint/protocols/a2a/agentCard/v1.0" \
      -H "Authorization: Bearer $TOKEN"

    Invoke-RestMethod -Method Get `
      -Uri "$BASE_URL/agents/$AGENT_NAME/endpoint/protocols/a2a/agentCard/v1.0" `
      -Headers @{ Authorization = "Bearer $TOKEN" }

The response contains the agent card with the description and skills you configured. Verify that the fields match your intended capabilities, and confirm that the card’s protocolVersion field matches the version path you requested.

Configure authentication for incoming requests

Incoming A2A requests require Microsoft Entra ID authentication. Key-based authentication and unauthenticated access aren’t supported. The calling agent must present a valid Microsoft Entra token. The identity behind that token must have the Foundry Agent Consumer role, or another Foundry role that grants endpoint access, on the target Foundry project or target agent. Two authentication patterns are supported:

On-behalf-of (OBO) the end user

The calling agent passes through the end user’s identity. Your agent receives a token that represents the actual user, so you can scope actions to that user’s permissions. This pattern is appropriate when your agent needs to enforce per-user access control.

Service identity (agent identity, service principal, or managed identity)

The calling agent authenticates with its own identity—either the platform-assigned agent identity, a service principal, or a managed identity. Your agent sees the calling service’s identity, not an individual user. This pattern is appropriate for backend agent-to-agent workflows where individual user context isn’t required.

Grant access to the A2A endpoint

Assign the Foundry Agent Consumer role to the identity that sends A2A requests. This role provides least-privilege access to agent endpoints without granting permission to create or modify agents. Choose the role-assignment scope based on the access the caller needs:

Assign the role at the target Foundry project scope to allow the identity to call every agent endpoint in the project.
Assign the role at the target agent scope to allow the identity to call only that agent endpoint.

Use the identity represented by the access token:

For OBO requests, grant access to the end user or a group that contains the user.
For service-to-service requests, grant access to the calling agent identity, service principal, or managed identity.
For a new-model Foundry agent, use the identity specified by the agent’s instance_identity. The agent has this unique identity from creation, and publishing doesn’t change it.
For a legacy Agent Application caller, use the shared project identity before publishing and the distinct Agent Application identity after publishing.

Use the identity’s Microsoft Entra object (principal) ID for the role assignment, not its application (client) ID. For more information about the two identity models, see Migrate from agent applications to the new agent endpoint and publishing experience. The project and agent scope formats are:

/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>

/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>/agents/<agent>

Assign the role by using its role definition ID:

PRINCIPAL_TYPE="ServicePrincipal"

az role assignment create \
  --assignee-object-id "<calling-principal-object-id>" \
  --assignee-principal-type "$PRINCIPAL_TYPE" \
  --role "eed3b665-ab3a-47b6-8f48-c9382fb1dad6" \
  --scope "<target-project-or-agent-scope>"

Set PRINCIPAL_TYPE to User, Group, or ServicePrincipal based on the calling identity. Agent identities and managed identities use ServicePrincipal. When the caller acquires a token directly, request the https://ai.azure.com/.default scope. For more information about role assignments, see Role-based access control for Microsoft Foundry.

Supported A2A transports

Transport support depends on the A2A protocol version:

Transport	v0.3	v1.0
HTTP+JSON	✔️	❌
JSONRPC	✔️	✔️
gRPC	❌	❌

A2A v1.0 is JSONRPC-only on Foundry’s incoming endpoint. Clients that require HTTP+JSON must either use v0.3 or switch to JSONRPC for v1.0.

Connect to a Foundry A2A agent with the Python A2A SDK

The following example shows how to use the open-source Python A2A SDK to connect to a Foundry agent that has incoming A2A enabled. The SDK reads the protocolVersion field from the agent card and negotiates the matching protocol version for subsequent requests, so pointing the resolver at agentCard/v1.0 causes the client to use A2A v1.0 end to end. Because the Foundry agent card requires authentication and uses a custom path (agentCard/v1.0 instead of the default .well-known/agent-card.json), you configure the httpx client with a bearer token and pass the custom agent card path to the resolver. Install the required packages:

pip install a2a-sdk==1.0.2 azure-identity==1.25.3 httpx==0.28.1

import asyncio

import httpx

from azure.identity import DefaultAzureCredential
from a2a.client import A2ACardResolver, ClientConfig, create_client
from a2a.helpers import new_text_message
from a2a.types.a2a_pb2 import (
    Role,
    SendMessageRequest,
)

# Your Foundry agent's A2A base path
A2A_BASE_URL = (
    "https://{account}.services.ai.azure.com/api/projects"
    "/{project}/agents/{agent}/endpoint/protocols/a2a"
)
# Agent card path, relative to the A2A base URL.
AGENT_CARD_PATH = "agentCard/v1.0"

async def main():
    # Get a Microsoft Entra token
    credential = DefaultAzureCredential()
    token = credential.get_token("https://ai.azure.com/.default").token

    async with httpx.AsyncClient(
        headers={"Authorization": f"Bearer {token}"},
        timeout=httpx.Timeout(120.0),
    ) as httpx_client:
        # Resolve the agent card from the custom path
        resolver = A2ACardResolver(
            httpx_client=httpx_client,
            base_url=A2A_BASE_URL,
            agent_card_path=AGENT_CARD_PATH,
        )
        agent_card = await resolver.get_agent_card()

        # Create a non-streaming A2A client
        config = ClientConfig(
            streaming=False,
            httpx_client=httpx_client,
        )
        client = await create_client(
            agent=agent_card, client_config=config
        )

        # Send a message to the Foundry agent
        message = new_text_message(
            "Hello, what can you do?", role=Role.ROLE_USER
        )
        request = SendMessageRequest(message=message)

        async for response in client.send_message(request):
            print(response)

        await client.close()

if __name__ == "__main__":
    asyncio.run(main())

Replace {account}, {project}, and {agent} with your Foundry resource name, project name, and agent name. The resolver constructs the full agent card URL by appending the relative AGENT_CARD_PATH to A2A_BASE_URL.

Connect from another Foundry agent

You can call a Foundry A2A agent from another Foundry agent by using the A2A tool. This section walks through the full setup: create a connection to the target agent, then create a calling agent that uses that connection.

Step 1: Create an A2A connection to the target agent

The connection stores the target agent’s A2A endpoint URL and authentication details. For a Foundry agent target, don’t set an agent card path. Foundry resolves the default agent card path automatically and negotiates the A2A protocol version for you.

REST API (Bash)
REST API (PowerShell)

Set up variables:

SUBSCRIPTION_ID="your-subscription-id"
RESOURCE_GROUP="your-resource-group"
FOUNDRY_ACCOUNT="your-foundry-account"
PROJECT_NAME="your-project"
CONNECTION_NAME="my-a2a-target"
TARGET_A2A_URL="https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/a2a"
TOKEN=$(az account get-access-token \
  --scope https://management.azure.com/.default \
  --query accessToken -o tsv)

Create the connection:

curl --request PUT \
  --url "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.CognitiveServices/accounts/$FOUNDRY_ACCOUNT/projects/$PROJECT_NAME/connections/$CONNECTION_NAME?api-version=2025-04-01-preview" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "properties": {
      "authType": "AgenticIdentityToken",
      "category": "RemoteA2A",
      "target": "'"$TARGET_A2A_URL"'",
      "audience": "https://ai.azure.com",
      "Credentials": {},
      "metadata": {}
    }
  }'

Set up variables:

$SUBSCRIPTION_ID = "your-subscription-id"
$RESOURCE_GROUP = "your-resource-group"
$FOUNDRY_ACCOUNT = "your-foundry-account"
$PROJECT_NAME = "your-project"
$CONNECTION_NAME = "my-a2a-target"
$TARGET_A2A_URL = "https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/a2a"
$TOKEN = az account get-access-token `
  --scope https://management.azure.com/.default `
  --query accessToken -o tsv

Create the connection:

$body = @{
    properties = @{
        authType = "AgenticIdentityToken"
        category = "RemoteA2A"
        target = $TARGET_A2A_URL
        audience = "https://ai.azure.com"
        Credentials = @{}
        metadata = @{}
    }
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Method Put `
  -Uri "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.CognitiveServices/accounts/$FOUNDRY_ACCOUNT/projects/$PROJECT_NAME/connections/$CONNECTION_NAME`?api-version=2025-04-01-preview" `
  -Headers @{ Authorization = "Bearer $TOKEN" } `
  -ContentType "application/json" `
  -Body $body

For other authentication options (key-based, OAuth, managed identity), see Create an A2A connection by using the REST API.

Step 2: Create the calling agent with the A2A tool

After the connection exists, create an agent that uses the A2ATool to call the target agent:

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    A2AProtocolVersion,
    A2ATool,
    PromptAgentDefinition,
)

PROJECT_ENDPOINT = "your_project_endpoint"
A2A_CONNECTION_NAME = "my-a2a-target"
AGENT_NAME = "my-calling-agent"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

a2a_connection = project.connections.get(A2A_CONNECTION_NAME)

tool = A2ATool(
    a2a_version=A2AProtocolVersion.V1_0,
    project_connection_id=a2a_connection.id,
)

agent = project.agents.create_version(
    agent_name=AGENT_NAME,
    definition=PromptAgentDefinition(
        model="gpt-4.1-mini",
        instructions=(
            "You are a helpful assistant. Use the A2A tool "
            "to delegate tasks to the target agent."
        ),
        tools=[tool],
    ),
)

# Send a message and stream the response
stream_response = openai.responses.create(
    stream=True,
    input="Ask the target agent what it can do.",
    extra_body={
        "agent_reference": {
            "name": agent.name,
            "type": "agent_reference",
        }
    },
)

for event in stream_response:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")
    elif event.type == "response.completed":
        print(f"\n\nCompleted: {event.response.output_text}")

# Clean up
project.agents.delete_version(
    agent_name=agent.name, agent_version=agent.version
)

For more language examples (C#, JavaScript, Java, REST), see Connect to an A2A agent endpoint from Foundry Agent Service.

Limitations

Generally available A2A protocol version 1.0 and preview version 0.3 are supported. Other versions aren’t supported.
For A2A v1.0, only the JSONRPC transport is supported. HTTP+JSON and gRPC aren’t supported for v1.0. See Supported A2A transports.
Only text modality is supported. File data and other nontext modalities aren’t supported.
Streaming responses (server-sent events) aren’t supported.
Incoming A2A requires the responses protocol. Agents that don’t use the responses protocol can’t be exposed as A2A endpoints.
A2A v0.3 is in preview and isn’t recommended for production workloads. Use v1.0 for production integrations.

What is Microsoft Foundry?

Product and capability map

Capability reference

Get started

Developer tools and integrations

Models

Agents

Toolboxes

Observability

Evaluation

Enable incoming A2A on a Foundry agent

Supported agent types

Prerequisites

Enable incoming A2A

A2A protocol versions

Understand A2A task and context retention

Verify the agent card

Configure authentication for incoming requests

On-behalf-of (OBO) the end user

Service identity (agent identity, service principal, or managed identity)

Grant access to the A2A endpoint

Supported A2A transports

Connect to a Foundry A2A agent with the Python A2A SDK

Connect from another Foundry agent

Step 1: Create an A2A connection to the target agent

Step 2: Create the calling agent with the A2A tool

Limitations

​Supported agent types

​Prerequisites

​Enable incoming A2A

​A2A protocol versions

​Understand A2A task and context retention

​Verify the agent card

​Configure authentication for incoming requests

​On-behalf-of (OBO) the end user

​Service identity (agent identity, service principal, or managed identity)

​Grant access to the A2A endpoint

​Supported A2A transports

​Connect to a Foundry A2A agent with the Python A2A SDK

​Connect from another Foundry agent

​Step 1: Create an A2A connection to the target agent

​Step 2: Create the calling agent with the A2A tool

​Limitations

​Related content

Supported agent types

Prerequisites

Enable incoming A2A

A2A protocol versions

Understand A2A task and context retention

Verify the agent card

Configure authentication for incoming requests

On-behalf-of (OBO) the end user

Service identity (agent identity, service principal, or managed identity)

Grant access to the A2A endpoint

Supported A2A transports

Connect to a Foundry A2A agent with the Python A2A SDK

Connect from another Foundry agent

Step 1: Create an A2A connection to the target agent

Step 2: Create the calling agent with the A2A tool

Limitations

Related content