AgentFrameworkArgumentExtractor
NexusLabs.Needlr.AgentFramework¶
NexusLabs.Needlr.AgentFramework¶
AgentFrameworkArgumentExtractor Class¶
Kind-tolerant argument extractors for source-generated [AgentFunction] wrappers.
Inheritance System.Object 🡒 AgentFrameworkArgumentExtractor
Remarks¶
Microsoft.Extensions.AI.AIFunctionArguments delivers tool argument values as
object — but the underlying IChatClient determines the
runtime shape:
- GitHub Copilot's IChatClient stringifies values: arrays/objects arrive as
System.Text.Json.JsonElement with System.Text.Json.JsonValueKind.String.
- AzureOpenAIClient.AsIChatClient() (and most others) parse the model's tool-call
JSON literally: arrays arrive as System.Text.Json.JsonValueKind.Array, objects as
System.Text.Json.JsonValueKind.Object, numbers as System.Text.Json.JsonValueKind.Number, etc.
Calling JsonElement.GetString() / GetInt32() / GetBoolean()
directly throws System.InvalidOperationException when System.Text.Json.JsonValueKind
doesn't match. These extractors translate per-kind so the source generator can emit a
single uniform call regardless of the chat client's delivery shape.
Extractors assume the value is present and non-null. Every extractor
throws on null raws, on System.Text.Json.JsonValueKind.Null, and on
System.Text.Json.JsonValueKind.Undefined. The generator is responsible for missing-key /
null / undefined handling — typically by gating each extraction call with
IsArgumentSupplied(object) and short-circuiting to a declared default
value or to null for nullable parameter types. This keeps the
presence/optionality concern at the generator layer where the C# parameter metadata
(HasExplicitDefaultValue, NullableAnnotation) lives, and keeps the
extractors focused on kind-tolerant decoding of present values.
Strict semantics for typed primitives. Booleans receiving numeric kinds
throw rather than coerce 0/1 — the model is violating its own schema; the
helper does not paper over it. Numeric extractors prefer the precision-preserving
TryGet* overload (TryGetDecimal for decimal, TryGetDouble for double)
and fall back to invariant-culture parsing on System.Text.Json.JsonValueKind.String.
Supported parameter types.System.String, System.Boolean, the 8 integer types (System.Byte/System.SByte/System.Int16/System.UInt16/ System.Int32/System.UInt32/System.Int64/System.UInt64), System.Single/System.Double/System.Decimal, System.Guid, System.DateTime, System.DateTimeOffset, and System.TimeSpan. JSON has no native kind for the temporal/GUID types — the model emits a string and the extractor parses it (ISO 8601 for date-time / duration, GUID literal for System.Guid).
Methods¶
AgentFrameworkArgumentExtractor.GetBooleanArgument(object) Method¶
Extracts a System.Boolean argument with strict kind semantics.
Parameters¶
raw System.Object
The raw argument value.
Returns¶
System.Boolean
System.Text.Json.JsonValueKind.True/System.Text.Json.JsonValueKind.False →
System.Text.Json.JsonElement.GetBoolean;
System.Text.Json.JsonValueKind.String → System.Boolean.TryParse(System.String,System.Boolean@);
already-typed System.Boolean → as-is.
Exceptions¶
System.InvalidOperationException
Thrown for System.Text.Json.JsonValueKind.Number, System.Text.Json.JsonValueKind.Array,
System.Text.Json.JsonValueKind.Object, System.Text.Json.JsonValueKind.Null,
System.Text.Json.JsonValueKind.Undefined, or unparseable strings such as "1" or
"yes". This is intentional — silently coercing 0/1 or
"yes"/"no" would mask schema violations from the model.
AgentFrameworkArgumentExtractor.GetByteArgument(object) Method¶
Extracts a System.Byte argument.
Parameters¶
raw System.Object
The raw argument value.
Returns¶
AgentFrameworkArgumentExtractor.GetDateTimeArgument(object) Method¶
Extracts a System.DateTime argument from an ISO 8601 string.
Parameters¶
raw System.Object
The raw argument value.
Returns¶
Remarks¶
JSON has no native date-time kind — the model emits a string. Uses
System.Text.Json.JsonElement.TryGetDateTime(System.DateTime@) which accepts the JSON-Schema-spec
"date-time" format (ISO 8601 with optional offset).
AgentFrameworkArgumentExtractor.GetDateTimeOffsetArgument(object) Method¶
Extracts a System.DateTimeOffset argument from an ISO 8601 string.
Parameters¶
raw System.Object
The raw argument value.
Returns¶
Remarks¶
JSON has no native date-time kind — the model emits a string with optional offset. Uses System.Text.Json.JsonElement.TryGetDateTimeOffset(System.DateTimeOffset@).
AgentFrameworkArgumentExtractor.GetDecimalArgument(object) Method¶
Extracts a System.Decimal argument with precision-preserving decoding.
Parameters¶
raw System.Object
The raw argument value.
Returns¶
Remarks¶
Uses System.Text.Json.JsonElement.TryGetDecimal(System.Decimal@) on System.Text.Json.JsonValueKind.Number first to preserve precision that would be lost via a System.Double round-trip. Falls back to invariant-culture parsing for System.Text.Json.JsonValueKind.String.
AgentFrameworkArgumentExtractor.GetDoubleArgument(object) Method¶
Extracts a System.Double argument with precision-first decoding.
Parameters¶
raw System.Object
The raw argument value.
Returns¶
Remarks¶
Uses System.Text.Json.JsonElement.TryGetDouble(System.Double@) on System.Text.Json.JsonValueKind.Number for IEEE-754 fidelity. Rejects non-finite values per JSON spec.
AgentFrameworkArgumentExtractor.GetGuidArgument(object) Method¶
Extracts a System.Guid argument.
Parameters¶
raw System.Object
The raw argument value.
Returns¶
Remarks¶
JSON has no native GUID kind — the model emits a string. Uses System.Text.Json.JsonElement.TryGetGuid(System.Guid@) on System.Text.Json.JsonValueKind.String; throws on any other kind to surface schema violations rather than silently substituting System.Guid.Empty.
AgentFrameworkArgumentExtractor.GetInt16Argument(object) Method¶
Extracts a System.Int16 argument.
Parameters¶
raw System.Object
The raw argument value.
Returns¶
AgentFrameworkArgumentExtractor.GetInt32Argument(object) Method¶
Extracts an System.Int32 argument.
Parameters¶
raw System.Object
The raw argument value.
Returns¶
AgentFrameworkArgumentExtractor.GetInt64Argument(object) Method¶
Extracts a System.Int64 argument.
Parameters¶
raw System.Object
The raw argument value.
Returns¶
AgentFrameworkArgumentExtractor.GetSByteArgument(object) Method¶
Extracts an System.SByte argument.
Parameters¶
raw System.Object
The raw argument value.
Returns¶
AgentFrameworkArgumentExtractor.GetSingleArgument(object) Method¶
Extracts a System.Single argument.
Parameters¶
raw System.Object
The raw argument value.
Returns¶
Remarks¶
Rejects non-finite values (System.Single.NaN, System.Single.PositiveInfinity, System.Single.NegativeInfinity) — JSON itself does not represent them, so receiving one indicates schema violation.
AgentFrameworkArgumentExtractor.GetStringArgument(object) Method¶
Extracts a System.String argument from a raw System.Object delivered
by AIFunctionArguments.
Parameters¶
raw System.Object
The raw argument value.
Returns¶
System.String
System.Text.Json.JsonElement with System.Text.Json.JsonValueKind.String →
System.Text.Json.JsonElement.GetString (or empty string if the JSON string is null);
System.Text.Json.JsonValueKind.Array, System.Text.Json.JsonValueKind.Object,
System.Text.Json.JsonValueKind.Number, System.Text.Json.JsonValueKind.True,
System.Text.Json.JsonValueKind.False → System.Text.Json.JsonElement.GetRawText;
already-typed System.String → as-is;
any other object → System.Object.ToString (or empty string).
Exceptions¶
System.InvalidOperationException
Thrown when raw is null, System.Text.Json.JsonValueKind.Null,
or System.Text.Json.JsonValueKind.Undefined. Callers must gate with
IsArgumentSupplied(object) first.
AgentFrameworkArgumentExtractor.GetTimeSpanArgument(object) Method¶
Extracts a System.TimeSpan argument from a string.
Parameters¶
raw System.Object
The raw argument value.
Returns¶
Remarks¶
JSON has no native duration kind. This helper accepts both common LLM outputs:
- .NET round-trip format like "01:30:00" or "1.02:03:04" via
System.TimeSpan.TryParse(System.String,System.IFormatProvider,System.TimeSpan@) with invariant culture.
- JSON-Schema-spec ISO 8601 duration like "PT1H30M" via
System.Xml.XmlConvert.ToTimeSpan(System.String).
AgentFrameworkArgumentExtractor.GetUInt16Argument(object) Method¶
Extracts a System.UInt16 argument.
Parameters¶
raw System.Object
The raw argument value.
Returns¶
AgentFrameworkArgumentExtractor.GetUInt32Argument(object) Method¶
Extracts a System.UInt32 argument.
Parameters¶
raw System.Object
The raw argument value.
Returns¶
AgentFrameworkArgumentExtractor.GetUInt64Argument(object) Method¶
Extracts a System.UInt64 argument.
Parameters¶
raw System.Object
The raw argument value.
Returns¶
AgentFrameworkArgumentExtractor.IsArgumentSupplied(object) Method¶
Returns true when raw represents a value the extractor methods are willing to decode. Returns false for null raws, System.Text.Json.JsonValueKind.Null, and System.Text.Json.JsonValueKind.Undefined — these mean the chat client did not supply the argument and the generator-emitted wrapper should fall back to the parameter's declared default value (or null for nullable parameters), or throw System.ArgumentException for required parameters.
Parameters¶
raw System.Object
The raw argument value as delivered by AIFunctionArguments.
Returns¶
System.Boolean
false when the argument is missing/null/undefined; true
otherwise (including for typed values, JSON strings, numbers, booleans, arrays, and objects).
Remarks¶
This is the documented gate for the extractor methods on this class. Source-generated agent-function wrappers call this once per parameter site to decide whether to invoke the kind-tolerant extractor or to short-circuit to a fallback. The check is intentionally inexpensive — a single null check plus, for System.Text.Json.JsonElement, two System.Text.Json.JsonValueKind comparisons.