Agent-SDK (förhandsversion)

Vidarebefordrar Bot Framework/Microsoft Agents SDK-aktivitetsnyttolaster till en agentslutpunkt som tillhandahålls av användaren. Agentens slutpunkts-URL anges per anrop som en indataparameter. Autentisering väljs när anslutningen skapas: ingen autentisering, en statisk API-nyckel eller Microsoft Entra ID OAuth (client_credentials eller användarinloggning). När OAuth har valts måste målgruppen för ägartoken (resurs-URL som konfigurerats för anslutningen) matcha målgruppen som förväntas av målagenten.

Den här anslutningsappen är tillgänglig i följande produkter och regioner:

Agent-SDK-anslutningsappen vidarebefordrar Bot Framework/Microsoft Agents SDK-aktivitetsnyttolaster till en agentslutpunkt som tillhandahålls av användaren. Agentens slutpunkts-URL anges per anrop som en indataparameter. Anslutningen väljer hur anslutningsappen autentiserar till agenten: ingen autentisering, en statisk API-nyckel, en Microsoft Entra ID endast apptoken (klientautentiseringsuppgifter) eller en Microsoft Entra ID delegerad användartoken (användarinloggning). För båda Microsoft Entra ID alternativen måste målgruppen för ägartoken (resurs-URL som konfigurerats för anslutningen) matcha målgruppen som förväntas av målagenten.

Förutsättningar

