Collegarsi a un endpoint dell'agente A2A dal servizio Foundry Agent (anteprima)

Creare un agente con lo strumento A2A

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

a2a_connection = project.connections.get(A2A_CONNECTION_NAME)

tool = A2APreviewTool(
    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.",
        tools=[tool],
    ),
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

user_input = input("Enter your question (e.g., 'What can the secondary agent do?'): \n")

stream_response = openai.responses.create(
    stream=True,
    tool_choice="required",
    input=user_input,
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

for event in stream_response:
    if event.type == "response.created":
        print(f"Follow-up response created with ID: {event.response.id}")
    elif event.type == "response.output_text.delta":
        print(f"Delta: {event.delta}")
    elif event.type == "response.text.done":
        print(f"\nFollow-up response done!")
    elif event.type == "response.output_item.done":
        item = event.item
        if item.type == "remote_function_call":
            print(f"Call ID: {getattr(item, 'call_id')}")
            print(f"Label: {getattr(item, 'label')}")
    elif event.type == "response.completed":
        print(f"\nFollow-up completed!")
        print(f"Full response: {event.response.output_text}")

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

Output previsto

L'agente risponde con informazioni sulle funzionalità dell'agente secondario, dimostrando la corretta comunicazione A2A. Viene visualizzato il testo incrementale in streaming mentre viene generata la risposta, seguito dai messaggi di completamento. L'output include l'ID risposta di completamento, i delta di testo e un riepilogo finale delle operazioni che l'agente secondario può eseguire.

Creare un agente con lo strumento A2A

Questo esempio crea un agente in grado di chiamare un endpoint A2A remoto. Per la procedura di configurazione della connessione, vedere Creare una connessione A2A.

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.

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.");
    }
    // Provide the service endpoint as a baseUri parameter
    // if the connection is not of a RemoteA2A type.
    a2aTool.BaseUri = new Uri(a2aBaseUri);
}
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-4.1-mini")
{
    Instructions = "You are a helpful assistant.",
    Tools = { a2aTool }
};
// Create the Agent version with the A2A tool.
AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "myAgent",
    options: new(agentDefinition));

// Create the response and make sure we are always using tool.
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);

// Print the Agent output.
if (response.Status != ResponseStatus.Completed)
{
    throw new InvalidOperationException($"Response did not complete. Status: {response.Status}");
}
Console.WriteLine(response.GetOutputText());

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

Output previsto

La console visualizza il testo della risposta dell'agente dall'endpoint A2A. Al termine, la versione dell'agente viene eliminata per pulire le risorse.

Creare una connessione A2A usando l'API REST

Usare questi esempi per creare una connessione di progetto che archivia le informazioni di autenticazione.

Per ottenere un token di accesso per l'endpoint Azure Resource Manager:

az account get-access-token --scope https://management.azure.com/.default --query accessToken -o tsv

Basato su chiave

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": "CustomKeys",
      "group": "ServicesAndApps",
      "category": "RemoteA2A",
      "expiryTime": null,
      "target": "{{a2a_endpoint}}",
      "isSharedToAll": true,
      "sharedUserList": [],
      "Credentials": {
        "Keys": {
          "{{key_name}}": "{{key_value}}"
        }
      },
      "metadata": {
        "ApiType": "Azure"
      }
    }
  }'

Trasmissione gestita dell'identità OAuth

Questa opzione è supportata quando si seleziona OAuth gestito nel catalogo degli strumenti 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"
      }
    }
  }'

Pass-through dell'identità OAuth personalizzata

OAuth personalizzato non supporta l'operazione di aggiornamento. Creare una nuova connessione se si desidera aggiornare determinati valori.

Se l'app OAuth non richiede un segreto client, omettere 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 Identità gestite

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

Identità 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": "AgenticIdentity",
      "group": "ServicesAndApps",
      "category": "RemoteA2A",
      "expiryTime": null,
      "target": "{{a2a_endpoint}}",
      "isSharedToAll": true,
      "sharedUserList": [],
      "audience": "{{audience}}",
      "Credentials": {},
      "metadata": {
        "ApiType": "Azure"
      }
    }
  }'

Aggiungere lo strumento A2A al servizio agente di Foundry

Ottenere un token di accesso:

az account get-access-token --scope https://ai.azure.com/.default --query accessToken -o tsv

Usare tale token come {{agent_token}} nella richiesta.

Creare una versione dell'agente con lo strumento A2A

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": "a2a_preview",
         "base_url": "{{a2a_endpoint}}",
         "project_connection_id": "{{project_connection_id}}"
      }
    ],
    "instructions": "You are a helpful agent."
  }
}'

