Skip to content

ChatCompletionDiagnostics

NexusLabs.Needlr.AgentFramework

NexusLabs.Needlr.AgentFramework.Diagnostics

ChatCompletionDiagnostics Class

Diagnostics for a single LLM chat completion call within an agent run.

public sealed record ChatCompletionDiagnostics : System.IEquatable<NexusLabs.Needlr.AgentFramework.Diagnostics.ChatCompletionDiagnostics>

Inheritance System.Object 🡒 ChatCompletionDiagnostics

Implements System.IEquatable<ChatCompletionDiagnostics>

Example

foreach (var call in diagnostics.ChatCompletions)
{
    var fresh = call.Tokens.InputTokens - call.Tokens.CachedInputTokens;
    Console.WriteLine($"[{call.Model}] in:{call.Tokens.InputTokens} " +
        $"(cached:{call.Tokens.CachedInputTokens} fresh:{fresh}) " +
        $"out:{call.Tokens.OutputTokens} | {call.Duration.TotalMilliseconds}ms");
}

Remarks

Each time the agent calls the underlying IChatClient.GetResponseAsync, the diagnostics chat client middleware captures timing, token usage, and model metadata into one of these records. An agent that makes multiple LLM calls (e.g., a tool-call loop) produces multiple ChatCompletionDiagnostics entries within a single IAgentRunDiagnostics.

Constructors

ChatCompletionDiagnostics(int, string, TokenUsage, int, TimeSpan, bool, string, DateTimeOffset, DateTimeOffset) Constructor

Diagnostics for a single LLM chat completion call within an agent run.

public ChatCompletionDiagnostics(int Sequence, string Model, NexusLabs.Needlr.AgentFramework.Diagnostics.TokenUsage Tokens, int InputMessageCount, System.TimeSpan Duration, bool Succeeded, string? ErrorMessage, System.DateTimeOffset StartedAt, System.DateTimeOffset CompletedAt);

Parameters

Sequence System.Int32

Zero-based invocation order within the agent run.

Model System.String

The model identifier returned by the LLM provider (e.g., "gpt-4o", "claude-sonnet-4-20250514").

Tokens TokenUsage

Token usage breakdown for this single call.

InputMessageCount System.Int32

Number of ChatMessage entries sent to the model.

Duration System.TimeSpan

Wall-clock time for the API call.

Succeeded System.Boolean

Whether the call returned without throwing.

ErrorMessage System.String

The exception message if the call failed; null on success.

StartedAt System.DateTimeOffset

UTC timestamp when the API call began.

CompletedAt System.DateTimeOffset

UTC timestamp when the API call finished.

Example

foreach (var call in diagnostics.ChatCompletions)
{
    var fresh = call.Tokens.InputTokens - call.Tokens.CachedInputTokens;
    Console.WriteLine($"[{call.Model}] in:{call.Tokens.InputTokens} " +
        $"(cached:{call.Tokens.CachedInputTokens} fresh:{fresh}) " +
        $"out:{call.Tokens.OutputTokens} | {call.Duration.TotalMilliseconds}ms");
}

Remarks

Each time the agent calls the underlying IChatClient.GetResponseAsync, the diagnostics chat client middleware captures timing, token usage, and model metadata into one of these records. An agent that makes multiple LLM calls (e.g., a tool-call loop) produces multiple ChatCompletionDiagnostics entries within a single IAgentRunDiagnostics.

Properties

ChatCompletionDiagnostics.AgentName Property

The name of the agent that triggered this completion, or null if the agent name was not available. Used to attribute completions to the correct stage in group chat workflows where multiple agents share a single chat client.

public string? AgentName { get; init; }

Property Value

System.String

ChatCompletionDiagnostics.CompletedAt Property

UTC timestamp when the API call finished.

public System.DateTimeOffset CompletedAt { get; init; }

Property Value

System.DateTimeOffset

ChatCompletionDiagnostics.Duration Property

Wall-clock time for the API call.

public System.TimeSpan Duration { get; init; }

Property Value

System.TimeSpan

ChatCompletionDiagnostics.ErrorMessage Property

The exception message if the call failed; null on success.

public string? ErrorMessage { get; init; }

Property Value

System.String

ChatCompletionDiagnostics.InputMessageCount Property

Number of ChatMessage entries sent to the model.

public int InputMessageCount { get; init; }

Property Value

System.Int32

ChatCompletionDiagnostics.Model Property

The model identifier returned by the LLM provider (e.g., "gpt-4o", "claude-sonnet-4-20250514").

public string Model { get; init; }

Property Value

System.String

ChatCompletionDiagnostics.RequestCharCount Property

Total character count of the text content across every message in RequestMessages. Complements token-based metrics with a direct programmatic measure of payload size. Defaults to 0 when not populated by the capture middleware.

public long RequestCharCount { get; init; }

Property Value

System.Int64

ChatCompletionDiagnostics.RequestMessages Property

The full list of Microsoft.Extensions.AI.ChatMessage instances sent to the model for this completion. Captured losslessly to enable post-hoc replay and evaluation without re-invoking the agent. null if capture was unavailable (e.g., on call failure before messages were materialized).

public System.Collections.Generic.IReadOnlyList<Microsoft.Extensions.AI.ChatMessage>? RequestMessages { get; init; }

Property Value

System.Collections.Generic.IReadOnlyList<Microsoft.Extensions.AI.ChatMessage>

Remarks

Populated on success. This is the input side of the call and is directly consumable by Microsoft.Extensions.AI.Evaluation evaluators.

ChatCompletionDiagnostics.Response Property

The full Microsoft.Extensions.AI.ChatResponse returned by the model for this completion, or null if the call failed or the response was not captured. Captured losslessly to enable post-hoc replay and evaluation.

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

Property Value

Microsoft.Extensions.AI.ChatResponse

ChatCompletionDiagnostics.ResponseCharCount Property

Total character count of the text content across every message in Response. Defaults to 0 when not populated by the capture middleware.

public long ResponseCharCount { get; init; }

Property Value

System.Int64

ChatCompletionDiagnostics.Sequence Property

Zero-based invocation order within the agent run.

public int Sequence { get; init; }

Property Value

System.Int32

ChatCompletionDiagnostics.StartedAt Property

UTC timestamp when the API call began.

public System.DateTimeOffset StartedAt { get; init; }

Property Value

System.DateTimeOffset

ChatCompletionDiagnostics.Succeeded Property

Whether the call returned without throwing.

public bool Succeeded { get; init; }

Property Value

System.Boolean

ChatCompletionDiagnostics.Tokens Property

Token usage breakdown for this single call.

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

Property Value

TokenUsage