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. In caso contrario, indirizza il traffico su 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 la creazione, gestione e richiamo di agenti
• Familiarità con Azure controllo 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 minima nel comando, produce una nuova versione.

Agent: rappresentazione stabile e rivolta al consumer di un agente. L'identità, l'endpoint e la superficie 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: l'URL che i client chiamano per invocare 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. Configuri quale versione serve, quali protocolli utilizza e come i chiamanti si autenticano.

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

Routing del traffico

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

• Usa sempre la versione più recente (predefinita): il 100% del traffico viene instradato alla versione dell'agente più recentemente creata. 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 a una versione specifica: 100% delle rotte di traffico si dirige verso la versione dell'agente che selezioni, denominata versione dell'agente attiva. Le nuove versioni non cambiano ciò che viene servito fino a quando non si aggiorna il selettore.

Fissare a una versione specifica quando è necessaria la stabilità tra versioni nuove, 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:

Schemi di autorizzazione

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

L'autenticazione con chiave API non è supportata. Usare Microsoft Entra ID (Azure RBAC - controllo degli accessi in base al ruolo) 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 a una versione specifica, aggiornare il version_selector.

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

{
  "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
Foundry-Features: AgentEndpoints=V1Preview

{
  "agent_endpoint": {
    "protocols": ["activity", "responses", "invocations"],
    "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,
        ],
        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à ai consumatori, inclusa l'individuazione da agente a agente (A2A).

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

{
  "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à dell'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
Foundry-Features: AgentEndpoints=V1Preview

Considerazioni sulla sicurezza e sulla privacy

• Usare 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 Agent

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