Agent SDK (anteprima)

Inoltra i payload dell'attività di Bot Framework/Microsoft Agents SDK a un endpoint dell'agente fornito dall'utente. L'URL dell'endpoint agente viene fornito per ogni chiamata come parametro di input. L'autenticazione viene selezionata durante la creazione della connessione: nessuna autenticazione, chiave API statica o Microsoft Entra ID OAuth (client_credentials o accesso utente). Quando si seleziona OAuth, il gruppo di destinatari del token di connessione (URL risorsa configurato nella connessione) deve corrispondere al gruppo di destinatari previsto dall'agente di destinazione.

Questo connettore è disponibile nei prodotti e nelle aree seguenti:

Service	Class	Regions
Copilot Studio	Standard	Tutte le aree Power Automate ad eccezione delle seguenti: - Governo degli Stati Uniti (GCC) - Us Government (GCC High) - China Cloud gestito da 21Vianet - Dipartimento della Difesa degli Stati Uniti (DoD)
App per la logica	Standard	Tutte le aree di App per la logica , ad eccezione delle seguenti: - Aree di Azure per enti pubblici - Azure cina - Dipartimento della Difesa degli Stati Uniti (DoD)
Power Apps	Standard	Tutte le aree Power Apps ad eccezione delle seguenti: - Governo degli Stati Uniti (GCC) - Us Government (GCC High) - China Cloud gestito da 21Vianet - Dipartimento della Difesa degli Stati Uniti (DoD)
Power Automate	Standard	Tutte le aree Power Automate ad eccezione delle seguenti: - Governo degli Stati Uniti (GCC) - Us Government (GCC High) - China Cloud gestito da 21Vianet - Dipartimento della Difesa degli Stati Uniti (DoD)

Contatto
Nome	Microsoft
URL	https://support.microsoft.com

Metadati del connettore
Editore	Microsoft
Sito web	https://www.microsoft.com
Informativa sulla privacy	https://privacy.microsoft.com/
Categories	Produttività

Il connettore Agent SDK inoltra i payload dell'attività di Bot Framework/Microsoft Agents SDK a un endpoint agente fornito dall'utente. L'URL dell'endpoint agente viene fornito per ogni chiamata come parametro di input. La connessione seleziona il modo in cui il connettore esegue l'autenticazione all'agente: nessuna autenticazione, una chiave API statica, un token Microsoft Entra ID solo app (credenziali client) o un token utente delegato Microsoft Entra ID (accesso utente). Per entrambe le opzioni Microsoft Entra ID, il gruppo di destinatari del token di connessione (URL risorsa configurato nella connessione) deve corrispondere al gruppo di destinatari previsto dall'agente di destinazione.

Prerequisiti

Un agente sdk per agenti Microsoft distribuito/Bot Framework raggiungibile tramite HTTPS.
Per Microsoft Entra ID (credenziali client): un'applicazione Microsoft Entra ID registrata nel tenant che ospita l'agente, configurata con la client_credentials concessione e l'autorizzazione per chiamare l'agente di destinazione.
Per Microsoft Entra ID (accesso utente): l'applicazione Microsoft Entra ID dell'agente (ID app Microsoft) con un segreto client, un ambito API esposto a cui gli utenti possono fornire il consenso, il Microsoft Graph User.Read ("Accedere e leggere il profilo utente") delegata l'autorizzazione con il consenso e https://global.consent.azure-apim.net/redirect/agentsdk aggiunta come URI di reindirizzamento Web.
Per le opzioni chiave API e credenziali client, il gruppo di destinatari del token previsto dell'agente (in genere l'ID app Microsoft dell'agente, ad esempio api://<appId> o il GUID ID app). Per l'accesso utente, il gruppo di destinatari deve essere il GUID ID app (vedere di seguito).

Ottenere le credenziali

Microsoft Entra ID (credenziali client)

Il connettore invia un token solo app. Per autenticare le richieste API, è necessario:

ID tenant dell'applicazione Microsoft Entra ID.
ID client (ID applicazione) dell'applicazione Microsoft Entra ID.
Segreto client per l'applicazione.
URL risorsa corrispondente al gruppo di destinatari previsto dall'agente di destinazione (modello di autenticazione delle competenze di Bot Framework).

Specificare questi valori quando si crea una connessione. Creare una connessione per agente se i gruppi di destinatari sono diversi.

Il connettore invia il token delegato dell'account connesso alla connessione, in modo che l'agente possa scambiarlo per conto dell'account, ad esempio con il gestore Managed DisksConnectorUserAuthorization. Sarà necessario:

ID tenant dell'applicazione Microsoft Entra ID dell'agente.
ID client: l'ID app Microsoft dell'agente. Il Managed Disks scambia il token per conto dell'utente solo quando il token è stato rilasciato alla propria applicazione dell'agente.
Segreto client per l'applicazione.
URL risorsa: l'ID app (GUID) dell'agente Microsoft, lo stesso valore dell'ID client. Poiché l'applicazione dell'agente è sia il client che la risorsa, Microsoft Entra richiede il GUID qui (AADSTS90009 altrimenti); api://<appId> non è supportato per questa opzione.

