[Bugfix] UserAgent Refactoring and Remove Duplicate Custom Prefix

[tvaron3]

Description

• When creating final user agent, rely on the base user agent from the UserAgentPolicy instead of the cosmos client.
• Pop the useragents kwargs before performing the database account calls to prevent the useragent from being added twice
• Update samples to use the recommended user_agent_suffix kwargs
• Update tests to be called prefix as user_agent kwarg adds a prefix to the useragent and add a new test for when a feature is enabled like PPCB

All SDK Contribution checklist:

• The pull request does not introduce [breaking changes]
• CHANGELOG is updated for new features, bug fixes or other significant changes.
• I have read the contribution guidelines.

General Guidelines and Best Practices

• Title of the pull request is clear and informative.
• There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

• Pull request includes test coverage for the included changes.

[Copilot]

Pull request overview

This PR refactors user agent handling in the Azure Cosmos DB Python SDK to fix a bug where custom user agents were duplicated in initial metadata requests. The key changes move user agent feature flag logic from the request layer into a custom UserAgentPolicy, and ensure the user_agent kwarg is properly cleaned up after policy instantiation.

Key Changes

• Created CosmosUserAgentPolicy that extends azure-core's UserAgentPolicy to append Cosmos-specific feature flags (circuit breaker, per-partition failover)
• Removed duplicate user agent logic from _synchronized_request.py and _asynchronous_request.py
• Added kwargs.pop("user_agent", None) after policy creation to prevent duplication in database account calls
• Updated samples to use recommended user_agent_suffix parameter instead of user_agent prefix
• Renamed tests from "suffix" to "prefix" to accurately reflect that user_agent parameter acts as a prefix
• Added new test test_user_agent_prefix_with_features to verify feature flags are properly appended

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
azure/cosmos/user_agent_policy.py	New custom policy that handles Cosmos-specific user agent feature flags by extending azure-core UserAgentPolicy
azure/cosmos/_cosmos_client_connection.py	Replaced standard UserAgentPolicy with CosmosUserAgentPolicy and added kwargs cleanup to prevent duplication
azure/cosmos/aio/_cosmos_client_connection_async.py	Same changes as sync version for async client
azure/cosmos/_synchronized_request.py	Removed user agent feature flag logic (moved to policy) and cleaned up imports
azure/cosmos/aio/_asynchronous_request.py	Same changes as sync version for async requests
tests/test_user_agent_prefix.py	New test file replacing suffix tests, validates user_agent acts as prefix with feature flag support
tests/test_user_agent_prefix_async.py	Async version of prefix tests with proper teardown handling
tests/test_user_agent_suffix.py	Removed - tests renamed to prefix to reflect actual behavior
tests/test_user_agent_suffix_async.py	Removed - tests renamed to prefix to reflect actual behavior
samples/user_agent_management.py	Updated to use recommended user_agent_suffix parameter instead of user_agent
samples/user_agent_management_async.py	Same changes as sync sample
CHANGELOG.md	Added entry documenting the bug fix for duplicated custom user_agent in metadata requests

[github-actions]

API Change Check

APIView identified API level changes in this PR and created the following API reviews

azure-cosmos

[xinlian12]

LGTM, thanks

[bambriz]

LGTM!