Ügynök SDK (előzetes verzió)

A Bot Framework/Microsoft Agent SDK-tevékenység hasznos adatainak továbbítása a felhasználó által megadott ügynökvégpontra. Az ügynök végpontJÁNAK URL-címét hívásonként adja meg bemeneti paraméterként. A kapcsolat létrehozásakor a rendszer a hitelesítést választja: nincs hitelesítés, statikus API-kulcs vagy Microsoft Entra ID OAuth (client_credentials vagy felhasználói bejelentkezés). Az OAuth kiválasztásakor a tulajdonosi jogkivonat célközönségének (a kapcsolaton konfigurált erőforrás URL-címének) meg kell egyeznie a célügynök által várt célközönségkel.

Ez az összekötő a következő termékekben és régiókban érhető el:

Szolgáltatás Class Regions
Copilot Studio Standard Az összes Power Automate régió kivéve a következőket:
     - USA kormánya (GCC)
     - Amerikai kormány (GCC High)
     - A 21Vianet által üzemeltetett China Cloud
     - Amerikai Védelmi Minisztérium (DoD)
Logikai alkalmazások Standard Az összes Logic Apps-régió , kivéve a következőket:
     - Azure Government-régiók
     - Azure China-régiók
     - Amerikai Védelmi Minisztérium (DoD)
Power Apps Standard Az összes Power Apps-régió , kivéve a következőket:
     - USA kormánya (GCC)
     - Amerikai kormány (GCC High)
     - A 21Vianet által üzemeltetett China Cloud
     - Amerikai Védelmi Minisztérium (DoD)
Power Automate Standard Az összes Power Automate régió kivéve a következőket:
     - USA kormánya (GCC)
     - Amerikai kormány (GCC High)
     - A 21Vianet által üzemeltetett China Cloud
     - Amerikai Védelmi Minisztérium (DoD)
Kapcsolat
Név Microsoft
URL https://support.microsoft.com
Összekötő metaadatai
Publisher Microsoft
Webhely https://www.microsoft.com
Adatvédelmi irányelvek https://privacy.microsoft.com/
Categories Termelékenység

Az Ügynök SDK-összekötő továbbítja a Bot Framework/Microsoft Agent SDK-tevékenység hasznos adatait egy felhasználó által megadott ügynökvégpontra. Az ügynök végpontJÁNAK URL-címét hívásonként adja meg bemeneti paraméterként. A kapcsolat kiválasztja, hogyan hitelesíti az összekötő az ügynököt: nincs hitelesítés, statikus API-kulcs, Microsoft Entra ID csak alkalmazásjogkivonat (ügyfél-hitelesítő adatok) vagy Microsoft Entra ID delegált felhasználói jogkivonat (felhasználói bejelentkezés). Mindkét Microsoft Entra ID beállításnál a tulajdonosi jogkivonat célközönségének (a kapcsolaton konfigurált erőforrás URL-címének) meg kell egyeznie a célügynök által várt célközönséggel.

