Integroi agentin havainnointikyky suoraan OTel-rajapintaan

Tämä opas ohjaa sinut koko prosessin läpi agentin telemetrian lähettämiseksi Agent 365:lle suoraan OpenTelemetryn (OTLP/HTTP+JSON) kautta. Ennen kuin aloitat, lue Agent 365:n havainnointikonseptit saadaksesi käsityksen mallista, autentikointipoluista ja kohteista, joihin tietosi päätyy.

Edellytykset

Varmista, että seuraavat asetukset ovat kunnossa ennen kuin telemetriaa lähetetään.

Todennusreseptit

Kaikki neljä menetelmää käyttävät tavallista Microsoft Entra -tunnus-päätepistettä:

Alla olevat integraatio-ohjeet näyttävät raakaa HTTP:tä selkeyden vuoksi. Tuotannossa suositellaan käyttämään Microsoft.Identity.Web:iä tai muuta MSAL-kirjastoa, joka hoitaa tunnusten päivityksen ja välimuistin hallinnan.

Minkä reseptin tarvitsen?

S2S, Microsoft Entra -vakiosovellus

Lähetä yksi POST-pyyntö vuokralaisen tunnuksen päätepisteelle kohteella grant_type=client_credentials. Tunnista sovellus käyttämällä asiakassalaisuutta, varmennetta (allekirjoitettu JWT-väite) tai hallittua identiteettiä tai liittoutunutta tunnistetietoa.

POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={your-app-id}
&scope=9b975845-388f-4429-889e-eab1ef63949c%2F.default
&client_secret={secret}
&grant_type=client_credentials

Palautettu token sisältää appid/azp = {your-app-id}, roles, joka sisältää Agent365.Observability.OtelWrite, sekä aud = 9b975845-.... Käytä sitä reitillä /observabilityService/.../traces.

Varmennepohjaisessa tunnistautumisessa korvaa client_secret={secret}client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={signed-jwt}:llä.

S2S, Blueprint-pohjainen agentti-identiteetti

Agentti-identiteeteillä ei ole omia tunnistetietoja. Agentti-identiteetin blueprint pitää hallussaan tunnistetiedot (hallittu identiteetti FIC, varmenne tai asiakkaan salaisuus) ja myöntää tunnuksia aliagentti-identiteettien puolesta kaksivaiheisen vaihtoprosessin kautta. Lisätietoja on kohdassa autonomisen sovelluksen OAuth-työnkulku.

1. Blueprint tunnistautuu ja saa federatiivisen identiteettivaihtotunnuksen T1:

   • {blueprint-credential} on blueprintin MSI-tunnus, sertifikaatilla allekirjoitettu JWT tai salainen vaihtotunnusväittämä – blueprint-konfiguraation mukaisesti.

   POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
   Content-Type: application/x-www-form-urlencoded
   
   client_id={blueprint-app-id}
   &scope=api%3A%2F%2FAzureADTokenExchange%2F.default
   &fmi_path={agent-identity-app-id}
   &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
   &client_assertion={blueprint-credential}
   &grant_type=client_credentials
   

2. Agentin identiteetti vaihtaa T1 Agent 365 Observability -resurssitunnuksen:

   POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
   Content-Type: application/x-www-form-urlencoded
   
   client_id={agent-identity-app-id}
   &scope=9b975845-388f-4429-889e-eab1ef63949c%2F.default
   &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
   &client_assertion={T1}
   &grant_type=client_credentials
   

   • Palautettu token sisältää appid/azp = {agent-identity-app-id}, roles, joka sisältää Agent365.Observability.OtelWrite, sekä aud = 9b975845-....
   • Käytä tätä tunnusta /observabilityService/.../traces -reitillä.
   • URL-osoite {agentId} on agentti-identiteetin appId, ei blueprintin appId.

OBO, Microsoft Entra -vakiosovellus

Vastaanota käyttäjän saapuva tunnus Tc yläpuoliselta kutsujalta (Bearer tai PFAT) ja vaihda se:

POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={your-app-id}
&scope=9b975845-388f-4429-889e-eab1ef63949c%2FAgent365.Observability.OtelWrite
&client_secret={secret}
&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion={Tc}
&requested_token_use=on_behalf_of

Sertifikaattitodennuksessa korvaa client_secret={secret} samalla client_assertion_type + client_assertion parilla kuin S2S:ssä.

