Skip to content

AgentScenarioRunner

NexusLabs.Needlr.AgentFramework.Testing

AgentScenarioRunner Class

Executes IAgentScenario instances with proper workspace isolation, execution context scoping, and diagnostics capture.

public sealed class AgentScenarioRunner

Inheritance System.Object 🡒 AgentScenarioRunner

Remarks

The runner handles the full seed → execute → verify lifecycle: 1. Creates an NexusLabs.Needlr.AgentFramework.Workspace.InMemoryWorkspace and calls SeedWorkspace(IWorkspace). 2. Establishes an NexusLabs.Needlr.AgentFramework.Context.IAgentExecutionContext with user ID and workspace in properties. 3. Opens diagnostics capture. 4. Invokes the agent with the scenario's system and user prompts. 5. Calls Verify(IWorkspace, IAgentRunDiagnostics) with the post-execution workspace and diagnostics.

Deterministic testing (no real LLM): The runner uses the NexusLabs.Needlr.AgentFramework.IAgentFactory from DI, which respects the ChatClientFactory configured on the syringe. To run scenarios without real LLM calls, wire a mock IChatClient via the syringe:

var sp = new Syringe()
    .UsingReflection()
    .UsingAgentFramework(af => af
        .Configure(opts => opts.ChatClientFactory = _ => mockChatClient.Object))
    .BuildServiceProvider(config);

var runner = new AgentScenarioRunner(
    sp.GetRequiredService<IAgentFactory>(),
    sp.GetRequiredService<IAgentExecutionContextAccessor>(),
    sp.GetRequiredService<IAgentDiagnosticsAccessor>());

Constructors

AgentScenarioRunner(IAgentFactory, IAgentExecutionContextAccessor, IAgentDiagnosticsAccessor) Constructor

public AgentScenarioRunner(NexusLabs.Needlr.AgentFramework.IAgentFactory agentFactory, NexusLabs.Needlr.AgentFramework.Context.IAgentExecutionContextAccessor contextAccessor, NexusLabs.Needlr.AgentFramework.Diagnostics.IAgentDiagnosticsAccessor diagnosticsAccessor);

Parameters

agentFactory NexusLabs.Needlr.AgentFramework.IAgentFactory

Factory for creating agents.

contextAccessor NexusLabs.Needlr.AgentFramework.Context.IAgentExecutionContextAccessor

Execution context accessor for scoping.

diagnosticsAccessor NexusLabs.Needlr.AgentFramework.Diagnostics.IAgentDiagnosticsAccessor

Diagnostics accessor for capture.

Methods

AgentScenarioRunner.RunAsync(IAgentScenario, CancellationToken) Method

Runs the scenario with full lifecycle management: seed workspace, establish context, capture diagnostics, execute agent, verify outcomes.

public System.Threading.Tasks.Task<NexusLabs.Needlr.AgentFramework.Testing.ScenarioRunResult> RunAsync(NexusLabs.Needlr.AgentFramework.Testing.IAgentScenario scenario, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));

Parameters

scenario IAgentScenario

The scenario to run.

cancellationToken System.Threading.CancellationToken

Cancellation token.

Returns

System.Threading.Tasks.Task<ScenarioRunResult>
The result of the scenario run, including diagnostics and verification outcome.

Remarks

NexusLabs.Needlr.AgentFramework.Testing.ScenarioRunResult.Diagnostics will be null unless the NexusLabs.Needlr.AgentFramework.IAgentFactory was configured with UsingDiagnostics() on the syringe. Without diagnostics middleware, Verify(IWorkspace, IAgentRunDiagnostics) receives null diagnostics.