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.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