.NET: Python: add ADR for threads by eavanvalkenburg · Pull Request #2420 · microsoft/agent-framework

eavanvalkenburg · 2025-11-24T12:52:05Z

Motivation and Context

ADR proposing changes to the thread setup in Python.

Description

Contribution Checklist

The code builds clean without any errors or warnings
The PR follows the Contribution Guidelines
All unit tests pass, and I have added new tests where possible
Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

Copilot

Pull request overview

This PR introduces an Architecture Decision Record (ADR) proposing changes to the thread management system in the Python agent framework. The ADR addresses confusion around the current AgentThread class, which can exist in multiple states and hold different types of data, making it difficult for users to understand and use correctly.

Key Changes

Proposes two options for restructuring thread management: maintaining the current single-class approach vs. separating into distinct RemoteThread and LocalThread classes
Documents the current implementation's limitations and the decision drivers focused on ease of use and clarity
Presents trade-offs between consistency with .NET implementation and Python-specific design patterns

dmytrostruk · 2025-11-25T01:08:39Z

+- We would then add a flag on ChatClients, to indicate which type of thread they support, and it can be both, so two flags are likely needed, although local thread might always be possible.
+- And finally, all Agents would get two methods, `get_service_thread()`/`get_remote_thread` and `get_local_thread()`, both of which might raise an error if the chat client does not support that type of thread.
+- the `run` methods would take both types of threads, but would raise an error if the thread type is not supported by the chat client. And it would also check with the `store` parameter to make sure it is used correctly, or set it correctly.
+- One open question is how to handle when there is a mismatch between the thread type and the `store` parameter, for example passing a `LocalAgentThread` with `store=True`, or a `ServiceAgentThread` with `store=False`. Options are to either raise an error, or to ignore the `store` parameter and always do the right thing based on the thread type. Or to transform the thread into the right type, but that seems more complex and might not always be possible. Although starting with a local thread (which would be a list of chat messages in a ChatMessageStore) and then setting store=True might make sense, the return would be a service thread then, but that adds complexity, this might be useful for workflows that combine different agent types.


I like the fact that it's explicit, but this also makes it more complicated with store parameter, because at the moment you only need to change this parameter value True/False, while with a separate thread type you would also need to change that thread type, so basically configuring the same logic in two different places.

If we introduce a separate thread type for remote and local messages, maybe we can remove store parameter in this case. Instead of using store parameter, we will just check a thread type, and by default it will be a local one.

good point, we do need to look at both conversation_id and store parameters in this case. I'll add

The only challenge is that chat options work at the chat client level, while this works at the agent level.

added more clarity on this choice, and the option I think makes most sense.

dmytrostruk · 2025-11-25T01:10:39Z

+- Good, because it is clear which chat clients support which type of thread.
+- Good, because we can make all the logic that deals with threads much clearer, as each class has a single responsibility.
+- Good, because it might also enable a abstracted method to get a list of chat messages from a thread through the chat client.
+- Bad, because it would more fundamentally diverge from dotnet.


I think if this API brings more clarity, it can be introduced in .NET as well. Otherwise, I'm not sure if we want to diverge from .NET this much.

When discussing with Weslie we also came to the conclusion that we might invert the order, and do this for python and follow with .net

The main problem in .net is that we don't know what kind of thread is supported by the underlying service until we get the first response from the chat client and changing this will be challenging.

The main problem in .net is that we don't know what kind of thread is supported by the underlying service until we get the first response from the chat client and changing this will be challenging.

@eavanvalkenburg Isn't it the same in Python?

It is, but since currently all the clients are built by us and part of AF, it's a onetime breaking change to add the flag to the protocol and base_client and then we are good to go, and if someone implements their own, it's a simple addition. For dotnet, this is a bit more tricky

moonbox3 · 2025-11-26T04:47:32Z

+- Bad, because it is unclear which chat clients can support which type of thread.
+- Bad, because dotnet also has subclasses for each type of agent, so already somewhat diverging from dotnet.
+
+### 2. Separate classes for `ServiceThread`/`RemoteThread` and `LocalAgentThread`/`LocalThread`, each with their own behaviors and methods.


I like the explicit-ness of the separate classes. I think doing it this way will be better for developers, too, as they'd know which type they're working with and what's available in each object.

dmytrostruk · 2025-12-02T00:05:34Z

+This approach would mean:
+- Creating two subclasses of AgentThread, one for service threads and one for local threads, both with different attributes and methods. Tentatively called `RemoteThread` and `LocalThread`.
+- Removing `ChatMessageStore`, instead a `LocalThread` would have a list of ChatMessages as attribute.
+- Moving `ContextProvider` back into Agent, replacing with a field `context_data`/`context_state` or a dict of `context_provider_name/id: context_data/state` on both thread types, which the agent would then use to get the context from the context providers when running in that thread. This makes the thread itself state-only, and the context provider can be stateless and live in the agent.


