Skip to main content
AgentDbg captures the events that matter most in an agent loop — LLM calls, tool calls, and intermediate state — through three recording functions. Each function attaches its event to the active traced run; if no run is active, the call is silently ignored unless implicit runs are enabled. All three functions apply the same redaction and truncation rules before writing to disk.

​
record_llm_call

Record a single LLM call event, including the prompt sent, the response received, token usage, and any metadata you want to attach. 
from agentdbg import record_llm_call

record_llm_call(
    model="gpt-4",
    prompt="Summarize the search results.",
    response="Found 2 users.",
    usage={"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15},
    meta={"step": "summarize"},
    provider="openai",
    temperature=0.7,
    stop_reason="stop",
    status="ok",
    error=None,
)

​
Parameters

​
model
str
required
Model name, for example "gpt-4" or "claude-3-opus". Required.
​
prompt
Any
default:"None"
Prompt sent to the model. Accepts a string, dict, or list (e.g. a chat messages array).
​
response
Any
default:"None"
Model response. Accepts the same types as prompt.
​
usage
dict | None
default:"None"
Token usage dictionary. Expected keys: prompt_tokens, completion_tokens, total_tokens.
​
meta
dict | None
default:"None"
Freeform metadata such as step labels, experiment tags, or any key-value pairs you want visible in the timeline.
​
provider
str
default:"\"unknown\""
Provider name: "openai", "anthropic", "local", etc.
​
temperature
float | None
default:"None"
Sampling temperature used for this call.
​
stop_reason
str | None
default:"None"
Why the model stopped generating: "stop", "length", etc.
​
status
str
default:"\"ok\""
"ok" for a successful call, "error" if the call failed.
​
error
str | BaseException | dict | None
default:"None"
Error details when status="error". Accepts an exception, a string message, or a dict.

​
record_tool_call

Record a tool call event: the tool name, its inputs, and either a result or an error. Typically called immediately after your tool function returns. 
from agentdbg import record_tool_call

record_tool_call(
    name="search_db",
    args={"query": "active users"},
    result={"count": 42},
    meta=None,
    status="ok",
    error=None,
)
To record a failed tool call, catch the exception and pass it through error: 
try:
    result = my_tool(args)
    record_tool_call(name="my_tool", args=args, result=result)
except Exception as e:
    record_tool_call(name="my_tool", args=args, status="error", error=e)
    raise

​
Parameters

​
name
str
required
Tool name as it appears in your agent code. Required.
​
args
Any
default:"None"
Arguments passed to the tool. Accepts any serialisable type.
​
result
Any
default:"None"
Return value from the tool.
​
meta
dict | None
default:"None"
Freeform metadata. Useful for tagging calls with step numbers, environment labels, or experiment identifiers.
​
status
str
default:"\"ok\""
"ok" for a successful call, "error" if the tool raised.
​
error
str | BaseException | dict | None
default:"None"
Error details when status="error".

​
record_state

Record a state-update event — a snapshot of your agent’s internal state at a point in time. This is useful for capturing message history length, memory contents, or any structured data that helps you understand where the agent is in its reasoning. 
from agentdbg import record_state

record_state(
    state={"step": 3, "messages": ["..."]},
    meta={"label": "after_search"},
    diff=None,
)

​
Parameters

​
state
Any
default:"None"
State snapshot. Accepts any object or string that describes the agent’s current state.
​
meta
dict | None
default:"None"
Freeform metadata.
​
diff
Any
default:"None"
Optional diff from the previous state, if you want to record only what changed.
record_state does not increment the LLM or tool call counters used by guardrails. It is safe to call it as often as you like without affecting guardrail thresholds.

​
Full example: ReAct-style agent loop

The following example shows all three recording functions working together inside a ReAct-style loop that alternates between LLM reasoning and tool execution. 
from agentdbg import trace, record_llm_call, record_tool_call, record_state

TOOLS = {"search": search_fn, "calculator": calc_fn}

@trace
def react_agent(question: str):
    messages = [{"role": "user", "content": question}]

    for step in range(10):
        response = llm_chat(messages)
        record_llm_call(
            model="gpt-4",
            prompt=messages,
            response=response,
            usage=response.get("usage"),
        )

        action = parse_action(response)
        if action is None:
            return response["content"]

        tool_fn = TOOLS[action["tool"]]
        result = tool_fn(**action["args"])
        record_tool_call(
            name=action["tool"],
            args=action["args"],
            result=result,
        )

        messages.append({"role": "assistant", "content": response["content"]})
        messages.append({"role": "tool", "content": str(result)})
        record_state(state={"step": step, "messages_count": len(messages)})

    return "Max steps reached"
After running, agentdbg view shows every LLM call, tool call, and state update in the order they occurred — making it straightforward to see where the agent went wrong or got stuck in a loop.

​
Redaction and truncation

All three record_* functions apply the same data-safety rules before writing events to disk:
  • Redaction: Dict keys matching configured patterns (such as api_key, token, or password) have their values replaced with __REDACTED__. This is applied recursively up to a depth of 10.
  • Truncation: Strings longer than AGENTDBG_MAX_FIELD_BYTES (default: 20 000 bytes) are truncated and suffixed with __TRUNCATED__.
You can adjust these rules through environment variables or your project or user YAML config. Environment variables take precedence over YAML:
SettingEnvironment variableYAML key
Redacted field namesAGENTDBG_REDACT_KEYSredact_keys
Enable/disable redactionAGENTDBG_REDACTredact
Max field size (bytes)AGENTDBG_MAX_FIELD_BYTESmax_field_bytes