Agent 365:n havaittavuuden käsitteet

Tämä artikkeli kertoo Agent 365 -havaittavuuden takana olevasta tietomallista ja siitä, mitä telemetrian agentit lähettävät, kuka voi lähettää, minne tiedot päätyvät ja mitkä rajoitukset niitä koskevat. Nämä käsitteet koskevat kaikkia integrointipolkuja, joita ovat Microsoft OpenTelemetry Distro, the Agent 365 SDK ja suora OTel.

Integrointipolun valitseminen

Kolme polkua lähettää saman aikavälin tietomallin Agent 365:een. Valitse yksi:

• Microsoft OpenTelemetry Distro - suositellaan uusille integroinneille. Yhtenäinen havaittavuuden SDK esimerkiksi Agent 365:ssä, Microsoft Foundryssa ja Azure Monitorissa.
• Agent 365 SDK (havaittavuuden SDK) – aiempi SDK. Toimii edelleen ilman muutoksia, mutta ei ole enää suositeltu polku uusille integroinneille. Siirto-ohjeet nykyisille SDK:n käyttäjille ovat tulossa.
• Suora OTel – käsittelemätön OTLP/HTTP-polku. Käytä tätä vain, jos sinulla on jo OpenTelemetry-putki käytössä, agentin kehys ei voi käyttää Agent 365 SDK:ta tai agentti on tehty ohjelmointikielellä, jota SDK ei vielä tue (kuten Java).

Alla kuvatut tietomallit, käyttäjätietomallit, laajuudet, rajoitukset ja tulevat ympäristöt koskevat kaikkia polkuja.

Sanasto

• Sovellustunnus (appId): Sovellustunnus, joka myönnetään, kun Microsoft Entra -sovellus tai Microsoft Entra -agentin tunnuksen käyttäjätiedot rekisteröidään.
  • Sama kuin OAuth client_id, ei Microsoft Entran objektitunnus.
  • Näissä ohjeissa agentin tunnus ja suunnitelman tunnus tarkoittavat appId-tunnusta.
• Keskustelu: Looginen ketju agentin vuorovaikutuksista, kuten Teams-keskusteluketju.
  • Tunnistamisperuste: gen_ai.conversation.id.
  • Suorituksen ensisijainen liitosavain.
• Kanava: Ympäristö, jossa agentti suoritetaan, esimerkiksi msteams, outlook tai web.
• Suoritus: Yksi käyttäjän viesti sisään, yksi agentin vastaus ulos. OTelin puuna mallinnettu, ja kattaatraceId-tunnuksen jakamisen.

Toimintatapa

Lisätietoja Agent 365:n yleiskatsauksesta ja siitä. mihin telemetria ohjataan, on kohdassa Microsoft Agent 365:n yleiskatsaus.

Telemetria lähetetään OpenTelemetry-jäljitystietoina seuraavasti:

• Aikavälien puu kuvaa yhden suorituksen (yksi käyttäjän viesti sisään, yksi agentin vastaus ulos).
• Jokainen aikaväli kuvaa yksittäistä vaihetta, joka voi olla esimerkiksi ylimmän tason agentin kutsu, LLM-kutsu, työkalun kutsu tai lopullinen vastaus.

Tiedonkulku

   Your agent code

        |
        v

   +---------------+
   | OTel SDK or   |
   | raw HTTP      |
   +---------------+

        |
        v

   POST /traces  agent365.svc.cloud.microsoft

        |
        v

  +-------------------------------------+
  | Microsoft Defender                  |
  |   (CloudAppEvents table             |
  |    in advanced hunting)             |
  |                                     |
  | Microsoft Purview                   |
  |                                     |
  | Microsoft 365 admin center          |
  |   (agent inventory and              |
  |    security views)                  |
  +-------------------------------------+

Käyttäjätietomallit

Lisätietoja täydellisen selityksen agentin käyttäjätietomalleista (tavallinen Microsoft Entra -sovelluksen rekisteröinti verrattuna Microsoft Entra -agentin tunnuksen agentin käyttäjätietojen suunnitelmaan, mukaan lukien tekoälytiimin jäsenet) on kohdassa Agent 365 -kehityksen aloittaminen. Valittu käyttäjätietomalli määrittää, mitä todennustyönkulkua ja päätepistettä käytetään.

Jos agentilla ei ole Microsoft Entra -rekisteröintiä, se ei voi käyttää näitä reittejä suoraan. Tunnista agentti vaihtoehtoisten tunnusmääritteiden avulla (katso Määritteen viite) ja ole yhteydessä Agent 365 -tiimiin sopivan saapumispolun löytämiseksi.

Todentaminen

Todennus haarautuu sen mukaan, todentaako palvelu itsensä vai tehdäänkö todennus käyttäjän puolesta. Haara määrittää OAuth-työnkulun, oikeuden sisältävän tunnuksen vaatimuksen ja URL-osoitteen reitin.

