Connect to an A2A agent endpoint from Foundry Agent Service (preview)

Create an agent with the A2A tool

Select Prompt Agents to use the Azure AI Projects SDK to create a server-side prompt agent, or Hosted Agents to use the Agent Framework FoundryChatClient to build an ephemeral, in-process agent.

Prompt agents

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

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
A2A_CONNECTION_NAME = "my-a2a-connection"
AGENT_NAME = "my-agent"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create the A2A tool from the project connection
a2a_connection = project.connections.get(A2A_CONNECTION_NAME)
tool = A2APreviewTool(
    project_connection_id=a2a_connection.id,
)

# Create the agent with the A2A tool
agent = project.agents.create_version(
    agent_name=AGENT_NAME,
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant.",
        tools=[tool],
    ),
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

Next, send a request to the agent and print the response:

# Send a request to the agent
response = openai.responses.create(
    tool_choice="required",
    input="What can the secondary agent do?",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
print(response.output_text)

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

Expected output

The agent responds with information about the secondary agent's capabilities, demonstrating successful A2A communication.

Hosted agents

This sample uses FoundryChatClient from the Microsoft Agent Framework to create the a2a-toolbox and connect to its MCP endpoint with MCPStreamableHTTPTool. Install the packages with pip install agent-framework-foundry httpx azure-ai-projects, replace PROJECT_ENDPOINT with your project endpoint, and sign in with az login. For the complete hosted-agent toolbox pattern, see the full sample.

import asyncio

import httpx
from agent_framework import Agent, MCPStreamableHTTPTool
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential, get_bearer_token_provider
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import A2APreviewToolboxTool

PROJECT_ENDPOINT = "https://<account>.services.ai.azure.com/api/projects/<project>"
A2A_CONNECTION_NAME = "my-a2a-connection"

# Create the A2A tool and add it to a toolbox
credential = AzureCliCredential()
project = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=credential)
a2a_connection = project.connections.get(A2A_CONNECTION_NAME)
toolbox = project.toolboxes.create_version(
    name="a2a-toolbox",
    description="Toolbox with the A2A tool",
    tools=[A2APreviewToolboxTool(project_connection_id=a2a_connection.id)],
)

Next, attach the toolbox to the hosted agent as an MCP tool and run it:

class _ToolboxAuth(httpx.Auth):
    def __init__(self, token_provider):
        self._token_provider = token_provider

    def auth_flow(self, request):
        request.headers["Authorization"] = f"Bearer {self._token_provider()}"
        yield request


async def main() -> None:
    # The toolbox exposes an MCP-compatible endpoint
    TOOLBOX_MCP_URL = (
        f"{PROJECT_ENDPOINT}/toolboxes/{toolbox.name}"
        f"/versions/{toolbox.version}/mcp?api-version=v1"
    )

    # Attach the toolbox to the hosted agent as an MCP tool
    token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")
    http_client = httpx.AsyncClient(auth=_ToolboxAuth(token_provider), timeout=120.0)
    mcp_tool = MCPStreamableHTTPTool(
        name="toolbox",
        url=TOOLBOX_MCP_URL,
        http_client=http_client,
        load_prompts=False,
    )

    agent = Agent(
        client=FoundryChatClient(credential=credential),
        instructions="You are a helpful assistant.",
        tools=[mcp_tool],
    )

    result = await agent.run("What can the secondary agent do?")
    print(f"Agent: {result.text}")


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

Expected output

The agent calls the secondary agent through the a2a-toolbox MCP endpoint and prints the consolidated reply:

Agent: The secondary agent can help with ...

For the complete hosted-agent toolbox pattern, see the full sample.

Create an agent with the A2A tool

This example creates an agent that can call a remote A2A endpoint. For the connection setup steps, see Create an A2A connection. Select Prompt Agents to use the Azure AI Projects SDK to create a server-side prompt agent, or Hosted Agents to use the Microsoft Agent Framework to compose two agents in-process by exposing one agent as a function tool of another.

Prompt agents

using System;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;

var projectEndpoint = "https://<resource>.ai.azure.com/api/projects/<project>";
var a2aConnectionName = "my-a2a-connection";
var a2aBaseUri = "https://<a2a-endpoint>"; // Optional for non-RemoteA2A connections.

// Create project client to call Foundry API
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: new DefaultAzureCredential());

// Create the A2ATool and provide it with the A2A connection ID
AIProjectConnection a2aConnection = projectClient.Connections.GetConnection(connectionName: a2aConnectionName);
A2APreviewTool a2aTool = new()
{
    ProjectConnectionId = a2aConnection.Id
};
if (!string.Equals(a2aConnection.Type.ToString(), "RemoteA2A"))
{
  if (string.IsNullOrWhiteSpace(a2aBaseUri))
    {
    throw new InvalidOperationException($"The connection {a2aConnection.Name} is of {a2aConnection.Type.ToString()} type and does not carry the A2A service base URI. Set a2aBaseUri before running this sample.");
    }
    a2aTool.BaseUri = new Uri(a2aBaseUri);
}

