Agent SDK (Vorschau)

Leitet Bot Framework/Microsoft Agents SDK Activity Payloads an einen vom Benutzer bereitgestellten Agentendpunkt weiter. Die Agentendpunkt-URL wird pro Aufruf als Eingabeparameter bereitgestellt. Die Authentifizierung wird beim Erstellen der Verbindung ausgewählt: keine Authentifizierung, kein statischer API-Schlüssel oder Microsoft Entra ID OAuth (client_credentials oder Benutzeranmeldung). Wenn OAuth ausgewählt ist, muss die Bearertokengruppe (Ressourcen-URL, die für die Verbindung konfiguriert ist) mit der vom Ziel-Agent erwarteten Zielgruppe übereinstimmen.

Dieser Connector ist in den folgenden Produkten und Regionen verfügbar:

Service	Class	Regions
Copilot Studio	Standard	Alle Power Automate Regionen mit Ausnahme der folgenden: - US Government (GCC) - US Government (GCC High) - China Cloud betrieben von 21Vianet - US Department of Defense (DoD)
Logik-Apps	Standard	Alle Logik-Apps-Regionen mit Ausnahme der folgenden Bereiche: – Azure Government-Regionen - Azure China-Regionen - US Department of Defense (DoD)
Power Apps	Standard	Alle Power Apps Regionen mit Ausnahme der folgenden: - US Government (GCC) - US Government (GCC High) - China Cloud betrieben von 21Vianet - US Department of Defense (DoD)
Power Automate	Standard	Alle Power Automate Regionen mit Ausnahme der folgenden: - US Government (GCC) - US Government (GCC High) - China Cloud betrieben von 21Vianet - US Department of Defense (DoD)

Kontakt
Name	Microsoft
URL	https://support.microsoft.com

Connectormetadaten
Herausgeber	Microsoft
Website	https://www.microsoft.com
Datenschutzrichtlinie	https://privacy.microsoft.com/
Kategorien	Produktivität

Der Agent SDK-Connector leitet Bot Framework/Microsoft Agents SDK-Aktivitätsnutzlasten an einen vom Benutzer bereitgestellten Agentendpunkt weiter. Die Agentendpunkt-URL wird pro Aufruf als Eingabeparameter bereitgestellt. Die Verbindung wählt aus, wie sich der Connector beim Agent authentifiziert: keine Authentifizierung, kein statischer API-Schlüssel, ein Microsoft Entra ID Nur-App-Token (Clientanmeldeinformationen) oder ein Microsoft Entra ID delegiertes Benutzertoken (Benutzeranmeldung). Für beide Microsoft Entra ID Optionen muss die Bearertokengruppe (ressourcen-URL, die für die Verbindung konfiguriert ist) mit der vom Ziel-Agent erwarteten Zielgruppe übereinstimmen.

Voraussetzungen