• En distribuerad Microsoft Agents SDK/Bot Framework-agent som kan nås via HTTPS.
• För Microsoft Entra ID (klientautentiseringsuppgifter): ett Microsoft Entra ID program som är registrerat i klientorganisationen som är värd för agenten, konfigurerat med client_credentials beviljandet och behörigheten att anropa målagenten.
• För Microsoft Entra ID (användarinloggning): agentens egna Microsoft Entra ID-program (dess Microsoft app-ID) med en klienthemlighet, ett exponerat API-omfång som användarna kan samtycka till, Microsoft Graph User.Read ("Logga in och läs användarprofil") delegerade behörighet med medgivande och https://global.consent.azure-apim.net/redirect/agentsdk lades till som en webbomdirigerings-URI.
• För alternativen API-nyckel och klientautentiseringsuppgifter är agentens förväntade tokenpublik (vanligtvis agentens Microsoft app-ID, till exempel api://<appId> eller app-ID GUID). För användarinloggning måste målgruppen vara app-ID-GUID (se nedan).

Hämta dina autentiseringsuppgifter

Microsoft Entra ID (klientautentiseringsuppgifter)

Anslutningsappen skickar en apptoken. Om du vill autentisera dina API-begäranden behöver du:

1. Klientorganisations-ID för Microsoft Entra ID-programmet.
2. Klient-ID (program-ID) för Microsoft Entra ID-programmet.
3. Klienthemligheten för det programmet.
4. Resurs-URL:en som matchar målgruppen som förväntas av målagenten (autentiseringsmönstret för Bot Framework-kunskap).

Ange dessa värden när du skapar en anslutning. Skapa en anslutning per agent om målgrupperna skiljer sig åt.

Microsoft Entra ID (användarinloggning)

Anslutningsappen skickar den delegerade token för det konto som är loggat in på anslutningen, så att agenten kan byta ut den för kontots räkning (till exempel med SDK för Microsoft 365-agenter-hanterarenConnectorUserAuthorization). Du behöver:

1. Klientorganisations-ID för agentens Microsoft Entra ID-program.
2. Klient-ID: agentens eget Microsoft app-ID. SDK för Microsoft 365-agenter byter ut token för användarens räkning endast när token utfärdades till agentens eget program.
3. Klienthemligheten för det programmet.
4. Resurs-URL:en: agentens Microsoft app-ID (GUID), samma värde som klient-ID:t. Eftersom agentens eget program både är klienten och resursen kräver Microsoft Entra GUID här (AADSTS90009 annars); api://<appId> stöds inte för det här alternativet.

Ange dessa värden när du skapar en anslutning och logga sedan in och godkänn agentens exponerade omfång. Skapa en anslutning per agent.

Programmet behöver också den delegerade behörigheten Microsoft Graph User.Read ("Logga in och läs användarprofil") med medgivande. Utan det misslyckas inloggningen med AADSTS90008.

Om du vill byta token mot ett underordnat API konfigurerar du API:ets delegerade behörigheter för agentens program och hämtar det nödvändiga användar- eller administratörsmedgivandet. Att exponera ett omfång för agentens eget API ger inte underordnade behörigheter.

Kända problem och begränsningar

• Indata agentEndpoint måste vara en fullständig HTTPS-URL (till exempel https://my-agent.azurewebsites.net). Anslutningsappen lägger till /api/messages och vidarebefordrar aktivitetsnyttolasten.
• Anslutningsappen vidarebefordrar aktivitetsnyttolasten as-is och anger deliveryModeinte . Agenten svarar asynkront (normal leverans) genom att posting svarsaktiviteter tillbaka till den serviceUrl angivna på den inkommande aktiviteten (anroparen, t.ex. Microsoft Copilot Studio, tillhandahåller en SAS-nyckelad motringning serviceUrl).
• En Microsoft Entra ID-anslutning (användarinloggning) skickar alltid den delegerade token för kontot som är inloggade på anslutningen, för varje anrop som görs med anslutningen, inklusive anrop för andra personer som chattar med agenten. Den skickar inte en separat token för varje anropare, så aktivitetens from användare kan skilja sig från användaren i token. Auktorisera endast begäranden som konto i den verifierade token och behandla inte aktivitetens from eller begäranderubrikerna som chattpersonens auktoritet. Om agenten måste fungera som varje person som chattar med den ska du inte använda den här anslutningstypen.
• Om det inloggade kontots medgivande återkallas eller om sessionen inte längre kan uppdateras loggar du in på anslutningen igen.
• Den här anslutningsappen är i förhandsversion. Tillgänglighet och funktioner kan komma att ändras.

Skapa en anslutning

Anslutningsappen stöder följande autentiseringstyper:

API-nyckel

Autentiserings-ID: apiKey

Tillämpligt: Alla regioner

Autentisera med en statisk API-nyckel som målagenten förväntar sig i ett anpassat HTTP-huvud. Ange både rubriknamnet (till exempel x-api-key) och dess värde.

Det här är inte delningsbar anslutning. Om power-appen delas med en annan användare uppmanas en annan användare att skapa en ny anslutning explicit.

Microsoft Entra ID (klientautentiseringsuppgifter)

Autentiserings-ID: oauthClientCredentials

Tillämpligt: Alla regioner

Mint OAuth-ägartoken från ett Microsoft Entra ID program med hjälp av client_credentials flödet. Målgruppen för ägartoken (resurs-URL) måste matcha målgruppen som förväntas av målagenten.

Det här är inte delningsbar anslutning. Om power-appen delas med en annan användare uppmanas en annan användare att skapa en ny anslutning explicit.

Microsoft Entra ID (användarinloggning)

Autentiserings-ID: oauthAuthorizationCode

Tillämpligt: Alla regioner

Logga in via målagentens Microsoft Entra ID program (auktoriseringskodflöde) och skicka det inloggade kontots delegerade ägartoken. Varje anrop som görs med den här anslutningen använder kontot som är loggat in på anslutningen, inte den person som chattar med agenten. För att kunna byta token åt användaren behöver agenten sina nedströms delegerade behörigheter och sitt medgivande konfigurerat.

Det här är inte delningsbar anslutning. Om power-appen delas med en annan användare uppmanas en annan användare att skapa en ny anslutning explicit.

Ingen autentisering

Autentiserings-ID: anonymt

Tillämpligt: Alla regioner

Anropa målagentens slutpunkt utan något autentiseringshuvud. Använd endast detta med agenter som uttryckligen accepterar anonyma samtal.

Det här är en delningsbar anslutning. Om power-appen delas med en annan användare delas även anslutningen. Mer information finns i Översikt över anslutningsappar för arbetsyteappar – Power Apps | Microsoft Docs

Standard [INAKTUELL]

Tillämpligt: Alla regioner

Det här alternativet är endast för äldre anslutningar utan en explicit autentiseringstyp och tillhandahålls endast för bakåtkompatibilitet.

Det här är inte delningsbar anslutning. Om power-appen delas med en annan användare uppmanas en annan användare att skapa en ny anslutning explicit.

Åtgärder

Skicka aktivitet till agent

Definitioner

object