// Create the agent with the A2A tool
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    Instructions = "You are a helpful assistant.",
    Tools = { a2aTool }
};
AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "myAgent",
    options: new(agentDefinition));

Next, send a request to the agent and print the response:

// Send the request and print the response
ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);
CreateResponseOptions responseOptions = new()
{
    ToolChoice = ResponseToolChoice.CreateRequiredChoice(),
    InputItems = { ResponseItem.CreateUserMessageItem("What can the secondary agent do?") },
};
ResponseResult response = responseClient.CreateResponse(responseOptions);
Console.WriteLine(response.GetOutputText());

// Clean up the created agent version
projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);

Expected output

The console displays the agent's response text from the A2A endpoint. After completion, the agent version is deleted to clean up resources.

Hosted agents

This sample creates the a2a-toolbox with the Azure AI Projects SDK, then uses ResponsesServer from the Microsoft Agent Framework with a custom ToolboxMcpClient to discover and invoke the A2A tool through the toolbox MCP endpoint. Set the AZURE_AI_PROJECT_ENDPOINT, AZURE_OPENAI_ENDPOINT, and AZURE_AI_MODEL_DEPLOYMENT_NAME environment variables, and sign in with az login. For the complete hosted-agent toolbox pattern, see the full sample.

using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;
using Azure.AI.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.DependencyInjection;
using OpenAI.Chat;

const string AgentInstructions = "You are a helpful assistant.";
const string AgentName = "A2AAgent";

string projectEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
    ?? "https://<account>.services.ai.azure.com/api/projects/<project>";
string a2aConnectionName = "my-a2a-connection";
string openAiEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5-mini";

DefaultAzureCredential credential = new();

// Create the A2A tool and add it to a toolbox
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: credential);
AIProjectConnection a2aConnection = projectClient.Connections.GetConnection(connectionName: a2aConnectionName);
A2APreviewTool a2aTool = new() { ProjectConnectionId = a2aConnection.Id };
ProjectsAgentTool a2aProjectTool = a2aTool;
ToolboxVersion toolboxVersion = projectClient.AgentAdministrationClient
    .GetAgentToolboxes().CreateToolboxVersion(
        toolboxName: "a2a-toolbox",
        tools: [a2aProjectTool],
        description: "Toolbox with the A2A tool");

Next, attach the toolbox to the hosted agent:

// The toolbox exposes an MCP-compatible endpoint
string toolboxMcpEndpoint =
    $"{projectEndpoint}/toolboxes/{toolboxVersion.Name}/versions/{toolboxVersion.Version}/mcp?api-version=v1";

// Attach the toolbox to the hosted agent
AzureOpenAIClient openAIClient = new(new Uri(openAiEndpoint), credential);
ChatClient chatClient = openAIClient.GetChatClient(deploymentName);

// ToolboxMcpClient discovers toolbox tools via MCP tools/list and calls them via tools/call
ToolboxMcpClient toolboxClient = new(toolboxMcpEndpoint, credential);

ResponsesServer.Run<ToolboxHandler>(configure: builder =>
{
    builder.Services.AddSingleton(new AgentConfig(
        name: AgentName,
        instructions: AgentInstructions,
        chatClient: chatClient,
        toolboxClient: toolboxClient));
});

Expected output

When invoked, the hosted agent calls the secondary agent through the a2a-toolbox MCP endpoint and prints the consolidated reply:

Agent: The secondary agent can help with ...

For a maintained .NET Agent Framework integration, see Use a toolbox with a hosted agent.

Create an A2A connection by using the REST API

Use these examples to create a project connection that stores your authentication information.

Get a short-lived access token for the Azure Resource Manager endpoint and keep it in the current shell. Don't print, log, commit, or persist the token. Request a new token after it expires:

ARM_TOKEN=$(az account get-access-token \
  --scope https://management.azure.com/.default \
  --query accessToken -o tsv)

Key-based

curl --request PUT \
  --url 'https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group_name}}/providers/Microsoft.CognitiveServices/accounts/{{foundry_account_name}}/projects/{{project_name}}/connections/{{connection_name}}?api-version=2025-04-01-preview' \
  --header "Authorization: Bearer $ARM_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "tags": null,
    "location": null,
    "name": "{{connection_name}}",
    "type": "Microsoft.MachineLearningServices/workspaces/connections",
    "properties": {
      "authType": "CustomKeys",
      "group": "ServicesAndApps",
      "category": "RemoteA2A",
      "expiryTime": null,
      "target": "{{a2a_endpoint}}",
      "isSharedToAll": true,
      "sharedUserList": [],
      "Credentials": {
        "Keys": {
          "{{key_name}}": "{{key_value}}"
        }
      },
      "metadata": {
        "ApiType": "Azure"
      }
    }
  }'

