ToolCallDiagnostics

NexusLabs.Needlr.AgentFramework

NexusLabs.Needlr.AgentFramework.Diagnostics

ToolCallDiagnostics Class

Diagnostics for a single tool/function invocation within an agent run.

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

Inheritance System.Object 🡒 ToolCallDiagnostics

Implements System.IEquatable<ToolCallDiagnostics>

Example

foreach (var tool in diagnostics.ToolCalls)
{
    Console.WriteLine($"{tool.ToolName}: {tool.Duration.TotalMilliseconds}ms " +
        $"({(tool.Succeeded ? "ok" : tool.ErrorMessage)})");
    if (tool.CustomMetrics is { Count: > 0 })
        foreach (var (k, v) in tool.CustomMetrics)
            Console.WriteLine($"  {k} = {v}");
}

Remarks

Tool calls are captured by the diagnostics function-calling middleware and ordered by their Sequence number, which is reserved before the call begins. This ensures parallel tool calls are ordered by invocation time, not completion time.

Custom metrics (e.g., cache hit/miss, provider name, byte counts) can be attached via AttachMetric(string, object) during tool execution.

Constructors

ToolCallDiagnostics(int, string, TimeSpan, bool, string, DateTimeOffset, DateTimeOffset, IReadOnlyDictionary<string,object>) Constructor

Diagnostics for a single tool/function invocation within an agent run.

public ToolCallDiagnostics(int Sequence, string ToolName, System.TimeSpan Duration, bool Succeeded, string? ErrorMessage, System.DateTimeOffset StartedAt, System.DateTimeOffset CompletedAt, System.Collections.Generic.IReadOnlyDictionary<string,object?>? CustomMetrics);

Parameters

Sequence System.Int32

Zero-based invocation order within the agent run. Reserved before async execution begins.

ToolName System.String

The name of the tool/function that was called (e.g., "ReadFile", "WebSearch").

Duration System.TimeSpan

Wall-clock time for the tool execution.

Succeeded System.Boolean

Whether the tool returned a result without throwing.

ErrorMessage System.String

The exception message if the tool threw; null on success.

StartedAt System.DateTimeOffset

UTC timestamp when the tool invocation began.

CompletedAt System.DateTimeOffset

UTC timestamp when the tool invocation finished.

CustomMetrics System.Collections.Generic.IReadOnlyDictionary<System.String,System.Object>

Arbitrary key-value pairs attached by the tool implementation via IToolMetricsAccessor. null if no metrics were recorded.

Example

foreach (var tool in diagnostics.ToolCalls)
{
    Console.WriteLine($"{tool.ToolName}: {tool.Duration.TotalMilliseconds}ms " +
        $"({(tool.Succeeded ? "ok" : tool.ErrorMessage)})");
    if (tool.CustomMetrics is { Count: > 0 })
        foreach (var (k, v) in tool.CustomMetrics)
            Console.WriteLine($"  {k} = {v}");
}

Remarks

Tool calls are captured by the diagnostics function-calling middleware and ordered by their Sequence number, which is reserved before the call begins. This ensures parallel tool calls are ordered by invocation time, not completion time.

Custom metrics (e.g., cache hit/miss, provider name, byte counts) can be attached via AttachMetric(string, object) during tool execution.

Properties

ToolCallDiagnostics.AgentName Property

The name of the agent that triggered this tool call, or null if the agent name was not available. Used to attribute tool calls to the correct agent in multi-agent workflows where diagnostics are aggregated.

public string? AgentName { get; init; }

Property Value

System.String

ToolCallDiagnostics.CompletedAt Property

UTC timestamp when the tool invocation finished.

public System.DateTimeOffset CompletedAt { get; init; }

Property Value

System.DateTimeOffset

ToolCallDiagnostics.CustomMetrics Property

Arbitrary key-value pairs attached by the tool implementation via IToolMetricsAccessor. null if no metrics were recorded.

public System.Collections.Generic.IReadOnlyDictionary<string,object?>? CustomMetrics { get; init; }

Property Value

System.Collections.Generic.IReadOnlyDictionary<System.String,System.Object>

ToolCallDiagnostics.Duration Property

Wall-clock time for the tool execution.

public System.TimeSpan Duration { get; init; }

Property Value

System.TimeSpan

ToolCallDiagnostics.ErrorMessage Property

The exception message if the tool threw; null on success.

public string? ErrorMessage { get; init; }

Property Value

System.String

ToolCallDiagnostics.Sequence Property

Zero-based invocation order within the agent run. Reserved before async execution begins.

public int Sequence { get; init; }

Property Value

System.Int32

ToolCallDiagnostics.StartedAt Property

UTC timestamp when the tool invocation began.

public System.DateTimeOffset StartedAt { get; init; }

Property Value

System.DateTimeOffset

ToolCallDiagnostics.Succeeded Property

Whether the tool returned a result without throwing.

public bool Succeeded { get; init; }

Property Value

System.Boolean

ToolCallDiagnostics.ToolName Property

The name of the tool/function that was called (e.g., "ReadFile", "WebSearch").

public string ToolName { get; init; }

Property Value

System.String