Palautettu token sisältää appid/azp = {your-app-id}, scp, joka sisältää Agent365.Observability.OtelWrite, sekä aud = 9b975845-.... Käytä sitä reitillä /observability/.../traces. Päivitystunniste palautetaan samalla; tallenna se välimuistiin ja käytä uudelleen sen sijaan, että suorittaisit vaihdon uudelleen jokaisella kutsulla.

OBO, Blueprintistä johdettu agentti-identiteetti (mukaan lukien tekoälytiimikaveri)

On kolme päävaihetta on-behalf-of-prosessissa. Katso lisätietoja kohdasta agentti OAuth-työnkulut: On behalf of -työnkulku.

1. Vastaanota käyttäjätunnus Tc. Tekoälyavustajalle tämä token edustaa agentin omaa käyttäjätiliä; muussa tapauksessa se edustaa ihmiskäyttäjää.

2. Blueprint todentaa itsensä ja saa T1, samalla tavalla kuin S2S blueprint -pohjaisessa agentin identiteettiprosessissa.

3. Agentti-identiteetti vaihtaa T1 ja Tc saadakseen delegoidun resurssitunnuksen:

   POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
   Content-Type: application/x-www-form-urlencoded
   
   client_id={agent-identity-app-id}
   &scope=9b975845-388f-4429-889e-eab1ef63949c%2FAgent365.Observability.OtelWrite
   &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
   &client_assertion={T1}
   &grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
   &assertion={Tc}
   &requested_token_use=on_behalf_of
   

Palautettu token sisältää appid/azp = {agent-identity-app-id}, scp, johon sisältyy Agent365.Observability.OtelWrite, ja edustaa agentin käyttäjää. Käytä sitä reitillä /observability/.../traces. URL-osoite {agentId} on agentti-identiteetin appId, ei blueprintin appId. Päivitystunnus palautetaan mukana; tallenna se välimuistiin ja käytä uudelleen.

Vaaditut vaatimukset palautettuun tunnukseen

S2S-reitti (/observabilityService/...) - pelkästään sovellukselle tarkoitettu tunnus:

Delegoitu reitti (/observability/...) - käyttäjän delegoima tunnus (Bearer tai PFAT):

Hyväksyy sekä Bearer- että MSAuth1.0 PFAT -tunnukset. Suorat kutsut tulisi tehdä käyttäen Bearer-koodia. Jos et tiedä, mitä sinulla on, käytä Bearer-koodia.

Päätepisteet

Kaksi reittiä; valitse sen mukaan, miten palvelusi tunnistautuu, älä sen mukaan, mitä käyttäjä tekee:

POST https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1   # S2S
POST https://agent365.svc.cloud.microsoft/observability/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1          # OBO

Otsikot:

Authorization: Bearer <token>      # or MSAuth1.0 ... for delegated PFAT
Content-Type: application/json

URL-parametrit

• {tenantId} - Asiakkaan vuokraajan GUID. Palvelin pitää tätä määräävänä; jos spanien microsoft.tenant.id-arvo poikkeaa tästä, pyyntö hylätään.
• {agentId} - kutsuvan sovelluksen appId (myös OAuth client_id). Blueprint-johdetuilla identiteeteillä tämä on agentti-identiteetin appId, ei blueprintin appId. Täytyy olla sama kuin tunnuksesi appid / azp-väite.
• api-version=1 - vaadittu.

Pyynnön rungon koodaus

Runko on standardi OTLP/HTTP+JSON-rakenne: ExportTraceServiceRequest, jonka resourceSpans → scopeSpans → spans. Ota huomioon seuraavat asiat:

• traceId (16 tavua) ja spanId (8 tavua) lähetetään pienaakkosin kirjoitettuina heksamerkkijonoina.
• startTimeUnixNano / endTimeUnixNano ovat merkkijonoja jotka sisältävät Unix-epookin nanosekunteja.
• kind on kokonaislukutyyppinen OTLP:n luettelointi-arvo (esimerkiksi 1INTERNAL); status.code on kokonaislukutyyppinen luettelointi-arvo (esimerkiksi 1OK, 2ERROR).
• Kaikki attribuuttien arvot lähetetään muodossa stringValue.

Vastemuoto

Onnistunut pyyntö palauttaa 200 OK:

{ "partialSuccess": null }

Jos joitakin spaneja hylättiin span-kohtaisella suodattimella:

{
  "partialSuccess": {
    "rejectedSpans": 2,
    "errorMessage": "Dropped 2 non-A365 span(s) ..."
  }
}

