Agentti 365 havaittavuuden attribuuttiviite

Tämä on Agentti 365:n käyttöputken kanoninen attribuutti-ominaisuus kerrallaan. Jokainen Agent 365:n vastaanottama sära – olipa se sitten Microsoft OpenTelemetry Distro, Agent 365 SDK tai direct OTel lähettämä – on noudatettava sitä. Jokainen merkintä listaa ne operaatiotyypit, joihin attribuutti sovelletaan, onko se pakollinen, kentän nimi, johon arvosi saapuu edistyneissä hakukyselyissä (jos sellainen on), sekä vaikutuksen, jos sen ohitat.

Jos käytät SDK:ta tai jakelua, SDK lähettää nämä ominaisuudet puolestasi, ja Picking values -osio pätee vain, kun sinun täytyy ohittaa oletus. Jos olet suoralla OTel-polulla, lähetät kaikki attribuutit käsin; ohjeet niiden kokoamiseen pyynnöksi katso Integraatio-opas.

Attribute table

Kaikki arvot lähetetään muodossa stringValue - token-lukujen on "42" oltava (ei 42); porttien on "443" oltava (ei 443).

Operaatio Legenda.IA = invoke_agent, ET = execute_tool, CH = chat, OM = output_messages, All = pätee jokaiseen operaatioon.

Required legend.

  • M: mandatory.
  • M*1: pakollinen vain ruumiillistuneille agenteille (agentilla on oma Entra-agenttitunnus -käyttäjätili).
  • M*2: pakollinen vain agenttien välisissä puheluissa.
  • M*3: pakollinen vain ei-juurisille. Juurella invoke_agent ei ole vanhempaa.
  • O*4: valinnainen, merkityksellinen vain, kun span-tila on Error.
  • O: optional.
  • Ei vastausta: älä lähetä. Agentti 365 täyttyy automaattisesti.

"RawEventData-kenttä" -sarakkeessa nimetään JSON-avain CloudAppEvents.RawEventData sen sisällä, joka on kanoninen edistyneen metsästyksen kysely Verifying ingestion parsessissa. Tyhjä solu tarkoittaa, että attribuutti on not näkyvissä CloudAppEvents tänään – sinun pitäisi silti lähettää se (Vaadit-sarakkeen mukaan), koska Agentti 365 käyttää sitä vastaanottoon, vanhempien ratkaisuun ja Microsoft Defender:n agenttitoimintojen näkymiin, mutta sitä ei voi suoraan kysyä Microsoft Defender edistyneestä metsästyksestä nykyään.

Note

Agentti 365 täyttää automaattisesti staattiset tietuekentät (Id, RecordType, WorkloadUserType, Version, ) ja generoidut pyyntö-/vastaustunnukset.

