[Marco Minerva (marcominerva)]

Workflows exposed as agents via AsAIAgent always used the internal WorkflowChatHistoryProvider, so callers could not customize how the conversation history is stored or read it back (#6327).

• Add WorkflowAgentOptions (Id, Name, Description, ExecutionEnvironment, IncludeExceptionDetails, IncludeWorkflowOutputsInResponse, ChatHistoryProvider) and an AsAIAgent(Workflow, WorkflowAgentOptions) overload.
• Add an optional chatHistoryProvider parameter to the existing AsAIAgent overload, which now delegates to the options-based one.
• WorkflowHostAgent now takes WorkflowAgentOptions and keeps a copy of it.
• When a custom provider is configured, only the new request messages are sent to the workflow, since the workflow keeps its own state through checkpoints. The provider is notified via InvokedAsync with the request and response messages, or with the exception if the run fails, and can be retrieved via GetService.
• Without a custom provider, the existing bookmark-based behavior is unchanged.
• Update PublicAPI.Unshipped.txt for all target frameworks and the XML doc crefs that pointed to the old AsAIAgent signature.
• Add unit tests covering both overloads, serialization, checkpointing and options isolation.

BREAKING CHANGE:

• Binary break: the signature of WorkflowHostingExtensions.AsAIAgent(Workflow, string?, string?, string?, IWorkflowExecutionEnvironment?, bool, bool) gained a trailing optional ChatHistoryProvider? parameter. Assemblies compiled against the previous version must be recompiled.
• Source break: calls that pass an untyped null as the first argument, such as workflow.AsAIAgent(null), no longer compile (CS0121), because they are now ambiguous between the existing overload and the new AsAIAgent(Workflow, WorkflowAgentOptions) overload.
  Migration: call workflow.AsAIAgent() or name the argument, e.g. workflow.AsAIAgent(id: null). Behavior is unchanged.

Fixes #6327

[Copilot]

Copilot review overview

🟡 Changes recommended

The options overload introduces an undocumented source incompatibility, and the new failure-notification path lacks tests.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Avoid ambiguous null calls from the new reference-type overload · New
• Add failure notification coverage for streaming and non-streaming runs · New

What changed in this PR

Adds configurable chat-history persistence to workflows hosted as agents while preserving legacy behavior when no custom provider is supplied.

Changes:

• Introduces WorkflowAgentOptions and updates AsAIAgent.
• Integrates custom-provider persistence, failure notification, serialization, and checkpointing.
• Updates tests, public API baselines, and XML references.

File	Description
WorkflowHostAgentChatHistoryProviderTests.cs	Tests provider integration and persistence.
WorkflowSession.cs	Accepts explicit invocation messages.
WorkflowHostingExtensions.cs	Adds provider parameter and options overload.
WorkflowHostAgent.cs	Implements custom provider lifecycle.
WorkflowAgentOptions.cs	Defines workflow-agent configuration.
PublicAPI/​netstandard2.0/​PublicAPI.Unshipped.txt	Updates netstandard API baseline.
PublicAPI/​net9.0/​PublicAPI.Unshipped.txt	Updates .NET 9 API baseline.
PublicAPI/​net8.0/​PublicAPI.Unshipped.txt	Updates .NET 8 API baseline.
PublicAPI/​net472/​PublicAPI.Unshipped.txt	Updates .NET Framework API baseline.
PublicAPI/​net10.0/​PublicAPI.Unshipped.txt	Updates .NET 10 API baseline.
Futures.cs	Updates AsAIAgent documentation reference.
DeclarativeWorkflowExecutor.cs	Updates hosting API reference.
DeclarativeWorkflowBuilder.cs	Updates hosting API reference.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.