Managed OAuth Identity Passthrough

This option is supported when you select Managed OAuth in the Foundry tool catalog.

curl --request PUT \
  --url 'https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group_name}}/providers/Microsoft.CognitiveServices/accounts/{{foundry_account_name}}/projects/{{project_name}}/connections/{{connection_name}}?api-version=2025-04-01-preview' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tags": null,
    "location": null,
    "name": "{{connection_name}}",
    "type": "Microsoft.MachineLearningServices/workspaces/connections",
    "properties": {
      "authType": "OAuth2",
      "group": "ServicesAndApps",
      "category": "RemoteA2A",
      "expiryTime": null,
      "target": "{{a2a_endpoint}}",
      "isSharedToAll": true,
      "sharedUserList": [],
      "useCustomConnector": false,
      "connectorName": "{{connector_name}}",
      "Credentials": {},
      "metadata": {
        "ApiType": "Azure"
      }
    }
  }'

Custom OAuth Identity Passthrough

Custom OAuth doesn't support the update operation. Create a new connection if you want to update certain values.

If your OAuth app doesn't require a client secret, omit ClientSecret.

curl --request PUT \
  --url 'https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group_name}}/providers/Microsoft.CognitiveServices/accounts/{{foundry_account_name}}/projects/{{project_name}}/connections/{{connection_name}}?api-version=2025-04-01-preview' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tags": null,
    "location": null,
    "name": "{{connection_name}}",
    "type": "Microsoft.MachineLearningServices/workspaces/connections",
    "properties": {
      "authType": "OAuth2",
      "group": "ServicesAndApps",
      "category": "RemoteA2A",
      "expiryTime": null,
      "target": "{{a2a_endpoint}}",
      "isSharedToAll": true,
      "sharedUserList": [],
      "TokenUrl": "{{token_url}}",
      "AuthorizationUrl": "{{authorization_url}}",
      "RefreshUrl": "{{refresh_url}}",
      "Scopes": [
        "{{scope}}"
      ],
      "Credentials": {
        "ClientId": "{{client_id}}",
        "ClientSecret": "{{client_secret}}"
      },
      "metadata": {
        "ApiType": "Azure"
      }
    }
  }'

Foundry project managed identity

curl --request PUT \
  --url 'https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group_name}}/providers/Microsoft.CognitiveServices/accounts/{{foundry_account_name}}/projects/{{project_name}}/connections/{{connection_name}}?api-version=2025-04-01-preview' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tags": null,
    "location": null,
    "name": "{{connection_name}}",
    "type": "Microsoft.MachineLearningServices/workspaces/connections",
    "properties": {
      "authType": "ProjectManagedIdentity",
      "group": "ServicesAndApps",
      "category": "RemoteA2A",
      "expiryTime": null,
      "target": "{{a2a_endpoint}}",
      "isSharedToAll": true,
      "sharedUserList": [],
      "audience": "{{audience}}",
      "Credentials": {},
      "metadata": {
        "ApiType": "Azure"
      }
    }
  }'

Agent identity

curl --request PUT \
  --url 'https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group_name}}/providers/Microsoft.CognitiveServices/accounts/{{foundry_account_name}}/projects/{{project_name}}/connections/{{connection_name}}?api-version=2025-04-01-preview' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tags": null,
    "location": null,
    "name": "{{connection_name}}",
    "type": "Microsoft.MachineLearningServices/workspaces/connections",
    "properties": {
      "authType": "AgenticIdentityToken",
      "group": "ServicesAndApps",
      "category": "RemoteA2A",
      "expiryTime": null,
      "target": "{{a2a_endpoint}}",
      "isSharedToAll": true,
      "sharedUserList": [],
      "audience": "{{audience}}",
      "Credentials": {},
      "metadata": {
        "ApiType": "Azure"
      }
    }
  }'

Add A2A tool to Foundry Agent Service

Get an access token:

AGENT_TOKEN=$(az account get-access-token --scope https://ai.azure.com/.default --query accessToken -o tsv)

Use AGENT_TOKEN to authorize requests to the project data plane.

The recommended way to add an A2A tool is through a toolbox, then attach the toolbox to your agent as an MCP tool. See What is a toolbox?

1. Create a toolbox that contains the A2A tool:

curl --request POST \
  --url '{{project_endpoint}}/toolboxes/a2a-toolbox/versions?api-version=v1' \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Toolbox with the A2A tool",
    "tools": [
      {
        "type": "a2a_preview",
        "base_url": "{{a2a_endpoint}}",
        "project_connection_id": "{{project_connection_id}}"
      }
    ]
  }'

The toolbox exposes an MCP-compatible endpoint at {{project_endpoint}}/toolboxes/a2a-toolbox/versions/<version>/mcp?api-version=v1, where <version> is the version returned by the previous call.

1. Create a remote-tool project connection that points at the toolbox endpoint, using a user Entra token so the caller's identity is passed through (audience https://ai.azure.com).

   azd ai connection create a2a-toolbox-conn \
     --kind remote-tool \
     --target "{{project_endpoint}}/toolboxes/a2a-toolbox/versions/<version>/mcp?api-version=v1" \
     --auth-type user-entra-token \
     --audience https://ai.azure.com
   

2. Create an agent version that uses the toolbox by attaching it as an MCP tool:

   curl --request POST \
     --url '{{project_endpoint}}/agents/{{agent_name}}/versions?api-version=v1' \
     -H "Authorization: Bearer $AGENT_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{
     "description": "Test agent version description",
     "definition": {
       "kind": "prompt",
       "model": "{{model}}",
       "tools": [
         {
           "type": "mcp",
           "server_label": "toolbox",
           "server_url": "{{project_endpoint}}/toolboxes/a2a-toolbox/versions/<version>/mcp?api-version=v1",
           "require_approval": "never",
           "project_connection_id": "a2a-toolbox-conn"
         }
       ],
       "instructions": "You are a helpful agent."
     }
   }'
   

To delete an agent version, send a DELETE request to the same endpoint with the agent name and version.

This sample demonstrates how to create an AI agent with A2A capabilities by using the a2a_preview tool type and the Azure AI Projects client. The agent communicates with other agents and provides responses based on inter-agent interactions by using the A2A protocol.

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

const PROJECT_ENDPOINT = "https://<resource>.ai.azure.com/api/projects/<project>";
const A2A_CONNECTION_NAME = "my-a2a-connection";

// Create clients to call Foundry API
const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
const openai = project.getOpenAIClient();

// Get the A2A connection by name to retrieve its ID
const a2aConnection = await project.connections.get(A2A_CONNECTION_NAME);

// Add the A2A tool to a toolbox
const toolbox = await project.toolboxes.createVersion(
  "a2a-toolbox",
  [
    {
      type: "a2a_preview",
      project_connection_id: a2aConnection.id,
    },
  ],
  { description: "Toolbox with the A2A tool" },
);

// The toolbox exposes an MCP-compatible endpoint
const toolboxMcpUrl =
  `${PROJECT_ENDPOINT}/toolboxes/${toolbox.name}` +
  `/versions/${toolbox.version}/mcp?api-version=v1`;

Create a remote-tool project connection that points at the toolbox endpoint. Use a user Entra token so the caller's identity is passed through (audience https://ai.azure.com). Create the connection once, for example with the Azure Developer CLI:

azd ai connection create a2a-toolbox-conn \
  --kind remote-tool \
  --target "<toolboxMcpUrl>" \
  --auth-type user-entra-token \
  --audience https://ai.azure.com

Next, attach the toolbox to a prompt agent as an MCP tool and run it:

const toolboxConnectionName = "a2a-toolbox-conn";

// Attach the toolbox to a prompt agent as an MCP tool
const agent = await project.agents.createVersion("MyA2AAgent", {
  kind: "prompt",
  model: "gpt-5-mini",
  instructions: "You are a helpful assistant.",
  tools: [
    {
      type: "mcp",
      server_label: "toolbox",
      server_url: toolboxMcpUrl,
      require_approval: "never",
      project_connection_id: toolboxConnectionName,
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

// Send a request to the agent
const response = await openai.responses.create(
  {
    input: "What can the secondary agent do?",
  },
  {
    body: {
      agent_reference: { name: agent.name, type: "agent_reference" },
      tool_choice: "required",
    },
  },
);
console.log(response.output_text);

// Clean up the created agent version
await project.agents.deleteVersion(agent.name, agent.version);

Expected output

The console displays the agent's response text from the A2A endpoint. After completion, the agent version is deleted to clean up resources.

Use agent-to-agent communication in Java

Update these values in your Java agent after you create the toolbox:

• projectEndpoint — Your project endpoint.
• toolboxMcpUrl — The MCP endpoint for the toolbox version that contains the A2A tool.
• toolboxConnectionName — The remote-tool project connection name for the toolbox endpoint.

Add the dependency to your pom.xml:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-agents</artifactId>
    <version>2.2.0</version>
</dependency>