Svibanj je ovdje, a i Microsoft 365 E7 i Agent 365 sada su životna činjenica. Mi smo svoje učinili početni izgled na Agent 365 API-jima na Graphu prošlog mjeseca, a “GA” donosi neke dobre i neke loše vijesti. Dobra vijest je da sada imamo pristup metodama PATCH i POST, što nam omogućuje izvođenje operacija poput blokiranja ili dodjele određenog agenta. Loša vijest je da nam je potrebna licenca Agent 365 kako bismo iskoristili bilo koju od krajnjih točaka, uključujući metode GET/LIST. I niti jedna od krajnjih točaka API-ja trenutno ne podržava dozvole za aplikacije, što je korak unatrag u odnosu na prije mjesec dana.
Nedostatak podrške za dopuštenja aplikacija znači da je automatizacija izazovna, iako još uvijek možemo istražiti neke osnovne skupne operacije putem dopuštenja delegiranja. Graph SDK za PowerShell preferiram takve scenarije, iako u ovom slučaju nema velike razlike jer nijedno od dostupnih izdanja još ne nudi cmdlete za te nove krajnje točke. Stoga se oslanjamo na Invoke-MgGraphRequest cmdlet umjesto toga, za bilo koji od primjera koje pokrivamo u nastavku.
Sadržaj objave
Skupno omogućivanje ili onemogućavanje agenata
S obzirom na mnoge neizvjesnosti koje okružuju integraciju AI/agenata u Microsoft 365 posjedu organizacije, razumno je očekivati da će neki korisnici izravno blokirati (neke) agente. Srećom, to se sada može lako učiniti skupno putem blokirati metoda. U donjem primjeru koristimo ga za blokiranje svih agenata koji nisu Microsoftovi (tj. agenata koje su izdali dobavljači trećih strana).
Za početak nam naravno treba pristupni token s dovoljnim dopuštenjima, naime CopilotPackages.ReadWrite.All. Uloga administratora također mora biti dodijeljena korisniku na kojeg ste prijavljeni, na primjer Administrator AI jedan. U našem scenariju koristimo SDK-ove Connect-MgGraph cmdlet za rukovanje zahtjevima dopuštenja:
Connect-MgGraph -Scopes CopilotPackages.ReadWrite.All
Zatim možemo dohvatiti popis svih agenata (“paketi kopilota”):
$packages = Invoke-MgGraphRequest -Method GET -Uri "https://graph.microsoft.com/beta/copilot/admin/catalog/packages?`$filter=supportedHosts/any(x:x eq 'Copilot')" -OutputType PSObject
Postoji nekoliko načina na koje možemo filtrirati: možemo se osloniti na Izdavač polje, ili još bolje, filtrirajte prema tip vlasništvo i a prva strana vrijednost. Čini se da niti jedno svojstvo nije podržano za filtriranje na strani poslužitelja, pa moramo raditi stvari na glup način:
#Filter third-party agents $3p = $packages.value | ? $_.Type -eq "thirdParty"
Kada imamo popis, možemo iskoristiti metodu blokiranja za svakog agenta/paket:
#Block all third-party packages
foreach ($package in ($3p | ? !$_.isBlocked))
Write-Verbose "Blocking package: $($package.Id) ($($package.DisplayName))"
Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/beta/copilot/admin/catalog/packages/$($package.Id)/block" -Verbose:$false
Da poništimo radnju i deblokiramo sve agente treće strane, možemo upotrijebiti sljedeće:
#Unblock all third-party packages
foreach ($package in ($3p | ? $_.isBlocked))
Write-Verbose "Unblocking package: $($package.Id) ($($package.DisplayName))"
Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/beta/copilot/admin/catalog/packages/$($package.Id)/unblock" -Verbose:$false
Skupno dodjeljivanje/uvođenje agenata
Drugi scenarij koji želimo pokriti ovdje je proces dodjele (činjenja dostupnim) ili implementacije (instalacije) agenata za skupinu korisnika, skupno. Da bismo to postigli, prvo trebamo skup korisnika i skup agenata s kojima ćemo raditi, u skladu s tim. Za korisnike možemo iskoristiti robusne mogućnosti filtriranja na strani poslužitelja, koje bi trebale pokriti većinu osnovnih scenarija. Na primjer, uzmite skup (omogućenih) korisnika unutar odjela:
$users = Get-MgUser -All -Filter "accountEnabled eq true and userType eq 'Member' and department eq 'sales'" -Property Id,DisplayName | select Id,DisplayName
Trebat će nam samo korisnički Iddakle displayName Svojstvo je iznad čisto izborno i korisno samo ako želite pregledati popis prije izvršavanja koda. Naravno, po potrebi možete prilagoditi filtar i skup svojstava, na primjer navesti samo korisnike s dodijeljenom licencom za Agent 365.
Nakon što se dobije skup korisnika, moramo pripremiti JSON-formatirani sadržaj koji predstavlja a packageAccessEntity objekt. Kao što je objašnjeno u našem prethodnom članku, četiri svojstva kontroliraju pristup agentu. Je li agent dostupan kontrolira se putem dostupanTo i dozvoljeniKorisniciIGrupe svojstva, dok raspoređenTo i pridobitiKorisnikeIGrupe kontrolirati raspoređivanje agenata. Na primjer, sljedeći kod će pripremiti korisni teret za scenarij implementacije agenata skupu korisnika koje smo gore definirali:
#Set the allowedUsersAndGroups property accordingly
$hash = @
deployedTo = "acquiredForSome"
acquireUsersAndGroups = @(
foreach ($user in $users)
@
resourceType = "user"
resourceId = $user.Id
)
Osim toga, trebat će nam i skup agenata za dodjelu/postavljanje. Kao što je već spomenuto, mogućnosti filtriranja su malo ograničene, stoga koristite filtre na strani klijenta za najbolji rezultat (ili definirajte popis ručno). Kao i gore, trebamo samo Id agenta, ali mogu se pojaviti dodatni podaci koji će vam pomoći uključiti/isključiti agente prema potrebi. Na primjer, ona je kako postići da sve agente objavi određeni dobavljač treće strane:
$packages1 = $packages.value | ? $_.Publisher -eq "Atlassian.com"
Uz to, spremni smo masovno implementirati skup agenata na naš popis korisnika. The PATCH metoda se koristi za ovu operaciju, s jednim zahtjevom po agentu. Dok implementiramo svakog agenta na isti skup korisnika, možemo ponovno koristiti korisni teret za svako izvršenje:
foreach ($package in $packages1) ConvertTo-Json) -Verbose:$false
Čini se da trenutačno postoje problemi s replikacijom s Graph API-jem kada su u pitanju četiri svojstva koja koristimo za kontrolu dodjele/pokretanja agenata. Iako bi gornji zahtjevi trebali rezultirati a 204 Bez sadržaja odgovoru, nikakve promjene u vrijednosti navedenih svojstava nisu uočene na sljedećim GET pozivima. Nasuprot tome, korisničko sučelje Agent 365 unutar M365 centra za administraciju savršeno odražava promjene:
Kao napomenu, pored navedenog 403 Zabranjeno pogreška zbog nedostatka Agent 365 SKU (“Korisnik mora imati licencu za Agent 365 kako bi koristio API-je Agent 365 Graph”), možete naići na a 405 Metoda nije dopuštena greška u scenarijima u kojima je potreban pristanak. Na primjer:
"error":
"code": "UnknownError",
"message": "\"StatusCode\":405,\"Message\":\"Admin consent has not been granted for AAD application bdc49611-ba72-43b9-a868-652243121c10. The following permissions are missing: email, offline_access, openid, profile\"",
"innerError":
"date": "2026-05-08T09:23:43",
"request-id": "8e23a844-11f2-4742-a1ad-c41d59d3cfaf",
"client-request-id": "6f7e3445-e1b8-f2a6-95f7-8287c87ea871"
API-ji Agent 365 trenutačno ne nude nikakav način zaobilaženja ovoga, pa trebate koristiti standard Oauth2PermissionGrant metode (vidi na primjer ovaj članak), ili UI umjesto toga. S jedne strane, ovo predstavlja izazov za automatizirane scenarije, ali s druge strane, to je zgodna prepreka koja može dovesti do potrebe za dodatnim odobrenjima i time spriječiti nenamjernu zlouporabu funkcionalnosti.
Gore navedeni primjer može se lako generalizirati na druge scenarije. Da biste skup agenata učinili dostupnim za korištenje, umjesto da ih izravno instalirate, ažurirajte nosivost na sljedeće:
$hash = @
availableTo = "allowedForSome"
allowedUsersAndGroups = @(
foreach ($user in $users)
@
resourceType = "user"
resourceId = $user.Id
)
U nastavku su sažeti neki drugi primjeri:
- Da bi agent bio dostupan svim korisnicima, ažurirajte vrijednost dostupanTo do dozvoljenoZaSve.
- Da biste implementirali agenta za sve korisnike, ažurirajte vrijednost raspoređenTo do stečenoZaSve.
- Da biste poništili promjene statusa dostupnosti, ažurirajte vrijednost dostupanTo do dozvoljenozanitko.
- Da biste deinstalirali agenta za sve korisnike, ažurirajte vrijednost raspoređenTo do stečenoZaNitko.
Za scenarije sve/ništa, ne morate dati popis dozvoljeniKorisniciIGrupe.
Grupno ponovno dodijelite vlasnika agenta
Posljednji scenarij koji želimo pokriti odnosi se na skupnu preraspodjelu vlasnika za određenog agenta. Ovo je relevantno samo kada je agenta stvorio korisnik u vašoj organizaciji u različitim iskustvima u sustavu SharePoint, PowerApps i tako dalje (agent tip je podijeljeno). Ako korisnik napusti tvrtku/njegov račun bude uklonjen, agent je sada bez vlasnika.
Da bismo dobili popis svih agenata bez vlasnika, možemo koristiti sljedeće (opet nema podrške za filtriranje na strani poslužitelja):
$packages = Invoke-MgGraphRequest -Method GET -Uri "https://graph.microsoft.com/beta/copilot/admin/catalog/packages?`$filter=supportedHosts/any(x:x eq 'Copilot')" -OutputType PSObject $OwnerlessPackages = $packages.value | ? $_.type -eq 'shared' -and !$_.OwnerId
Možda imate i neke agente s “null” ownerId vrijednost od 00000000-0000-0000-0000-000000000000slobodno prilagodite gornji filtar da uključi i njih.
Da biste dodijelili novog vlasnika, upotrijebite reassign metodato je POST zahtjev protiv /packages/id/reassign krajnja točka. Mora se navesti JSON sadržaj koji označava novog vlasnika. Po agentu je podržan samo jedan vlasnik, a grupe nisu dopuštene. Evo primjera zahtjeva:
#Assigning owner to ownerless packages
foreach ($package in $OwnerlessPackages)
Write-Verbose "Assigning owner to package $($package.DisplayName)"
Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/beta/copilot/admin/catalog/packages/$($package.Id)/reassign" -Body (@userId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Uspješno izvršenje treba biti označeno a 204 Bez sadržaja odgovor, iako se čini da mi proces ne uspijeva ni u API-ju ni u korisničkom sučelju… pa za sada nemojte zadržavati dah na ovome 🙂
I time možemo zatvoriti trenutni članak. Nakon što Microsoft uvede podršku za dopuštenja aplikacija, možemo se vratiti na Agent API i ispitati neka robusnija rješenja, prikladna za automatizaciju.