AgentRunDiagnosticsBuilder

NexusLabs.Needlr.AgentFramework

NexusLabs.Needlr.AgentFramework.Diagnostics

AgentRunDiagnosticsBuilder Class

Thread-safe accumulator for diagnostics captured during a single agent run. Implements IDiagnosticsSink so writers (middleware, loops) record through a stable interface rather than coupling to the concrete builder.

public sealed class AgentRunDiagnosticsBuilder : NexusLabs.Needlr.AgentFramework.Diagnostics.IDiagnosticsSink, System.IDisposable

Inheritance System.Object 🡒 AgentRunDiagnosticsBuilder

Implements IDiagnosticsSink, System.IDisposable

Remarks

Stored in an System.Threading.AsyncLocal<> so middleware layers 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.

Each event class has a single designated writer. Chat completions are written exclusively by NexusLabs.Needlr.AgentFramework.Diagnostics.DiagnosticsChatClientMiddleware. Tool calls are written exclusively by the IterativeAgentLoop (MEAI path) or DiagnosticsFunctionCallingMiddleware (MAF path). Two writers for the same event class is a bug.

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();

Implements NextChatCompletionSequence()

Returns

System.Int32

AgentRunDiagnosticsBuilder.NextToolCallSequence() Method

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

public int NextToolCallSequence();

Implements 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

AgentRunDiagnosticsBuilder.StartNew(string, IReadOnlyList<IDiagnosticsSink>) Method

Creates a new builder with secondary sinks that receive forwarded diagnostic records. The builder remains the primary accumulator; secondary sinks receive copies of each NexusLabs.Needlr.AgentFramework.Diagnostics.AgentRunDiagnosticsBuilder.AddChatCompletion(NexusLabs.Needlr.AgentFramework.Diagnostics.ChatCompletionDiagnostics) and NexusLabs.Needlr.AgentFramework.Diagnostics.AgentRunDiagnosticsBuilder.AddToolCall(NexusLabs.Needlr.AgentFramework.Diagnostics.ToolCallDiagnostics) call on a best-effort basis (sink failures are swallowed).

public static NexusLabs.Needlr.AgentFramework.Diagnostics.AgentRunDiagnosticsBuilder StartNew(string agentName, System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.AgentFramework.Diagnostics.IDiagnosticsSink>? secondarySinks);

Parameters

agentName System.String

The name of the agent being traced.

secondarySinks System.Collections.Generic.IReadOnlyList<IDiagnosticsSink>

Additional sinks to fan out to, or null.

Returns

AgentRunDiagnosticsBuilder