AgentRunDiagnosticsBuilder

NexusLabs.Needlr.AgentFramework

NexusLabs.Needlr.AgentFramework.Diagnostics

AgentRunDiagnosticsBuilder Class

Thread-safe accumulator for diagnostics captured during a single agent run. Both Needlr's built-in diagnostics middleware and consumer-provided middleware use this class to record tool calls, chat completions, and message counts as an agent executes.

public sealed class AgentRunDiagnosticsBuilder : System.IDisposable

Inheritance System.Object 🡒 AgentRunDiagnosticsBuilder

Implements System.IDisposable

Remarks

Stored in an System.Threading.AsyncLocal<> so the agent-run, chat-completion, and function-calling middleware all access the same builder instance within an async flow. Call StartNew(string) at the beginning of an agent run and dispose the returned builder when the run completes.

Sequence numbers are reserved BEFORE async work begins (via System.Threading.Interlocked.Increment(System.Int32@)), ensuring parallel tool calls are ordered by invocation time, not completion time.

Methods

AgentRunDiagnosticsBuilder.ClearCurrent() Method

Clears the builder from the current async flow.

public static void ClearCurrent();

AgentRunDiagnosticsBuilder.Dispose() Method

Clears this builder from the current async flow. Equivalent to calling ClearCurrent() but usable in a using statement.

public void Dispose();

Implements Dispose()

AgentRunDiagnosticsBuilder.GetCurrent() Method

Gets the builder for the current async flow, or null if outside a run.

public static NexusLabs.Needlr.AgentFramework.Diagnostics.AgentRunDiagnosticsBuilder? GetCurrent();

Returns

AgentRunDiagnosticsBuilder

AgentRunDiagnosticsBuilder.NextChatCompletionSequence() Method

Reserves a sequence number for a chat completion (thread-safe).

public int NextChatCompletionSequence();

Returns

System.Int32

AgentRunDiagnosticsBuilder.NextToolCallSequence() Method

Reserves a sequence number for a tool call (thread-safe).

public int NextToolCallSequence();

Returns

System.Int32

AgentRunDiagnosticsBuilder.SetExecutionMode(string) Method

Sets the execution mode label for these diagnostics. Known values: "FunctionInvokingChatClient", "IterativeLoop".

public void SetExecutionMode(string executionMode);

Parameters

executionMode System.String

AgentRunDiagnosticsBuilder.StartNew(string) Method

Creates a new builder and stores it in the current async flow so middleware can access it.

public static NexusLabs.Needlr.AgentFramework.Diagnostics.AgentRunDiagnosticsBuilder StartNew(string agentName);

Parameters

agentName System.String

Returns

AgentRunDiagnosticsBuilder