Aggiungi un agente Foundry come agente connesso (GitHub Copilot)

Usa gli agenti connessi per permettere al tuo agente primario di delegare attività specifiche ad agenti specializzati. Questo articolo ti mostra come collegare un agente Microsoft Foundry esistente affinché il tuo agente principale possa delegare le attività a tale agente.

Annotazioni

Il framework utilizzato per costruire questo agente utilizza una fatturazione basata sull'uso. Utilizzare, costruire, testare e valutare agenti potrebbe consumare Copilot Credits. Scopri di più in Panoramica della fatturazione basata sull'uso.

Aggiungi ogni agente connesso dalla stessa finestra di dialogo Aggiungi un agente connesso . Per una panoramica degli agenti connessi e di come funziona il routing, vedi Panoramica degli agenti connessi. Per collegare un altro agente Copilot Studio, vedi Aggiungi un agente Copilot Studio come agente connesso. Per collegare un agente remoto tramite il protocollo Agent2Agent (A2A), vedi Aggiungi un agente A2A come agente connesso. Per collegare un agente creato con Managed Disks, vedi Aggiungi un agente Managed Disks come agente connesso.

Prerequisites

  • Un agente creato con il harness GitHub Copilot per essere l'agente principale. Vedi Creare un agente (anteprima).
  • Un agente Foundry esistente creato in un progetto nel portale Microsoft Foundry, con il Activity protocol abilitato e l'Agent ID dell'agente disponibile. Gli agenti Foundry non hanno il protocollo Activity abilitato di default. Consulta Abilitare il protocollo Attività sul tuo agente Foundry.
  • L'URL dell'endpoint di Azure AI Project per il progetto che ospita l'agente Foundry.
  • Permesso di accedere al progetto Foundry. La connessione si autentica con il login utente del tuo Microsoft Entra ID.

Annotazioni

Puoi connetterti solo agli agenti creati nell'attuale portale Microsoft Foundry. Collegarsi a un agente creato nel portale precedente restituisce un 404 - Version not found errore.

Aggiungi un agente Foundry

  1. Accedere a Copilot Studio.

  2. Scegli e apri l'agente che vuoi usare come agente primario.

  3. Nella barra di navigazione agente, seleziona la scheda Build .

  4. Nel pannello dei componenti, seleziona Agenti connessi per aprire la finestra di dialogo Aggiungi un agente connesso.

  5. Nel dialogo, seleziona Aggiungi, poi seleziona Aggiungi agente Foundry.

  6. Nel passaggio Connetti ad Azure AI Foundry, scegli la connessione che questo agente utilizza per raggiungere Microsoft Foundry:

    • Seleziona una connessione esistente dalla lista Connessione.
    • Se non è disponibile alcuna connessione, seleziona Crea nuova connessione e continua con il passaggio successivo.

  7. Se stai creando una nuova connessione, inserisci i dettagli della connessione e poi seleziona Crea:

    • Nome visualizzato (opzionale): un nome che ti aiuta a identificare questa connessione in seguito.
    • Tipo di autenticazione: Accesso utente Microsoft Entra ID. Questo valore è impostato per te.
    • Azure AI Project Endpoint: l'URL dell'endpoint del project Foundry che ospita l'agente.

  8. Tornando al passaggio Connect to Azure AI Foundry, conferma che la connessione è selezionata, poi seleziona Next.

  9. Nel passaggio Revisione e aggiungi, inserisci i dati dell'agente Foundry che vuoi collegare, poi seleziona Aggiungi all'agente:

    • Nome: il nome mostrato all'agente autore.
    • Descrizione: una chiara indicazione di quando questo agente Foundry dovrebbe essere utilizzato. L'orchestratore usa questa descrizione per decidere quando instradare una richiesta all'agente, quindi rendila specifica ed evita sovrapposizioni con gli altri strumenti e agenti. Per altre informazioni, vedi scrittura di metadati efficaci.
    • ID agente: l'ID dell'agente Foundry a cui vuoi connetterti.

  10. Conferma che l'agente connesso appare sotto Agenti connessi nel pannello componenti.

