Conectar-se a um ponto de extremidade de agente A2A do Serviço de Agente do Foundry (versão prévia)

Criar um agente com a ferramenta A2A

Selecione Prompt Agents para usar o SDK de Projetos de IA Azure para criar um agente de prompt do lado do servidor ou Hosted Agents para usar o Agent Framework FoundryChatClient para criar um agente efêmero em processo.

Agentes de prompt

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})")

Em seguida, envie uma solicitação para o agente e imprima a resposta:

# 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)

Saída esperada

O agente responde com informações sobre os recursos do agente secundário, demonstrando uma comunicação A2A bem-sucedida.

Agentes hospedados

Este exemplo usa FoundryChatClient do Microsoft Agent Framework para criar o a2a-toolbox e conectar-se ao seu endpoint MCP com FoundryToolbox. Instale os pacotes com pip install agent-framework-foundry azure-ai-projects, substitua PROJECT_ENDPOINT pelo endpoint do seu projeto e faça login com az login. Para obter o padrão completo da caixa de ferramentas do agente hospedado, consulte o exemplo completo.

import asyncio

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox
from azure.identity import AzureCliCredential
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)],
)

Em seguida, anexe a caixa de ferramentas ao agente hospedado como uma ferramenta MCP e execute-a:

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
, timeout=120.0)
    toolbox_tool = FoundryToolbox(credential, url=TOOLBOX_MCP_URL)

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

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


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

Saída esperada

O agente chama o agente secundário via o endpoint MCP a2a-toolbox e imprime a resposta consolidada:

Agent: The secondary agent can help with ...

Para obter o padrão completo da caixa de ferramentas do agente hospedado, consulte o exemplo completo.

Criar um agente com a ferramenta A2A

Este exemplo cria um agente que pode chamar um endpoint A2A remoto. Para obter as etapas de configuração da conexão, consulte Criar uma conexão A2A. Selecione Prompt Agents para usar o SDK do Azure AI Projects para criar um agente de prompt no servidor, ou Hosted Agents para usar o Microsoft Agent Framework para compor dois agentes no processo, expondo um agente como ferramenta de função de outro agente.

Agentes de prompt

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));

Em seguida, envie uma solicitação para o agente e imprima a resposta:

// 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);

Saída esperada

O console exibe o texto de resposta do agente do ponto de extremidade A2A. Após a conclusão, a versão do agente é excluída para limpar os recursos.

Agentes hospedados

Este exemplo cria o a2a-toolbox com o SDK do Azure AI Projects e, em seguida, usa a integração AddFoundryToolboxes do Microsoft Agent Framework para tornar a ferramenta A2A disponível para o agente hospedado. Defina as variáveis de ambiente AZURE_AI_PROJECT_ENDPOINT, AZURE_OPENAI_ENDPOINT e AZURE_AI_MODEL_DEPLOYMENT_NAME e faça login com az login. Para obter o padrão completo da caixa de ferramentas do agente hospedado, consulte o exemplo completo.

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.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;
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");

Em seguida, anexe a caixa de ferramentas ao agente hospedado:

// Create the hosted agent and register the toolbox integration.
AIAgent agent = projectClient.AsAIAgent(
    model: deploymentName,
    instructions: "You are a helpful assistant with access to the toolbox tools.",
    name: "hosted-toolbox-agent");

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.Services.AddFoundryToolboxes(credential, toolboxVersion.Name);

var app = builder.Build();
app.MapFoundryResponses();
app.Run();

Saída esperada

Ao ser invocado, o agente hospedado chama o agente secundário por meio do endpoint MCP a2a-toolbox e imprime a resposta consolidada:

Agent: The secondary agent can help with ...

Para obter uma integração mantida do .NET Agent Framework, consulte Usar uma caixa de ferramentas com um agente hospedado.

Criar uma conexão A2A usando a API REST

Use esses exemplos para criar uma conexão de projeto que armazene suas informações de autenticação.

Obtenha um token de acesso de curta duração para o endpoint do Azure Resource Manager e mantenha-o na sessão atual do shell. Não imprima, registre, faça commit nem armazene o token. Solicite um novo token depois que ele expirar:

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

Baseado em chave

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"
      }
    }
  }'

Passagem de identidade gerenciada por OAuth

Essa opção tem suporte quando você seleciona OAuth Gerenciado no catálogo de ferramentas do Foundry.

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"
      }
    }
  }'

Passagem de identidade OAuth personalizada

O OAuth personalizado não dá suporte à operação de atualização. Crie uma nova conexão se você quiser atualizar determinados valores.

Se o aplicativo OAuth não exigir um segredo do cliente, omita 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"
      }
    }
  }'

Identidade gerenciada do projeto Foundry

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"
      }
    }
  }'

Identidade do agente

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"
      }
    }
  }'

Adicione a ferramenta A2A ao Serviço de Agente do Foundry

Obtenha um token de acesso:

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

Use AGENT_TOKEN para autorizar solicitações para o plano de dados do projeto.

A maneira recomendada de adicionar uma ferramenta A2A é por meio de uma caixa de ferramentas e anexar a caixa de ferramentas ao seu agente como uma ferramenta MCP. Veja o que é uma caixa de ferramentas?

1. Crie uma caixa de ferramentas que contenha a ferramenta A2A:

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}}"
      }
    ]
  }'

O kit de ferramentas expõe um endpoint compatível com MCP em {{project_endpoint}}/toolboxes/a2a-toolbox/versions/<version>/mcp?api-version=v1, em que <version> é a versão retornada pela chamada anterior.

1. Crie uma conexão de projeto de ferramenta remota que aponte para o ponto de extremidade da caixa de ferramentas, usando um token Entra do usuário para que a identidade do chamador seja passada (audiência 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. Crie uma versão do agente que use a caixa de ferramentas anexando-a como uma ferramenta MCP:

   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."
     }
   }'
   

Para excluir uma versão do agente, envie uma DELETE solicitação para o mesmo endpoint com o nome e a versão do agente.

Este exemplo demonstra como criar um agente de IA com recursos A2A usando o tipo de ferramenta a2a_preview e o cliente Azure projetos de IA. O agente se comunica com outros agentes e fornece respostas com base nas interações entre agentes usando o protocolo A2A.

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`;

Crie uma conexão de projeto de ferramenta remota que aponte para o ponto de extremidade da caixa de ferramentas. Use um token de usuário do Entra para que a identidade do chamador seja transmitida (público-alvo https://ai.azure.com). Crie a conexão uma vez, por exemplo, com a CLI do desenvolvedor do Azure:

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

Em seguida, anexe a caixa de ferramentas a um agente de prompt como uma ferramenta MCP e execute-a:

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);

Saída esperada

O console exibe o texto de resposta do agente do ponto de extremidade A2A. Após a conclusão, a versão do agente é excluída para limpar os recursos.

Usar a comunicação agente a agente no Java

Atualize esses valores em seu agente de Java depois de criar a caixa de ferramentas:

• projectEndpoint — O ponto de extremidade do projeto.
• toolboxMcpUrl — O ponto de extremidade MCP para a versão da caixa de ferramentas que contém a ferramenta A2A.
• toolboxConnectionName — O nome da conexão de projeto de ferramenta remota para o ponto de extremidade da caixa de ferramentas.

Adicione a dependência ao seu pom.xml:

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