Skip to content

IAgentRunDiagnostics

NexusLabs.Needlr.AgentFramework

NexusLabs.Needlr.AgentFramework.Diagnostics

IAgentRunDiagnostics Interface

Immutable view of diagnostics captured during a single agent run, including token usage, per-call timing, tool call details, and success/failure state.

public interface IAgentRunDiagnostics

Example

using (diagnosticsAccessor.BeginCapture())
{
    await agent.RunAsync("Summarize this document.", cancellationToken: ct);
    var diag = diagnosticsAccessor.LastRunDiagnostics!;

    Console.WriteLine($"Agent: {diag.AgentName}");
    Console.WriteLine($"Duration: {diag.TotalDuration.TotalMilliseconds}ms");
    Console.WriteLine($"Tokens: {diag.AggregateTokenUsage.TotalTokens}");
    Console.WriteLine($"LLM calls: {diag.ChatCompletions.Count}");
    Console.WriteLine($"Tool calls: {diag.ToolCalls.Count}");
}

Remarks

Captured automatically when UsingDiagnostics() is called on the AgentFrameworkSyringe. Access via LastRunDiagnostics after an agent run, or via Diagnostics for pipeline/group-chat stages.

Properties

IAgentRunDiagnostics.AgentName Property

Gets the name of the agent that ran.

string AgentName { get; }

Property Value

System.String

IAgentRunDiagnostics.AggregateTokenUsage Property

Gets the aggregate token usage across all LLM calls in this run.

NexusLabs.Needlr.AgentFramework.Diagnostics.TokenUsage AggregateTokenUsage { get; }

Property Value

TokenUsage

IAgentRunDiagnostics.ChatCompletions Property

Gets per-call diagnostics for each LLM chat completion, ordered by invocation time.

System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.AgentFramework.Diagnostics.ChatCompletionDiagnostics> ChatCompletions { get; }

Property Value

System.Collections.Generic.IReadOnlyList<ChatCompletionDiagnostics>

IAgentRunDiagnostics.CompletedAt Property

Gets when the agent run completed.

System.DateTimeOffset CompletedAt { get; }

Property Value

System.DateTimeOffset

IAgentRunDiagnostics.ErrorMessage Property

Gets the error message if the run failed; null on success.

string? ErrorMessage { get; }

Property Value

System.String

IAgentRunDiagnostics.StartedAt Property

Gets when the agent run started.

System.DateTimeOffset StartedAt { get; }

Property Value

System.DateTimeOffset

IAgentRunDiagnostics.Succeeded Property

Gets whether the agent run completed successfully.

bool Succeeded { get; }

Property Value

System.Boolean

IAgentRunDiagnostics.ToolCalls Property

Gets per-call diagnostics for each tool invocation, ordered by invocation time.

System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.AgentFramework.Diagnostics.ToolCallDiagnostics> ToolCalls { get; }

Property Value

System.Collections.Generic.IReadOnlyList<ToolCallDiagnostics>

IAgentRunDiagnostics.TotalDuration Property

Gets the total wall-clock duration of the agent run.

System.TimeSpan TotalDuration { get; }

Property Value

System.TimeSpan

IAgentRunDiagnostics.TotalInputMessages Property

Gets the number of input messages provided to the agent.

int TotalInputMessages { get; }

Property Value

System.Int32

IAgentRunDiagnostics.TotalOutputMessages Property

Gets the number of output messages produced by the agent.

int TotalOutputMessages { get; }

Property Value

System.Int32