Per eliminare una versione dell'agente, inviare una DELETE richiesta allo stesso endpoint con il nome e la versione dell'agente.

Questo esempio illustra come creare un agente di intelligenza artificiale con funzionalità A2A usando il tipo di strumento a2a_preview e il client di progetti di intelligenza artificiale Azure. L'agente può comunicare con altri agenti e fornire risposte in base alle interazioni tra agenti usando il protocollo A2A.

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

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

export async function main(): Promise<void> {
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openAIClient = project.getOpenAIClient();

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

  // Create the agent with A2A tool
  const agent = await project.agents.createVersion("MyA2AAgent", {
    kind: "prompt",
    model: "gpt-4.1-mini",
    instructions: "You are a helpful assistant.",
    // Define A2A tool for agent-to-agent communication
    tools: [
      {
        type: "a2a_preview",
        project_connection_id: a2aConnection.id,
      },
    ],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  // Prompt user for input
  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
  });

  const userInput = await new Promise<string>((resolve) => {
    rl.question("Enter your question (e.g., 'What can the secondary agent do?'): \n", (answer) => {
      rl.close();
      resolve(answer);
    });
  });

  // Send request and stream the response
  const streamResponse= await openAIClient.responses.create(
    {
      input: userInput,
      stream: true,
    },
    {
      body: {
        agent: { name: agent.name, type: "agent_reference" },
        tool_choice: "required",
      },
    },
  );

  // Process the streaming response
  for await (const event of streamResponse) {
    if (event.type === "response.created") {
      console.log(`Follow-up response created with ID: ${event.response.id}`);
    } else if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    } else if (event.type === "response.output_text.done") {
      console.log("\n\nFollow-up response done!");
    } else if (event.type === "response.output_item.done") {
      const item = event.item as any;
      if (item.type === "remote_function_call") {
        // Add your handling logic for remote function call items here
        const callId = item.call_id;
        const label = item.label;
        console.log(`Call ID: ${callId ?? "None"}`);
        console.log(`Label: ${label ?? "None"}`);
      }
    } else if (event.type === "response.completed") {
      console.log("\nFollow-up completed!");
    }
  }

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

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Output previsto

La console visualizza il testo della risposta trasmesso mentre l'agente A2A elabora la richiesta. Vengono visualizzati l'ID di risposta di follow-up, i delta di testo stampati su stdout e i messaggi di completamento. La versione dell'agente viene eliminata al termine dell'interazione.

Usare la comunicazione da agente a agente in Java

Aggiornare questi valori nell'esempio:

• projectEndpoint - L'endpoint del progetto.
• model — Nome del modello distribuito.
• a2aConnectionId — ID della connessione A2A nel progetto Foundry.

Aggiungi la dipendenza a pom.xml:

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

Creare agenti con lo strumento di interazione tra agenti

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.A2APreviewTool;
import com.azure.ai.agents.models.AzureCreateResponseOptions;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

import java.util.Collections;

public class AgentToAgentExample {
    public static void main(String[] args) {
        String projectEndpoint = "https://<resource>.ai.azure.com/api/projects/<project>";
        String a2aConnectionId = "<a2a-connection-id>";

        AgentsClientBuilder builder = new AgentsClientBuilder()
            .credential(new DefaultAzureCredentialBuilder().build())
            .endpoint(projectEndpoint);

        AgentsClient agentsClient = builder.buildAgentsClient();
        ResponsesClient responsesClient = builder.buildResponsesClient();

        // Create agent-to-agent tool with connection ID
        A2APreviewTool a2aTool = new A2APreviewTool()
            .setProjectConnectionId(a2aConnectionId);

        // Create agent with agent-to-agent tool
        PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-4.1-mini")
            .setInstructions("You are a coordinator agent that can communicate with other agents.")
            .setTools(Collections.singletonList(a2aTool));

        AgentVersionDetails agent = agentsClient.createAgentVersion("a2a-agent", agentDefinition);
        System.out.printf("Agent created: %s (version %s)%n", agent.getName(), agent.getVersion());

        // Create a response
        AgentReference agentReference = new AgentReference(agent.getName())
            .setVersion(agent.getVersion());

        Response response = responsesClient.createAzureResponse(
            new AzureCreateResponseOptions().setAgentReference(agentReference),
            ResponseCreateParams.builder()
                .input("What can the secondary agent do?"));

        System.out.println("Response: " + response.output());

        // Clean up
        agentsClient.deleteAgentVersion(agent.getName(), agent.getVersion());
    }
}