Kenttien nimet ovat camelCase-muodossa tiedonsiirrossa. Tarkista aina partialSuccess: 200-vastaus, jossa kaikki spanit on hylätty, on todellinen lopputulos, joka täytyy tuoda esiin. Rajoitus- ja pudotusehdot -osio listaa hiljaiset pudotustapaukset, joissa 200 palautuu partialSuccess: null, vaikka tietoja ei näy jatkovirrassa.

Pienin mahdollinen pyyntö

Yksinkertaisin end-to-end-testi lähettää yhden invoke_agent-spanin. Tämä span on pienin runko, joka päätyy Microsoft Defenderiin.

Vaihe 1. Hanki haltijatunnus. S2S:ssä käytä asiakastunnuksia laajuudella 9b975845-388f-4429-889e-eab1ef63949c/.default (katso Todentamisreseptit koko reseptiä varten).

Vaihe 2: JULKAISEE yhden spanin:

TOKEN="$(./get-token.sh)"
TENANT_ID="<customer-tenant-guid>"
AGENT_ID="<your-agent-app-id>"

curl -i -X POST \
  "https://agent365.svc.cloud.microsoft/observabilityService/tenants/${TENANT_ID}/otlp/agents/${AGENT_ID}/traces?api-version=1" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  --data @- <<EOF
{
  "resourceSpans": [{
    "scopeSpans": [{
      "scope": { "name": "my-instrumentation", "version": "1.0.0" },
      "spans": [{
        "traceId": "0102030405060708090a0b0c0d0e0f10",
        "spanId":  "1111111111111111",
        "parentSpanId": "",
        "name": "invoke_agent",
        "kind": 1,
        "startTimeUnixNano": "1736175600000000000",
        "endTimeUnixNano":   "1736175601500000000",
        "status": { "code": 1 },
        "attributes": [
          { "key": "gen_ai.operation.name", "value": { "stringValue": "invoke_agent" } },
          { "key": "gen_ai.agent.id",       "value": { "stringValue": "${AGENT_ID}" } },
          { "key": "gen_ai.agent.name",     "value": { "stringValue": "MyAgent" } },
          { "key": "microsoft.a365.agent.blueprint.id", "value": { "stringValue": "${AGENT_ID}" } },
          { "key": "gen_ai.conversation.id","value": { "stringValue": "conv-001" } },
          { "key": "microsoft.channel.name","value": { "stringValue": "web" } },
          { "key": "user.id",               "value": { "stringValue": "<entra-user-objectid>" } },
          { "key": "client.address",        "value": { "stringValue": "10.1.2.80" } },
          { "key": "server.address",        "value": { "stringValue": "myagent.example.com" } },
          { "key": "server.port",           "value": { "stringValue": "443" } },
          { "key": "gen_ai.input.messages", "value": { "stringValue": "[{\"role\":\"user\",\"content\":\"hi\"}]" } },
          { "key": "gen_ai.output.messages","value": { "stringValue": "[{\"role\":\"assistant\",\"content\":\"hello\"}]" } }
        ]
      }]
    }]
  }]
}
EOF

Vaihe 3: Odota 200 OK tällä sisällöllä:

{ "partialSuccess": null }

Vaihe 4: Varmista, että data todella saapui. 200 OK ei ole todiste käsittelystä; Vastaanoton tarkistusohjeet käyvät läpi varmennusprosessin. Jos haluat JULKAISTA tallennetun runkotiedoston, korvaa se --data @- <<EOF ... EOF kohteella --data @./otlp-request.json

Esimerkki agentin suorituksesta

Microsoft Teamsin käyttäjä kysyy: "Millainen sää Seattlessa on?". Agenttisi kutsuu GetWeather-funktion, pyytää LLM:ää muotoilemaan vastauksen ja vastaa. Tuo yksittäinen suoritus koostuu neljästä spanista:

graph TD
    A["<b>invoke_agent</b> · spanId=A · parentSpanId=∅<br/><i>root - the run itself</i>"]
    B["<b>chat</b> · spanId=B · parentSpanId=A<br/><i>LLM picks the tool / formats reply</i>"]
    C["<b>execute_tool</b> · spanId=C · parentSpanId=A<br/><i>the GetWeather call</i>"]
    D["<b>output_messages</b> · spanId=D · parentSpanId=A<br/><i>final reply emitted to the user</i>"]
    A --> B
    A --> C
    A --> D

Suorituksen kattavat attribuutit asetetaan jokaiseen spaniin:

