From a684f9f54dae0cfb2f4225769c904214e3328873 Mon Sep 17 00:00:00 2001 From: Anthony Dagneaux Date: Fri, 3 Jul 2026 16:43:15 +0200 Subject: [PATCH 1/3] docs(audit-trail): document agentic usage attribution Add a new-field reference for @evt.actor.mode / @delegator.actor / is_mcp_call on the events page, a delegated-activity query example on the Audit Trail overview page, and a new guide on tracking agentic usage across the org, following the GA feature announcement for agent actor + delegation attribution. --- .../account_management/audit_trail/_index.md | 12 ++++ .../account_management/audit_trail/events.md | 22 +++++++ ...rack_agentic_usage_in_your_organization.md | 61 +++++++++++++++++++ 3 files changed, 95 insertions(+) create mode 100644 content/en/account_management/audit_trail/guides/track_agentic_usage_in_your_organization.md diff --git a/content/en/account_management/audit_trail/_index.md b/content/en/account_management/audit_trail/_index.md index 9e66b806c6a..a728b91f91f 100644 --- a/content/en/account_management/audit_trail/_index.md +++ b/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:` 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:` | +| All actions attributed to a user, including actions a Datadog AI agent performed on their behalf | `(@usr.name: OR @delegator.name:)` | + +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/ diff --git a/content/en/account_management/audit_trail/events.md b/content/en/account_management/audit_trail/events.md index 4fdcb84d1ca..2102d2c6f0e 100644 --- a/content/en/account_management/audit_trail/events.md +++ b/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 workflows. + +| 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 a Datadog-managed OAuth client, such as 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**: Coverage rolls out per product and depends on each Datadog AI agent team onboarding to the actor and delegation model. 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/ diff --git a/content/en/account_management/audit_trail/guides/track_agentic_usage_in_your_organization.md b/content/en/account_management/audit_trail/guides/track_agentic_usage_in_your_organization.md new file mode 100644 index 00000000000..f5fa50c7fde --- /dev/null +++ b/content/en/account_management/audit_trail/guides/track_agentic_usage_in_your_organization.md @@ -0,0 +1,61 @@ +--- +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 workflows, 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]. +1. 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). +1. Optionally, use the {{< ui >}}Agent Type{{< /ui >}} and {{< ui >}}Agent Name{{< /ui >}} facets to narrow results down to a specific agent, such as Bits SRE or Bits Dev. +1. Click an event to open the detail drawer and see the full actor breakdown: the delegator (the user, if any), the agent, and the mode. + +**Note**: Coverage rolls out per product and depends on each Datadog AI agent team onboarding to the actor and delegation model. Until an agent team completes onboarding, `@evt.actor.mode:*` under-reports that agent's activity. + +## View actions taken through the Datadog MCP server + +Actions taken through a Datadog-managed OAuth client, such as the Datadog MCP server, carry the `is_mcp_call` field. + +1. Navigate to [Audit Trail][1]. +1. In the search bar, enter the query: `is_mcp_call:true`. +1. 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:` 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]. +1. In the search bar, enter the query: `(@usr.name: OR @delegator.name:)`. Replace `` with the user's email address. + + | Description of audit event | Query in audit explorer | + | ------------------------------------------------------------------------------------------------------| ------------------------------------------------------------ | + | Actions a user performed directly | `@usr.name:` | + | All actions attributed to a user, including actions a Datadog AI agent performed on their behalf | `(@usr.name: OR @delegator.name:)` | +1. 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. Use this alongside the {{< ui >}}Agent Type{{< /ui >}} and {{< ui >}}Agent Name{{< /ui >}} facets to build a saved view of agent activity for your security or compliance team. + +## 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 From 0d444b4b6425472d1b5c7042006125922bf0310e Mon Sep 17 00:00:00 2001 From: Anthony Dagneaux Date: Fri, 3 Jul 2026 17:35:46 +0200 Subject: [PATCH 2/3] docs(audit-trail): incorporate review edits --- .../account_management/audit_trail/events.md | 6 +++--- ...rack_agentic_usage_in_your_organization.md | 21 +++++++++---------- 2 files changed, 13 insertions(+), 14 deletions(-) diff --git a/content/en/account_management/audit_trail/events.md b/content/en/account_management/audit_trail/events.md index 2102d2c6f0e..28fea7c5dcf 100644 --- a/content/en/account_management/audit_trail/events.md +++ b/content/en/account_management/audit_trail/events.md @@ -18,13 +18,13 @@ further_reading: ## 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 workflows. +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 a Datadog-managed OAuth client, such as the Datadog MCP server. | +| `is_mcp_call` | Set to `true` for actions taken through the Datadog MCP server. | Use the following queries to find agent-driven events: @@ -33,7 +33,7 @@ Use the following queries to find agent-driven events: | All actions taken by a Datadog AI agent | `@evt.actor.mode:*` | | All actions taken through the Datadog MCP server | `is_mcp_call:true` | -**Note**: Coverage rolls out per product and depends on each Datadog AI agent team onboarding to the actor and delegation model. 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. +**Note**: It's progressively being rolled out to all Datadog AI Agents. 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]. diff --git a/content/en/account_management/audit_trail/guides/track_agentic_usage_in_your_organization.md b/content/en/account_management/audit_trail/guides/track_agentic_usage_in_your_organization.md index f5fa50c7fde..0b7b1a3aabe 100644 --- a/content/en/account_management/audit_trail/guides/track_agentic_usage_in_your_organization.md +++ b/content/en/account_management/audit_trail/guides/track_agentic_usage_in_your_organization.md @@ -13,26 +13,25 @@ further_reading: ## Overview -Datadog AI agents, including the Bits fleet (Bits SRE, Bits Dev, Bits Assistant, Bits Security Analyst) and Agent Builder workflows, 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. +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]. -1. In the search bar, enter the query: `@evt.actor.mode:*`. +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). -1. Optionally, use the {{< ui >}}Agent Type{{< /ui >}} and {{< ui >}}Agent Name{{< /ui >}} facets to narrow results down to a specific agent, such as Bits SRE or Bits Dev. -1. Click an event to open the detail drawer and see the full actor breakdown: the delegator (the user, if any), the agent, and the mode. +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**: Coverage rolls out per product and depends on each Datadog AI agent team onboarding to the actor and delegation model. Until an agent team completes onboarding, `@evt.actor.mode:*` under-reports that agent's activity. +**Note**: It's progressively being rolled out to all Datadog AI Agents. 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 a Datadog-managed OAuth client, such as the Datadog MCP server, carry the `is_mcp_call` field. +Actions taken through the Datadog MCP server, carry the `is_mcp_call` field. 1. Navigate to [Audit Trail][1]. -1. In the search bar, enter the query: `is_mcp_call:true`. -1. Click an event to see a link back to the MCP server configuration and to other events from the same MCP session. +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 @@ -41,17 +40,17 @@ When a Datadog AI agent acts on a user's behalf, the agent becomes `@evt.actor` To retrieve a user's complete activity, including delegated agent actions: 1. Navigate to [Audit Trail][1]. -1. In the search bar, enter the query: `(@usr.name: OR @delegator.name:)`. Replace `` with the user's email address. +2. In the search bar, enter the query: `(@usr.name: OR @delegator.name:)`. Replace `` with the user's email address. | Description of audit event | Query in audit explorer | | ------------------------------------------------------------------------------------------------------| ------------------------------------------------------------ | | Actions a user performed directly | `@usr.name:` | | All actions attributed to a user, including actions a Datadog AI agent performed on their behalf | `(@usr.name: OR @delegator.name:)` | -1. See [Create a dashboard or a graph][2] if you want to put this information into a dashboard or graph. +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. Use this alongside the {{< ui >}}Agent Type{{< /ui >}} and {{< ui >}}Agent Name{{< /ui >}} facets to build a saved view of agent activity for your security or compliance team. +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 From 2e96c28e309a630b0d65f49cff75e064330ae3a7 Mon Sep 17 00:00:00 2001 From: Anthony Dagneaux Date: Fri, 3 Jul 2026 17:37:35 +0200 Subject: [PATCH 3/3] docs(audit-trail): clarify Bits agent rollout coverage note --- content/en/account_management/audit_trail/events.md | 2 +- .../guides/track_agentic_usage_in_your_organization.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/account_management/audit_trail/events.md b/content/en/account_management/audit_trail/events.md index 28fea7c5dcf..462fd05431a 100644 --- a/content/en/account_management/audit_trail/events.md +++ b/content/en/account_management/audit_trail/events.md @@ -33,7 +33,7 @@ Use the following queries to find agent-driven events: | All actions taken by a Datadog AI agent | `@evt.actor.mode:*` | | All actions taken through the Datadog MCP server | `is_mcp_call:true` | -**Note**: It's progressively being rolled out to all Datadog AI Agents. 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. +**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]. diff --git a/content/en/account_management/audit_trail/guides/track_agentic_usage_in_your_organization.md b/content/en/account_management/audit_trail/guides/track_agentic_usage_in_your_organization.md index 0b7b1a3aabe..0364ad675d6 100644 --- a/content/en/account_management/audit_trail/guides/track_agentic_usage_in_your_organization.md +++ b/content/en/account_management/audit_trail/guides/track_agentic_usage_in_your_organization.md @@ -23,7 +23,7 @@ Datadog AI agents, including the Bits fleet (Bits SRE, Bits Dev, Bits Assistant, 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**: It's progressively being rolled out to all Datadog AI Agents. Actions from agents that have not yet onboarded do not appear in `@evt.actor.mode:*` results. +**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