Skip to content

NexusLabs.Needlr.AgentFramework.Diagnostics

NexusLabs.Needlr.AgentFramework

NexusLabs.Needlr.AgentFramework.Diagnostics Namespace

Classes
AgentRunDiagnosticsBuilder 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.
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.
TokenUsage Token usage breakdown for a single LLM call or aggregate across an agent run.
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 pipeline, 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.
IPipelineRunResult Aggregated result of a multi-agent pipeline run, providing per-stage diagnostics alongside the response text from each agent.
IToolMetricsAccessor Allows tools to attach custom domain-specific metrics during execution. Metrics are collected by the diagnostics function-calling middleware and included in NexusLabs.Needlr.AgentFramework.Diagnostics.ToolCallDiagnostics.CustomMetrics.