Span A: invoke_agent (juuri)

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "1111111111111111",
  "parentSpanId": "",
  "name": "invoke_agent",
  "kind": 1,
  "startTimeUnixNano": "1736175600000000000",
  "endTimeUnixNano":   "1736175601500000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",   "value": { "stringValue": "invoke_agent" } },
    { "key": "gen_ai.execution.type",   "value": { "stringValue": "HumanToAgent" } },
    { "key": "gen_ai.input.messages",   "value": { "stringValue": "[{\"role\":\"user\",\"content\":\"What's the weather in Seattle?\"}]" } },
    { "key": "gen_ai.output.messages",  "value": { "stringValue": "[{\"role\":\"assistant\",\"content\":\"It's 65F and partly cloudy in Seattle.\"}]" } },
    { "key": "user.email",              "value": { "stringValue": "alice@contoso.com" } }
    /* plus all the run-wide attributes listed above */
  ]
}

Span B: chat (LLM-kutsu)

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "2222222222222222",
  "parentSpanId": "1111111111111111",
  "name": "chat",
  "kind": 1,
  "startTimeUnixNano": "1736175600200000000",
  "endTimeUnixNano":   "1736175600900000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",      "value": { "stringValue": "chat" } },
    { "key": "gen_ai.request.model",       "value": { "stringValue": "gpt-4o" } },
    { "key": "gen_ai.provider.name",       "value": { "stringValue": "openai" } },
    { "key": "gen_ai.usage.input_tokens",  "value": { "stringValue": "42" } },
    { "key": "gen_ai.usage.output_tokens", "value": { "stringValue": "23" } }
    /* plus all the run-wide attributes */
  ]
}

Span C: execute_tool

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "3333333333333333",
  "parentSpanId": "1111111111111111",
  "name": "execute_tool",
  "kind": 1,
  "startTimeUnixNano": "1736175600950000000",
  "endTimeUnixNano":   "1736175601200000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",      "value": { "stringValue": "execute_tool" } },
    { "key": "gen_ai.tool.name",           "value": { "stringValue": "GetWeather" } },
    { "key": "gen_ai.tool.type",           "value": { "stringValue": "function" } },
    { "key": "gen_ai.tool.call.id",        "value": { "stringValue": "call-001" } },
    { "key": "gen_ai.tool.call.arguments", "value": { "stringValue": "{\"location\":\"Seattle\"}" } },
    { "key": "gen_ai.tool.call.result",    "value": { "stringValue": "{\"tempF\":65,\"condition\":\"partly cloudy\"}" } }
    /* plus all the run-wide attributes */
  ]
}

Span D: output_messages

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "4444444444444444",
  "parentSpanId": "1111111111111111",
  "name": "output_messages",
  "kind": 1,
  "startTimeUnixNano": "1736175601400000000",
  "endTimeUnixNano":   "1736175601500000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",  "value": { "stringValue": "output_messages" } },
    { "key": "gen_ai.output.messages", "value": { "stringValue": "[{\"role\":\"assistant\",\"content\":\"It's 65F and partly cloudy in Seattle.\"}]" } }
    /* plus all the run-wide attributes */
  ]
}

Telemetrian lähettäminen

OTel SDK:n käyttö

Useimmat kumppanit lähettävät traceja OTel SDK:n kautta itse toteutetun HTTP:n sijaan. OTel SDK hoitaa eräkäsittelyt, uudelleenyritykset ja OTLP/HTTP+JSON-koodauksen puolestasi. Aseta vientipäätepiste ja lisää otsake Authorization.

Vientipäätepiste on reitin URL, mukaan lukien kyselymerkkijono:

https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1

(Käytä /observability/... delegoidun reitin tapauksessa /observabilityService/... sijaan.)

Python

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1",
    headers={"Authorization": f"Bearer {token}"},
)

Paketti: opentelemetry-exporter-otlp-proto-http.

Node.js / TypeScript

import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";

const exporter = new OTLPTraceExporter({
  url: "https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1",
  headers: { Authorization: `Bearer ${token}` },
});

Paketti: @opentelemetry/exporter-trace-otlp-http.

.NET

using OpenTelemetry.Exporter;

services.AddOpenTelemetry().WithTracing(b => b
    .AddOtlpExporter(o =>
    {
        o.Endpoint = new Uri("https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1");
        o.Headers = $"Authorization=Bearer {token}";
        o.Protocol = OtlpExportProtocol.HttpJson;
    }));

Paketti: OpenTelemetry.Exporter.OpenTelemetryProtocol.

