Document agentic usage attribution in Audit Trail

content/en/account_management/audit_trail/_index.md

@@ -164,6 +164,17 @@ Events that match the following queries are marked as notable. You can also retr
 | Creation or deletion of Synthetic tests | `@evt.name:"Synthetics Monitoring" @asset.type:synthetics_test @action:(created OR deleted)` |
 | Activation, deactivation, and modification of Product Analytics for applications | `@evt.name:"Product Analytics" @asset.type:product_analytics @action:(enabled OR disabled OR modified)` |
 
+### View a user's full activity, including agent-delegated actions
+
+When a Datadog AI agent acts on a user's behalf, the agent becomes `@evt.actor` for that event, and the user moves to `@delegator.actor`. Searching only `@usr.name:<USER_EMAIL>` returns the actions a user performed directly, and does not include actions a Datadog AI agent performed on their behalf.
+
+| Description of audit event                                                                        | Query in audit explorer                                     |
+| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Actions a user performed directly                                                                    | `@usr.name:<USER_EMAIL>`                                      |
+| All actions attributed to a user, including actions a Datadog AI agent performed on their behalf     | `(@usr.name:<USER_EMAIL> OR @delegator.name:<USER_EMAIL>)`    |
+
+See [Track Agentic Usage in Your Organization][18] for more information on filtering and viewing agent-driven audit events.
+
 ### Inspect Changes (Diff)
 
 The Inspect Changes (Diff) tab in the audit event details panel compares the configuration changes that were made to what was previously set. It shows the changes made to dashboard, notebook, and monitor configurations, which are represented as JSON objects.
@@ -254,4 +265,5 @@ Datadog Audit Trail comes with an [out-of-the-box dashboard][13] that shows vari
 [15]: /security/cloud_siem/
 [16]: /getting_started/cloud_siem/
 [17]: /dashboards/sharing/scheduled_reports/#schedule-a-report
+[18]: /account_management/audit_trail/guides/track_agentic_usage_in_your_organization/
 

content/en/account_management/audit_trail/events.md

@@ -16,6 +16,27 @@ further_reading:
 
 [Datadog Audit Trail][1] records more than 100 types of audit events from across the Datadog platform. These audit events are categorized into different product categories as event names.
 
+## Agent actor and delegation fields
+
+In addition to product-specific events, Audit Trail events can carry actor and delegation metadata that identifies actions taken by a Datadog AI agent, such as Bits SRE, Bits Dev, Bits Assistant, Bits Security Analyst, and Agent Builder.
+
+| Field               | Description                                                                                                                                                                    |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `@evt.actor.mode`    | The mode a Datadog AI agent acted in: `interactive` (a user was present and approved the action) or `autonomous` (the agent acted on a system trigger, with no user present).  |
+| `@delegator.actor`   | The user on whose behalf a Datadog AI agent acted. When an agent acts on a user's behalf, `@evt.actor` reflects the agent, and the user moves to `@delegator.actor`.           |
+| `is_mcp_call`        | Set to `true` for actions taken through the Datadog MCP server.                                                                        |
+
+Use the following queries to find agent-driven events:
+
+| Description of audit event                        | Query in audit explorer |
+| ---------------------------------------------------- | -------------------------- |
+| All actions taken by a Datadog AI agent              | `@evt.actor.mode:*`        |
+| All actions taken through the Datadog MCP server     | `is_mcp_call:true`         |
+
+**Note**: Rollout to all Bits agents is in progress, and coverage is not yet complete. Actions from agents that have not yet onboarded do not appear in `@evt.actor.mode:*` results. Datadog-managed AI agent features are not available in GovCloud environments.
+
+For a complete walkthrough on filtering by agent type, agent name, and delegated user activity, see [Track Agentic Usage in Your Organization][2].
+
 {{< account_management/audit_events additional_info="See the [Audit Trail documentation](/account_management/audit_trail/) for more information on setting up and configuring Audit Trail." >}}
 
 
