FoundryHarnessAgentConfiguration

NexusLabs.Foundry.MicrosoftAgentFramework.Harness.Bundle

FoundryHarnessAgentConfiguration Class

Immutable, fully explicit configuration for constructing an official upstream Microsoft.Agents.AI.HarnessAgent complete-bundle pipeline via FoundryHarnessAgentFactory.

public sealed record FoundryHarnessAgentConfiguration : System.IEquatable<NexusLabs.Foundry.MicrosoftAgentFramework.Harness.Bundle.FoundryHarnessAgentConfiguration>

Inheritance System.Object 🡒 FoundryHarnessAgentConfiguration

Implements System.IEquatable<FoundryHarnessAgentConfiguration>

Remarks

Every property is required. There are no hidden defaults: a caller must consciously supply a value (including explicit null for optional-by-design upstream inputs) for every dimension this type exposes. This is a deliberate departure from the upstream Microsoft.Agents.AI.HarnessAgentOptions shape, which allows every property to be left unset and silently defaulted.

This type composes the official upstream bundle (Microsoft.Agents.AI.Harness); it is not part of, and must not be confused with, the selected-provider composition surface in NexusLabs.Foundry.MicrosoftAgentFramework. The two lanes are intentionally separate and are not interchangeable.

Properties

FoundryHarnessAgentConfiguration.AdditionalContextProviders Property

Gets additional Microsoft.Agents.AI.AIContextProvider instances (mapped to HarnessAgentOptions.AIContextProviders) included in the agent pipeline alongside the built-in providers. Supply an empty list for none; this list is never null (unlike the nullable backing-object properties above) because upstream applies no default substitution here; an empty collection and a null collection are equivalent upstream, so this type always uses the non-nullable empty-list spelling.

public System.Collections.Generic.IReadOnlyList<Microsoft.Agents.AI.AIContextProvider> AdditionalContextProviders { get; init; }

Property Value

System.Collections.Generic.IReadOnlyList<Microsoft.Agents.AI.AIContextProvider>

FoundryHarnessAgentConfiguration.AgentModeProviderOptions Property

Gets the AgentModeProviderOptions configuring the plan/execute agent-mode context provider (mapped to HarnessAgentOptions.AgentModeProviderOptions), or null to use the upstream default modes ("plan" and "execute"). Only meaningful when EnableAgentModeProvider is true; the factory fails closed if this is supplied while that feature is disabled.

public Microsoft.Agents.AI.AgentModeProviderOptions? AgentModeProviderOptions { get; init; }

Property Value

Microsoft.Agents.AI.AgentModeProviderOptions

FoundryHarnessAgentConfiguration.AgentSkillsSource Property

Gets the AgentSkillsSource backing the agent skills provider (mapped to HarnessAgentOptions.AgentSkillsSource), or null to use the upstream default: file-based skill discovery rooted at the current working directory. Only meaningful when EnableAgentSkills is true; the factory fails closed if this is supplied while that feature is disabled.

public Microsoft.Agents.AI.AgentSkillsSource? AgentSkillsSource { get; init; }

Property Value

Microsoft.Agents.AI.AgentSkillsSource

FoundryHarnessAgentConfiguration.BackgroundAgents Property

Gets the upstream Microsoft.Agents.AI.AIAgent instances available for background delegation. Supply an empty list when EnableBackgroundAgents is false. At least one uniquely named agent is required when it is true.

public System.Collections.Generic.IReadOnlyList<Microsoft.Agents.AI.AIAgent> BackgroundAgents { get; init; }

Property Value

System.Collections.Generic.IReadOnlyList<Microsoft.Agents.AI.AIAgent>

Remarks

Each task receives its own child session and runs concurrently. Upstream does not propagate the parent run's cancellation token into started child tasks. In-flight task and child-session references are runtime-only; after parent-session serialization and restore, a task that was still running is reported as lost. Callers must bound child work independently and treat returned child text as untrusted input to the parent. The provider stores only AgentResponse.Text; a response containing only approval requests or other non-text content is surfaced as empty text, and child session identifiers are not part of the parent-visible task metadata. The provider has no task-count, concurrency, timeout, retry, or cancellation bound; callers must impose those constraints through their child agents and phase design.

FoundryHarnessAgentConfiguration.BackgroundAgentsProviderOptions Property

Gets optional upstream Microsoft.Agents.AI.BackgroundAgentsProviderOptions controlling the provider instructions and rendered agent list, or null to use upstream defaults. Only meaningful when EnableBackgroundAgents is true. In the MAF 1.17 implementation, a custom instructions value injects the rendered child list only where it contains the {background_agents} placeholder. This source-verified behavior is stricter than the corresponding upstream XML documentation, which says the list is always appended.

