StageTermination

NexusLabs.Needlr.AgentFramework ¶

NexusLabs.Needlr.AgentFramework.Diagnostics ¶

StageTermination Class¶

Describes why a pipeline stage terminated. Framework cases carry structured metadata (e.g. MaxIterationsReached knows the limit and the iterations used); application narrative goes through Custom.

public abstract record StageTermination : NexusLabs.Needlr.AgentFramework.Diagnostics.IStageTermination, System.IEquatable<NexusLabs.Needlr.AgentFramework.Diagnostics.StageTermination>

Inheritance System.Object 🡒 StageTermination

Derived
↳ BudgetPressure
↳ Cancelled
↳ Completed
↳ CompletedEarlyAfterToolCall
↳ Custom
↳ Failed
↳ MaxIterationsReached
↳ MaxToolCallsReached
↳ NaturalCompletion
↳ Skipped
↳ StallDetected

Implements IStageTermination, System.IEquatable<StageTermination >

Remarks¶

Use pattern matching to inspect the termination at a stage:

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

For OpenTelemetry / Prometheus tag values, use ToTagValue() — it returns a stable, low-cardinality string suitable for use as a metric dimension. Every case — including Custom — returns its case name (e.g. "MaxIterationsReached", "Custom"), so the tag stays bounded by the case enumeration no matter what free-form text a Reason carries. The reason is preserved on the record and in JSON for diagnostics — it is deliberately not used as a metric/span tag.

JSON serialization is supported via System.Text.Json.Serialization.JsonPolymorphicAttribute with the $kind discriminator. Each derived type is registered with its case name (e.g. "MaxIterationsReached") as the discriminator value. Once shipped, the JSON wire format is part of the API surface — renaming or removing a case breaks the wire format.

Adding a new framework case in a future release is a soft break for consumers using exhaustive switch expressions — they will need to add a default arm. Switch statements with no return value continue to work without modification.

Methods¶