@@ -24,3 +45,4 @@ further_reading:
 {{< partial name="whats-next/whats-next.html" >}}
 
 [1]: https://app.datadoghq.com/audit-trail
+[2]: /account_management/audit_trail/guides/track_agentic_usage_in_your_organization/

content/en/account_management/audit_trail/guides/track_agentic_usage_in_your_organization.md

@@ -0,0 +1,60 @@
+---
+title: Track Agentic Usage in Your Organization
+description: Use Audit Trail to see which actions Datadog AI agents take in your organization, distinguish agent activity from human activity, and trace agent actions back to the user who authorized them.
+disable_toc: false
+further_reading:
+- link: "account_management/audit_trail/"
+  tag: "Documentation"
+  text: "Set up Audit Trail"
+- link: "account_management/audit_trail/events/"
+  tag: "Documentation"
+  text: "Learn about Audit Trail events"
+---
+
+## Overview
+
+Datadog AI agents, including the Bits fleet (Bits SRE, Bits Dev, Bits Assistant, Bits Security Analyst) and Agent Builder, can take actions inside your organization on their own or on behalf of a user. Audit Trail attributes these actions to the agent that performed them and, when applicable, to the user who authorized them. This guide walks you through finding agent-driven events, filtering them by agent type, and tracing an agent's actions back to the user who delegated them.
+
+## View all Datadog AI agent activity
+
+1. Navigate to [Audit Trail][1].
+2. In the search bar, enter the query: `@evt.actor.mode:*`.
+
+   This query returns every event where a Datadog AI agent is the actor, whether the agent acted `interactive` (a user was present and approved the action) or `autonomous` (the agent acted on a system trigger, with no user present).
+3. Click an event to open details and see the full actor breakdown: the delegator (the user, if any), the agent, and the mode.
+
+**Note**: Rollout to all Bits agents is in progress, and coverage is not yet complete. Actions from agents that have not yet onboarded do not appear in `@evt.actor.mode:*` results.
+
+## View actions taken through the Datadog MCP server
+
+Actions taken through the Datadog MCP server, carry the `is_mcp_call` field.
+
+1. Navigate to [Audit Trail][1].
+2. In the search bar, enter the query: `is_mcp_call:true`.
+3. Click an event to see a link back to the MCP server configuration and to other events from the same MCP session.
+
+## View a user's full activity, including agent-delegated actions
+
+When a Datadog AI agent acts on a user's behalf, the agent becomes `@evt.actor` for that event, and the user moves to `@delegator.actor`. Searching only `@usr.name:<USER_EMAIL>` returns the actions the user performed directly, and does not include actions a Datadog AI agent performed on their behalf.
+
+To retrieve a user's complete activity, including delegated agent actions:
+
+1. Navigate to [Audit Trail][1].
+2. In the search bar, enter the query: `(@usr.name:<USER_EMAIL> OR @delegator.name:<USER_EMAIL>)`. Replace `<USER_EMAIL>` with the user's email address.
+
+   | Description of audit event                                                                          | Query in audit explorer                                     |
+   | ------------------------------------------------------------------------------------------------------| ------------------------------------------------------------ |
+   | Actions a user performed directly                                                                     | `@usr.name:<USER_EMAIL>`                                      |
+   | All actions attributed to a user, including actions a Datadog AI agent performed on their behalf      | `(@usr.name:<USER_EMAIL> OR @delegator.name:<USER_EMAIL>)`    |
+3. See [Create a dashboard or a graph][2] if you want to put this information into a dashboard or graph.
+
+## Distinguish agent events from human events
+
+Agent-driven events display a visual badge in the event list, so you can distinguish them from human-driven events without opening each one.
+
+## Further reading
+
+{{< partial name="whats-next/whats-next.html" >}}
+
+[1]: https://app.datadoghq.com/audit-trail
+[2]: /account_management/audit_trail/#create-a-dashboard-or-a-graph