Redact Secrets from Agent Traces Automatically

AgentDbg scrubs values for sensitive keys before writing any trace data to disk, keeping API keys and tokens out of your local trace files by default.

AgentDbg applies redaction to every trace it writes. Before any event data touches disk, AgentDbg walks the payload and replaces values whose keys match known sensitive patterns with the placeholder __REDACTED__. This means that even if your agent passes API keys, authorization headers, or passwords through its tool calls or LLM inputs, those values do not end up in your local trace files.

What redaction does

When AgentDbg records an event, it serializes the payload — which may include nested dicts and lists from LLM inputs, tool arguments, and state snapshots. Before writing, it walks the structure and applies two protections:

• Key-based redaction: if a dict key contains any of the configured patterns as a case-insensitive substring, the value is replaced with __REDACTED__. The key itself is kept so you can still see which field was sensitive.
• Size-based truncation: strings longer than AGENTDBG_MAX_FIELD_BYTES bytes (UTF-8) are cut at the limit and suffixed with __TRUNCATED__.

Both rules are applied recursively into nested dicts and lists, up to a depth of 10. At depth 10, any remaining value is replaced with __TRUNCATED__ regardless of size.

Default behavior

Redaction is on by default. You do not need to configure anything to get it.

The default set of redacted key patterns is:

api_key, token, authorization, cookie, secret, password

Matching is case-insensitive and uses substring comparison. A dict key of auth_token matches token; API_KEY matches api_key; X-Authorization matches authorization.

The default truncation limit is 20,000 bytes. Strings longer than that are cut and marked __TRUNCATED__.

Configure redaction

Env vars

# Keep redaction on (default)
export AGENTDBG_REDACT=1

# Replace the full list of key patterns
export AGENTDBG_REDACT_KEYS="api_key,token,authorization,cookie,secret,password"

# Lower the truncation limit
export AGENTDBG_MAX_FIELD_BYTES=10000

YAML

# .agentdbg/config.yaml  or  ~/.agentdbg/config.yaml
redact: true
redact_keys:
  - api_key
  - token
  - authorization
  - cookie
  - secret
  - password
max_field_bytes: 10000

AGENTDBG_REDACT accepts 1, true, or yes to enable redaction. Any other value disables it.

Add custom redaction keys

To redact additional fields, replace the AGENTDBG_REDACT_KEYS list with your full desired set. The list is not additive — if you set it, it replaces the defaults. Include the default patterns you still want to keep.

Env vars

# Adds "session_id" and "client_secret" alongside the defaults
export AGENTDBG_REDACT_KEYS="api_key,token,authorization,cookie,secret,password,session_id,client_secret"

YAML

redact_keys:
  - api_key
  - token
  - authorization
  - cookie
  - secret
  - password
  - session_id
  - client_secret

Disable redaction for local debugging

If you need to inspect raw payloads during a debugging session, you can turn redaction off entirely.

Env vars

export AGENTDBG_REDACT=0

YAML

redact: false

Disabling redaction means every value in every payload is written to disk exactly as recorded, including API keys, tokens, authorization headers, and passwords. Only disable redaction when you are debugging locally and the trace files will not be shared, committed, or left on a shared machine.

Redaction reference

Env var	YAML key	Default	Description
AGENTDBG_REDACT	redact	1 (on)	Enable or disable redaction globally.
AGENTDBG_REDACT_KEYS	redact_keys	api_key,token,authorization,cookie,secret,password	Comma-separated list of key patterns. Replaces defaults when set.
AGENTDBG_MAX_FIELD_BYTES	max_field_bytes	20000	Truncation limit in bytes. Minimum enforced value: 100.

For a full list of all AgentDbg settings in one place, see Configuration overview.