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