• Palvelu todentaa itsensä: Ei kirjautunutta käyttäjää – autonominen, aikataulutettu tai tapahtumaan perustuva.

  • OAuth-työnkulku: Palvelusta palveluun (S2S) -asiakasohjelman tunnistetiedot.
  • Tunnusvaatimus: roles.
  • URL-osoitteen reitti: /observabilityService/....

• Palvelu tekee todennuksen käyttäjän puolesta: Tekoälytiimin jäsenille tai agentin omalle käyttäjätilille.

  • OAuth-työnkulku: OBO (On-behalf-of ), todentautuminen jonkun nimissä.
  • Tunnusvaatimus: scp.
  • URL-osoitteen reitti: /observability/....

Sama agenttisovellus voi osallistua molempiin työnkulkuihin, esimerkiksi tekoälytiimin jäsen voi suorittaa myös yöaikaisen autonomisen yhteenvedon välittämisen. Lisätietoja on kohdissa Autonomisen sovelluksen OAuth-työnkulku ja On-Behalf-Of-vuo.

Täydelliset tunnusreseptit kullekin käyttäjätietomallin ja työnkulun yhdistelmälle löytyvät Todennusreseptit-kohdasta.

Agentin käyttäjätiedot on sidottu URL-osoitteeseen

URL-osoitteen {agentId}-kohteen on oltava sama kuin kutsuvan sovelluksen appId (appid- tai azp-vaatimus tunnuksessa). Ristiriidat palauttavat 403 Forbidden -viestin. Suunnitelmasta johdetuissa käyttäjätiedoissa {agentId} on agentin käyttäjätietojen appId, ei suunnitelman appId.

Lisäksi jokaisen lähetettävän aikavälin on määritettävä gen_ai.agent.id samalle appId-tunnukselle. Palvelin tarkistaa sisäisten tietojen agentin käyttäjätiedot todennetun agentin perusteella ja hylkää ristiriidat. Tämä vaihe estää eri agenttien aikavälien vahingossa tapahtuvan yhdistämisen yhteen pyyntöön.

Laajuudet ja suostumus

Laajuus (delegoitu) tai sovellusrooli (sovellus) on nimetty käyttöoikeus, jonka Microsoft Entra lisää käyttöoikeustietueeseen. Agent 365 -telemetriassa käyttöoikeus on Agent365.Observability.OtelWrite Agent 365:n havaittavuusresurssissa (käyttäjäryhmä 9b975845-388f-4429-889e-eab1ef63949c).

Sama käyttöoikeusnimi rekisteröidään molempiin tyyppeihin seuraavasti:

• Sovelluksen rooli autonomista (S2S / asiakasohjelman tunnistetiedot) työnkulkua varten. Päätyy roles-vaatimukseen. Valitsija on <resource>/.default.
• Delegoitu käyttöoikeus OBO-työnkululle. Päätyy scp-vaatimukseen. Valitsija on <resource>/Agent365.Observability.OtelWrite (tai <resource>/.default).

Agentti 365 paljastaa myös lukemisen käyttöoikeuden (Agent365.Observability.OtelRead), jota tekevät Agent 365:n telemetriasta kyselyjä. Useimmat kumppanit eivät tarvitse sitä. Nämä ohjeet kattavat vain käsittelyyn liittyvät asiat.

Käyttöoikeuden lisääminen sovellukseen

• Microsoft Entra -sovelluksen vakiorekisteröinti: Lisää Azure-portaalissa Agent365.Observability.OtelWrite (sovelluksen rooli S2S:lle, edustajan laajuus) agentin sovelluksen rekisteröinnin Ohjelmointirajapinnan oikeudet -kohdassa.
• Suunnitelma: Microsoft Entra -agentin käyttäjätietojen suunnitelman pohjalta luodut agentit perivät suunnitelmassa määritellyt OAuth-oikeudet, joten vuokraajan järjestelmänvalvojan tarvitsee määrittää esivalmistelut vain kerran. Jokainen kyseisestä suunnitelmasta luotu agentti-instanssi saa oikeudet automaattisesti. Katso Periytyvien oikeuksien määrittäminen agentin käyttäjätietojen suunnitelmaa varten.

Vuokraajan suostumus

Ennen kuin tunnukset sisältävät roolin tai laajuuden, vuokraajan järjestelmänvalvojan on annettava suostumus asiakkaan vuokraajassa. Katso agenttien pääsyn myöntäminen Microsoft 365 -resursseihin.

Ilman suostumusta tunnuksen hankinta epäonnistuu virhekoodilla AADSTS65001 (käyttäjä tai järjestelmänvalvoja ei ole antanut suostumusta) tai tunnus myönnetään ilman roles / scp-vaatimusta, jolloin käytön päätepiste hylkää pyynnön virhekoodilla 403.

