IAgentStageResult

NexusLabs.Needlr.AgentFramework

NexusLabs.Needlr.AgentFramework.Diagnostics

IAgentStageResult Interface

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.

public interface IAgentStageResult

Example

var result = await workflow.RunWithDiagnosticsAsync(prompt, accessor);
foreach (var stage in result.Stages)
{
    var tokens = stage.Diagnostics?.AggregateTokenUsage;
    Console.WriteLine($"[{stage.AgentName}] {tokens?.TotalTokens ?? 0} tokens, " +
        $"{stage.Diagnostics?.TotalDuration.TotalSeconds:F1}s");
    var text = stage.FinalResponse?.Text ?? string.Empty;
    Console.WriteLine($"  Response: {text[..Math.Min(100, text.Length)]}...");
}

Remarks

Access stage results via Stages after calling RunWithDiagnosticsAsync. Each stage corresponds to one agent turn in the workflow.

Properties

IAgentStageResult.AgentName Property

Gets the agent's executor ID (agent name, possibly with a MAF-assigned GUID suffix).

string AgentName { get; }

Property Value

System.String

IAgentStageResult.Diagnostics Property

Gets the diagnostics captured during this agent's execution, including per-call token usage, tool call details, and timing. null if diagnostics were not enabled via UsingDiagnostics().

NexusLabs.Needlr.AgentFramework.Diagnostics.IAgentRunDiagnostics? Diagnostics { get; }

Property Value

IAgentRunDiagnostics

IAgentStageResult.FinalResponse Property

Gets the final Microsoft.Extensions.AI.ChatResponse the agent produced during this stage (preserving full message content, role, usage, and metadata), or null if the agent responded only via tool calls with no terminating text response. Call .Text for a flat text view when evaluating.

Microsoft.Extensions.AI.ChatResponse? FinalResponse { get; }

Property Value

Microsoft.Extensions.AI.ChatResponse

IAgentStageResult.Outcome Property

Gets the outcome of this stage's execution. Defaults to Succeeded for backward compatibility with implementations that do not track outcomes.

NexusLabs.Needlr.AgentFramework.Diagnostics.StageOutcome Outcome { get; }

Property Value

StageOutcome

IAgentStageResult.PhaseName Property

Gets the name of the pipeline phase this stage belongs to, or null when running a flat (non-phased) pipeline.

string? PhaseName { get; }

Property Value

System.String

IAgentStageResult.Termination Property

Gets the typed termination cause for this stage. null when the executor or runner did not specify one (legacy implementations / executors with no termination metadata).

NexusLabs.Needlr.AgentFramework.Diagnostics.IStageTermination? Termination { get; }

Property Value

IStageTermination

Remarks

Use pattern matching to inspect specific cases:

if (stage.Termination is StageTermination.MaxToolCallsReached { Limit: var limit })
{
    _logger.LogWarning("Stage {Name} exceeded {Limit} tool calls",
        stage.AgentName, limit);
}

For OpenTelemetry / Prometheus tag values, use ToTagValue() — it returns a stable, low-cardinality string suitable for use as a metric dimension.

Distinct from Outcome: Outcome is the rollup 3-value enum the runner decided about the stage; Termination is the detailed reason. For example, an executor that uses shouldTreatAsSuccess to flip a MaxIterationsReached result to Succeeded still reports MaxIterationsReached here.

Typed as IStageTermination so consumers can supply their own typed extension cases by implementing the interface directly. The framework's closed StageTermination hierarchy (with the Custom escape hatch) covers the canonical cases; see IStageTermination for the contract on extending.