I'm not sure if context provider should be part of the thread at all, it feels to me like an optional component that should be part of the Agent.

I agree the provider should not be, but a state of some sort is needed, for instance when you are running with a RemoteThread, it might contain the last few messages in order to accurately be able to search for related content, so the last X number of messages of the thread might be kept. Also something like a user_id or session_id could be stored and should be part of the thread, not the agent or some other thing.

dmytrostruk · 2025-12-02T00:10:18Z

+- Moving `ContextProvider` back into Agent, replacing with a field `context_data`/`context_state` or a dict of `context_provider_name/id: context_data/state` on both thread types, which the agent would then use to get the context from the context providers when running in that thread. This makes the thread itself state-only, and the context provider can be stateless and live in the agent.
+- The protocol/interface for ContextProviders would need a slight update, one to return a initial `context_data/state` object, the logic of which is maintained by the provider (whether it matches a app, user or session and what to record in there), and adding that `context_data/state` to the invoked and invoking methods. The `context_data/state` needs to be (de)serializable in a standard way, to make handling the thread easier.
+- We would need to add a flag on `ChatClients`, to indicate if they support `remote/service` threads, and we assume that we always support `local` threads.
+- All Agents would get two methods, `get_service_thread(thread_id: str | None = None, ...)`/`get_remote_thread(thread_id: str | None = None, ...)` and `get_local_thread(messages: list[ChatMessage] | None = None, ...)`, both of which might raise an error if the chat client does not support that type of thread, after creation the agent then calls the context_provider(s) to get a `context_data/state` assigned as well.


In previous point there is a statement and we assume that we always support local threads, but in this point we say that both remote and local thread get methods might raise an error if the chat client does not support that type of thread. But if we always support local threads (which makes sense to me), then method get_local_thread should never throw.

good one, clarified

dmytrostruk · 2025-12-02T00:15:31Z

+        - `LocalThread`
+        - `ClientSideThread`
+
+    `RemoteThread` and `LocalThread` seem the clearest and most concise options and the most pythonic.


I like RemoteThread and LocalThread, but if we are doing this refactoring, we should also make a decision if thread terminology is the final option, or we want to think about conversation and any other potential alternatives. I remember there was some feedback about thread naming.

Also, one potential alternative to RemoteThread is HostedThread. It's also short and works well with tool types like HostedMCPTool.

Good one, added that. I'll add a note on alternatives to Threads.

Copilot AI review requested due to automatic review settings November 24, 2025 12:52

eavanvalkenburg added the python label Nov 24, 2025

markwallace-microsoft added the documentation Improvements or additions to documentation label Nov 24, 2025

Copilot started reviewing on behalf of eavanvalkenburg November 24, 2025 12:52 View session

Copilot finished reviewing on behalf of eavanvalkenburg November 24, 2025 12:55

Copilot AI reviewed Nov 24, 2025

View reviewed changes

dmytrostruk reviewed Nov 25, 2025

View reviewed changes

eavanvalkenburg force-pushed the python_threads_adr branch from 4510170 to 531d751 Compare November 25, 2025 08:06

moonbox3 reviewed Nov 26, 2025

View reviewed changes

eavanvalkenburg force-pushed the python_threads_adr branch from 4200763 to db563ac Compare November 28, 2025 14:27

eavanvalkenburg changed the title ~~Python: add ADR for threads in python~~ Python: add ADR for threads Dec 1, 2025

eavanvalkenburg added the .NET label Dec 1, 2025

github-actions Bot changed the title ~~Python: add ADR for threads~~ .NET: Python: add ADR for threads Dec 1, 2025

dmytrostruk reviewed Dec 2, 2025

View reviewed changes

dmytrostruk approved these changes Dec 2, 2025

View reviewed changes

eavanvalkenburg added 15 commits January 12, 2026 20:19

add ADR for threads in python

e3e67ec

typo

569256f

updates on store/conversation_id

1057912

update with diagrams

9d0b369

simplified

758c1ca

add additional thoughts on context provider handling and hosted flow

f12ddd8

hosting flow slight update

77320cb

updated about context

0c99f23

current state context provider added

58762f8

clarified issue

603fde8

removed other note

977a641

typo

df27418

language clarification

8ea7135

updated language

cc4e3a6

updated flows

0733e59

eavanvalkenburg added 11 commits January 12, 2026 20:19

udpated create flows

70ee8b4

updated based on comments

c68122f

update with additional issues

ac0a7da

updated

5fab8ce

slight language fix

2b6c974

major updates

4559353

smaller refinements

1a7d6f3

added note on possible divergence between python and dotnet

445a719

fixed note

1650154

fixed language and numbering

d6bc3ec

small language update

752742a

eavanvalkenburg force-pushed the python_threads_adr branch from 34e416b to 752742a Compare January 12, 2026 19:19

eavanvalkenburg closed this Feb 10, 2026

Conversation

eavanvalkenburg commented Nov 24, 2025

Motivation and Context

Description

Contribution Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants