Configurare e condividere l'agente

Ogni agente in Microsoft Foundry ha un endpoint stabile dal momento in cui viene creato. Dietro ogni endpoint, un modello Foundry elabora l'input dell'utente in base alle istruzioni e agli strumenti dell'agente. Quando gli utenti finali interagiscono con l'agente tramite Microsoft 365 Copilot, Teams, l'applicazione esistente o altre superfici, interagiscono con l'endpoint stabile dell'agente. Prima di condividere l'agente, verificare queste impostazioni:

• Versione agente attivo : verificare che la versione che riceve il traffico sia quella con cui gli utenti finali interagiscono. Per impostazione predefinita, l'agente viene aggiornato automaticamente alla versione più recente, il che significa che viene immediatamente servita una versione appena creata. Se non è quello che vuoi, vincola il traffico a una versione specifica.
• Protocolli e schemi di autorizzazione : assicurarsi che corrispondano alla posizione e al modo in cui gli utenti interagiscono con l'agente. Ad esempio, un agente pubblicato in Microsoft 365 o Teams deve avere il protocollo Activity abilitato e usare uno schema di autorizzazione BotService o BotServiceRbac.

Questo articolo illustra come selezionare la versione attiva, abilitare i protocolli, impostare gli schemi di autorizzazione e aggiungere una scheda agente. Dopo aver configurato l'endpoint, è possibile:

• Pubblicare gli agenti per Microsoft 365 Copilot e Microsoft Teams
• Pubblicare un agente come lavoratore digitale in Agent 365

Prerequisiti

• Progetto Foundry con almeno una versione dell'agente creata
• Ruolo utente Azure AI nell'ambito del progetto Foundry per creare, gestire e attivare gli agenti
• Familiarità con Azure controllo degli accessi basato sui ruoli (RBAC) per configurare le autorizzazioni
• Familiarità con i concetti relativi all'identità dell'agente in Foundry
• Installare i runtime del linguaggio necessari, gli strumenti globali e le estensioni Visual Studio Code come descritto in Prepare l'ambiente di sviluppo

Comprendere il modello a oggetti dell'agente

Prima di configurare l'endpoint, comprendere in che modo i progetti, gli agenti, le versioni degli agenti e l'endpoint stabile sono correlati tra loro.

Progetto Foundry: cartella che raggruppa risorse correlate, ad esempio agenti, file e strumenti.

Versione dell'agente: snapshot non modificabile della configurazione dell'agente. Qualsiasi modifica, anche una singola modifica della richiesta, produce una nuova versione.

Agent: rappresentazione stabile e rivolta al consumer di un agente. L'identità, l'endpoint e l'ambito di autorizzazione dell'agente rimangono coerenti man mano che le versioni sottostanti si evolvono, quindi i consumatori interagiscono sempre con la stessa entità.

Endpoint agente: gli utenti chiamano l'URL per richiamare l'agente. È attivo il momento in cui si crea l'agente, senza un passaggio di pubblicazione separato e l'URL non cambia man mano che si esegue l'implementazione di nuove versioni. Si configura quale versione è utilizzata, quali protocolli sono supportati, e come gli utenti eseguono l'autenticazione.

Per l'elenco completo delle proprietà dell'oggetto agente, vedere la sezione di riferimento alla fine di questo articolo.

Instradamento del traffico

version_selector determina il modo in cui il traffico viene instradato alle versioni dell'agente. Sono disponibili due criteri di routing:

• Usare sempre la versione più recente (predefinita): il 100% del traffico viene instradato alla versione dell'agente creata più di recente. Quando l'agente viene pubblicato in Teams o Microsoft 365, la creazione di una nuova versione aggiorna automaticamente ciò che viene fornito in tali canali.
• Bloccato su una versione specifica: 100% del traffico viene instradato alla versione dell'agente selezionata, chiamata versione attiva dell'agente. Le nuove versioni non cambiano ciò che viene servito fino a quando non si aggiorna il selettore.

Fissare a una versione specifica quando hai bisogno di stabilità tra le nuove versioni, ad esempio quando un agente è in produzione o pubblicato per gli utenti finali in Teams o Microsoft 365.

Protocolli

Un agente può esporre più protocolli contemporaneamente:

Per abilitare il protocollo A2A nell'agente, vedere Abilitare A2A in ingresso in un agente Foundry.

Schemi di autorizzazione

È possibile configurare l'autenticazione in ingresso nell'endpoint dell'agente:

L'autenticazione con chiave API non è supportata. Usare Azure Active Directory (Azure RBAC) per autorizzare i chiamanti.

Configurare le proprietà dell'agente

Per impostazione predefinita, il selettore di versione instrada 100% del traffico alla versione più recente dell'agente, il protocollo Responses è abilitato e l'autorizzazione è impostata su Entra. È possibile modificare il routing della versione, abilitare altri protocolli, impostare schemi di autorizzazione e aggiungere una scheda agente.

Selezionare la versione dell'agente attivo

Per impostazione predefinita, i criteri di routing sono sempre usati più recenti. Per fissare il traffico su una versione specifica, aggiornare il version_selector.

PATCH {{endpoint}}/agents/{{agent_name}}?api-version=v1
Authorization: Bearer {{token}}
Content-Type: application/merge-patch+json