Attribute Applies to Required RawEventData field Huomautuksia / vaikutus, jos puuttuu
gen_ai.operation.name All M Operation Yksi invoke_agent, execute_tool, chat, . output_messages Kanta on laskenut, jos se puuttuu tai ei tunnisteta.
microsoft.tenant.id All M OrganizationId URL {tenantId} on auktoritatiivinen. Jos asetat tämän ja se ei hyväksy, pyyntö hylätään (403).
gen_ai.agent.id All M TargetAgentId (IA, myös ylin AgentIdtaso); AgentId (ET, CH) Soittosovelluksen appId. Täytyy vastata URL-osoitetta {agentId} ja todennuksella varustettua sovellusta. Mismatch palauttaa 403.
gen_ai.agent.name All M TargetAgentName (IA); AgentName (ET, CH) Defender / admin center näyttävät raaka GUID nimen sijaan, jos puuttuu.
microsoft.a365.agent.blueprint.id All M TargetAgentBlueprintID (IA); AgentBlueprintId (ET, CH) Piirustuksen appId. Tavallisissa Entra-sovelluksissa, joissa ei ole blueprinttia, käytä agentin appId:tä uudelleen. Blueprint-roll-upit hallintokeskuksessa rikkovat muuten.
gen_ai.agent.description All O -- Yksityiskohtainen näkymä hallintokeskuksessa on tyhjä agentille.
gen_ai.agent.type All O PlatformTargetAgentType (IA); PlatformAgentType (ET); CopilotEventData.PlatformAgentType (CH) Tunniste identiteettijärjestelmällesi, yhdistettynä microsoft.a365.agent.platform.id siihen, kun agentilla ei ole Entra-rekisteröintiä. Vapaamuotoinen teksti; Valitse arvo, joka yksilöllisesti tunnistaa identiteettijärjestelmäsi. Jätä pois, kun agentilla on Entra-rekisteröinti – Agentti 365 luokittelee automaattisesti. Älä käytä Microsoft-varattuja arvoja (ks. Picking values).
microsoft.a365.agent.platform.id All O PlatformTargetAgentId (IA, myös ylin AlternateIdtaso); PlatformAgentId (ET, CH) Agentin yksilöllinen tunniste ei-Entra-identiteettijärjestelmässäsi. Free-form text. Aseta yhdessä .gen_ai.agent.type Jätä pois, kun agentilla on Entra-rekisteröinti. Katso Arvojen valinta.
gen_ai.conversation.id All M ConversationId (IA, ET); CopilotEventData.ConversationId / CopilotEventData.ThreadId (CH) Pääliitosavain juoksuun. Ilman sitä juoksu ei näy Defender agent-activity -näkymissä tai hallintokeskuksessa.
microsoft.channel.name All M ChannelName (IA, ET) Pinta, jolla agentti juoksee. Käytä lyhyttä pientä merkkiä; Defender / Admin Center -suodattimien käyttämät kanoniset arvot ovat nykyään msteams ja outlook. Mukautetut merkkijonot (esimerkiksi web, <your-product-name>) hyväksytään, mutta ne eivät käänny sisäänrakennetuissa kanavasuodattimissa. Sama arvo jokaisella jaksolla. Katso Arvojen valinta.
microsoft.channel.link All O -- Channel deep-link.
microsoft.session.id All O SessionIdentity Sessio kääntyy tyhjäksi, jos se puuttuu.
microsoft.session.description All O -- Session description.
microsoft.conversation.item.link All O -- Syvälinkki viestiin.
correlation.id All O -- Cross-service tracing. Tätä ei löydy edistyneessä metsästyksessä nykyään.
operation.source All O InvokeSource (IA) Tunniste SDK:lle / palvelulle, joka lähettää telemetriaa. Voi olla resurssi-attribuutti.
client.address I, ET, CH M ClientIP (IA, ET) Caller IP. IP-pohjainen tutkinta estetty, jos se on tyhjä.
server.address I, ET, CH M ServerAddress (IA, ET) Päätepiste, johon palvelusi soittaa.
server.port I, ET, CH M ServerPort (IA) Merkkijonoilla koodattu (esimerkiksi "443").
user.id IA M UserKey Microsoft Entra -objektitunnus ihmiskutsujalle. "Kuka johti tätä agenttia" on tyhjä ilman sitä.
user.email IA O UserId Soittajan UPN.
user.name IA O -- Soittajan näytynimi.
gen_ai.input.messages IA, CH M -- Pyydä hyötykuormaa (JSON-merkkijono). Pyydystetty alavirran analyysiä varten, mutta ei vielä noussut pintaan edistyneessä metsästyksessä.
gen_ai.output.messages I, CH, OM M -- Vastekuorma (JSON-merkkijono).
gen_ai.execution.type IA O -- Yksi HumanToAgent, Agent2Agent, EventToAgent.
microsoft.a365.agent.thought.process IA, CH O -- Vapaan tekstin päättely / ajatusketju.
gen_ai.author.app.id OM O -- Microsoft Entra -sovelluksen tunnus sovelluksesta, joka loi agentin.
gen_ai.tool.name ET M ToolName Tool name. Defender-työkalun käyttönäkymät ovat tyhjiä, jos niitä puuttuu.
gen_ai.tool.type ET M ToolType Yksi , , , , , functionPower Platform ConnectorMCP Server, , . APIKnowledge Sourcebing_groundingcode_interpreterfile_search
gen_ai.tool.call.id ET M ToolId Tämän työkalukutsun tunniste.
gen_ai.tool.call.arguments ET M -- Työkaluargumentit (JSON-merkkijono). Vangittu, mutta ei vielä noussut esiin edistyneessä metsästyksessä.
gen_ai.tool.call.result ET M -- Työkalun tulos (JSON-merkkijono).
gen_ai.tool.description ET O ToolDescription Tool description.
gen_ai.tool.server.name ET O -- Työkalupalvelimen isäntänimi. Aseta tämä attribuutti MCP-työkaluille.
gen_ai.request.model CH M -- Mallin nimi (esim. gpt-4o). Vangittu, mutta ei vielä noussut esiin edistyneessä metsästyksessä.
gen_ai.provider.name CH M -- Palveluntarjoajan nimi (esimerkiksi, openai).
gen_ai.usage.input_tokens CH O -- Syötetokenien määrä, merkkijonoilla.
gen_ai.usage.output_tokens CH O -- Ulostulotokenien määrä, merkkijonolla koodattuna.
gen_ai.response.finish_reasons CH O -- Finish reason(s).
microsoft.a365.caller.agent.id IA M*2 -- Soitan agentin appId:lle. Vaaditaan agentti-agentin välisessä keskustelussa.
microsoft.a365.caller.agent.name IA M*2 -- Kutsun agentin näyttönimeä.
microsoft.a365.caller.agent.blueprint.id IA M*2 AgentBlueprintId Soitan agentin blueprint appId:hen. Vaaditaan ruumiillistuneelle A2A:lle.
microsoft.a365.caller.agent.user.id IA M*2 -- Soitan agentin käyttäjätunnukselle.
microsoft.a365.caller.agent.user.email IA M*2 -- Soitan agentti UPN:lle.
microsoft.a365.caller.agent.platform.id IA N/A -- Varattu ei-Entra-vaihtoehtoisille ID:ille.
gen_ai.caller.agent.type IA N/A -- Agentti 365 luokittelee automaattisesti.
microsoft.agent.user.id I, ET, CH M*1 TargetAgentUserKey (IA); UserKey (ET, CH) Microsoft Entra -objekti-ID agentin omalle käyttäjätilille. Vaaditaan tekoälytiimikavereilta / ruumiillistuneilta agenteilta.
microsoft.agent.user.email I, ET, CH O*1 UserId (ET, CH) Agentin käyttäjätilin UPN.
span.SpanId All M OpId OTel SDK lähettää tämän.
span.ParentSpanId All M*3 ParentId Vaaditaan vain ei-juuri-jänteisiin; Juurella invoke_agent ei ole yhtään.
span.StartTimeUnixNano All M Ylätaso TimeGenerated (myös CreationTime )RawEventData Unix epoch nanos merkkijonona.
span.EndTimeUnixNano All M CompletionTime (IA, ET); CopilotEventData.CompletionTime (CH) Kestoa ei voi laskea, jos se puuttuu.
span.Status.Message All O*4 ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) Epäonnistuneiden suoritusten juurisyy on tyhjä, jos se puuttuu.
span.Status.Code All O*4 ErrorType (IA); CopilotEventData.ErrorType (CH) Virhekategoria tyhjä, jos puuttuu.