Suostumus myönnetään kerran vuokraajaa kohti. Se koskee kaikkia suunnitelmasta luotuja instansseja jatkossa. Suostumuksen uusiminen tarvitaan vain, kun suunnitelmaan lisätään uusi oikeus.

Rajoitukset ja pudotusehdot

Näiden rajoitusten tunteminen etukäteen estää yllätykset integroinnin aikana. Useimmat toiminnot tapahtuvat taustalla (ohjelmointirajapinta hyväksyy pyynnön, mutta tiedot eivät näy milloinkaan tulevissa toiminnoissa).

Siirtotason rajoitukset:

• api-version=1 on pakollinen jokaisessa pyynnössä.
• Pyynnön tekstiosan enimmäiskoko on 1 Mt. Tätä suurempien pyyntöjen vastauksena on 413 Payload Too Large.
• Näillä kahdella reitillä on erilliset määrärajoitukset. 429 noudattaa arvoa Retry-After (asetettu arvoksi 1 sekunti) ja viiveen vaihtelu.

Virhevastaukset:

• 403 Forbidden--tunnus puuttuu vaaditusta sovelluksen roolista / laajuudesta tai {agentId} URL-osoitteessa ei vastaa tunnuksen arvoa appid / azp.
• 413 Payload Too Large--teksti on suurempi kuin 1 Mt.
• 429 Too Many Requests--määrärajoitus saavutettu; noudata arvoa Retry-After: 1 ja vaihtele viivettä.

Pudotusehdot (HTTP hyväksyy pyynnön, mutta tiedot eivät näy jatkokäsittelyssä):

200 OK ei ole todiste käsittelystä. Käytä vahvistustyönkulkua varmistaaksesi, että tiedot saapuvat perille.

Tietojen näkyvyys

Hyväksynnän jälkeen aikavälit näkyvät kolmessa asiakaskokemuksessa. Kaikki kolme riippuvat sallitusta invoke_agent-aikavälistä suorituksen juuressa. Suorituksesta, jossa on vain aikavälit chat / execute_tool / output_messages, voi tehdä kyselyjä Defenderin edistyneellä uhkien etsinnällä (CloudAppEvents-taulukko), mutta se on näkymätön joka toisessa alla mainitussa ympäristössä.

Microsoft Defender. Agentin aktiviteetti (invoke_agent, execute_tool, chat) näkyy agentin aktiviteettinäkymissä. Vuokraajan järjestelmänvalvojat ja tietoturva-analyytikot voivat porautua yksittäisiin suorituksiin, työkaluihin ja päättelykutsuihin. Agentin aktiviteettinäkymät perustuvat invoke_agent-aikaväliin. Ilman sitä suoritus ei näy, vaikka aliaikavälit ovat edelleen kyseltävissä edistyneen uhkien etsinnän avulla. Edistyneen uhkien etsinnän näkymä – CloudAppEvents – hyväksyy kaikki toiminnot: ActionType ilmentää toimintoa (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer) ja kunkin aikavälin kentät ovat kohteen RawEventData sisällä. Asiakkaalle näkyvät kenttien nimet vastaavat suoraan lähetettyihin aikavälimääritteisiin: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id ja niin edelleen. Lisätietoja täydellisestä yhdistämismäärityksestä on kohdassa Määritteen viite.

Microsoft 365 -hallintakeskus. Agenttien aktiviteetti näkyy myös agenttien inventaario- ja suojausnäkymissä, joita vuokraajan järjestelmänvalvojat käyttävät agenttien hallinnassa omassa vuokraajassaan. Hallintakeskus käsittelee vain invoke_agent-rivit: Agentit, joille ei ole invoke_agent telemetriaa, eivät näy varastossa, ja suoritukset, jotka lähettävät vain kohteet chat / execute_tool / output_messages ovat tässä näkymättömiä. Hallintakeskuksen lukemat määritteet (agentin tunnus, agentin nimi, suunnitelman tunnus, kutsujan käyttäjätiedot, keskustelun tunnus, kanava, virheen tila) ovat kaikki peräisin invoke_agent-aikavälistä.

Microsoft Purview. Agentin aktiviteetti on myös näkyvissä vaatimustenmukaisuuden järjestelmänvalvojille Microsoft Purview'ssa. He voivat määrittää tiedonkäsittely- ja käytäntösääntöjä agenttien suorituksille (tietojen menetyksen estäminen, säilytys, viestinnän vaatimustenmukaisuus ja vastaavat). Määritteet, joihin Purview-käytännöt perustuvat (agentin tunnus, suunnitelman tunnus, kutsujan käyttäjätiedot, keskustelu/kanava, pyyntö- ja vastausviestit) saadaan kaikki invoke_agent-aikavälistä ja sen alitasoilta.

Seuraavat vaiheet

• Määritteen viite – Määritekohtainen määritys, vaatimukset ja arvon valitsemisen ohjeet.
• Vianmääritys – Vastaanoton tarkistaminen, yleiset sudenkuopat ja virhevasteet.