Getting Guardrail Trace with Strands Agents and LiteLLM (Bedrock)

[naorlevi1]

Hi!

We want to use guardrail detection actions to track user behavior in our Strands Agents–based chat app.
We set the guardrail on our Bedrock account in detection mode only. However, we are unable to get the guardrail trace when using Strands Agents with LiteLLM (LiteLLMModel).

Note that we are self-hosting the LiteLLM proxy. In our case, we define the guardrailConfig on the request itself (example below) rather than in the config.yaml of the LiteLLM proxy.

When we access Bedrock directly, we were able to confirm the guardrail is applied (e.g., by changing detection mode to block and verifying the input was blocked), but we still were not able to get the trace in the response.

Here is a working example using LiteLLM (https://docs.litellm.ai/docs/providers/bedrock#usage---bedrock-guardrails):

litellm.completion(
    model="hosted_vllm/bedrock/claude-sonnet-4",
    messages=[{"role": "user", "content": "Pretend you are a financial advisor"}],
    api_key="<api-key>",
    api_base="<url-base>",
    guardrailConfig={
        "guardrailIdentifier": "<guardrail-id>",  # The identifier (ID) for the guardrail.
        "guardrailVersion": "1",  # The version of the guardrail.
        "trace": "enabled",       # Can be "disabled" or "enabled"
    }
)

Our attempt using Strands Agents with LiteLLM:

LiteLLMModel(
    model_id="hosted_vllm/bedrock/claude-sonnet-4",
    client_args={
        "api_key": os.getenv("LITELLM_CELESTE_VIRTUAL_KEY"),
        "base_url": os.getenv("LITELLM_PROXY_URL"),
    },
    params={
        "temperature": 0.1,
        "guardrailConfig": {
            "guardrailIdentifier": "<guardrail-id>",
            "guardrailVersion": "1",
            "trace": "enabled"
        }
    }
)

Is it possible to achieve guardrail detection and especially getting the trace using Strands Agents together with LiteLLM?
Any guidance or examples would be greatly appreciated.
Many thanks in advance!

[yonib05]

Hi @naorlevi1, thanks for the detailed writeup, and sorry for the very late response; it shouldn't have taken this long.

Two separate things are going on here. Passing guardrailConfig inside params does work for enforcement: everything in params is forwarded as-is to the litellm.completion call, which matches your working raw LiteLLM example. But the trace is a different story. The Strands LiteLLM provider only reads message content, tool calls, the finish reason, and token usage from LiteLLM responses, so any guardrail trace data that comes back is dropped before it reaches you. There's currently no way to get the trace out through LiteLLMModel. So what you're seeing is expected, not a config problem on your end.

For your detection-mode tracking use case there are two paths that work today. The first is going to Bedrock directly. BedrockModel has first-class guardrail support (guardrail_id, guardrail_version, guardrail_trace="enabled"), surfaces the trace in the response metadata, and handles blocked-content redaction for you. If you need to stay on your LiteLLM proxy, you can run the guardrail out of band instead: register hooks that call Bedrock's ApplyGuardrail API on each user message and agent response in shadow mode, which gives you the full assessment payload to log without touching the model call. The guardrails docs have a complete notify-only example of exactly this pattern: guardrails.

[yonib05]

Separately, on making this better going forward: #1925 is an open ask for first-class observability when guardrails trigger. If that's your use case too, give it a 👍 so we know more people want it. The LiteLLM-specific piece (passing provider response fields like the trace through) isn't tracked anywhere yet, so if the hook approach doesn't cut it, open a feature request and we'll take it from there.