Manuaalinen HTTP

Jos et voi tai halua käyttää OTel-SDK:ta, rakenna OTLP/HTTP+JSON-pyyntö itse ja JULKAISE se. Pyynnön rungon rakenne määritellään OpenTelemetry OTLP/HTTP+JSON -määrityksen mukaisesti:

{
  "resourceSpans": [{
    "resource":  { "attributes": [ ... ] },          // optional
    "scopeSpans": [{
      "scope":  { "name": "<your-instrumentation>", "version": "1.0.0" },
      "spans":  [ <span>, <span>, ... ]
    }]
  }]
}

Jokainen <span> on objekti, jonka pakollisia kenttiä ovat traceId, spanId, name, kind, startTimeUnixNano, endTimeUnixNano, attributes sekä (ei-juuri-spanien tapauksessa) parentSpanId. Tutustu osioihin Päätepisteet sekä Pyynnön rungon koodaus koodaussääntöjen osalta (merkkijonona koodatut ajat, heksadesimaalina traceId / spanId, kokonaislukuna kind / status.code, kaikki attribuuttiarvot muodossa stringValue).

Asetettavat attribuutit kullekin spanille määritellään kohdassa Viestisopimukset. Katso täydellinen määriteluettelo kohdassa Määriteviittaus. Katso agentti-suoritusesimerkkiä päästä päähän toimivasta mallista, jossa haltijatunnus on otsikossa ja runko sisältyy suoraan.

Voit lähettää kaikki suorituksen spanit yhdessä POST-pyynnön rungossa (suositeltu – yksi pyyntö, yksi jäljitys) tai useissa POST-pyynnöissä. Palvelin kokoaa ajon uudelleen traceId + parentSpanId + gen_ai.conversation.id avulla, joten jokainen span sisältää riittävästi tietoa, jotta ne voidaan korreloida kummassakin tapauksessa.

Viestisopimukset

Tässä osiossa määritellään, mitä spaneja voit lähettää ja mitkä attribuutit liitetään kuhunkin. Katso täydellinen attribuuttikohtainen spesifikaatio attribuuttiviitteestä.

Toimintotyypit

Jokaisessa lähettämässäsi spanissa täytyy olla gen_ai.operation.name asetettuna johonkin näistä neljästä arvosta (kirjainkoolla ei ole väliä). Jokainen span, jolta puuttuu tai jonka arvoa ei tunnisteta, hiljaisesti pudotetaan ja huomioidaan laskurissa partialSuccess.rejectedSpans.

Span-hierarkia ja suoritusryhmittely

Agent 365 rekonstruoi suorituksen tavallisesta OTLP-span-graafista (traceId, spanId, parentSpanId) sekä Attribuuttiviitteen suorituslaajuisista attribuuteista.

Kuusi sääntöä:

1. Aseta aina parentSpanId jokaiseen ei-juurispaniin. Ilman sitä suorituksen puurakennetta ei voi rekonstruoida.
2. Käytä samaa traceId kaikissa suorituksen spaneissa.
3. Aseta gen_ai.conversation.id jokaiselle spanille sama arvo. Tämä on ensisijainen yhdistämisavain "kaikille tämän suorituksen spaneille". Se ei välity automaattisesti.
4. Aseta microsoft.channel.name jokaiselle spanille sama arvo. Työkaluspanit, joilta puuttuu kanava / keskustelu, voivat periä ne pääelementiltä invoke_agentvain jos pääelementti on samassa OTLP-pyynnössä, joten määritä ne itse jokaiseen spaniin.
5. Aseta microsoft.session.id jokaiselle spanille kun käytössäsi on looginen istunto.
6. Agentista agenttiin tehtävissä kutsuissa, joissa aliagentti on eri pyynnössä, käytä samaa gen_ai.conversation.id ja käytä microsoft.a365.caller.agent.* attribuutteja (katso Attribuuttiviite) tallentaaksesi kutsuja-agentin kontekstin.

Neljän spanin puu agentin suoritusesimerkissä on kanoninen muoto.

Yleiset suorituksen muodot

Käyttöönoton tarkistuslista

Käy läpi tämä käyttöönoton tarkistuslista ennen tuotannon aloittamista.

Seuraavat vaiheet

• Attribuuttiviite – Attribuuttikohtainen spesifikaatio ja arvonvalintaohjeistus.
• Vianmääritys – Vastaanoton tarkistaminen, yleiset sudenkuopat ja virhevasteet.