Agent-SDK (preview)

Stuurt Bot Framework/Microsoft SDK-activiteitspayloads van agents door naar een door de gebruiker opgegeven agenteindpunt. De eindpunt-URL van de agent wordt per aanroep opgegeven als invoerparameter. Verificatie wordt geselecteerd bij het maken van de verbinding: geen verificatie, een statische API-sleutel of Microsoft Entra ID OAuth (client_credentials of aanmelding van gebruikers). Wanneer OAuth is geselecteerd, moet de bearer-tokendoelgroep (resource-URL die is geconfigureerd voor de verbinding) overeenkomen met de doelgroep die door de doelagent wordt verwacht.

Deze connector is beschikbaar in de volgende producten en regio's:

Dienst	Class	Regions
Copilot Studio	Standard	Alle Power Automate regio's behalve: - Amerikaanse overheid (GCC) - Amerikaanse overheid (GCC High) - China Cloud beheerd door 21Vianet - Us Department of Defense (DoD)
Logic-apps	Standard	Alle Logic Apps-regio's , met uitzondering van het volgende: - Azure Government-regio's - Azure China-regio's - Us Department of Defense (DoD)
Power Apps	Standard	Alle Power Apps regio's behalve: - Amerikaanse overheid (GCC) - Amerikaanse overheid (GCC High) - China Cloud beheerd door 21Vianet - Us Department of Defense (DoD)
Power Automate	Standard	Alle Power Automate regio's behalve: - Amerikaanse overheid (GCC) - Amerikaanse overheid (GCC High) - China Cloud beheerd door 21Vianet - Us Department of Defense (DoD)

Contact
Naam	Microsoft
URL	https://support.microsoft.com

Connectormetagegevens
Uitgever	Microsoft
Website	https://www.microsoft.com
Privacybeleid	https://privacy.microsoft.com/
Categorieën	Productiviteit

De Agent SDK-connector stuurt Bot Framework/Microsoft Agents SDK-activiteit nettoladingen door naar een door de gebruiker opgegeven agenteindpunt. De eindpunt-URL van de agent wordt per aanroep opgegeven als invoerparameter. De verbinding selecteert hoe de connector wordt geverifieerd bij de agent: geen verificatie, een statische API-sleutel, een Microsoft Entra ID alleen-app-token (clientreferenties) of een Microsoft Entra ID gedelegeerd gebruikerstoken (gebruikersaanmelding). Voor beide Microsoft Entra ID opties moet de bearer-tokendoelgroep (resource-URL die is geconfigureerd voor de verbinding) overeenkomen met de doelgroep die door de doelagent wordt verwacht.

Prerequisites

