Skip to content

IterationRecord

NexusLabs.Needlr.AgentFramework

NexusLabs.Needlr.AgentFramework.Iterative

IterationRecord Class

Captures what happened during a single iteration of an IIterativeAgentLoop, including tool calls made, any text response produced, token usage, and wall-clock duration.

public sealed record IterationRecord : System.IEquatable<NexusLabs.Needlr.AgentFramework.Iterative.IterationRecord>

Inheritance System.Object 🡒 IterationRecord

Implements System.IEquatable<IterationRecord>

Constructors

IterationRecord(int, IReadOnlyList<ToolCallResult>, ChatResponse, TokenUsage, TimeSpan, int, int) Constructor

Captures what happened during a single iteration of an IIterativeAgentLoop, including tool calls made, any text response produced, token usage, and wall-clock duration.

public IterationRecord(int Iteration, System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.AgentFramework.Iterative.ToolCallResult> ToolCalls, Microsoft.Extensions.AI.ChatResponse? FinalResponse, NexusLabs.Needlr.AgentFramework.Diagnostics.TokenUsage Tokens, System.TimeSpan Duration, int LlmCallCount, int ToolCallCount);

Parameters

Iteration System.Int32

Zero-based iteration index.

ToolCalls System.Collections.Generic.IReadOnlyList<ToolCallResult>

All tool calls executed during this iteration, in execution order. Empty if the model produced a text response without requesting tools.

FinalResponse Microsoft.Extensions.AI.ChatResponse

The final Microsoft.Extensions.AI.ChatResponse produced by the model during this iteration (preserving full message content, role, usage, and metadata), or null if the model only made tool calls without a terminating text response. In OneRoundTrip and MultiRound modes, this is the response emitted after tool results were sent back. Call .Text for a flat text view when evaluating.

Tokens TokenUsage

Aggregate token usage across all LLM calls in this iteration.

Duration System.TimeSpan

Wall-clock time for the entire iteration (LLM calls + tool execution).

LlmCallCount System.Int32

Number of LLM calls made during this iteration. Always 1 for SingleCall, at most 2 for OneRoundTrip.

ToolCallCount System.Int32

Number of tool calls executed during this iteration.

Properties

IterationRecord.Duration Property

Wall-clock time for the entire iteration (LLM calls + tool execution).

public System.TimeSpan Duration { get; init; }

Property Value

System.TimeSpan

IterationRecord.FinalResponse Property

The final Microsoft.Extensions.AI.ChatResponse produced by the model during this iteration (preserving full message content, role, usage, and metadata), or null if the model only made tool calls without a terminating text response. In OneRoundTrip and MultiRound modes, this is the response emitted after tool results were sent back. Call .Text for a flat text view when evaluating.

public Microsoft.Extensions.AI.ChatResponse? FinalResponse { get; init; }

Property Value

Microsoft.Extensions.AI.ChatResponse

IterationRecord.Iteration Property

Zero-based iteration index.

public int Iteration { get; init; }

Property Value

System.Int32

IterationRecord.LlmCallCount Property

Number of LLM calls made during this iteration. Always 1 for SingleCall, at most 2 for OneRoundTrip.

public int LlmCallCount { get; init; }

Property Value

System.Int32

IterationRecord.Tokens Property

Aggregate token usage across all LLM calls in this iteration.

public NexusLabs.Needlr.AgentFramework.Diagnostics.TokenUsage Tokens { get; init; }

Property Value

TokenUsage

IterationRecord.ToolCallCount Property

Number of tool calls executed during this iteration.

public int ToolCallCount { get; init; }

Property Value

System.Int32

IterationRecord.ToolCalls Property

All tool calls executed during this iteration, in execution order. Empty if the model produced a text response without requesting tools.

public System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.AgentFramework.Iterative.ToolCallResult> ToolCalls { get; init; }

Property Value

System.Collections.Generic.IReadOnlyList<ToolCallResult>