KQL Search

Query Details

09 Datalake Unified Agent Executions Job

Query

UnifiedAgentObservability
| where TimeGenerated > ago(LookbackWindow)
| extend
    EventTime = coalesce(EventStartTime, TimeGenerated),
    AgentIdentityId = coalesce(TargetAgentId, SrcAgentId, PlatformTargetAgentId),
    AgentName = coalesce(TargetAgentName, SrcAgentName, PlatformTargetAgentName),
    AgentBlueprintId = coalesce(TargetAgentBlueprintId, SrcAgentBlueprintId),
    Operation = coalesce(EventOriginalType, EventType),
    ExecutionContext = case(
        isnotempty(ActorUserId) or isnotempty(ActorUsername), "delegatedObo",
        isnotempty(ActingAppId), "application",
        isnotempty(SrcAgentId), "agentToAgent",
        "unknown"
    ),
    ResultType = case(
        isnotempty(EventErrorDetails) or isnotempty(EventOriginalErrorType), "error",
        isnotempty(EventResponseId) or isnotnull(EventEndTime), "success",
        "unknown"
    ),
    Capability = case(
        isnotempty(ToolName), strcat(
            coalesce(ToolOriginalType, "tool"),
            ":",
            ToolName
        ),
        isnotempty(ModelName), strcat(
            "model:",
            coalesce(ModelProviderName, "unknown"),
            "/",
            ModelName
        ),
        isnotempty(TargetAgentId) and isnotempty(SrcAgentId), "agent-to-agent",
        Operation
    ),
    ResourceLocator = coalesce(ToolId, TargetAgentId),
    DurationMs = iff(
        isnotnull(EventStartTime) and isnotnull(EventEndTime),
        datetime_diff("millisecond", EventEndTime, EventStartTime),
        long(null)
    )
| project
    TimeGenerated = EventTime,
    EventUid,
    EventOriginalUid,
    EventSchema,
    EventSchemaVersion,
    EventVendor,
    EventProduct,
    AgentIdentityId,
    AgentName,
    AgentBlueprintId,
    SrcAgentId,
    SrcAgentName,
    SrcAgentBlueprintId,
    TargetAgentId,
    TargetAgentName,
    TargetAgentUserId,
    TargetAgentUsername,
    ActorUserId,
    ActorUsername,
    ActorUserScope,
    ActingAppId,
    ActingAppName,
    ActingAppType,
    ExecutionContext,
    EventSessionId,
    EventSessionName,
    Operation,
    EventRequestId,
    EventResponseId,
    ResultType,
    EventOriginalErrorType,
    EventErrorDetails,
    EventFinishReasons = tostring(EventFinishReasons),
    EventOutputType,
    Capability,
    ResourceLocator,
    ToolId,
    ToolName,
    ToolDescription,
    ToolOriginalType,
    ModelProviderName,
    ModelName,
    InputTokensUsed,
    OutputTokensUsed,
    DurationMs,
    SrcIpAddr,
    SrcFQDN,
    SrcPortNumber,
    EventCount,
    TenantId,
    SourceWorkspace = _Workspace,
    AdditionalFieldsJson = tostring(AdditionalFields)
| order by TimeGenerated desc

About this query

// Phase 3, query 9 of 9: native Agent 365 execution/tool telemetry projection. // // The workbook queries UnifiedAgentObservability directly through its Data // lake data source. Use this file as an OPTIONAL one-time or scheduled KQL job // when you want analytics-tier retention, joins with analytics-only sources, // or a smaller recurring projection. Suggested table: // AgentExecutionActivity_KQL_CL // // Keep the job lookback and schedule bounded to control promotion costs. A // common starting point is a daily job over the previous 2 days (overlap is // intentional for late-arriving records; de-duplicate downstream by EventUid). // // Source: UnifiedAgentObservability (73-column schema confirmed in the tenant). // // This output intentionally excludes EventThoughtProcessDetails, // EventOriginalRequestDetails, and EventOriginalResultDetails. Those fields can // contain prompts, responses, tool arguments/results, or reasoning data. The // workbook needs identity, lineage, tool, model, timing, and error metadata -- // not raw content.

let LookbackWindow = 2d; // PLACEHOLDER: align with the KQL job schedule.

Explanation

This query is designed to extract and process data from a data source called UnifiedAgentObservability. It focuses on capturing telemetry related to the execution of tools or agents within a system, specifically for Microsoft 365 environments. Here's a simplified breakdown of what the query does:

  1. Data Source and Purpose: The query pulls data from the UnifiedAgentObservability data source, which contains detailed telemetry information. It's intended for use in analytics scenarios where you need to retain data for a longer period, join it with other analytics data, or create a smaller, recurring dataset.

  2. Time Frame: The query looks at data generated in the last two days (LookbackWindow = 2d). This is to ensure that any late-arriving records are captured, and duplicates can be removed later using a unique identifier (EventUid).

  3. Data Transformation: The query processes the data by:

    • Calculating event times and identifying agents using various fields.
    • Determining the context of execution (e.g., whether it was initiated by a user, an application, or another agent).
    • Classifying the result of each event as a success or error based on available details.
    • Identifying the capability involved, such as a tool or model used.
    • Calculating the duration of events when start and end times are available.

  4. Data Projection: It selects and organizes specific fields to be included in the final output, such as agent identities, operation types, execution contexts, and error details. Certain fields containing raw content are intentionally excluded to focus on metadata like identity, lineage, and timing.

  5. Output: The final dataset is ordered by the time the events were generated, in descending order, to prioritize the most recent events.

Overall, this query is part of a larger set of queries (Phase 3, query 9 of 9) and is used to create a structured view of agent execution activities, which can be used for further analysis or reporting.