Agentti 365 havaittavuuden attribuuttiviite

Tämä artikkeli on Agentti 365:n käyttöputken kanoninen attribuutti-ominaisuus kerrallaan. Jokainen Agent 365:n vastaanottama span – olipa se sitten Microsoft OpenTelemetry Distron lähettämä, vanhentuneen Agent 365 Observability SDK:n tai suoran OTelin kautta lähetetty – 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 Distroa, SDK lähettää nämä ominaisuudet puolestasi. Arvojen poimiminen -osio koskee vain silloin, kun sinun täytyy ohittaa oletus. Jos käytät suoraa OTel-polkua, lähetät kaikki attribuutit manuaalisesti. Ohjeet niiden kokoamiseen pyynnöksi löydät integraatiooppaasta.

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, ettei attribuuttia näy tänään CloudAppEvents . Sinun tulisi silti lähettää sitä (Vaadit-sarakkeen mukaan), koska Agent 365 käyttää sitä vastaanottoon, vanhempien resoluutioon ja Microsoft Defender:n agenttitoimintanäkymiin. Kuitenkin et voi suoraan kysyä sitä Microsoft Defender Advanced Huntingista tänään.

Note

Agentti 365 täyttää automaattisesti staattiset tietuekentät (Id, RecordType, WorkloadUserType, Version, ) sekä luodut pyyntö- ja 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 arvon ja se ei hyväksy, pyyntö hylätään (403).
gen_ai.agent.id All M TargetAgentId (IA); 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 ja admin center näyttävät raakan käyttöliittymän 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ä tokenia. Defender- ja admin centerin suodattimien käyttämät kanoniset arvot ovat msteams ja outlook. Mukautetut merkkijonot (esimerkiksi web, <your-product-name>) hyväksytään, mutta sisäänrakennettuja kanavasuodattimia ei käännetä. Käytä samaa arvoa jokaisessa skannassa. 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 tai telemetrian lähettävälle palvelulle. Saattaa 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 tai ajatusketju.
gen_ai.author.app.id OM O -- Microsoft Entra -sovelluksen tunnus sovellukselle, joka loi tai 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 reasons.
microsoft.a365.caller.agent.id IA M*2 AgentId (IA) Soitan agentin appId:lle. Vaaditaan agentti-agentin välisessä keskustelussa.
microsoft.a365.caller.agent.name IA M*2 AgentName (IA) 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älytiimikavereille ja ruumiillistuneille agenteille.
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

Agentti 365 hyväksyy useita lähettämiäsi attribuutteja, kuten työkaluargumentteja ja tuloksia, malliparametreja sekä kanavan syvälinkkejä. Downstream Microsoft Defender -näkymät käyttävät näitä attribuutteja, mutta Agent 365 ei vielä paljasta niitä JSON-avaimenaCloudAppEvents.RawEventData. Aseta ne Pakollinen-sarakkeen mukaan. Ne saatetaan lisätä metsästyskuormaan tulevassa julkaisussa.

Important

invoke_agent (IA)-tietueissa AgentId, AgentName, ja AgentBlueprintId kentät kuvaavat kutsuvaa agenttia, eivät kutsuttua agenttia. Agentti 365 täyttää ne microsoft.a365.caller.agent.* attribuuttien avulla. Kun ihminen kutsuu agenttisi, jätä nämä attribuutit AgentId pois ja AgentBlueprintId ne näkyvät täysin nollan GUID:nä (00000000-0000-0000-0000-000000000000) ja AgentName on tyhjä auditointitietueissa ja Microsoft Purview'ssa. Kaikkien nollan arvoa odotetaan ihmisen aloittamilla suorituksilla. Kutsutun agentin tunnistamiseksi käytä TargetAgentId, TargetAgentName, ja TargetAgentBlueprintID.

Arvojen valitseminen, kun sinulla ei ole luonnollista arvoa

Jotkut vaaditut attribuutit kuvaavat käsitteitä, joita agentin arkkitehtuurissa ei välttämättä ole. Jos luonnollista arvoa ei ole saatavilla, aseta seuraavat arvot sen sijaan. Älä jätä pakollista kenttää tyhjäksi. Jo pelkkä nolla-GUID piilottaa juoksun joiltakin asiakaskohtauksilta. Tämä sääntö koskee vain pakollisia attribuutteja. Se ei koske kutsuja-agentin attribuutteja ihmisen aloittamissa ajoissa, joissa tietueissa odotetaan nollaa AgentIdinvoke_agent .

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. Tietueissa invoke_agent kutsuja ilmestyy AgentId ja AgentBlueprintId näyttää kaikki nollat -GUID:n. Käytä TargetAgentId agentin tunnistamiseen.
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 tunniste identiteettijärjestelmässäsi ; agent.type on lyhyt tunniste, joka tunnistaa, mikä identiteettijärjestelmä 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

  • Viimeksi päivitetty