Skip to content

ToolInvocationResult

NexusLabs.Needlr.AgentFramework.Testing

ToolInvocationResult Class

Result of a single InvokeAsync<TTool>(string, Action<AIFunctionArguments>, CancellationToken) call.

public sealed record ToolInvocationResult : System.IEquatable<NexusLabs.Needlr.AgentFramework.Testing.ToolInvocationResult>

Inheritance System.Object 🡒 ToolInvocationResult

Implements System.IEquatable<ToolInvocationResult>

Constructors

ToolInvocationResult(object, Exception, ToolFunctionSource, IWorkspace, TimeSpan) Constructor

Result of a single InvokeAsync<TTool>(string, Action<AIFunctionArguments>, CancellationToken) call.

public ToolInvocationResult(object? ReturnValue, System.Exception? Exception, NexusLabs.Needlr.AgentFramework.Testing.ToolFunctionSource FunctionSource, NexusLabs.Needlr.AgentFramework.Workspace.IWorkspace? Workspace, System.TimeSpan Duration);

Parameters

ReturnValue System.Object

The raw return value from the underlying Microsoft.Extensions.AI.AIFunction.InvokeAsync(Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken) call, or null if the invocation threw.

Exception System.Exception

The exception thrown during invocation, or null if the invocation succeeded. Exceptions from argument extraction (the source-generated wrapper) and from the user method itself are not currently distinguished; both surface here.

FunctionSource ToolFunctionSource

Which discovery path produced the Microsoft.Extensions.AI.AIFunction that was invoked. Use this in assertions to confirm the test exercised the source-generated wrapper rather than the reflection fallback.

Workspace NexusLabs.Needlr.AgentFramework.Workspace.IWorkspace

The NexusLabs.Needlr.AgentFramework.Workspace.IWorkspace attached to the execution context for the invocation, or null if no workspace was configured. Useful for post-invocation assertions on files the tool wrote.

Duration System.TimeSpan

Wall-clock duration of the invocation.

Properties

ToolInvocationResult.Duration Property

Wall-clock duration of the invocation.

public System.TimeSpan Duration { get; init; }

Property Value

System.TimeSpan

ToolInvocationResult.Exception Property

The exception thrown during invocation, or null if the invocation succeeded. Exceptions from argument extraction (the source-generated wrapper) and from the user method itself are not currently distinguished; both surface here.

public System.Exception? Exception { get; init; }

Property Value

System.Exception

ToolInvocationResult.FunctionSource Property

Which discovery path produced the Microsoft.Extensions.AI.AIFunction that was invoked. Use this in assertions to confirm the test exercised the source-generated wrapper rather than the reflection fallback.

public NexusLabs.Needlr.AgentFramework.Testing.ToolFunctionSource FunctionSource { get; init; }

Property Value

ToolFunctionSource

ToolInvocationResult.ReturnValue Property

The raw return value from the underlying Microsoft.Extensions.AI.AIFunction.InvokeAsync(Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken) call, or null if the invocation threw.

public object? ReturnValue { get; init; }

Property Value

System.Object

ToolInvocationResult.Succeeded Property

Whether the invocation completed without throwing.

public bool Succeeded { get; }

Property Value

System.Boolean

ToolInvocationResult.Workspace Property

The NexusLabs.Needlr.AgentFramework.Workspace.IWorkspace attached to the execution context for the invocation, or null if no workspace was configured. Useful for post-invocation assertions on files the tool wrote.

public NexusLabs.Needlr.AgentFramework.Workspace.IWorkspace? Workspace { get; init; }

Property Value

NexusLabs.Needlr.AgentFramework.Workspace.IWorkspace

Methods

ToolInvocationResult.AssertResultContains(string) Method

Throws if the string form of ReturnValue does not contain substring.

public void AssertResultContains(string substring);

Parameters

substring System.String

The substring expected to appear in the return value.

Exceptions

System.InvalidOperationException
Thrown when the return value is null or does not contain the substring.

ToolInvocationResult.AssertSuccess() Method

Throws if the invocation failed, surfacing the original exception with context.

public void AssertSuccess();

Exceptions

System.InvalidOperationException
Thrown when Exception is not null, with the original exception attached as the inner exception.

ToolInvocationResult.GetValue<T>() Method

Returns ReturnValue cast to T, or default if the value is null or not assignable to T.

public T? GetValue<T>();

Type parameters

T

Expected return type.

Returns

T