Specificare questi valori quando si crea una connessione e quindi accedere e fornire il consenso per l'ambito esposto dell'agente. Creare una connessione per agente.

L'applicazione richiede anche l'autorizzazione delegata Microsoft Graph User.Read ("Accesso e lettura del profilo utente") con il consenso; senza di esso, l'accesso ha esito negativo con AADSTS90008.

Per scambiare il token per un'API downstream, configurare le autorizzazioni delegate dell'API per l'applicazione dell'agente e ottenere il consenso dell'utente o dell'amministratore richiesto. L'esposizione di un ambito nell'API dell'agente non concede autorizzazioni downstream.

Problemi noti e limitazioni

L'input agentEndpoint deve essere un URL HTTPS completo (ad esempio, https://my-agent.azurewebsites.net). Il connettore aggiunge /api/messages e inoltra il payload dell'attività.
Il connettore inoltra il payload attività as-is e non imposta deliveryMode. L'agente risponde in modo asincrono (recapito normale) tramite POSTing le attività di risposta all'oggetto fornito nell'attività serviceUrl in ingresso (il chiamante, ad esempio Microsoft Copilot Studio, fornisce un callback serviceUrlcon chiave DI firma di accesso condiviso).
Una connessione Microsoft Entra ID (accesso utente) invia sempre il token delegato dell'account connesso alla connessione, per ogni chiamata effettuata con tale connessione, incluse le chiamate per conto di altre persone che chiacchierano con l'agente. Non invia un token separato per ogni chiamante, quindi l'utente dell'attività from può differire dall'utente nel token. Autorizzare le richieste solo come account nel token convalidato e non considerare le intestazioni dell'attività from o della richiesta come autorità della persona di chat. Se l'agente deve fungere da ogni persona che chatta con esso, non usare questo tipo di connessione.
Se il consenso dell'account connesso viene revocato o la relativa sessione non può più essere aggiornata, accedere di nuovo alla connessione.
Questo connettore è in anteprima. Disponibilità e funzionalità sono soggette a modifiche.

Creazione di una connessione

Il connettore supporta i tipi di autenticazione seguenti:


Chiave API	Eseguire l'autenticazione con una chiave API statica prevista dall'agente di destinazione in un'intestazione HTTP personalizzata. Specificare sia il nome dell'intestazione ,ad esempio x-api-key, sia il relativo valore.	Tutte le aree geografiche	Non condivisibile
Microsoft Entra ID (credenziali client)	Token di connessione OAuth mint da un'applicazione Microsoft Entra ID usando il flusso di client_credentials. Il gruppo di destinatari del token di connessione (URL risorsa) deve corrispondere al gruppo di destinatari previsto dall'agente di destinazione.	Tutte le aree geografiche	Non condivisibile
Microsoft Entra ID (accesso utente)	Accedere tramite l'applicazione Microsoft Entra ID dell'agente di destinazione (flusso del codice di autorizzazione) e inviare il token di connessione delegato dell'account connesso. Ogni chiamata effettuata con questa connessione usa l'account connesso alla connessione, non la persona che chatta con l'agente. Per scambiare il token per conto dell'utente, l'agente deve disporre delle autorizzazioni delegate downstream e del consenso configurate.	Tutte le aree geografiche	Non condivisibile
Nessuna autenticazione	Chiamare l'endpoint dell'agente di destinazione senza alcuna intestazione di autenticazione. Usare questa opzione solo con gli agenti che accettano in modo esplicito chiamate anonime.	Tutte le aree geografiche	Condivisibile
Impostazione predefinita [DEPRECATO]	Questa opzione è solo per le connessioni meno recenti senza un tipo di autenticazione esplicito e viene fornita solo per la compatibilità con le versioni precedenti.	Tutte le aree geografiche	Non condivisibile

API key

ID di autenticazione: apiKey

Applicabile: tutte le aree

Eseguire l'autenticazione con una chiave API statica prevista dall'agente di destinazione in un'intestazione HTTP personalizzata. Specificare sia il nome dell'intestazione ,ad esempio x-api-key, sia il relativo valore.

Questa connessione non è condivisibile. Se l'app power viene condivisa con un altro utente, verrà richiesto a un altro utente di creare una nuova connessione in modo esplicito.

Nome	Tipo	Descrzione	Obbligatorio
Nome dell'intestazione della chiave API	string	Nome dell'intestazione HTTP in cui l'agente di destinazione prevede la chiave API (ad esempio, x-api-key o Ocp-Apim-Subscription-Key).	True
Valore della chiave API	Securestring	Valore della chiave API statica inviato a ogni richiesta all'endpoint dell'agente di destinazione.	True

Microsoft Entra ID (credenziali client)

ID autenticazione: oauthClientCredentials

Applicabile: tutte le aree

Token di connessione OAuth mint da un'applicazione Microsoft Entra ID usando il flusso di client_credentials. Il gruppo di destinatari del token di connessione (URL risorsa) deve corrispondere al gruppo di destinatari previsto dall'agente di destinazione.

Questa connessione non è condivisibile. Se l'app power viene condivisa con un altro utente, verrà richiesto a un altro utente di creare una nuova connessione in modo esplicito.

Nome	Tipo	Descrzione	Obbligatorio
Tenant	string	ID tenant di per l'applicazione Microsoft Entra ID	True
ID del cliente	string	ID client (o applicazione) dell'applicazione Microsoft Entra ID.	True
Segreto del cliente	Securestring	Segreto client dell'applicazione Microsoft Entra ID.	True
URL della risorsa	string	Destinatari per il token OAuth. In genere, l'ID app Microsoft dell'agente di destinazione, ad esempio api://< appId> o il GUID ID app.	True

ID autenticazione: oauthAuthorizationCode

Applicabile: tutte le aree

Accedere tramite l'applicazione Microsoft Entra ID dell'agente di destinazione (flusso del codice di autorizzazione) e inviare il token di connessione delegato dell'account connesso. Ogni chiamata effettuata con questa connessione usa l'account connesso alla connessione, non la persona che chatta con l'agente. Per scambiare il token per conto dell'utente, l'agente deve disporre delle autorizzazioni delegate downstream e del consenso configurate.

Questa connessione non è condivisibile. Se l'app power viene condivisa con un altro utente, verrà richiesto a un altro utente di creare una nuova connessione in modo esplicito.

Nome	Tipo	Descrzione	Obbligatorio
Tenant	string	ID tenant dell'applicazione Microsoft Entra ID dell'agente di destinazione.	True
ID del cliente	string	ID app Microsoft dell'agente di destinazione. Usare l'applicazione dell'agente in modo che l'agente possa scambiare il token delegato per conto dell'utente.	True
Segreto del cliente	Securestring	Segreto client dell'applicazione Microsoft Entra ID dell'agente di destinazione.	True
URL della risorsa	string	Destinatari per il token delegato. Deve essere l'ID app Microsoft (GUID) dell'agente di destinazione, lo stesso valore dell'ID client: Microsoft Entra accetta solo il GUID quando un'applicazione richiede un token per se stesso.	True

Nessuna autenticazione

ID autenticazione: anonimo

Applicabile: tutte le aree

Chiamare l'endpoint dell'agente di destinazione senza alcuna intestazione di autenticazione. Usare questa opzione solo con gli agenti che accettano in modo esplicito chiamate anonime.

Si tratta di una connessione condivisibile. Se l'app per l'alimentazione viene condivisa con un altro utente, anche la connessione viene condivisa. Per altre informazioni, vedere Panoramica dei connettori per le app canvas - Power Apps | Microsoft Docs

Impostazione predefinita [DEPRECATO]

Applicabile: tutte le aree

Questa opzione è solo per le connessioni meno recenti senza un tipo di autenticazione esplicito e viene fornita solo per la compatibilità con le versioni precedenti.

Questa connessione non è condivisibile. Se l'app power viene condivisa con un altro utente, verrà richiesto a un altro utente di creare una nuova connessione in modo esplicito.

Azioni

Inviare attività all'agente

Inoltra un payload del protocollo attività all'endpoint dell'agente in {agentEndpoint}/api/messages. Quando la connessione usa Microsoft Entra ID OAuth, il gruppo di destinatari del token (URL risorsa nella connessione) deve essere uguale al gruppo di destinatari previsto dall'agente di destinazione (modello di autenticazione della competenza di Bot Framework); creare una connessione per ogni agente se i destinatari differiscono. Il connettore inoltra il payload attività as-is e non imposta 'deliveryMode'; l'agente risponde in modo asincrono (recapito normale) tramite POSTing attività di risposta all'oggetto 'serviceUrl' fornito nell'attività in ingresso.

Inviare attività all'agente

ID operazione:: SendActivity

Parametri

Nome	Chiave	Necessario	Tipo	Descrizione
URL endpoint agente	agentEndpoint	True	string	URL di base del Microsoft Agents SDK /Bot Framework endpoint (ad esempio, https://my-agent.azurewebsites.net). Il connettore aggiunge /api/messages.
			object

Agent SDK (anteprima)

Prerequisiti

Ottenere le credenziali

Microsoft Entra ID (credenziali client)

Microsoft Entra ID (accesso utente)

Problemi noti e limitazioni

Creazione di una connessione

API key

Microsoft Entra ID (credenziali client)

Microsoft Entra ID (accesso utente)

Nessuna autenticazione

Impostazione predefinita [DEPRECATO]

Azioni

Inviare attività all'agente

Parametri

Valori restituiti

Definizioni

object