IInFlightAgentDiagnosticsAccessor

NexusLabs.Needlr.AgentFramework ¶

NexusLabs.Needlr.AgentFramework.Diagnostics ¶

IInFlightAgentDiagnosticsAccessor Interface¶

Read-only accessor that exposes a snapshot of the diagnostics being accumulated for the currently in-flight agent run on the calling async flow. The post-run sibling is LastRunDiagnostics.

public interface IInFlightAgentDiagnosticsAccessor

Remarks¶

Backed by the same AgentRunDiagnosticsBuilder that produces the post-run IAgentRunDiagnostics. Each call to Current returns a freshly materialized snapshot — the chat completion and tool call collections are copied into ordered arrays at snapshot time so the caller can iterate freely while the underlying run continues to accumulate records.

The primary use case is intra-tool verification: a tool can inspect prior completed tool calls (and their structured arguments / return values, which are captured losslessly by Arguments and Result) to cross-check what an LLM is now claiming against what actually happened earlier in the same run.\<example> \<code> public sealed class RecordFixDecisionTool(IInFlightAgentDiagnosticsAccessor diagnostics) { [AgentFunction] public Result Record(int issueId, string action, string reason) { if (action == "Applied" && diagnostics.Current is { } snap) { var lastWrite = snap.ToolCalls .Where(t => t.ToolName == "FindReplaceWithCount") .LastOrDefault(); if (lastWrite?.Result is FindReplaceResult { Success: false } r) { // Override: agent said Applied but the prior write failed. action = "Rejected"; reason = $"[auto-corrected: prior write failed: {r.Error}] {reason}"; } } // ... } } \</code> \</example>

Mid-flight semantics on the returned snapshot. The shape is IAgentRunDiagnostics, which is also used post-run, but a few fields have provisional meaning while the run is still executing: - ToolCalls contains every tool call that has completed on this async flow so far, in chronological order by reserved sequence number. The currently executing tool call (the one whose body called Current) is not present — diagnostics are appended only after the tool returns. - ChatCompletions contains every chat completion that has finished so far. Like tool calls, the in-progress completion that triggered the current tool call is not yet present. - AggregateTokenUsage reflects only the completed completions; it grows as the run continues. - TotalDuration is elapsed-so-far, measured from StartedAt to the instant the snapshot was taken. - CompletedAt is the snapshot time, not a true run-end time. - Succeeded defaults to true unless the run has already explicitly recorded a failure. ErrorMessage follows the same rule. - OutputResponse is typically null mid-run because the response is recorded at run end.

Sub-agent semantics. If a sub-agent is currently executing (i.e. its own AgentRunDiagnosticsBuilder was pushed onto the AsyncLocal stack), Current reflects the innermost (sub-agent's) run. When the sub-agent completes and its builder is disposed, the parent run's builder becomes current again.

Concurrency. Each agent run on a parallel async flow has its own AsyncLocal-scoped builder, so Current on flow A never returns diagnostics from flow B. The snapshot itself is immutable: subsequent additions to the underlying builder do not mutate previously-returned snapshots.

Returns when called outside an active agent run (e.g. from production code that resolves the accessor directly without going through the diagnostics middleware, or from tests that did not start a builder). Callers must handle null gracefully.

Properties¶