public Microsoft.Agents.AI.BackgroundAgentsProviderOptions? BackgroundAgentsProviderOptions { get; init; }

Property Value

Microsoft.Agents.AI.BackgroundAgentsProviderOptions

FoundryHarnessAgentConfiguration.ChatClient Property

Gets the provider Microsoft.Extensions.AI.IChatClient the upstream bundle pipeline wraps.

public Microsoft.Extensions.AI.IChatClient ChatClient { get; init; }

Property Value

Microsoft.Extensions.AI.IChatClient

Remarks

This must be a "raw" selected-provider chat client. FoundryHarnessAgentFactory rejects function-invocation, message-injection, and OpenTelemetry middleware that is discoverable through Microsoft.Extensions.AI.IChatClient.GetService(System.Type,System.Object), following the forwarding convention implemented by DelegatingChatClient. The Microsoft.Extensions.AI.IChatClient contract does not require wrappers to forward service discovery, so opaque wrappers can defeat this check. Callers remain responsible for supplying an undecorated client; this validation catches common accidental double-wrapping and is not a security boundary.

FoundryHarnessAgentConfiguration.ChatHistoryProvider Property

Gets the ChatHistoryProvider backing history persistence (mapped to HarnessAgentOptions.ChatHistoryProvider), or null to use the upstream default: an InMemoryChatHistoryProvider. When compaction is enabled, the default provider uses a compaction-based chat reducer backed by either CompactionStrategy or the strategy constructed from MaxContextWindowTokens and MaxOutputTokens. When compaction is disabled, upstream configures the default provider without chat reduction.

public Microsoft.Agents.AI.ChatHistoryProvider? ChatHistoryProvider { get; init; }

Property Value

Microsoft.Agents.AI.ChatHistoryProvider

FoundryHarnessAgentConfiguration.CompactionStrategy Property

Gets an explicit compaction strategy for upstream's per-turn compaction (mapped to HarnessAgentOptions.CompactionStrategy), or null to let the upstream bundle construct a default ContextWindowCompactionStrategy from MaxContextWindowTokens and MaxOutputTokens. When a strategy is supplied here, MaxContextWindowTokens must be null because upstream ignores it. MaxOutputTokens may still separately apply as the chat options' default output-token cap. Only meaningful when EnableCompaction is true; the factory fails closed if this is supplied while that feature is disabled.

public Microsoft.Agents.AI.Compaction.CompactionStrategy? CompactionStrategy { get; init; }

Property Value

Microsoft.Agents.AI.Compaction.CompactionStrategy

Remarks

This strategy is \<em>not\</em> evaluated inside the tool loop. Upstream runs it once per agent turn, against the persisted history index, so it bounds what the agent remembers between turns rather than what any individual provider request carries. Use HybridCompactionOptions to bound context within a turn; see Compaction for the measured behavior.

FoundryHarnessAgentConfiguration.Description Property

Gets a human-readable description of the agent's purpose, or null for none.

public string? Description { get; init; }

Property Value

System.String

FoundryHarnessAgentConfiguration.Features Property

Gets the explicit choices for every default-on-but-disableable upstream bundle dimension.

public NexusLabs.Foundry.MicrosoftAgentFramework.Harness.Bundle.FoundryHarnessFeatureSelections Features { get; init; }

Property Value

FoundryHarnessFeatureSelections

FoundryHarnessAgentConfiguration.FileAccessProviderOptions Property

Gets the options backing the FileAccessProvider configuration (mapped to HarnessAgentOptions.FileAccessProviderOptions), or null to let the provider use its own default options. Only meaningful when FileAccessStore is non-null; the factory fails closed if this is supplied while FileAccessStore is null.

public Microsoft.Agents.AI.FileAccessProviderOptions? FileAccessProviderOptions { get; init; }

Property Value

Microsoft.Agents.AI.FileAccessProviderOptions

FoundryHarnessAgentConfiguration.FileAccessStore Property

Gets the Microsoft.Agents.AI.AgentFileStore that enables the shared file-access provider, or null to leave file access disabled (the upstream default: this dimension is opt-in, not default-on).

public Microsoft.Agents.AI.AgentFileStore? FileAccessStore { get; init; }

Property Value

Microsoft.Agents.AI.AgentFileStore

FoundryHarnessAgentConfiguration.FileMemoryStore Property

