AG UI fronted agent with conversation history provider vs AG UI requiring pure Conversation ID

[VaclavK]

We were looking into Cosmos history provider and decorated it for our agents. However one of them is fronted via AG UI protocol and ultimately we saw the flow breaking up. After investigated we uncovered the internal error of

Only ConversationId or ChatHistoryProvider may be used, but not both. The service returned a conversation id indicating server-side chat history management, but the agent has a ChatHistoryProvider configured.

which after a lot of documentation traversal led us to https://learn.microsoft.com/en-us/agent-framework/integrations/ag-ui/?pivots=programming-language-csharp#how-agent-framework-translates-to-ag-ui

and pointer to conversation id..

The cosmos MAF package does not expose session store but only history provider. I suppose session store would work here.

As a side node, I find most modern era doco to be lacking. Unfortunately, that applies to MAF doco as well. I understand MAF is still in early stage and lot of movement but ultimately unless you are a maintainer, deep cohesive doco is what you need especially when you move away from hello world samples. To this day, the exact handling between sessions store and history provider is not something that sits well in my head w/o questions marks. Doco certainly did not help.

I am no AG UI expert so mainly wanted to confirm this is indeed expected .

[moonbox3]

Hi @VaclavK, confirming this is expected, not a bug, and there's a knob you can flip today.

AG-UI's protocol delegates history to the server: every response carries a ConversationId (pulled from agui_thread_id) and full history is replayed each turn. A client-side ChatHistoryProvider on the same agent would race that and double-store, so ChatClientAgent guards against it. The invariant itself is right.

The escape hatch is on ChatClientAgentOptions. There are three booleans: ThrowOnChatHistoryProviderConflict (defaults to true, that's what you hit), WarnOnChatHistoryProviderConflict, and ClearOnChatHistoryProviderConflict. Set ThrowOnChatHistoryProviderConflict to false and the conflict resolves silently: the provider is cleared for that invocation, a warning is logged, and AG UI's server-side history takes over. That lets you keep one Cosmos-decorated agent definition and front it with either AG UI or a raw chat client without branching construction code.

On the session store question: Cosmos only ships ChatHistoryProvider today, and for the AG-UI path you don't actually need a session-store primitive because the AG-UI server owns the session. ChatHistoryProvider is the right tool for the non-AG-UI paths.

Your docs feedback is fair. The relationship between ConversationId, ChatHistoryProvider, and AG-UI's role isn't written down cohesively anywhere. I'll file a docs issue covering the exclusivity invariant, the three conflict-handling options, and the conceptual model for server-managed vs client-managed history with an AG-UI-plus-Cosmos example.