Abilitare l'ingresso A2A su un agente Foundry (anteprima)

Importante

Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate. Per altre informazioni, vedere Condizioni aggiuntive di utilizzo per le anteprime di Microsoft Azure.

È possibile esporre l'agente del servizio agente Foundry come endpoint Agent2Agent (A2A) in modo che altri agenti possano individuarlo e chiamarlo tramite il protocollo A2A. Quando A2A in ingresso è abilitato, Foundry pubblica una scheda agente per l'agente e accetta le richieste A2A in ingresso da chiamanti esterni.

Nota

Il servizio agente Foundry supporta solo la versione 0.3 del protocollo A2A.

Tipi di agente supportati

L'A2A in ingresso richiede il protocollo di risposta. I tipi di agente seguenti lo supportano:

  • Agenti prompt : supportano il protocollo delle risposte per impostazione predefinita. Tutti gli agenti prompt possono essere esposti come endpoint A2A.
  • Agenti ospitati — supportano A2A in ingresso solo se l'agente ospitato viene configurato per gestire il protocollo di risposta. Se l'agente ospitato non implementa il protocollo di risposte, non è possibile abilitare A2A in ingresso.

Suggerimento

Questo articolo illustra come esporre il tuo agente come un endpoint A2A che altri agenti possono chiamare. Se vuoi che l'agente chiami un endpoint A2A remoto, vedi Connettersi a un endpoint A2A dell'agente dal Servizio Agente di Foundry.

Prerequisiti

  • Sottoscrizione Azure con un progetto Foundry attivo.
  • Un agente distribuito nel Servizio Agente Foundry che utilizza il protocollo delle risposte (agente di prompt o un agente ospitato progettato per supportarlo).
  • Ruolo necessario Azure: Utente Azure AI o superiore nel progetto Foundry.

Abilitare A2A in ingresso

L'abilitazione di A2A in ingresso richiede due elementi: una scheda agente che descrive le funzionalità dell'agente e il protocollo A2A abilitato nell'endpoint dell'agente. È possibile impostare entrambi in una singola chiamata PATCH. Questa funzionalità non è ancora disponibile nel portale foundry. Usare l'API REST o Python SDK.

L'abilitazione di A2A in ingresso non è ancora configurabile nel portale di Foundry. Usare l'API REST o Python SDK.

Verificare la scheda agente

Dopo aver abilitato A2A in ingresso, l'agente espone due URL che gli agenti chiamanti utilizzano.

  • Percorso di base A2A : l'URL radice per le interazioni con il protocollo A2A con l'agente:

    https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/a2a

  • URL scheda agente — L'endpoint di individuazione in cui gli agenti recuperano le funzionalità, le competenze e i metadati dell'agente:

    https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/a2a/agentCard/v0.3

Importante

Entrambi gli URL richiedono l'autenticazione Microsoft Entra ID. L'accesso anonimo alla scheda agente non è supportato. L'agente chiamante deve presentare un token valido con il ruolo di Azure AI User nel progetto Foundry.

Per verificare che la scheda agente sia configurata correttamente, recuperarla direttamente:

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

La risposta contiene la scheda agente con la descrizione e le competenze configurate. Verificare che i campi corrispondano alle funzionalità desiderate.

Configurare l'autenticazione per le richieste in ingresso

Le richieste A2A in ingresso richiedono l'autenticazione Microsoft Entra ID. L'accesso basato su chiavi e non autenticato non è supportato. L'agente chiamante deve fornire un token Microsoft Entra valido e l'identità associata a tale token deve avere il ruolo Utente Azure AI (o superiore) nel progetto Foundry che ospita l'agente.

Sono supportati due modelli di autenticazione:

On-behalf-of (OBO) l'utente finale

L'agente chiamante trasferisce l'identità dell'utente finale. L'agente riceve un token che rappresenta l'utente effettivo, in modo da poter definire l'ambito delle azioni per le autorizzazioni dell'utente. Questo modello è appropriato quando l'agente deve applicare il controllo di accesso per utente.

