Python: Document shared chat client concurrency

[Ricky-7-Yan]

Motivation & Context

Long-lived async hosts need to reuse provider clients and their HTTP connection pools without leaking request-scoped Agent or session state. The Python API did not define whether OpenAIChatClient and FoundryChatClient support concurrent reuse, especially when streaming and non-streaming calls overlap.

Description & Review Guide

• What are the major changes? Document the supported same-event-loop concurrency contract for the shared protocol and both concrete clients, and add deterministic transport-backed regression coverage for OpenAI and Foundry across streaming, non-streaming, and mixed calls.
• What is the impact of these changes? Applications can safely share one provider wrapper while keeping each Agent, AgentSession, message set, and options request-scoped. There is no runtime or public API behavior change.
• What do you want reviewers to focus on? The stated contract boundaries and whether the regression test covers the isolation guarantees without extending them to user-supplied mutable extensions or cross-thread/event-loop use.

Related Issue

Fixes #7654

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add [BREAKING] to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR clarifies and validates the concurrency contract for the OpenAI and Foundry chat clients, documenting when a single client instance can be safely reused across concurrent async runs and adding a regression test to ensure concurrent runs remain isolated.

Changes:

• Documented concurrency/reuse guarantees (and non-guarantees) for OpenAIChatClient and FoundryChatClient in docstrings and READMEs.
• Added guidance to the core chat protocol docs that protocol conformance doesn’t imply concurrency safety.
• Added an async concurrency isolation test covering streaming, non-streaming, and mixed scenarios for both providers.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
python/packages/openai/agent_framework_openai/_chat_client.py	Adds explicit concurrency contract to OpenAIChatClient docstring.
python/packages/openai/README.md	Documents concurrent reuse guidance for OpenAI package users.
python/packages/foundry/agent_framework_foundry/_chat_client.py	Adds explicit concurrency contract to FoundryChatClient docstring.
python/packages/foundry/README.md	Documents concurrent reuse guidance for Foundry package users.
python/packages/core/agent_framework/_clients.py	Clarifies that protocol implementation doesn’t guarantee concurrency safety.
python/packages/foundry/tests/foundry/test_chat_client_concurrency.py	Adds regression test ensuring concurrent runs don’t leak state across requests/sessions.

---

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

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_clients.py	143	12	91%	329, 380, 543–546, 996, 998–999, 1001–1003
packages/foundry/agent_framework_foundry
_chat_client.py	253	22	91%	112, 114–116, 120–121, 125, 221, 268, 277, 333, 338, 389, 601, 605, 699, 706–709, 756, 838
packages/openai/agent_framework_openai
_chat_client.py	1389	119	91%	314, 327, 681–687, 696–699, 705–709, 717, 761–766, 770–773, 775–777, 784–786, 789, 846, 854, 877, 1094, 1153, 1155, 1157, 1159, 1225, 1239, 1319, 1329, 1334, 1377, 1489–1490, 1505, 1784, 1891, 1896–1897, 1980, 1990, 2017, 2023, 2033, 2039, 2044, 2050, 2055–2056, 2136, 2180, 2183–2186, 2200, 2210–2211, 2223, 2265, 2330, 2347, 2350, 2377–2379, 2418, 2435, 2438, 2500, 2507, 2544–2545, 2580, 2618–2619, 2637–2638, 2810–2811, 2829, 2915–2923, 3101, 3116, 3205–3207, 3217–3218, 3224, 3239, 3372–3373
TOTAL	46770	4358	90%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9453	36 💤	0 ❌	0 🔥	2m 37s ⏱️

[Ricky-7-Yan]

@microsoft-github-policy-service agree