share thread context

[pgrayy]

Description

agent(...) is a sync invocation that internally invokes stream_async. To run stream_async in a sync context, we create a thread so as to isolate the creation of an async event loop. As part of that thread creation, we are not copying contextvars from the main thread. Customers are asking to have this context copied. The thread we create is not meant for context isolation, only async event loop isolation.

Note, I was initially hesitant to make this change because of the following scenario:

• Customer defines a thread local contextvar in their sync tool func that is invoked by the agent, which itself is invoked synchronously.
• Contextvars from the main thread are now copied into that tool func.
• The tool func defines a contextvar with the same name as a contextvar in the main thread.
• The contextvar in the main thread overwrites the contextvar in the tool thread.

I think this is okay though because the use of threads is an internal implementation detail of Strands. Customers are not designing their tools with our use of threads in mind. Additionally, the use of threads here is specifically meant for asyncio event loop isolation, not context isolation. Thus, this is a bug we are fixing here.

Another note, customers may also want to copy context out of the agent threads. However, modifications made to a contextvar in a subthread do not propagate to the parent thread. The context copy only goes one way.

Shout outs

Shout out to @patrickbradshawdallas for proposing this change in #946.

Related Issues

• [BUG] Tools operating in different context and breaking AgentCore 3LO #946
• [BUG] Configurable Threads #769

Documentation PR

Not necessary as this is an implementation detail of Strands.

Type of Change

Bug fix

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare
• I ran hatch test tests_integ/tools/test_thread_context.py: New integ test for thread context sharing.

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!