Skip to main content
AgentDbg gives you two ways to start a traced run: the @trace decorator for wrapping agent functions, and the traced_run context manager for scripts, notebooks, or dynamic workflows where a decorator doesn’t fit. Both create an active run context that record_llm_call, record_tool_call, and record_state automatically attach to.

​
@trace decorator

Apply @trace to any function to turn it into a traced run. When the function is called, AgentDbg emits a RUN_START event, runs the body, then emits RUN_END. If the function raises, AgentDbg emits ERROR followed by RUN_END with status="error" and re-raises the exception. 
from agentdbg import trace

@trace
def run_agent():
    ...
You can pass arguments to configure the run name and enable guardrails: 
from agentdbg import trace

@trace(
    name="support_agent",
    stop_on_loop=True,
    max_llm_calls=12,
    max_tool_calls=20,
    max_events=100,
    max_duration_s=30,
)
def run_agent():
    ...

​
Parameters

​
name
str | None
default:"None"
Run name shown in agentdbg list and the timeline UI. Defaults to the function name when not set.
​
stop_on_loop
bool
default:"False"
Abort the run when loop detection emits a LOOP_WARNING event. Raises AgentDbgLoopAbort.
​
stop_on_loop_min_repetitions
int
default:"3"
Minimum number of repeated pattern occurrences required before stop_on_loop triggers.
​
max_llm_calls
int | None
default:"None"
Abort after more than N LLM calls. Raises AgentDbgGuardrailExceeded.
​
max_tool_calls
int | None
default:"None"
Abort after more than N tool calls. Raises AgentDbgGuardrailExceeded.
​
max_events
int | None
default:"None"
Abort after more than N total events recorded. Raises AgentDbgGuardrailExceeded.
​
max_duration_s
float | None
default:"None"
Abort when elapsed run time reaches this limit in seconds. Raises AgentDbgGuardrailExceeded.

​
traced_run context manager

traced_run starts a traced run using a with block. Use it when you cannot or don’t want to use a decorator — for example, in a Jupyter notebook cell, a script with a flat structure, or a dynamic workflow that assembles steps at runtime. 
from agentdbg import traced_run, record_tool_call, record_llm_call

with traced_run(name="my_pipeline"):
    record_tool_call(name="fetch", args={"url": "..."}, result="...")
    record_llm_call(model="gpt-4", prompt="...", response="...")
Guardrails are available on traced_run as well: 
from agentdbg import traced_run

with traced_run(
    name="react_debug",
    stop_on_loop=True,
    max_llm_calls=8,
    max_tool_calls=12,
    max_events=60,
    max_duration_s=20,
):
    ...
traced_run accepts the same parameters as @trace. See the parameter table above.
traced_run behavior is identical to @trace: if no run is already active it creates a new one; if a run is already active it attaches to it without creating nested run events.

​
has_active_run

has_active_run() returns True when a traced run is active in the current context — that is, inside a @trace-decorated function call or an open traced_run block. 
from agentdbg import has_active_run

if has_active_run():
    print("Inside a traced run")
Use has_active_run when you are writing utility code or library integrations that should record events only when the caller has already started a run, rather than creating a new implicit one.

​
Nested runs

Calling a @trace-decorated function from inside an already active run does not create a nested run or extra RUN_START/RUN_END events. All record_* calls inside the inner function still attach to the outer run. 
from agentdbg import trace, record_llm_call

@trace
def inner():
    record_llm_call(model="gpt-4", prompt="inner prompt", response="inner response")

@trace
def outer():
    inner()   # attaches to the outer run — no second RUN_START emitted
This means you can safely add @trace to helper functions without worrying about polluting the timeline with spurious run boundaries.

​
Implicit runs

By default, calling record_llm_call, record_tool_call, or record_state outside any traced run does nothing — the call is silently ignored. If your script does not have a single top-level entrypoint you can wrap, set the environment variable: 
export AGENTDBG_IMPLICIT_RUN=1
With this set, the first recorder call that finds no active run automatically creates an implicit run. All subsequent recorder calls attach to it until the process exits, at which point AgentDbg finalizes and writes the run.
Implicit runs capture everything in a single process-lifetime run. If your script calls multiple distinct agent workflows, consider using traced_run explicitly for each one so the timeline stays readable.