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

Gets the execution mode that produced these diagnostics, or null if unknown. Known values: "FunctionInvokingChatClient", "IterativeLoop".

string? ExecutionMode { get; }

Property Value

System.String

IAgentRunDiagnostics.InputMessages Property

Gets the full input messages provided to the agent for this run. Captured once at the agent-run boundary so evaluators can replay the exact prompt without re-reading per-call chat completion snapshots. Empty when no messages were captured (e.g., the run failed before the middleware observed the input).

System.Collections.Generic.IReadOnlyList<Microsoft.Extensions.AI.ChatMessage> InputMessages { get; }

Property Value

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

IAgentRunDiagnostics.OutputResponse Property

Gets the aggregated output response produced by the agent for this run, or null when no output was produced (e.g., the run failed before any updates were emitted). For streaming runs this is synthesized from accumulated Microsoft.Agents.AI.AgentResponseUpdate items grouped by message.

Microsoft.Agents.AI.AgentResponse? OutputResponse { get; }

Property Value

Microsoft.Agents.AI.AgentResponse

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