Identità del servizio (identità agente, entità servizio o identità gestita)

L'agente chiamante esegue l'autenticazione con la propria identità, ovvero l'identità dell'agente assegnata dalla piattaforma, un'entità servizio o un'identità gestita. L'agente vede l'identità del servizio chiamante, non un singolo utente. Questo modello è appropriato per i flussi di lavoro da agente back-end a agente in cui il contesto utente singolo non è obbligatorio.

Per concedere l'accesso a un'identità di chiamata, assegnare il ruolo Utente Azure AI nel progetto Foundry che ospita l'agente. Per altre informazioni sulle assegnazioni di ruolo, vedere Controllo degli accessi in base al ruolo nel portale foundry.

Trasporti A2A supportati

Foundry Agent Service supporta i trasferimenti A2A seguenti per le richieste in entrata:

Trasporto Supportato
HTTP+JSON ✔️
JSONRPC ✔️
gRPC ❌

Connettersi a un agente Foundry A2A con Python A2A SDK

L'esempio seguente illustra come usare l'Python A2A SDK per connettersi a un agente Foundry con A2A in ingresso abilitato. L'SDK usa automaticamente la modalità di compatibilità 0.3 in base alla versione del protocollo nella scheda agente.

Poiché la scheda dell'agente Foundry richiede l'autenticazione e usa un percorso personalizzato (agentCard/v0.3 anziché il percorso predefinito .well-known/agent-card.json), si configura il client httpx con un token bearer e si passa il percorso della scheda agente personalizzata al resolver.

Installare i pacchetti necessari:

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/v0.3"


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

Sostituire {account}, {project}e {agent} con il nome della risorsa Foundry, il nome del progetto e il nome dell'agente. Il resolver costruisce l'URL della scheda dell'agente completo aggiungendo il relativo AGENT_CARD_PATH a A2A_BASE_URL.

Connettersi attraverso un altro agente Foundry

È possibile chiamare un agente Foundry A2A da un altro agente Foundry usando lo strumento A2A. Questa sezione illustra la configurazione completa: creare una connessione all'agente di destinazione, quindi creare un agente chiamante che usa tale connessione.

Passaggio 1: Creare una connessione A2A all'agente di destinazione

La connessione archivia l'URL dell'endpoint A2A dell'agente di destinazione, i dettagli di autenticazione e il percorso della scheda dell'agente personalizzato. Gli agenti foundry servono la loro scheda agente in agentCard/v0.3 (anziché l'impostazione predefinita .well-known/agent-card.json), quindi è necessario impostare i metadati di connessione in AgentCardPath.

Nota

L'impostazione di un percorso di scheda agente personalizzato non è supportata nel portale di Foundry. Usare l'API REST per creare la connessione.

Configurare le variabili:

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)

Creare la connessione:

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": "AgenticIdentity",
      "category": "RemoteA2A",
      "target": "'"$TARGET_A2A_URL"'",
      "audience": "https://ai.azure.com",
      "Credentials": {},
      "metadata": {
        "AgentCardPath": "/agentCard/v0.3"
      }
    }
  }'

Per altre opzioni di autenticazione (basata su chiave, OAuth, identità gestita), vedere Creare una connessione A2A usando l'API REST.

Passaggio 2: Creare l'agente chiamante con lo strumento A2A

Una volta stabilita la connessione, creare un agente che utilizza A2APreviewTool per chiamare l'agente di destinazione.

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

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 = 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. 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
)

Per altri esempi di linguaggio (C#, JavaScript, Java, REST), vedere Connect to an A2A agent endpoint from Foundry Agent Service.

Limitazioni

  • È supportato solo il protocollo A2A versione 0.3.
  • È supportata solo la modalità di testo . Non sono supportati i dati dei file e altri formati non testuali.
  • L'A2A in ingresso richiede il protocollo di risposta. Gli agenti che non usano il protocollo di risposte non possono essere esposti come endpoint A2A.
  • Questa funzionalità è in anteprima e non è consigliata per i carichi di lavoro di produzione.

Contenuto correlato

  • Last updated on