Prerequisites

  • A HTTPS-en keresztül elérhető üzembe helyezett Microsoft Agent SDK/Bot Framework-ügynök.
  • Microsoft Entra ID (ügyfél hitelesítő adatai): az ügynököt üzemeltető bérlőben regisztrált Microsoft Entra ID alkalmazás, amely a client_credentials célügynök meghívására vonatkozó engedélyekkel és engedélyekkel van konfigurálva.
  • Microsoft Entra ID (felhasználói bejelentkezés) esetén: az ügynök saját Microsoft Entra ID alkalmazása (Microsoft alkalmazásazonosítója) egy ügyféltitkos, egy közzétett API-hatókörrel, amelyet a felhasználók jóváhagyhatnak, a Microsoft Graph User.Read ("Bejelentkezés és felhasználói profil olvasása") delegált engedély hozzájárulással, és https://global.consent.azure-apim.net/redirect/agentsdkwebes átirányítási URI-ként hozzáadva.
  • Az API-kulcs és az ügyfél hitelesítő adatainak beállításainál az ügynök várt jogkivonat-célközönsége (általában az ügynök Microsoft alkalmazásazonosítója, például api://<appId> az alkalmazásazonosító GUID azonosítója). A felhasználói bejelentkezéshez a célközönségnek az alkalmazásazonosító GUID azonosítójának kell lennie (lásd alább).

Hitelesítő adatok lekérése

Microsoft Entra ID (ügyfél hitelesítő adatai)

Az összekötő csak alkalmazásjogkivonatot küld. Az API-kérések hitelesítéséhez a következőkre lesz szüksége:

  1. A Microsoft Entra ID alkalmazás bérlőazonosítója.
  2. Az Microsoft Entra ID alkalmazás ügyfélazonosítója (alkalmazásazonosítója).
  3. Az alkalmazás titkos ügyfélkódja .
  4. Az erőforrás URL-címe , amely megfelel a célügynök által várt célközönségnek (Bot Framework skill auth pattern).

Adja meg ezeket az értékeket kapcsolat létrehozásakor. Hozzon létre egy kapcsolatot ügynökönként, ha a célközönségek eltérőek.

Microsoft Entra ID (felhasználói bejelentkezés)

Az összekötő elküldi a fiók delegált jogkivonatát a kapcsolatnak, így az ügynök az adott fiók nevében (például a Microsoft 365-ügynökök SDK-ja ConnectorUserAuthorization kezelőjével) cserélheti azt. A következőkre lesz szüksége:

  1. Az ügynök Microsoft Entra ID alkalmazás bérlőazonosítója.
  2. Az ügyfélazonosító: az ügynök saját Microsoft alkalmazásazonosítója. A Microsoft 365-ügynökök SDK-ja csak akkor cseréli le a jogkivonatot a felhasználó nevében, ha a jogkivonatot az ügynök saját alkalmazásának bocsátották ki.
  3. Az alkalmazás titkos ügyfélkódja .
  4. Az erőforrás URL-címe: az ügynök Microsoft alkalmazásazonosítója (GUID), ugyanaz az érték, mint az ügyfélazonosító. Mivel az ügynök saját alkalmazása az ügyfél és az erőforrás is, Microsoft Entra itt a GUID szükséges (egyébként AADSTS90009); api://<appId> ez a beállítás nem támogatott.

Adja meg ezeket az értékeket egy kapcsolat létrehozásakor, majd jelentkezzen be, és járuljon hozzá az ügynök közzétett hatóköréhez. Hozzon létre egy kapcsolatot ügynökönként.

Az alkalmazásnak a Microsoft Graph User.Read ("Bejelentkezés és felhasználói profil olvasása") delegált engedélyre is szüksége van hozzájárulással; nélküle a bejelentkezés AADSTS90008 meghiúsul.

Ha egy alsóbb rétegbeli API jogkivonatát szeretné kicserélni, konfigurálja az API delegált engedélyeit az ügynök alkalmazásához, és szerezze be a szükséges felhasználói vagy rendszergazdai hozzájárulást. Ha egy hatókört az ügynök saját API-ján hoz létre, az nem ad alsóbb rétegbeli engedélyeket.

Ismert problémák és korlátozások

  • A agentEndpoint bemenetnek teljes HTTPS URL-címnek kell lennie (például https://my-agent.azurewebsites.net). Az összekötő hozzáfűzi /api/messages és továbbítja a tevékenység hasznos adatait.
  • Az összekötő továbbítja a tevékenység hasznos adatait as-is, és nem állítja be deliveryMode. Az ügynök aszinkron módon (normál kézbesítéssel) válaszol, ha a posTing választevékenységeket küld vissza a serviceUrl bejövő tevékenységhez (a hívó például Microsoft Copilot Studio SAS-kulcsú visszahívást serviceUrlbiztosít).
  • A Microsoft Entra ID (felhasználói bejelentkezési) kapcsolat mindig elküldi a kapcsolatba bejelentkezett fiók delegált jogkivonatát minden, ezzel a kapcsolattal indított híváshoz, beleértve az ügynökkel csevegő többi személy nevében folytatott hívásokat is. Nem küld külön jogkivonatot az egyes hívókhoz, így a tevékenység felhasználója from eltérhet a jogkivonat felhasználójától. A kérések engedélyezése csak az érvényesített jogkivonatban szereplő fiókként, és ne kezelje a tevékenység from vagy a kérés fejlécét a csevegő személy szolgáltatójaként. Ha az ügynöknek úgy kell működnie, mint a vele csevegő összes személynek, ne használja ezt a kapcsolattípust.
  • Ha a bejelentkezett fiók hozzájárulását visszavonták, vagy a munkamenete már nem frissíthető, jelentkezzen be újra a kapcsolatba.
  • Ez az összekötő előzetes verzióban érhető el. A rendelkezésre állás és a képességek változhatnak.

Kapcsolat létrehozása

Az összekötő a következő hitelesítési típusokat támogatja:
API-kulcs Hitelesítés egy statikus API-kulccsal, amit a célügynök elvár egy egyéni HTTP-fejlécben. Adja meg a fejléc nevét (például x-api-key) és értékét is. Minden régió Nem osztható meg
Microsoft Entra ID (ügyfél hitelesítő adatai) Mint OAuth-jogkivonatok egy Microsoft Entra ID alkalmazásból a client_credentials folyamat használatával. A tulajdonosi jogkivonat célközönségének (erőforrás URL-címének) meg kell egyeznie a célügynök által várt célközönségkel. Minden régió Nem osztható meg
Microsoft Entra ID (felhasználói bejelentkezés) Jelentkezzen be a célügynök Microsoft Entra ID alkalmazásán keresztül (engedélyezési kódfolyamat), és küldje el a bejelentkezett fiók delegált tulajdonosi jogkivonatát. Minden ezzel a kapcsolattal végrehajtott hívás a kapcsolatba bejelentkezett fiókot használja, nem az ügynökkel csevegő személyt. A jogkivonat felhasználó nevében történő cseréjéhez az ügynöknek konfigurálnia kell az alárendelt delegált engedélyeket és hozzájárulásokat. Minden régió Nem osztható meg
Nincs hitelesítés Hívja meg a célügynök végpontját hitelesítési fejléc nélkül. Ezt csak olyan ügynökökkel használja, amelyek kifejezetten fogadnak névtelen hívásokat. Minden régió Megosztható
Alapértelmezett [ELAVULT] Ez a beállítás csak olyan régebbi kapcsolatokhoz használható, amelyeknek nincs explicit hitelesítési típusuk, és csak a visszamenőleges kompatibilitást biztosítják. Minden régió Nem osztható meg

API-kulcs

Hitelesítési azonosító: apiKey

Alkalmazható: Minden régió

Hitelesítés egy statikus API-kulccsal, amit a célügynök elvár egy egyéni HTTP-fejlécben. Adja meg a fejléc nevét (például x-api-key) és értékét is.

Ez nem megosztható kapcsolat. Ha a power app meg van osztva egy másik felhasználóval, a rendszer kérni fogja, hogy hozzon létre új kapcsolatot.

Név Típus Description Required
API-kulcs fejlécének neve karakterlánc Annak a HTTP-fejlécnek a neve, amelyen a célügynök az API-kulcsot várja (például x-api-key vagy Ocp-Apim-Subscription-Key). True
API-kulcs értéke securestring A célügynök végpontjának küldött minden kérés statikus API-kulcsértéke. True

Microsoft Entra ID (ügyfél hitelesítő adatai)

Hitelesítési azonosító: oauthClientCredentials

Alkalmazható: Minden régió

Mint OAuth-jogkivonatok egy Microsoft Entra ID alkalmazásból a client_credentials folyamat használatával. A tulajdonosi jogkivonat célközönségének (erőforrás URL-címének) meg kell egyeznie a célügynök által várt célközönségkel.

Ez nem megosztható kapcsolat. Ha a power app meg van osztva egy másik felhasználóval, a rendszer kérni fogja, hogy hozzon létre új kapcsolatot.

Név Típus Description Required
Tenant karakterlánc A Microsoft Entra ID alkalmazás bérlőazonosítója True
Ügyfélazonosító karakterlánc Az Microsoft Entra ID alkalmazás ügyfél-(vagy alkalmazás-) azonosítója. True
Titkos ügyfélkód securestring Az Microsoft Entra ID alkalmazás titkos ügyfélkódja. True
Erőforrás URL-címe karakterlánc Az OAuth-jogkivonat célközönsége. Általában a célügynök Microsoft alkalmazásazonosítója (például api://< appId> vagy az alkalmazásazonosító GUID azonosítója). True

Microsoft Entra ID (felhasználói bejelentkezés)

Hitelesítési azonosító: oauthAuthorizationCode

Alkalmazható: Minden régió

Jelentkezzen be a célügynök Microsoft Entra ID alkalmazásán keresztül (engedélyezési kódfolyamat), és küldje el a bejelentkezett fiók delegált tulajdonosi jogkivonatát. Minden ezzel a kapcsolattal végrehajtott hívás a kapcsolatba bejelentkezett fiókot használja, nem az ügynökkel csevegő személyt. A jogkivonat felhasználó nevében történő cseréjéhez az ügynöknek konfigurálnia kell az alárendelt delegált engedélyeket és hozzájárulásokat.

Ez nem megosztható kapcsolat. Ha a power app meg van osztva egy másik felhasználóval, a rendszer kérni fogja, hogy hozzon létre új kapcsolatot.

Név Típus Description Required
Tenant karakterlánc A célügynök Microsoft Entra ID alkalmazás bérlőazonosítója. True
Ügyfélazonosító karakterlánc A célügynök Microsoft alkalmazásazonosítója. Használja az ügynök saját alkalmazását, hogy az ügynök kicserélhesse a delegált jogkivonatot a felhasználó nevében. True
Titkos ügyfélkód securestring A célügynök Microsoft Entra ID alkalmazásának titkos ügyfélkódja. True
Erőforrás URL-címe karakterlánc A delegált jogkivonat célközönsége. A célügynök Microsoft alkalmazásazonosítójának (GUID) kell lennie, amely megegyezik az ügyfélazonosítóval: Microsoft Entra csak a GUID-t fogadja el, amikor egy alkalmazás jogkivonatot kér magának. True

Nincs hitelesítés

Hitelesítési azonosító: névtelen

Alkalmazható: Minden régió

Hívja meg a célügynök végpontját hitelesítési fejléc nélkül. Ezt csak olyan ügynökökkel használja, amelyek kifejezetten fogadnak névtelen hívásokat.

Ez megosztható kapcsolat. Ha a power app meg van osztva egy másik felhasználóval, a kapcsolat is meg van osztva. További információ: Összekötők áttekintése vászonalapú alkalmazásokhoz – Power Apps | Microsoft Docs

Alapértelmezett [ELAVULT]

Alkalmazható: Minden régió

Ez a beállítás csak olyan régebbi kapcsolatokhoz használható, amelyeknek nincs explicit hitelesítési típusuk, és csak a visszamenőleges kompatibilitást biztosítják.

Ez nem megosztható kapcsolat. Ha a power app meg van osztva egy másik felhasználóval, a rendszer kérni fogja, hogy hozzon létre új kapcsolatot.

Műveletek

Tevékenység küldése ügynöknek

Az Activity Protocol hasznos adatait továbbítja az ügynök végpontjának a(z) {agentEndpoint}/api/messages címen. Ha a kapcsolat Microsoft Entra ID OAuth-ot használ, a jogkivonat célközönségének (a kapcsolat erőforrás-URL-címének) meg kell egyeznie a célügynök által várt célközönségmel (Bot Framework-képesség hitelesítési mintája); ügynökönként egy kapcsolatot kell létrehoznia, ha a célközönségek eltérőek. Az összekötő továbbítja a tevékenység hasznos adatait as-is, és nem állítja be a "deliveryMode" értéket; az ügynök aszinkron módon (normál kézbesítéssel) válaszol, ha a posTing választevékenységeket küld a bejövő tevékenységhez megadott "serviceUrl"-nek.

Tevékenység küldése ügynöknek

Műveletazonosító:
SendActivity

Az Activity Protocol hasznos adatait továbbítja az ügynök végpontjának a(z) {agentEndpoint}/api/messages címen. Ha a kapcsolat Microsoft Entra ID OAuth-ot használ, a jogkivonat célközönségének (a kapcsolat erőforrás-URL-címének) meg kell egyeznie a célügynök által várt célközönségmel (Bot Framework-képesség hitelesítési mintája); ügynökönként egy kapcsolatot kell létrehoznia, ha a célközönségek eltérőek. Az összekötő továbbítja a tevékenység hasznos adatait as-is, és nem állítja be a "deliveryMode" értéket; az ügynök aszinkron módon (normál kézbesítéssel) válaszol, ha a posTing választevékenységeket küld a bejövő tevékenységhez megadott "serviceUrl"-nek.

Paraméterek

Név Kulcs Kötelező Típus Description
Ügynökvégpont URL-címe
 agentEndpoint True string

A cél Microsoft Ügynökök SDK/Bot Framework végpontjának alap URL-címe (példáulhttps://my-agent.azurewebsites.net). Az összekötő hozzáfűzi az /api/üzeneteket.
object

Válaszok

response
object

Definíciók

objektum

Ez az "objektum" típus.