Een geïmplementeerde Microsoft Agents SDK/Bot Framework-agent bereikbaar via HTTPS.
Voor Microsoft Entra ID (clientreferenties): een Microsoft Entra ID toepassing die is geregistreerd in de tenant die als host fungeert voor de agent, geconfigureerd met de client_credentials toekenning en machtiging om de doelagent aan te roepen.
Voor Microsoft Entra ID (gebruikersaanmelding): de eigen Microsoft Entra ID-toepassing van de agent (de bijbehorende Microsoft-app-id) met een clientgeheim, een beschikbaar API-bereik waarmee gebruikers toestemming kunnen geven, de Microsoft Graph User.Read ('Aanmeldings- en leesgebruikersprofiel') gedelegeerde machtiging met toestemming en https://global.consent.azure-apim.net/redirect/agentsdk toegevoegd als een webomleidings-URI.
Voor de api-sleutel- en clientreferentieopties is de verwachte tokendoelgroep van de agent (meestal de Microsoft app-id van de agent, bijvoorbeeld api://<appId> de GUID van de app-id). Voor gebruikersaanmelding moet de doelgroep de GUID van de app-id zijn (zie hieronder).

Uw referenties ophalen

Microsoft Entra ID (clientreferenties)

De connector verzendt een app-token. Voor het verifiëren van uw API-aanvragen hebt u het volgende nodig:

De tenant-id van de Microsoft Entra ID-toepassing.
De client-id (toepassings-id) van de Microsoft Entra ID-toepassing.
Het clientgeheim voor die toepassing.
De resource-URL die overeenkomt met de doelgroep die wordt verwacht door de doelagent (bot framework-verificatiepatroon).

Geef deze waarden op wanneer u een verbinding maakt. Maak één verbinding per agent als doelgroepen verschillen.

De connector verzendt het gedelegeerde token van het account dat is aangemeld bij de verbinding, zodat de agent het kan uitwisselen namens dat account (bijvoorbeeld met de SDK voor Microsoft 365-agenten ConnectorUserAuthorization handler). U hebt het volgende nodig:

De tenant-id van de Microsoft Entra ID-toepassing van de agent.
De client-id: de eigen Microsoft app-id van de agent. De SDK voor Microsoft 365-agenten wisselt het token alleen uit namens de gebruiker wanneer het token is uitgegeven aan de eigen toepassing van de agent.
Het clientgeheim voor die toepassing.
De resource-URL: de Microsoft app-id (GUID) van de agent, dezelfde waarde als de client-id. Omdat de eigen toepassing van de agent zowel de client als de resource is, vereist Microsoft Entra hier de GUID (anders AADSTS90009api://<appId>); wordt niet ondersteund voor deze optie.

Geef deze waarden op wanneer u een verbinding maakt en meld u vervolgens aan en geef toestemming voor het bereik van de weergegeven agent. Maak één verbinding per agent.

De toepassing heeft ook de Microsoft Graph gedelegeerde machtiging User.Read ('Aanmelden en gebruikersprofiel lezen') met toestemming nodig. Zonder toestemming mislukt de aanmelding met AADSTS90008.

Als u het token wilt uitwisselen voor een downstream-API, configureert u de gedelegeerde machtigingen van de API voor de toepassing van de agent en verkrijgt u de vereiste toestemming van de gebruiker of beheerder. Het beschikbaar maken van een bereik op de eigen API van de agent verleent geen downstreammachtigingen.

Bekende problemen en beperkingen

De agentEndpoint invoer moet een volledige HTTPS-URL zijn (bijvoorbeeld https://my-agent.azurewebsites.net). De connector voegt de nettolading van de activiteit toe /api/messages en stuurt deze door.
De connector stuurt de nettolading van de activiteit door as-is en wordt niet ingesteld deliveryMode. De agent reageert asynchroon (normale bezorging) door antwoordactiviteiten posting terug te sturen naar de serviceUrl opgegeven inkomende activiteit (de beller, bijvoorbeeld Microsoft Copilot Studio, biedt een callback serviceUrlmet SAS-sleutel).
Een Microsoft Entra ID -verbinding (gebruikersaanmelding) verzendt altijd het gedelegeerde token van het account dat is aangemeld bij de verbinding, voor elke oproep die met die verbinding is gedaan, inclusief oproepen namens andere personen die met de agent chatten. Er wordt geen afzonderlijk token verzonden voor elke beller, zodat de gebruiker van from de activiteit kan verschillen van de gebruiker in het token. Autoriseren aanvragen alleen als het account in het gevalideerde token en behandelen de activiteits from - of aanvraagheaders niet als de instantie van de chattende persoon. Als de agent moet fungeren als elke persoon die ermee praat, gebruikt u dit verbindingstype niet.
Als de toestemming van het aangemelde account wordt ingetrokken of de sessie niet meer kan worden vernieuwd, meldt u zich opnieuw aan bij de verbinding.
Deze connector is in preview. Beschikbaarheid en mogelijkheden kunnen worden gewijzigd.

Een verbinding maken

De connector ondersteunt de volgende verificatietypen:


API-sleutel	Verifieer met een statische API-sleutel die de doelagent verwacht in een aangepaste HTTP-header. Geef zowel de headernaam (bijvoorbeeld x-api-sleutel) als de waarde op.	Alle regio's	Niet deelbaar
Microsoft Entra ID (clientreferenties)	Mint OAuth bearer-tokens van een Microsoft Entra ID toepassing met behulp van de client_credentials stroom. De bearer-tokendoelgroep (resource-URL) moet overeenkomen met de doelgroep die door de doelagent wordt verwacht.	Alle regio's	Niet deelbaar
Microsoft Entra ID (gebruikersaanmelding)	Meld u aan via de Microsoft Entra ID-toepassing van de doelagent (autorisatiecodestroom) en verzend het gedelegeerde Bearer-token van het aangemelde account. Elke aanroep met deze verbinding maakt gebruik van het account dat is aangemeld bij de verbinding, niet de persoon die met de agent praat. Als de agent het token namens de gebruiker wil uitwisselen, moet de downstream gedelegeerde machtigingen en toestemming zijn geconfigureerd.	Alle regio's	Niet deelbaar
Geen authenticatie	Roep het eindpunt van de doelagent aan zonder verificatieheader. Gebruik dit alleen met agents die expliciet anonieme oproepen accepteren.	Alle regio's	Deelbaar
Standaard [AFGESCHAFT]	Deze optie is alleen bedoeld voor oudere verbindingen zonder expliciet verificatietype en is alleen beschikbaar voor compatibiliteit met eerdere versies.	Alle regio's	Niet deelbaar

API-sleutel

Verificatie-id: apiKey

Van toepassing: Alle regio's

Verifieer met een statische API-sleutel die de doelagent verwacht in een aangepaste HTTP-header. Geef zowel de headernaam (bijvoorbeeld x-api-sleutel) als de waarde op.

Dit is geen deelbare verbinding. Als de power-app wordt gedeeld met een andere gebruiker, wordt een andere gebruiker gevraagd om expliciet een nieuwe verbinding te maken.

Naam	Typ	Description	Required
Naam van api-sleutelheader	string	Naam van de HTTP-header waarop de doelagent de API-sleutel verwacht (bijvoorbeeld x-api-key of Ocp-Apim-Subscription-Key).	True
API-sleutelwaarde	beveiligde string	Statische API-sleutelwaarde die wordt verzonden op elke aanvraag naar het eindpunt van de doelagent.	True

Microsoft Entra ID (clientreferenties)

Verificatie-id: oauthClientCredentials

Van toepassing: Alle regio's

Mint OAuth bearer-tokens van een Microsoft Entra ID toepassing met behulp van de client_credentials stroom. De bearer-tokendoelgroep (resource-URL) moet overeenkomen met de doelgroep die door de doelagent wordt verwacht.

Dit is geen deelbare verbinding. Als de power-app wordt gedeeld met een andere gebruiker, wordt een andere gebruiker gevraagd om expliciet een nieuwe verbinding te maken.

Naam	Typ	Description	Required
Tenant	string	De tenant-id van de Microsoft Entra ID-toepassing	True
Client-ID	string	Client-id (of toepassing) van de Microsoft Entra ID-toepassing.	True
Clientgeheim	beveiligde string	Clientgeheim van de Microsoft Entra ID-toepassing.	True
URL van de bron	string	Doelgroep voor het OAuth-token. De Microsoft app-id van de doelagent (bijvoorbeeld api://< appId> of de GUID van de app-id).	True

Verificatie-id: oauthAuthAuthorizationCode

Van toepassing: Alle regio's

Meld u aan via de Microsoft Entra ID-toepassing van de doelagent (autorisatiecodestroom) en verzend het gedelegeerde Bearer-token van het aangemelde account. Elke aanroep met deze verbinding maakt gebruik van het account dat is aangemeld bij de verbinding, niet de persoon die met de agent praat. Als de agent het token namens de gebruiker wil uitwisselen, moet de downstream gedelegeerde machtigingen en toestemming zijn geconfigureerd.

Dit is geen deelbare verbinding. Als de power-app wordt gedeeld met een andere gebruiker, wordt een andere gebruiker gevraagd om expliciet een nieuwe verbinding te maken.

Naam	Typ	Description	Required
Tenant	string	De tenant-id van de Microsoft Entra ID-toepassing van de doelagent.	True
Client-ID	string	De Microsoft app-id van de doelagent. Gebruik de eigen toepassing van de agent, zodat de agent het gedelegeerde token namens de gebruiker kan uitwisselen.	True
Clientgeheim	beveiligde string	Clientgeheim van de Microsoft Entra ID-toepassing van de doelagent.	True
URL van de bron	string	Doelgroep voor het gedelegeerde token. Moet de Microsoft app-id (GUID) van de doelagent zijn, dezelfde waarde als client-id: Microsoft Entra accepteert alleen de GUID wanneer een toepassing een token voor zichzelf aanvraagt.	True

Geen authenticatie

Verificatie-id: anoniem

Van toepassing: Alle regio's

Roep het eindpunt van de doelagent aan zonder verificatieheader. Gebruik dit alleen met agents die expliciet anonieme oproepen accepteren.

Dit is deelbare verbinding. Als de power-app wordt gedeeld met een andere gebruiker, wordt de verbinding ook gedeeld. Zie het overzicht van Connectors voor canvas-apps - Power Apps | Microsoft Docs

Standaard [AFGESCHAFT]

Van toepassing: Alle regio's

Deze optie is alleen bedoeld voor oudere verbindingen zonder expliciet verificatietype en is alleen beschikbaar voor compatibiliteit met eerdere versies.

Dit is geen deelbare verbinding. Als de power-app wordt gedeeld met een andere gebruiker, wordt een andere gebruiker gevraagd om expliciet een nieuwe verbinding te maken.

Acties

Activiteit verzenden naar agent

Stuurt een payload van het Activity Protocol door naar het eindpunt van de agent op {agentEndpoint}/api/messages. Wanneer de verbinding gebruikmaakt van Microsoft Entra ID OAuth, moet de tokendoelgroep (resource-URL voor de verbinding) gelijk zijn aan de doelgroep die wordt verwacht door de doelagent (Bot Framework-vaardigheidsverificatiepatroon); maak één verbinding per agent als doelgroepen verschillen. De connector stuurt de nettolading van de activiteit door as-is en stelt 'deliveryMode' niet in; de agent antwoordt asynchroon (normale levering) door POSTing-antwoordactiviteiten te beantwoorden aan de serviceUrl die is opgegeven voor de binnenkomende activiteit.

Activiteit verzenden naar agent

Bewerkings-id:: SendActivity

Parameters

Naam	Sleutel	Vereist	Type	Description
Eindpunt-URL van agent	agentEndpoint	True	string	Basis-URL van de doel-Microsoft Agents SDK/Bot Framework-eindpunt (bijvoorbeeldhttps://my-agent.azurewebsites.net). De connector voegt /api/messages toe.
			object

Agent-SDK (preview)

Prerequisites

Uw referenties ophalen

Microsoft Entra ID (clientreferenties)

Microsoft Entra ID (gebruikersaanmelding)

Bekende problemen en beperkingen

Een verbinding maken

API-sleutel

Microsoft Entra ID (clientreferenties)

Microsoft Entra ID (gebruikersaanmelding)

Geen authenticatie

Standaard [AFGESCHAFT]

Acties

Activiteit verzenden naar agent

Parameters

Retouren

Definities

Object