Configuration reference

AgentDbg is configured via environment variables and YAML config files. All settings are optional; defaults are tuned for safe, local-only tracing.

Precedence

Configuration is merged in this order (highest wins):

Environment variables
Project config: .agentdbg/config.yaml in project root (current working directory when config is loaded)
User config: ~/.agentdbg/config.yaml
Defaults (see below)

Settings

Data directory

Env	YAML key	Default	Description
`AGENTDBG_DATA_DIR`	`data_dir`	`~/.agentdbg`	Base directory for runs. Runs are stored under `<data_dir>/runs/<run_id>/`.

Example (env):

export AGENTDBG_DATA_DIR=/path/to/my/agentdbg/data

Example (YAML):

# ~/.agentdbg/config.yaml or .agentdbg/config.yaml
data_dir: /path/to/my/agentdbg/data

Redaction

Env	YAML key	Default	Description
`AGENTDBG_REDACT`	`redact`	`1` (on)	Enable redaction. Use `1`, `true`, or `yes` to enable; any other value disables.
`AGENTDBG_REDACT_KEYS`	`redact_keys`	`api_key,token,authorization,cookie,secret,password`	Comma-separated list of key patterns (case-insensitive substring match).
`AGENTDBG_MAX_FIELD_BYTES`	`max_field_bytes`	`20000`	Maximum size in bytes for a string/field before truncation. Minimum enforced: 100.

Redaction behavior:

Applied recursively to nested dicts and lists (e.g. payloads and meta).
Key match: If a dict key contains any of the redact keys as a case-insensitive substring, the value is replaced with __REDACTED__ (the key is not redacted; the value is). Example: auth_token matches token; API_KEY matches api_key.
Recursion depth: Traversal is limited to depth 10 to avoid pathological structures; deeper values are replaced with the truncation marker.

Truncation behavior:

Strings (and other values serialized to strings) longer than AGENTDBG_MAX_FIELD_BYTES bytes (UTF-8) are truncated and suffixed with __TRUNCATED__.
At the recursion depth limit (10), the value is replaced with __TRUNCATED__.

Example (env):

export AGENTDBG_REDACT=1
export AGENTDBG_REDACT_KEYS="api_key,token,password,secret"
export AGENTDBG_MAX_FIELD_BYTES=10000

Example (YAML):

redact: true
redact_keys:
  - api_key
  - token
  - authorization
  - password
max_field_bytes: 10000

Loop detection

Env	YAML key	Default	Description
`AGENTDBG_LOOP_WINDOW`	`loop_window`	`12`	Number of recent events to consider for pattern detection. Minimum: 4.
`AGENTDBG_LOOP_REPETITIONS`	`loop_repetitions`	`3`	Consecutive repetitions of a pattern required to emit `LOOP_WARNING`. Minimum: 2.

Example (env):

export AGENTDBG_LOOP_WINDOW=20
export AGENTDBG_LOOP_REPETITIONS=4

Example (YAML):

loop_window: 20
loop_repetitions: 4

Guardrails

Guardrails are opt-in limits that stop a run after AgentDbg has enough evidence to show why it was aborted. They are applied after events are recorded, so the trace still contains the event that crossed the threshold.

Env	YAML key	Default	Description
`AGENTDBG_STOP_ON_LOOP`	`guardrails.stop_on_loop`	`false`	Abort when loop detection emits `LOOP_WARNING`.
`AGENTDBG_STOP_ON_LOOP_MIN_REPETITIONS`	`guardrails.stop_on_loop_min_repetitions`	`3`	Minimum repeated pattern count required to abort when `stop_on_loop` is enabled. Minimum: 2.
`AGENTDBG_MAX_LLM_CALLS`	`guardrails.max_llm_calls`	`null`	Abort after more than N LLM calls. Triggers at N+1.
`AGENTDBG_MAX_TOOL_CALLS`	`guardrails.max_tool_calls`	`null`	Abort after more than N tool calls. Triggers at N+1.
`AGENTDBG_MAX_EVENTS`	`guardrails.max_events`	`null`	Abort after more than N total events.
`AGENTDBG_MAX_DURATION_S`	`guardrails.max_duration_s`	`null`	Abort when elapsed run time reaches the configured number of seconds.

Important behavior:

Existing event types only: guardrails use normal LOOP_WARNING, ERROR, and RUN_END events.
Loop aborts: if stop_on_loop=true, AgentDbg writes LOOP_WARNING first, then aborts.
Count-based limits: max_llm_calls=10 allows 10 calls and aborts after the 11th is recorded.
Exception propagation: guardrail aborts raise AgentDbgLoopAbort or AgentDbgGuardrailExceeded; they are not swallowed.
Decorator/context-manager args win: values passed to @trace(...) or traced_run(...) override env and YAML config.

Example (env):

export AGENTDBG_STOP_ON_LOOP=1
export AGENTDBG_STOP_ON_LOOP_MIN_REPETITIONS=3
export AGENTDBG_MAX_LLM_CALLS=50
export AGENTDBG_MAX_TOOL_CALLS=50
export AGENTDBG_MAX_EVENTS=200
export AGENTDBG_MAX_DURATION_S=60

Example (YAML):

guardrails:
  stop_on_loop: true
  stop_on_loop_min_repetitions: 3
  max_llm_calls: 50
  max_tool_calls: 50
  max_events: 200
  max_duration_s: 60

See Guardrails for usage examples and lifecycle details.

Run name (env only)

Env	YAML	Default	Description
`AGENTDBG_RUN_NAME`	(not in YAML)	(derived)	Override the run name for the current process. Used when starting a run via `@trace`, `traced_run()`, or implicit run. If unset, run name is the explicit name argument, or a default like `path/to/script.py:main - 2026-02-18 14:12`.

Example:

export AGENTDBG_RUN_NAME="my-experiment-v1"

Implicit run (env only)

Env	YAML	Default	Description
`AGENTDBG_IMPLICIT_RUN`	(not in YAML)	unset (off)	If set to `1`, the first `record_*` call with no active run creates an implicit run; all subsequent recorder calls attach to it until process exit.

This is useful for scripts without a single @trace entrypoint. Only read from the environment; not configurable via YAML.

Example:

export AGENTDBG_IMPLICIT_RUN=1

Full YAML example

# ~/.agentdbg/config.yaml or .agentdbg/config.yaml
data_dir: ~/.agentdbg
redact: true
redact_keys:
  - api_key
  - token
  - authorization
  - cookie
  - secret
  - password
max_field_bytes: 20000
loop_window: 12
loop_repetitions: 3
guardrails:
  stop_on_loop: false
  stop_on_loop_min_repetitions: 3
  max_llm_calls: null
  max_tool_calls: null
  max_events: null
  max_duration_s: null

Safe-by-default local traces

Redaction is on by default so that common secret keys are not written to disk.
Data directory defaults to ~/.agentdbg so traces stay on the machine.
No cloud or network is used for trace storage. Override only what you need (e.g. AGENTDBG_DATA_DIR for project-local storage, or AGENTDBG_REDACT=0 for local debugging with full payloads).