Gets the Microsoft.Agents.AI.AgentFileStore backing the file-based session memory provider (mapped to HarnessAgentOptions.FileMemoryStore), or null to use the upstream default: a FileSystemAgentFileStore rooted at a process-local, timestamp/guid-qualified directory under the current working directory. Only meaningful when EnableFileMemory is true; the factory fails closed if this is supplied while that feature is disabled.

public Microsoft.Agents.AI.AgentFileStore? FileMemoryStore { get; init; }

Property Value

Microsoft.Agents.AI.AgentFileStore

FoundryHarnessAgentConfiguration.HarnessInstructionsOverride Property

Gets an override for the harness-level instructions (mapped to HarnessAgentOptions.HarnessInstructions). Pass null to use the upstream built-in default instructions, or System.String.Empty to omit harness-level instructions entirely.

public string? HarnessInstructionsOverride { get; init; }

Property Value

System.String

FoundryHarnessAgentConfiguration.HybridCompactionOptions Property

Gets the configuration for Foundry's per-provider-call hybrid compaction, or null to leave it disabled.

public NexusLabs.Foundry.MicrosoftAgentFramework.Harness.Bundle.FoundryHarnessHybridCompactionOptions? HybridCompactionOptions { get; init; }

Property Value

FoundryHarnessHybridCompactionOptions

Remarks

This is independent of CompactionStrategy rather than an alternative to it. That property configures upstream's compaction, which runs once per agent turn and reduces the persisted history — it bounds what the agent remembers. This property configures Foundry's compaction, which runs once per provider request and reduces the messages of that one request — it bounds what is sent. Neither suppresses the other and both may be supplied together; see Compaction and HybridCompaction.

Hybrid compaction wraps the supplied ChatClient at the innermost position, so it observes and bounds every provider request the agent makes, including each intermediate tool round. The factory fails closed when this is supplied while EnableHybridCompaction is false, when that feature is enabled without this, and when ChatClient already contains a hybrid compaction component.

FoundryHarnessAgentConfiguration.Id Property

Gets the agent identifier, or null to let the upstream bundle generate one.

public string? Id { get; init; }

Property Value

System.String

FoundryHarnessAgentConfiguration.Instructions Property

Gets agent-specific instructions (mapped to HarnessAgentOptions.ChatOptions.Instructions), or null for none. These are combined with, and follow, HarnessInstructionsOverride (or the upstream default harness instructions when that is null).

public string? Instructions { get; init; }

Property Value

System.String

FoundryHarnessAgentConfiguration.LoopAgentOptions Property

Gets optional upstream Microsoft.Agents.AI.LoopAgentOptions for the outer loop, or null to use upstream defaults. Only meaningful when EnableLoopEvaluation is true.

public Microsoft.Agents.AI.LoopAgentOptions? LoopAgentOptions { get; init; }

Property Value

Microsoft.Agents.AI.LoopAgentOptions

Remarks

Enabling fresh context per iteration requires the wrapped agent session to support serialization when the caller supplies a session, and the serialized form must contain independently cloneable history. A service-managed session that serializes only a remote conversation identifier can restore another reference to the same history rather than a fresh copy. Foundry passes these options through unchanged and does not introduce another loop implementation. Reaching the maximum iteration count returns the latest response without proving that every evaluator accepted it. Non-streaming response usage comes from the final iteration; Foundry progress aggregates model and tool usage across the whole loop.

FoundryHarnessAgentConfiguration.LoopEvaluators Property

Gets the ordered upstream Microsoft.Agents.AI.LoopEvaluator instances that decide whether the complete Harness agent should run again after each iteration. Supply an empty list when EnableLoopEvaluation is false. At least one evaluator is required when it is true.

public System.Collections.Generic.IReadOnlyList<Microsoft.Agents.AI.LoopEvaluator> LoopEvaluators { get; init; }

Property Value

System.Collections.Generic.IReadOnlyList<Microsoft.Agents.AI.LoopEvaluator>

Remarks

Evaluators are applied in order and upstream honors the first evaluator that requests another iteration; an evaluator returning stop does not veto a later evaluator that requests continuation. Each iteration is a complete Harness run, so tools with external side effects must remain idempotent or otherwise deduplicated by the caller.

FoundryHarnessAgentConfiguration.MaxContextWindowTokens Property

Gets the maximum number of tokens the model's context window supports, or null if not applicable.

public System.Nullable<int> MaxContextWindowTokens { get; init; }

Property Value

System.Nullable<System.Int32>

Remarks

Required (together with MaxOutputTokens) when EnableCompaction is true and CompactionStrategy is null. Must be positive when provided.

