Skip to content

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.

Properties

AgentRunDiagnosticsBuilder.ParentAgentName Property

Gets the name of the parent (outer) agent when this builder was created inside a nested sub-agent run, or null if this is a top-level agent.

public string? ParentAgentName { get; }

Property Value

System.String

Methods

AgentRunDiagnosticsBuilder.ClearCurrent() Method

Clears the builder from the current async flow.

public static void ClearCurrent();

AgentRunDiagnosticsBuilder.Dispose() Method

Restores the previous builder (if any) to the current async flow. If this builder was created inside a nested sub-agent run, the outer agent's builder is restored. Otherwise equivalent to ClearCurrent().

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.RecordInputMessages(IReadOnlyList<ChatMessage>) Method

Records the full input messages supplied to the agent for this run. Captured once at the agent-run boundary; calling more than once replaces the snapshot.

public void RecordInputMessages(System.Collections.Generic.IReadOnlyList<Microsoft.Extensions.AI.ChatMessage> messages);

Parameters

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

AgentRunDiagnosticsBuilder.RecordOutputResponse(AgentResponse) Method

Records the aggregated output response produced by the agent for this run. Pass null when no response was produced.

public void RecordOutputResponse(Microsoft.Agents.AI.AgentResponse? response);

Parameters

response Microsoft.Agents.AI.AgentResponse

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. If a builder already exists (nested sub-agent scenario), the previous builder is saved and restored when this builder is disposed.

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

Parameters

agentName System.String

Returns

AgentRunDiagnosticsBuilder