Ein bereitgestellter Microsoft Agents SDK / Bot Framework-Agent erreichbar über HTTPS.
Für Microsoft Entra ID (Clientanmeldeinformationen): eine Microsoft Entra ID Anwendung, die im Mandanten registriert ist, der den Agent hostt, konfiguriert mit der client_credentials Erteilung und Berechtigung zum Aufrufen des Ziel-Agents.
Für Microsoft Entra ID (Benutzeranmeldung): die eigene Microsoft Entra ID-Anwendung des Agents (seine Microsoft App-ID) mit einem geheimen Clientschlüssel, einem verfügbar gemachten API-Bereich, dem Benutzer zustimmen können, dem Microsoft Graph User.Read ("Anmelden und Lesen des Benutzerprofils") delegierte Berechtigung mit Zustimmung und https://global.consent.azure-apim.net/redirect/agentsdk als Webumleitungs-URI hinzugefügt.
Für die Optionen für API-Schlüssel und Clientanmeldeinformationen wird die erwartete Tokengruppe des Agents (in der Regel die Microsoft App-ID des Agents, zapi://<appId>. B. oder die APP-ID-GUID), erwartet. Für die Benutzeranmeldung muss die Benutzergruppe die APP-ID-GUID sein (siehe unten).

Holen Sie Ihre Anmeldeinformationen ab

Microsoft Entra ID (Clientanmeldeinformationen)

Der Connector sendet ein Nur-App-Token. Um Ihre API-Anforderungen zu authentifizieren, benötigen Sie Folgendes:

Die Mandanten-ID der Microsoft Entra ID Anwendung.
Die Client-ID (Anwendungs-ID) der Microsoft Entra ID Anwendung.
Der geheime Clientschlüssel für diese Anwendung.
Die Ressourcen-URL , die der Zielgruppe entspricht, die vom Ziel-Agent erwartet wird (Bot Framework-Fähigkeits-Authentifizierungsmuster).

Geben Sie diese Werte an, wenn Sie eine Verbindung erstellen. Erstellen Sie eine Verbindung pro Agent, wenn benutzergruppen unterschiedlich sind.

Der Connector sendet das delegierte Token des kontos, das an die Verbindung angemeldet ist, sodass der Agent es im Namen dieses Kontos austauschen kann (z. B. mit dem Microsoft 365 Agents SDK-HandlerConnectorUserAuthorization). Sie benötigen Folgendes:

Die Mandanten-ID der Microsoft Entra ID Anwendung des Agents.
Die Client-ID: die eigene Microsoft App-ID des Agents. Die Microsoft 365 Agents SDK tauschen das Token im Namen des Benutzers nur aus, wenn das Token für die eigene Anwendung des Agents ausgestellt wurde.
Der geheime Clientschlüssel für diese Anwendung.
Die Ressourcen-URL: die Microsoft App-ID (GUID) des Agents, derselbe Wert wie die Client-ID. Da die eigene Anwendung des Agents sowohl der Client als auch die Ressource ist, erfordert Microsoft Entra hier die GUID (AADSTS90009 andernfalls); api://<appId> wird für diese Option nicht unterstützt.

Geben Sie diese Werte an, wenn Sie eine Verbindung erstellen, und melden Sie sich dann an, und stimmen Sie dem verfügbar gemachten Bereich des Agents zu. Erstellen Sie eine Verbindung pro Agent.

Die Anwendung benötigt außerdem die delegierte Berechtigung Microsoft Graph User.Read ("Anmelden und Benutzerprofil lesen") mit Zustimmung. Ohne dies schlägt die Anmeldung mit AADSTS90008 fehl.

Um das Token für eine nachgeschaltete API auszutauschen, konfigurieren Sie die delegierten Berechtigungen dieser API für die Anwendung des Agents, und rufen Sie die erforderliche Zustimmung des Benutzers oder Administrators ab. Durch das Verfügbarmachen eines Bereichs für die eigene API des Agents werden keine nachgelagerten Berechtigungen gewährt.

Bekannte Probleme und Einschränkungen

Die agentEndpoint Eingabe muss eine vollständige HTTPS-URL (z. B https://my-agent.azurewebsites.net. ) sein. Der Connector fügt die Aktivitätsnutzlast /api/messages an und leitet sie weiter.
Der Connector leitet die Aktivitätsnutzlast as-is weiter und legt nicht fest deliveryMode. Der Agent antwortet asynchron (normale Zustellung) durch POSTing-Antwortaktivitäten zurück auf die serviceUrl bereitgestellten eingehenden Aktivitäten (der Anrufer, z. B. Microsoft Copilot Studio, stellt einen SAS-Schlüssel-Rückruf serviceUrlbereit).
Eine Microsoft Entra ID -Verbindung (Benutzeranmeldung) sendet immer das delegierte Token des Kontos, das an die Verbindung angemeldet ist, für jeden Anruf, der mit dieser Verbindung getätigt wurde, einschließlich Anrufe im Namen anderer Personen, die mit dem Agent chatten. Es sendet kein separates Token für jeden Aufrufer, sodass sich der Benutzer der from Aktivität vom Benutzer im Token unterscheiden kann. Autorisieren Sie Anforderungen nur als Konto im überprüften Token, und behandeln Sie die Kopfzeilen der Aktivität from oder anforderungsheader nicht als Autorität der Chatperson. Wenn der Agent als jede Person handeln muss, die damit chattet, verwenden Sie diesen Verbindungstyp nicht.
Wenn die Zustimmung des angemeldeten Kontos widerrufen wird oder die Sitzung nicht mehr aktualisiert werden kann, melden Sie sich erneut bei der Verbindung an.
Dieser Connector befindet sich in der Vorschau. Verfügbarkeit und Funktionen können geändert werden.

Eine Verbindung wird erstellt

Der Connector unterstützt die folgenden Authentifizierungstypen:


API-Schlüssel	Authentifizieren mit einem statischen API-Schlüssel, den der Ziel-Agent in einem benutzerdefinierten HTTP-Header erwartet. Geben Sie sowohl den Headernamen (z. B. x-api-key) als auch den zugehörigen Wert an.	Alle Regionen	Nicht teilbar
Microsoft Entra ID (Clientanmeldeinformationen)	OAuth-Bearertoken aus einer Microsoft Entra ID Anwendung mithilfe des client_credentials-Flusses. Die Bearertokengruppe (Ressourcen-URL) muss der vom Ziel-Agent erwarteten Zielgruppe entsprechen.	Alle Regionen	Nicht teilbar
Microsoft Entra ID (Benutzeranmeldung)	Melden Sie sich über die Microsoft Entra ID-Anwendung des Ziel-Agents (Autorisierungscodefluss) an, und senden Sie das delegierte Bearertoken des angemeldeten Kontos. Jeder Mit dieser Verbindung getätigte Anruf verwendet das bei der Verbindung angemeldete Konto, nicht die Person, die mit dem Agent chattet. Um das Token im Namen des Benutzers auszutauschen, benötigt der Agent seine nachgeschalteten delegierten Berechtigungen und seine Zustimmung konfiguriert.	Alle Regionen	Nicht teilbar
Keine Authentifizierung	Rufen Sie den Ziel-Agent-Endpunkt ohne Authentifizierungsheader auf. Verwenden Sie dies nur für Agents, die anonyme Anrufe explizit akzeptieren.	Alle Regionen	Freigabefähig
Standard [VERALTET]	Diese Option ist nur für ältere Verbindungen ohne expliziten Authentifizierungstyp vorgesehen und wird nur aus Gründen der Abwärtskompatibilität bereitgestellt.	Alle Regionen	Nicht teilbar

API-Schlüssel

Auth-ID: apiKey

Anwendbar: Alle Regionen

Authentifizieren mit einem statischen API-Schlüssel, den der Ziel-Agent in einem benutzerdefinierten HTTP-Header erwartet. Geben Sie sowohl den Headernamen (z. B. x-api-key) als auch den zugehörigen Wert an.

Dies ist keine freigabefähige Verbindung. Wenn die Power-App für einen anderen Benutzer freigegeben wird, wird ein anderer Benutzer aufgefordert, eine neue Verbindung explizit zu erstellen.

Name	Typ	Description	Erforderlich
API-Schlüsselheadername	string	Name des HTTP-Headers, für den der Ziel-Agent den API-Schlüssel erwartet (z. B. x-api-key oder Ocp-Apim-Subscription-Key).	True
API-Schlüsselwert	Securestring	Statischer API-Schlüsselwert, der für jede Anforderung an den Ziel-Agent-Endpunkt gesendet wird.	True

Microsoft Entra ID (Clientanmeldeinformationen)

Auth-ID: oauthClientCredentials

Anwendbar: Alle Regionen

OAuth-Bearertoken aus einer Microsoft Entra ID Anwendung mithilfe des client_credentials-Flusses. Die Bearertokengruppe (Ressourcen-URL) muss der vom Ziel-Agent erwarteten Zielgruppe entsprechen.

Dies ist keine freigabefähige Verbindung. Wenn die Power-App für einen anderen Benutzer freigegeben wird, wird ein anderer Benutzer aufgefordert, eine neue Verbindung explizit zu erstellen.

Name	Typ	Description	Erforderlich
Tenant	string	Die Mandanten-ID der Microsoft Entra ID Anwendung	True
Client-ID	string	Client-ID (oder Anwendungs-ID) der Microsoft Entra ID Anwendung.	True
Geheimer Clientschlüssel	Securestring	Geheimer Clientschlüssel der Microsoft Entra ID Anwendung.	True
Ressourcen-URL	string	Zielgruppe für das OAuth-Token. In der Regel die Microsoft App-ID des Ziel-Agents (z. B. api://< appId> oder die App-ID-GUID).	True

Auth-ID: oauthAuthorizationCode

Anwendbar: Alle Regionen

Melden Sie sich über die Microsoft Entra ID-Anwendung des Ziel-Agents (Autorisierungscodefluss) an, und senden Sie das delegierte Bearertoken des angemeldeten Kontos. Jeder Mit dieser Verbindung getätigte Anruf verwendet das bei der Verbindung angemeldete Konto, nicht die Person, die mit dem Agent chattet. Um das Token im Namen des Benutzers auszutauschen, benötigt der Agent seine nachgeschalteten delegierten Berechtigungen und seine Zustimmung konfiguriert.

Dies ist keine freigabefähige Verbindung. Wenn die Power-App für einen anderen Benutzer freigegeben wird, wird ein anderer Benutzer aufgefordert, eine neue Verbindung explizit zu erstellen.

Name	Typ	Description	Erforderlich
Tenant	string	Die Mandanten-ID der Microsoft Entra ID Anwendung des Ziel-Agents.	True
Client-ID	string	Die Microsoft App-ID des Ziel-Agents. Verwenden Sie die eigene Anwendung des Agents, damit der Agent das delegierte Token im Namen des Benutzers austauschen kann.	True
Geheimer Clientschlüssel	Securestring	Geheimer Clientschlüssel der Microsoft Entra ID Anwendung des Ziel-Agents.	True
Ressourcen-URL	string	Zielgruppe für das delegierte Token. Muss die Microsoft App-ID (GUID) des Ziel-Agents sein, derselbe Wert wie die Client-ID: Microsoft Entra akzeptiert nur die GUID, wenn eine Anwendung ein Token für sich selbst anfordert.	True

Keine Authentifizierung

Authentifizierungs-ID: anonym

Anwendbar: Alle Regionen

Rufen Sie den Ziel-Agent-Endpunkt ohne Authentifizierungsheader auf. Verwenden Sie dies nur für Agents, die anonyme Anrufe explizit akzeptieren.

Dies ist eine freigabefähige Verbindung. Wenn die Power-App für einen anderen Benutzer freigegeben wird, wird auch die Verbindung freigegeben. Weitere Informationen finden Sie in der Übersicht über Connectors für Canvas-Apps – Power Apps | Microsoft-Dokumentation

Standard [VERALTET]

Anwendbar: Alle Regionen

Diese Option ist nur für ältere Verbindungen ohne expliziten Authentifizierungstyp vorgesehen und wird nur aus Gründen der Abwärtskompatibilität bereitgestellt.

Dies ist keine freigabefähige Verbindung. Wenn die Power-App für einen anderen Benutzer freigegeben wird, wird ein anderer Benutzer aufgefordert, eine neue Verbindung explizit zu erstellen.

Aktionen

Aktivität an Agent senden

Leitet eine Aktivitätsprotokollnutzlast an den Agentendpunkt unter {agentEndpoint}/api/messages weiter. Wenn die Verbindung Microsoft Entra ID OAuth verwendet, muss die Tokengruppe (Ressourcen-URL für die Verbindung) der vom Ziel-Agent erwarteten Zielgruppe (Bot Framework-Fähigkeitsauthentifizierungsmuster) entsprechen. Erstellen Sie eine Verbindung pro Agent, wenn benutzergruppen unterschiedlich sind. Der Connector leitet die Aktivitätsnutzlast as-is weiter und legt "deliveryMode" nicht fest; Der Agent antwortet asynchron (normale Zustellung) durch POSTing-Antwortaktivitäten auf die "serviceUrl", die für die eingehende Aktivität bereitgestellt werden.

Aktivität an Agent senden

Vorgangs-ID:: SendActivity

Parameter

Name	Schlüssel	Erforderlich	Typ	Beschreibung
Agent-Endpunkt-URL	agentEndpoint	True	string	Basis-URL des Ziel-Microsoft Agents SDK/Bot Framework-Endpunkts (z. Bhttps://my-agent.azurewebsites.net. ). Der Connector fügt /api/messages an.
			object

Agent SDK (Vorschau)

Voraussetzungen

Holen Sie Ihre Anmeldeinformationen ab

Microsoft Entra ID (Clientanmeldeinformationen)

Microsoft Entra ID (Benutzeranmeldung)

Bekannte Probleme und Einschränkungen

Eine Verbindung wird erstellt

API-Schlüssel

Microsoft Entra ID (Clientanmeldeinformationen)

Microsoft Entra ID (Benutzeranmeldung)

Keine Authentifizierung

Standard [VERALTET]

Aktionen

Aktivität an Agent senden

Parameter

Gibt zurück

Definitionen

Objekt