Record LLM Calls, Tool Calls, and State in AgentDbg

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

str

required

Model name, for example "gpt-4" or "claude-3-opus". Required.

Any

default:"None"

Prompt sent to the model. Accepts a string, dict, or list (e.g. a chat messages array).

Any

default:"None"

Model response. Accepts the same types as prompt.

dict | None

default:"None"

Token usage dictionary. Expected keys: prompt_tokens, completion_tokens, total_tokens.

dict | None

default:"None"

Freeform metadata such as step labels, experiment tags, or any key-value pairs you want visible in the timeline.

str

default:"\"unknown\""

Provider name: "openai", "anthropic", "local", etc.

float | None

default:"None"

Sampling temperature used for this call.

str | None

default:"None"

Why the model stopped generating: "stop", "length", etc.

str

default:"\"ok\""

"ok" for a successful call, "error" if the call failed.

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

str

required

Tool name as it appears in your agent code. Required.

Any

default:"None"

Arguments passed to the tool. Accepts any serialisable type.

Any

default:"None"

Return value from the tool.

dict | None

default:"None"

Freeform metadata. Useful for tagging calls with step numbers, environment labels, or experiment identifiers.

str

default:"\"ok\""

"ok" for a successful call, "error" if the tool raised.

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

Any

default:"None"

State snapshot. Accepts any object or string that describes the agent’s current state.

dict | None

default:"None"

Freeform metadata.

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:

Setting	Environment variable	YAML key
Redacted field names	`AGENTDBG_REDACT_KEYS`	`redact_keys`
Enable/disable redaction	`AGENTDBG_REDACT`	`redact`
Max field size (bytes)	`AGENTDBG_MAX_FIELD_BYTES`	`max_field_bytes`

Get Started

SDK

Integrations

Configuration

Reference

Record LLM Calls, Tool Calls, and State in AgentDbg

`record_llm_call`

Parameters

`record_tool_call`

Parameters

`record_state`

Parameters

Full example: ReAct-style agent loop

Redaction and truncation

​record_llm_call

​Parameters

​record_tool_call

​Parameters

​record_state

​Parameters

​Full example: ReAct-style agent loop

​Redaction and truncation

`record_llm_call`

Parameters

`record_tool_call`

Parameters

`record_state`

Parameters

Full example: ReAct-style agent loop

Redaction and truncation