NexusLabs.Needlr.AgentFramework.Diagnostics

NexusLabs.Needlr.AgentFramework

NexusLabs.Needlr.AgentFramework.Diagnostics Namespace

Classes
AgentFrameworkMetricsOptions	Configuration options for the agent framework's OpenTelemetry metrics and tracing.
AgentRunDiagnosticsBuilder	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.
AgentRunDiagnosticsTimelineExtensions	Extensions for producing ordered timeline views of an IAgentRunDiagnostics.
AgentRunDiagnosticsTranscriptExtensions	Extensions for rendering an IAgentRunDiagnostics as a human-readable markdown transcript.
ChatCompletionCollectorHolder	DI-registered singleton that holds the IChatCompletionCollector instance. The diagnostics middleware sets the real collector during factory construction; consumers resolve this to access it. Unlike a static holder, each DI container has its own instance, making it testable and thread-safe across containers.
ChatCompletionDiagnostics	Diagnostics for a single LLM chat completion call within an agent run.
DiagnosticsCharCounter	Computes character counts of chat messages, responses, tool arguments, and tool results for diagnostics capture. Character counts are a direct programmatic measure of payload size — distinct from the LLM-provider-reported TokenUsage — and are useful for detecting chat-reducer drift, prompt bloat, and unexpectedly large tool responses during evaluation.
DiagnosticsFunctionInvocationExtensions	Extension methods for wiring DiagnosticsFunctionInvokingChatClient into an MEAI chat client pipeline.
DiagnosticsFunctionInvokingChatClient	A Microsoft.Extensions.AI.FunctionInvokingChatClient that records per-tool-call diagnostics, OTel metrics, and Activity spans for every function invocation. This is the MEAI-native equivalent of the MAF DiagnosticsFunctionCallingMiddleware in Workflows.
DiagnosticsRecordingChatClient	Microsoft.Extensions.AI.DelegatingChatClient that routes calls through a NexusLabs.Needlr.AgentFramework.Diagnostics.DiagnosticsChatClientMiddleware and is detectable via GetService. Because this extends Microsoft.Extensions.AI.DelegatingChatClient, MEAI's GetService walks the delegation chain and returns this instance when queried by type — enabling idempotent middleware installation.
DiagnosticsTimelineEntry	A single entry in an agent run's ordered timeline of chat completions and tool calls.
TeeDiagnosticsSink	An IDiagnosticsSink that dispatches every record to N inner sinks. Owns its own sequence counters so all sinks see consistent sequence numbers.
TokenUsage	Token usage breakdown for a single LLM call or aggregate across an agent run.
ToolCallCollectorHolder	DI-registered singleton that holds the IToolCallCollector instance. The diagnostics middleware sets the real collector during factory construction; consumers resolve this to access it. Unlike a static holder, each DI container has its own instance, making it testable and thread-safe across containers.
ToolCallDiagnostics	Diagnostics for a single tool/function invocation within an agent run.
WorkflowRunOptions	Options for running a workflow with diagnostics and progress reporting. Consolidates the parameters for RunWithDiagnosticsAsync into a single record to avoid excessive parameter counts.

Interfaces
IAgentDiagnosticsAccessor	Provides access to the diagnostics captured during the most recent agent run in the current async flow. Uses the mutable-holder System.Threading.AsyncLocal<> pattern so that writes from child async flows (inside middleware) are visible to the parent scope.
IAgentDiagnosticsWriter	Write-side interface for storing diagnostics captured by middleware. Separated from IAgentDiagnosticsAccessor (the read-side) so that middleware can resolve this from DI without casting to a concrete type.
IAgentMetrics	Records agent execution metrics for observability. The default implementation emits System.Diagnostics.Metrics.Meter counters/histograms and System.Diagnostics.ActivitySource activities compatible with OpenTelemetry.
IAgentRunDiagnostics	Immutable view of diagnostics captured during a single agent run, including token usage, per-call timing, tool call details, and success/failure state.
IAgentStageResult	Result of a single agent stage within a multi-agent pipeline or group chat workflow, combining the response text with the captured diagnostics for that stage.
IChatCompletionCollector	Provides access to per-LLM-call completion diagnostics captured by the chat client middleware. Used by pipeline run extensions to correlate LLM call timing with agent turns.
IDagNodeResult	Diagnostics for a single node within a DAG workflow execution, including edge connectivity, timing offsets relative to the workflow start, and the NodeKind discriminator that distinguishes agent nodes from reducer nodes.
IDagRunResult	Aggregated result of a DAG workflow run, extending IPipelineRunResult with per-node diagnostics, edge metadata, and parallel branch grouping.
IDiagnosticsSink	Accepts diagnostic records produced during an agent run. Writers (middleware, orchestration loops) call these methods to record individual chat completions and tool calls. The sink is responsible for storage and aggregation.
IInFlightAgentDiagnosticsAccessor	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.
IPipelineRunResult	Aggregated result of a multi-agent pipeline run, providing per-stage diagnostics alongside the response text from each agent.
IToolCallCollector	Provides access to per-tool-call diagnostics captured by the function-calling middleware. Used by pipeline run extensions to prevent silent tool call data loss when AsyncLocal diagnostics builders don't propagate across workflow infrastructure.
IToolMetricsAccessor	Allows tools to attach custom domain-specific metrics during execution. Metrics are collected by the diagnostics function-calling middleware and included in CustomMetrics.

Enums
ChatCompletionActivityMode	Controls how Needlr's diagnostics middleware creates System.Diagnostics.Activity spans for chat completion calls.
DiagnosticsTimelineEntryKind	Identifies the kind of event a DiagnosticsTimelineEntry represents.
NodeKind	Discriminates between agent nodes (backed by an LLM) and reducer nodes (pure deterministic functions) in a DAG workflow result.
StageOutcome	The outcome of a pipeline stage execution.