Note

Useat lähettämäsi attribuutit (kuten työkaluargumentit / tulokset, malliparametrit ja kanavan syvälinkit) hyväksytään Agent 365:n toimesta ja niitä käytetään Microsoft Defender-näkymien alavirran yhteydessä, mutta niitä ei vielä paljasteta CloudAppEvents.RawEventData JSON-avaimena. Aseta ne joka tapauksessa vaaditun sarakkeen mukaan – ne saatetaan lisätä metsästyskuormaan tulevassa julkaisussa.

Arvojen valitseminen, kun sinulla ei ole luonnollista arvoa

Jotkut vaaditut attribuutit kuvaavat käsitteitä, joita ei välttämättä ole agentin arkkitehtuurissa. Jos luonnollista arvoa ei ole, tässä on, mitä asetat sen sijaan. Älä jätä pakollista kenttää tyhjäksi – jopa nollan GUID piilottaa juoksusi joiltakin asiakaskohtaisilta kokemuksilta.

Kysymys / skenaario Field(s) Mitä asettaa
Agenttini on standardi Entra-sovelluksen rekisteröinti (ei rakennettu Entra-agenttitunnus blueprintin pohjalta). gen_ai.agent.id Entra-sovelluksen appId.
↑ Sama tilanne microsoft.a365.agent.blueprint.id Käytä samaa arvoa uudelleen kuin gen_ai.agent.id (agentin appId). Skeema vaatii ei-tyhjän arvon; Agent appId:n uudelleenkäyttö on turvallinen oletus, kun blueprinttia ei ole.
Agenttini on rakennettu Entra-agenttitunnus blueprintista – yksi tai useampi agenttiidentiteetti, jotka on luotu samasta blueprintista. gen_ai.agent.id Agentin identiteetin appId ( instanssi appId, ei blueprintin).
↑ Sama tilanne microsoft.a365.agent.blueprint.id Piirustuksen appId. Kaikki saman blueprintin pohjalta luodut instanssit jakavat tämän arvon.
Soittaja on ihmiskäyttäjä, ei toinen agentti. Kaikki microsoft.a365.caller.agent.* ja gen_ai.caller.agent.* ominaisuudet Omit. Ne ovat pakollisia vain agenttien välisissä tilanteissa.
Agentti-agentti -järjestelmässä: kutsuva agentti on tavallinen Entra-sovellus (ei blueprinttia). microsoft.a365.caller.agent.blueprint.id Käytä soittajan appId:tä uudelleen.
Agenttini ei ole tekoälytiimikaveri – sillä ei ole omaa käyttäjätiliä vuokralaisessa. Kaikki microsoft.agent.user.* ominaisuudet Omit. Ne ovat pakollisia vain, jos agentilla on oma Entra-agenttitunnus -käyttäjätili.
Agentillani ei ole käsitystä sessiosta enempää kuin yhdellä kierroksella. microsoft.session.id Valinnainen – jätä pois. Jos haluat, että jokainen pelikerta on oma sessio, aseta GUID-kuva per kierros.
Agentillani ei ole käsitystä keskustelusta (kertaluontoinen, kansalaisuudeton). gen_ai.conversation.id Luo uusi GUID per pelikerta. Kenttä on pakollinen; ohittamalla se poistuu ajon Defender agent-activity -näkymistä ja Microsoft 365 -hallintakeskus -toiminnosta.
Soittajalla ei ole IP-osoitetta (esimerkiksi autonominen ajoitettu laukaisin). client.address Käytä vakaata paikkamerkkiä, jota hallitset (esimerkiksi "0.0.0.0"). Kenttä on pakollinen; tyhjä arvo poistaa suorituksen IP-pohjaisista tutkimuspivoteista.
Agentti toimii prosessissa; Erillistä "palvelinta" ei kutsuta. server.address / server.port Käytä koneen isäntänimeä, joka ajoi agentin (esim. myagent.example.com), ja porttia, jota päätepisteesi kuuntelee. Pakollinen, vaikka erillistä alavirran palvelua ei olisi.
Spanissani chat ei ole mallitokenien käyttöä. gen_ai.usage.input_tokens / gen_ai.usage.output_tokens Valinnainen – jätä pois. Jos sinulla on likimääräiset määrät, lähetä ne muodossa stringValue.
Spanissani ei ole virheilmoitusta. span.Status.Message, span.Status.Code Aseta OTel-tilaksi OK (numeerinen koodi 1) ja jätä viesti pois. Putki käyttää näitä kenttiä vain, kun tila on Error.
Agenttini käyttää ei-Entra-identiteettijärjestelmää (agentilla ei ole Entra-rekisteröintiä). microsoft.a365.agent.platform.id Ja gen_ai.agent.type Aseta molemmat, jokaiselle särmälle. platform.id on agentin yksilöllinen ID identiteettijärjestelmässäsi ; agent.type on lyhyt etiketti, joka tunnistaa, mikä identiteettijärjestelmä se on. Molemmat ovat vapaamuotoisia tekstejä – valitse se, mikä tuntuu järkevältä järjestelmällesi. Älä käytä Microsoft-varattuja tyyppiarvoja: CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, Custom (nämä arvot on varattu sisäisille Microsoft pinnoille). Soittava sovellus, jolla tunnistat, tarvitsee edelleen Entra-rekisteröinnin näiden reittien käyttämiseksi – vaihtoehtoinen ID-pari kuvaa kohdeagenttia, ei soittajaa.
Mitä arvoa minun pitäisi panostaa microsoft.channel.name? microsoft.channel.name Pinta, jolla agentti juoksee. Defender ja Admin Center suodattavat avaimen kirjaimellisen merkkijonon kautta, joten käytä lyhyttä, vakaata pientä merkkiä. Nykyään kanoniset arvot ovat msteams ja outlook; yleiset asiakaspinnat käyttävät webmyös , office, sharepoint, tai <your-product-name>. Valitse yksi arvo ja pysy siinä – työkalut eivät pysty sovittamaan msteams ja Microsoft Teams saman kanavan kanssa.
Pitäisikö minun asettaa gen_ai.agent.type? gen_ai.agent.type Vain jos olet myös asettamassa microsoft.a365.agent.platform.id (esimerkiksi agentillasi ei ole Entra-rekisteröintiä). Pari kertoo Agentti 365:lle, mistä identiteettijärjestelmästä agentti tulee. Valitse lyhyt nimitys, joka yksilöllisesti tunnistaa identiteettijärjestelmäsi. Älä käytä CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent tai Custom – nämä arvot on varattu sisäiseen Microsoft käyttöön. Entra-rekisteröityjen asiamiesten kohdalla jätä kenttä pois; Agentti 365 täyttää sen takaisin.
Minkä OTLP kind :n minun pitäisi asettaa jännevälilleni? span.kind Käytä kokonaislukua enum-arvoa, älä protoenum-merkkijonoa - 1 (INTERNAL), 2 (SERVER), 3 (CLIENT),4PRODUCER (), (5). CONSUMER Agentti 365 hyväksyy kaikki näistä eikä johda asiakkaan näkyvää käyttäytymistä , kindjoten 1 (INTERNAL) on turvallinen oletus jokaiselle jaksolle. Jos haluat, että tyyppi heijastaa kutsumuotoa, INTERNAL forinvoke_agent / output_messagesja CLIENT for chat / execute_tool on kohtuullinen.

Related content

  • Last updated on