Must be null when EnableCompaction is false. Upstream ignores this value when HarnessAgentOptions.DisableCompaction is true. Foundry rejects that no-op configuration so an explicitly supplied context-window budget is never silently discarded. Must also be null when CompactionStrategy is supplied because upstream uses that strategy directly and ignores this budget. MaxOutputTokens alone is still permitted as an independent per-response output cap when compaction is disabled; it does not trigger the reducer.

FoundryHarnessAgentConfiguration.MaximumIterationsPerRequest Property

Gets the maximum number of function-invocation loop iterations per request, or null to use the upstream FunctionInvokingChatClient default.

public System.Nullable<int> MaximumIterationsPerRequest { get; init; }

Property Value

System.Nullable<System.Int32>

FoundryHarnessAgentConfiguration.MaxOutputTokens Property

Gets the maximum number of output tokens the model can generate per response, or null if not applicable.

public System.Nullable<int> MaxOutputTokens { get; init; }

Property Value

System.Nullable<System.Int32>

Remarks

Required (together with MaxContextWindowTokens) when EnableCompaction is true and CompactionStrategy is null. Must be non-negative when provided. May also be supplied when compaction is disabled or an explicit strategy is used as a standalone per-response output cap. Upstream propagates this value to ChatOptions.MaxOutputTokens while DisableCompaction prevents chat reduction.

FoundryHarnessAgentConfiguration.Name Property

Gets the agent's name.

public string Name { get; init; }

Property Value

System.String

FoundryHarnessAgentConfiguration.OpenTelemetrySourceName Property

Gets the System.Diagnostics.ActivitySource name used by the OpenTelemetry instrumentation wrapper (mapped to HarnessAgentOptions.OpenTelemetrySourceName), or null to use the upstream default source name ("Experimental.Microsoft.Agents.AI"). Only meaningful when EnableOpenTelemetry is true; the factory fails closed if this is supplied while that feature is disabled, or if it is a whitespace-only string.

public string? OpenTelemetrySourceName { get; init; }

Property Value

System.String

FoundryHarnessAgentConfiguration.ProgressAccessor Property

Gets the Foundry progress accessor used to emit ordered agent, model-call, and tool-call events around the upstream bundle pipeline, or null to disable Foundry progress.

public NexusLabs.Foundry.MicrosoftAgentFramework.Progress.IProgressReporterAccessor? ProgressAccessor { get; init; }

Property Value

NexusLabs.Foundry.MicrosoftAgentFramework.Progress.IProgressReporterAccessor

Remarks

The caller must establish an active reporter scope before running the agent; without one, reporting is a no-op. The accessor is supplied explicitly rather than resolved from the factory's service provider so progress composition has one inspectable source of truth.

This option does not add OpenTelemetry instrumentation or another function-invocation loop. The upstream Harness bundle remains the sole owner of both.

Foundry observes tool execution by chaining the constructed bundle's FunctionInvokingChatClient.FunctionInvoker. Replacing that delegate after construction also replaces Foundry's tool-progress hook.

FoundryHarnessAgentConfiguration.ToolApprovalAgentOptions Property

Gets the ToolApprovalAgentOptions configuring the "don't ask again" tool auto-approval middleware (mapped to HarnessAgentOptions.ToolApprovalAgentOptions), or null to use the middleware's own default options. Only meaningful when EnableToolAutoApproval is true; the factory fails closed if this is supplied while that feature is disabled.

public Microsoft.Agents.AI.ToolApprovalAgentOptions? ToolApprovalAgentOptions { get; init; }

Property Value

Microsoft.Agents.AI.ToolApprovalAgentOptions

FoundryHarnessAgentConfiguration.Tools Property

Gets the complete set of tools available to the agent (mapped to HarnessAgentOptions.ChatOptions.Tools).

public System.Collections.Generic.IReadOnlyList<Microsoft.Extensions.AI.AITool> Tools { get; init; }

Property Value

System.Collections.Generic.IReadOnlyList<Microsoft.Extensions.AI.AITool>

Remarks

Supply an empty list for no additional tools. Source-generator callers (for example, [AgentFunctionGroup]-declared functions resolved via NexusLabs.Foundry.MicrosoftAgentFramework) must resolve their generated Microsoft.Extensions.AI.AIFunction instances explicitly and include them in this list; this configuration type intentionally performs no reflection-based or generated-tool discovery of its own. Duplicate caller tool names and collisions with enabled, known upstream built-in provider tools cause FoundryHarnessAgentFactory to fail closed. Additional caller-supplied Microsoft.Agents.AI.AIContextProvider instances can inject tools dynamically; their names are outside the factory's control and must not collide with this list or each other.