Annotazioni

Sei responsabile di rivedere e testare attentamente gli agenti connessi nel contesto dei tuoi casi d'uso specifici, e di prendere tutte le decisioni e personalizzazioni appropriate. Quando ti connetti ad agenti esterni a Copilot Studio, sei responsabile dell'utilizzo di tali agenti. Le considerazioni includono garantire:

  • I flussi di dati, la gestione dei dati e la condivisione dei dati tra agenti sono appropriati per il tuo caso d'uso e rispettano i requisiti e le leggi pertinenti.
  • Gli agenti soddisfano adeguati standard di qualità, affidabilità, sicurezza e fidatezza.
  • Sono previsti permessi, limiti e approvazioni appropriati, se opportuno per il tuo caso d'uso.
  • Sono presenti adeguate funzionalità di osservabilità, identità e tracciabilità, nonché funzioni di supervisione umana.

Abilita il protocollo Activity sul tuo agente Foundry

Copilot Studio comunica con un agente Foundry connesso utilizzando il protocollo Activity. Gli agenti Foundry non hanno questo protocollo attivato di default, quindi devi attivarlo prima che il tuo agente principale possa scambiare messaggi con l'agente Foundry. Se il protocollo Activity non è abilitato, puoi comunque aggiungere la connessione, ma la chiamata all'agente Foundry non riesce.

Puoi abilitare il protocollo Activity in uno dei seguenti modi:

  • Pubblica l'agente Foundry su Microsoft 365 o Microsoft Teams. Quando pubblichi un prompt agent su Microsoft 365 o Teams, il protocollo Activity e lo schema di autorizzazione richiesto BotServiceRbac vengono attivati automaticamente. Scegli questa opzione se già hai intenzione di pubblicare l'agente su quei canali.

  • Abilitalo manualmente con una chiamata API REST. Se non pubblichi l'agente su Microsoft 365 o Teams, chiama l'API REST Foundry Agents - Update agent per aggiungere il activity protocollo e lo BotServiceRbac schema di autorizzazione all'agente.

Per maggiori informazioni su come configurare e condividere il tuo agente Foundry, consulta Configura e condividi il tuo agente Microsoft Foundry.

Abilita il protocollo Activity con una chiamata API REST

Invoca gli agenti Foundry - Aggiorna l'API REST dell'agente. Sostituisci {{endpoint}}, {{agent_name}}, e {{token}} con l'endpoint, il nome dell'agente e il token di accesso per il tuo progetto Foundry.

Importante

Tieni responses e Entra nelle liste. Rimuoverli impedisce di chattare con l'agente dal portale Foundry o dall'SDK.

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

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

Come l'orchestratore instrada verso l'agente Foundry

Dopo aver aggiunto l'agente Foundry, il runtime di orchestrazione determina automaticamente quando delegare a esso. La decisione di instradamento si basa su:

  • Il nome e la descrizione dell'agente connesso
  • Il messaggio dell'utente e il contesto della conversazione
  • Le istruzioni dell'agente primario

Tip

Scrivi una descrizione chiara e specifica per l'agente Foundry così che l'orchestratore possa determinare con precisione quando instradare le richieste ad esso. Evita descrizioni sovrapposte tra agenti connessi.

Delega di test

Dopo aver aggiunto l'agente Foundry:

  1. Nella barra di spostamento dell'agente seleziona la scheda Anteprima.

  2. Invia un messaggio che corrisponda al dominio dell'agente Foundry.

  3. Verifica che la risposta provenga dall'agente Foundry e sia appropriata.

  4. Invia un messaggio al di fuori del dominio dell'agente Foundry per confermare che il tuo agente principale lo gestisce.

Se devi cambiare l'ID agente o la descrizione in seguito, modifica l'agente connesso dal pannello componenti. Vedi "Gestire gli agenti connessi in un agente".

  • Ultimo aggiornamento: