Skip to main content

Documentation Index

Fetch the complete documentation index at: https://reasonblocks.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

ReasonBlocks records a StepRecord for every reasoning step the agent takes during a run. After the run completes you access the full list through TraceState.steps, along with aggregate fields like difficulty_history and total_tokens. Both types are dataclasses defined in reasonblocks.types. 
from reasonblocks.types import StepRecord, TraceState, FSMState

​
StepRecord

StepRecord captures the raw content and scoring result for one agent step.
​
step_index
int
required
Zero-based position of this step within the run. The first scored step is 0.
​
thought
str
required
The agent’s reasoning text for this step — the content of the Thought: section parsed from the agent output. Always populated; empty string if the agent produced no explicit thought.
​
action
str | None
The tool or action name the agent selected, if any. None for steps where the agent produced a final answer rather than a tool call.
​
action_input
str | None
The input passed to the tool or action. None when action is None.
​
observation
str | None
The tool’s return value for this step. None for the final answer step and for any step where no tool was called.
​
difficulty
float
Difficulty score for this step in the range [0.0, 1.0]. Higher values indicate the agent is struggling. Scores above 0.6 contribute toward a SLOW transition; scores above 0.85 count toward SKIP.
​
state
FSMState
The FSM state after this step was scored. Reflects any state transition that occurred as a result of this step’s difficulty score. See FSMState for the full state reference.
​
tokens_used
int
Number of tokens consumed by the LLM call that produced this step. Summed across all steps in TraceState.total_tokens.

​
TraceState

TraceState is the internal state accumulator for the entire agent run. It is managed by the SDK and not directly exposed via step_log — you access per-step data via the step_log list instead. The fields below are documented here as a reference for their data shapes.
​
trace_id
str
required
Unique identifier for this run, set from the run_id you pass to rb.middleware(run_id=...). Used to correlate steps with run-level events in the ReasonBlocks dashboard.
​
steps
list[StepRecord]
Ordered list of every StepRecord captured during the run, from step_index=0 to the final step. Empty until the first step is scored.
​
current_state
FSMState
The FSM state at the end of the run (or at the point you read this field if you inspect it mid-run). Starts as FSMState.INIT.
​
difficulty_history
list[float]
Flat list of difficulty scores in step order. Equivalent to [s.difficulty for s in steps]. Useful for plotting difficulty over time or computing aggregate statistics.
​
total_tokens
int
Cumulative token count across all steps in the run. Sum of every StepRecord.tokens_used value.
​
token_budget
int | None
The token budget configured for this run, if any. When set, the SDK uses this value to calculate StepAssessment.budget_used and may trigger early-exit behavior as the budget is approached. None if no budget was configured.

​
Reading step_log after a run

Access step_log on the middleware instance after the with block exits. step_log is a list[StepLogEntry] — one entry per model call — that includes FSM state, difficulty, monitors fired, and injection details for each step. 
from reasonblocks import ReasonBlocks

rb = ReasonBlocks(api_key="rb_live_...")

with rb.middleware(run_id="run-1", agent_name="reviewer", task="review PR #42") as mw:
    result = agent.invoke({"messages": [("user", "Review the changes in PR #42")]})

for entry in mw.step_log:
    print(
        f"  [{entry.step}] difficulty={entry.difficulty:.2f}  "
        f"state={entry.fsm_state}  action={entry.tool_calls}"
    )
Use entry.as_dict() on any StepLogEntry to get a serialisable dict with all fields, useful for logging or exporting run data.