[Datadog AI Guard](https://docs.datadoghq.com/security/ai_guard/) is a defense-in-depth security solution that inspects, blocks, and governs AI behavior in real time. This integration connects AI Guard with Strands agents through the [Plugins](/docs/user-guide/concepts/plugins/index.md) system, providing inline security protection for your agent workflows.

With this integration, AI Guard automatically evaluates user prompts, model responses, tool calls, and tool results against configurable security policies — detecting and blocking threats like prompt injection, jailbreaking, data exfiltration, and destructive tool calls.

## Installation

Install the `ddtrace` package:

```bash
pip install ddtrace
```

Set the required environment variables:

```bash
export DD_AI_GUARD_ENABLED=true
export DD_API_KEY=<your-datadog-api-key>
export DD_APP_KEY=<your-datadog-application-key>
```

Ensure the Datadog Agent is running and reachable by the SDK. See the [AI Guard onboarding guide](https://docs.datadoghq.com/security/ai_guard/onboarding/?tab=python) for detailed setup instructions, including creating a retention filter and configuring security policies.

## Requirements

-   Python >= 3.9
-   `strands-agents` >= 1.29.0
-   `ddtrace` >= 4.7.0rc1
-   A [Datadog](https://www.datadoghq.com/) account with AI Guard enabled
-   Datadog API key and Application key (with `ai_guard_evaluate` scope)

Note

AI Guard is currently in **Preview**. Contact Datadog support to enable the feature flag for your organization.

## Usage

Import the `AIGuardStrandsPlugin` and pass it to your Strands agent:

agent.py

```python
from strands import Agent
from ddtrace.appsec.ai_guard import AIGuardStrandsPlugin

agent = Agent(
    plugins=[AIGuardStrandsPlugin()],
)

response = agent("What is the weather today?")
```

AI Guard automatically evaluates all prompts, responses, and tool interactions against your configured security policies. No additional instrumentation code is needed.

## How it works

The integration is provided by [`ddtrace`](https://github.com/DataDog/dd-trace-py) through the `AIGuardStrandsPlugin` class. It registers callbacks for four agent lifecycle events:

| Hook event | What it scans | On block |
| --- | --- | --- |
| `BeforeModelCallEvent` | User prompts (excludes tool results) | Raises `AIGuardAbortError` |
| `AfterModelCallEvent` | Assistant text content | Raises `AIGuardAbortError` |
| `BeforeToolCallEvent` | Pending tool call and conversation context | Cancels the tool with a descriptive message |
| `AfterToolCallEvent` | Tool result and conversation context | Replaces the tool result content |

Each callback calls the AI Guard API to evaluate the agent’s messages against your configured security policies. If a threat is detected, the hook blocks or sanitizes the content before it reaches the model or the user.

Tool results processed by `AfterToolCallEvent` are excluded from the next `BeforeModelCallEvent` scan to prevent double-evaluation.

## Configuration options

The `AIGuardStrandsPlugin` constructor accepts the following parameters:

| Parameter | Default | Description |
| --- | --- | --- |
| `detailed_error` | `False` | When `True`, appends the AI Guard reason to blocked messages (e.g., `"... canceled for security reasons: prompt_injection"`) |
| `raise_error_on_tool_calls` | `False` | When `True`, raises `AIGuardAbortError` on tool call violations instead of replacing the tool result content |

```python
plugin = AIGuardStrandsPlugin(
    detailed_error=True,
    raise_error_on_tool_calls=True,
)

agent = Agent(plugins=[plugin])
```

### Environment variables

| Variable | Description |
| --- | --- |
| `DD_AI_GUARD_ENABLED` | Set to `true` to enable AI Guard |
| `DD_API_KEY` | Your Datadog API key |
| `DD_APP_KEY` | Your Datadog Application key (requires `ai_guard_evaluate` scope) |

## Observability and security signals

When AI Guard is active, every LLM interaction is evaluated and traced. In Datadog you can:

-   View AI Guard traces in **APM** with the resource name `ai_guard`
-   Monitor blocked interactions using `@ai_guard.action: (DENY OR ABORT)`
-   Filter by attack categories such as `jailbreak`, `prompt_injection`, `data_exfiltration`, and `destructive_tool_call`
-   Set up alerts on the `datadog.ai_guard.evaluations` metric

See the [AI Guard documentation](https://docs.datadoghq.com/security/ai_guard/) for the full list of detected attack categories and monitoring capabilities.

## Error handling

If the AI Guard service is unreachable or returns a non-abort error, the agent continues operating normally. Only `AIGuardAbortError` exceptions propagate to the caller — network errors and other failures are logged at debug level and do not block agent execution.

## References

-   [Datadog AI Guard documentation](https://docs.datadoghq.com/security/ai_guard/)
-   [AI Guard onboarding guide](https://docs.datadoghq.com/security/ai_guard/onboarding/?tab=python)
-   [ddtrace-py repository](https://github.com/DataDog/dd-trace-py)
-   [Strands Plugins documentation](/docs/user-guide/concepts/plugins/index.md)