{
  "agent_endpoint": {
    "version_selector": {
      "version_selection_rules": [
        {
          "type": "FixedRatio",
          "agent_version": "2",
          "traffic_percentage": 100
        }
      ]
    }
  }
}

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentEndpoint,
    AgentEndpointProtocol,
    FixedRatioVersionSelectionRule,
    VersionSelector,
)
from azure.identity import DefaultAzureCredential

PROJECT_ENDPOINT = "https://{account}.services.ai.azure.com/api/projects/{project}"

agent_name = "name-of-your-existing-agent"

project_client = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
    allow_preview=True,
)

with project_client:
    endpoint_config = AgentEndpoint(
        version_selector=VersionSelector(
            version_selection_rules=[
                FixedRatioVersionSelectionRule(agent_version="2", traffic_percentage=100),
            ]
        ),
    )

    patched_agent = project_client.beta.agents.patch_agent_details(
        agent_name=agent_name,
        agent_endpoint=endpoint_config,
    )
    print(f"Agent endpoint configured for agent: {patched_agent.name}")

Abilitare protocolli e schemi di autorizzazione

Un agente può esporre più protocolli contemporaneamente. Configurare i protocolli e l'autorizzazione in ingresso nell'endpoint dell'agente.

PATCH {{endpoint}}/agents/{{agent_name}}?api-version=v1
Authorization: Bearer {{token}}
Content-Type: application/merge-patch+json

{
  "agent_endpoint": {
    "protocols": ["activity", "responses", "invocations", "a2a"],
    "authorization_schemes": [
      {
        "type": "Entra",
        "isolation_key_source": {
          "kind": "Entra"
        }
      },
      {
        "type": "BotServiceRbac"
      }
    ]
  }
}

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentEndpoint,
    AgentEndpointProtocol,
    EntraAuthorizationScheme,
    BotServiceRbacAuthorizationScheme,
    EntraIsolationKeySource,
)
from azure.identity import DefaultAzureCredential

PROJECT_ENDPOINT = "https://{account}.services.ai.azure.com/api/projects/{project}"

agent_name = "name-of-your-existing-agent"

project_client = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
    allow_preview=True,
)

with project_client:
    endpoint_config = AgentEndpoint(
        protocols=[
            AgentEndpointProtocol.RESPONSES,
            AgentEndpointProtocol.ACTIVITY,
            AgentEndpointProtocol.INVOCATIONS,
            AgentEndpointProtocol.A2A,
        ],
        authorization_schemes=[
            EntraAuthorizationScheme(
                isolation_key_source=EntraIsolationKeySource(),
            ),
            BotServiceRbacAuthorizationScheme(),
        ],
    )

    patched_agent = project_client.beta.agents.patch_agent_details(
        agent_name=agent_name,
        agent_endpoint=endpoint_config,
    )
    print(f"Protocols and authorization updated for agent: {patched_agent.name}")

Aggiungere una scheda agente

Una scheda agente presenta dettagli e funzionalità per i consumatori, inclusa l'individuazione tra agenti (A2A).

PATCH {{endpoint}}/agents/{{agent_name}}?api-version=v1
Authorization: Bearer {{token}}
Content-Type: application/merge-patch+json

{
  "agent_card": {
    "version": "1.0.0",
    "description": "A competitive intelligence analyst that monitors market trends and competitor activity.",
    "skills": [
      {
        "id": "competitor-analysis",
        "name": "Competitor Analysis",
        "description": "Analyzes competitor products, pricing strategies, and market positioning across specified industry verticals.",
        "tags": ["research", "analysis", "market-intel"],
        "examples": [
          "Compare our Q3 pricing against Contoso's latest catalog",
          "Summarize recent product launches from our top 5 competitors",
          "Identify gaps in competitor coverage for the EMEA region"
        ]
      },
      {
        "id": "trend-monitoring",
        "name": "Trend Monitoring",
        "description": "Tracks emerging market trends and surfaces early signals from earnings calls, filings, and news.",
        "tags": ["trends", "monitoring"],
        "examples": [
          "What themes are emerging from this quarter's earnings calls?",
          "Flag any regulatory changes affecting our sector in the last 30 days"
        ]
      }
    ]
  }
}

# Agent card update via SDK is not yet supported. Use the REST API.

Ottieni le proprietà del tuo agente

Per visualizzare le proprietà correnti dell'agente, ovvero identità, protocolli, autorizzazione ed endpoint, eseguire:

GET {endpoint}/agents/{agent_name}?api-version=v1
Authorization: Bearer {{token}}
Content-Type: application/json

Considerazioni sulla sicurezza e sulla privacy

• Utilizzare i privilegi minimi. Concedere agli utenti il ruolo minimo necessario. Ad esempio, creare ruoli personalizzati che separano le autorizzazioni di creazione dell'agente dalle autorizzazioni di chiamata dell'agente.
• Non incorporare token di accesso nel codice sorgente, negli script o nelle applicazioni client. Usare il flusso di autenticazione Microsoft Entra appropriato per l'app.

Limitazioni

Risoluzione dei problemi

Riferimento: Proprietà dell'oggetto Agente

Contenuto correlato

• Informazioni sui concetti relativi all'identità dell'agente in Foundry
• Informazioni sugli agenti ospitati
• Pubblicare gli agenti per Microsoft 365 Copilot e Microsoft Teams
• Eseguire la migrazione da Applicazioni agente al nuovo modello di agente