feat(core): add breaking changes warning and logging utility #45

OhYee · 2026-01-27T07:35:32Z

Adds a warning message that displays when using early versions of the AgentRun Python SDK, informing users about potential breaking changes and recommending dependency pinning. Also imports necessary os and logger utilities for the warning implementation.

The warning includes both English and Chinese messages and can be disabled via DISABLE_BREAKING_CHANGES_WARNING environment variable.

This change enhances user experience by providing clear guidance on version management and helps prevent compatibility issues in production environments.

添加破坏性更改警告和日志工具

添加一个警告消息，在使用 AgentRun Python SDK 的早期版本时显示，
告知用户有关潜在的破坏性更改并推荐依赖版本固定。
同时导入必要的 os 和 logger 工具用于警告实现。

该警告包含英文和中文消息，并可通过 DISABLE_BREAKING_CHANGES_WARNING 环境变量禁用。

此更改通过提供清晰的版本管理指导来增强用户体验，
并帮助防止生产环境中的兼容性问题。

BREAKING CHANGE: adds breaking changes warning that displays on SDK startup

A warning message will now appear when importing the module, which may affect automated systems that expect clean output. Users can disable this warning by setting DISABLE_BREAKING_CHANGES_WARNING=1 environment variable.

破坏性更改：在 SDK 启动时添加破坏性更改警告

现在在导入模块时会出现警告消息，这可能会影响期望干净输出的自动化系统。
用户可以通过设置 DISABLE_BREAKING_CHANGES_WARNING=1 环境变量来禁用此警告。

Change-Id: Ieebfcc0dcf6faaf4aaffd20279f0794053b9cf7d

Thank you for creating a pull request to contribute to Serverless Devs agentrun-sdk-python code! Before you open the request please answer the following questions to help it be more easily integrated. Please check the boxes "[ ]" with "[x]" when done too.
Please select one of the PR types below to complete

Fix bugs

Bug detail

The specific manifestation of the bug or the associated issue.

Pull request tasks

Add test cases for the changes
Passed the CI test

Update docs

Reason for update

Why do you need to update your documentation?

Pull request tasks

Update Chinese documentation
Update English documentation

Add contributor

Contributed content

Code
Document

Content detail

if content_type == 'code' || content_type == 'document':
    please tell us `PR url`，like: https://github.com/Serverless-Devs/agentrun-sdk-python/pull/1
else:
    please describe your contribution in detail

Others

Reason for update

Why do you need to update your documentation?

Adds a warning message that displays when using early versions of the AgentRun Python SDK, informing users about potential breaking changes and recommending dependency pinning. Also imports necessary os and logger utilities for the warning implementation. The warning includes both English and Chinese messages and can be disabled via DISABLE_BREAKING_CHANGES_WARNING environment variable. This change enhances user experience by providing clear guidance on version management and helps prevent compatibility issues in production environments. 添加破坏性更改警告和日志工具添加一个警告消息，在使用 AgentRun Python SDK 的早期版本时显示，告知用户有关潜在的破坏性更改并推荐依赖版本固定。同时导入必要的 os 和 logger 工具用于警告实现。该警告包含英文和中文消息，并可通过 DISABLE_BREAKING_CHANGES_WARNING 环境变量禁用。此更改通过提供清晰的版本管理指导来增强用户体验，并帮助防止生产环境中的兼容性问题。 BREAKING CHANGE: adds breaking changes warning that displays on SDK startup A warning message will now appear when importing the module, which may affect automated systems that expect clean output. Users can disable this warning by setting DISABLE_BREAKING_CHANGES_WARNING=1 environment variable. 破坏性更改：在 SDK 启动时添加破坏性更改警告现在在导入模块时会出现警告消息，这可能会影响期望干净输出的自动化系统。用户可以通过设置 DISABLE_BREAKING_CHANGES_WARNING=1 环境变量来禁用此警告。 Change-Id: Ieebfcc0dcf6faaf4aaffd20279f0794053b9cf7d Signed-off-by: OhYee <oyohyee@oyohyee.com>

Copilot

Pull request overview

Adds an import-time warning for users of early AgentRun SDK versions to highlight potential breaking changes and recommend version pinning, with an environment-variable opt-out.

Changes:

Import os and the SDK logger in agentrun/__init__.py.
Emit a bilingual (Chinese + English) warning at import time unless DISABLE_BREAKING_CHANGES_WARNING is set.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-27T07:39:22Z

agentrun/__init__.py

    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+if not os.getenv("DISABLE_BREAKING_CHANGES_WARNING"):


DISABLE_BREAKING_CHANGES_WARNING is treated as “disabled if the variable exists with any value”. That means values like "0"/"false" will still disable the warning, which is inconsistent with how other env flags are parsed in this repo (e.g., AGENTRUN_SDK_DEBUG in agentrun/utils/log.py). Consider normalizing the value and only disabling when it’s truthy ("1", "true", "yes"), or reusing the same allow/deny list pattern used in log.py.

Suggested change

if not os.getenv("DISABLE_BREAKING_CHANGES_WARNING"):

_disable_warning_val = os.getenv("DISABLE_BREAKING_CHANGES_WARNING")

_disable_warning = (

_disable_warning_val is not None

and _disable_warning_val.strip().lower() in ("1", "true", "yes")

)

if not _disable_warning:

Copilot · 2026-01-27T07:39:22Z

agentrun/__init__.py

    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+if not os.getenv("DISABLE_BREAKING_CHANGES_WARNING"):


The warning currently runs for all versions, but the message/PR description says it should display for “early versions”. To avoid accidentally warning on future stable releases, gate this by version (e.g., only when major version == 0, or when __version__ < 1.0.0), and keep the env var override as an escape hatch.

Suggested change

if not os.getenv("DISABLE_BREAKING_CHANGES_WARNING"):

def _is_early_version(version: str) -> bool:

"""Return True if the given version string represents an early (pre-1.0.0) version."""

parts = version.split(".")

if not parts:

# Conservatively treat unknown/malformed versions as early

return True

try:

major = int(parts[0])

except ValueError:

# Conservatively treat non-numeric major versions as early

return True

return major == 0

if _is_early_version(__version__) and not os.getenv(

"DISABLE_BREAKING_CHANGES_WARNING"

):

Copilot · 2026-01-27T07:39:23Z

agentrun/__init__.py

+        "早期版本通常包含许多新功能，这些功能\033[1;33m 可能引入不兼容的变更"
+        " \033[0m。为避免潜在问题，我们强烈建议\033[1;32m 将依赖锁定为此版本"
+        " \033[0m。\nYou are currently using AgentRun Python SDK version"
+        f" {__version__}. Early versions often include many new features,"
+        " which\033[1;33m may introduce breaking changes\033[0m. To avoid"
+        " potential issues, we strongly recommend \033[1;32mpinning the"
+        " dependency to this version\033[0m.\n\033[2;3m  pip install"


The warning text embeds raw ANSI escape sequences (e.g., \033[...m) inside the log message. If users redirect logs to files/CI systems or replace the SDK’s formatter/handlers, these control codes can end up as unreadable output. Prefer keeping the message plain and letting the logger formatter handle coloring (or only add ANSI codes when output is a TTY).

Several critical fixes were implemented to resolve test failures in CI environments: 1. Updated MockLLMServer to properly use respx_mock fixture instead of global respx, ensuring HTTP mocks work consistently across local and CI environments 2. Modified tool call argument handling to check tc_args is not None rather than truthy 3. Improved scenario matching logic to check all user messages instead of just the last 4. Added proper async handling for Google ADK integration tests 5. Fixed tool call argument formatting to use "{}" instead of empty strings These changes resolve infinite loop issues with Google ADK tests and ensure consistent behavior across different test environments. fix(integration): 修复 CI mock 服务器问题并改进工具调用处理实施了几项关键修复以解决 CI 环境中的测试失败： 1. 更新 MockLLMServer 以正确使用 respx_mock fixture 而不是全局 respx，确保 HTTP mocks 在本地和 CI 环境中一致工作 2. 修改工具调用参数处理以检查 tc_args 不为 None 而不是真值 3. 改进场景匹配逻辑以检查所有用户消息而不是仅最后一条 4. 为 Google ADK 集成测试添加了适当的异步处理 5. 修复工具调用参数格式为使用"{}"而不是空字符串这些更改解决了 Google ADK 测试的无限循环问题并确保跨不同测试环境的一致行为。 Change-Id: I46c8b4faedb357f8a4a2149756f4cab121c2fb8e Signed-off-by: OhYee <oyohyee@oyohyee.com>

OhYee requested a review from Copilot January 27, 2026 07:35

Copilot started reviewing on behalf of OhYee January 27, 2026 07:36 View session

Copilot AI reviewed Jan 27, 2026

View reviewed changes

OhYee force-pushed the add-breaking-changes-warning branch 5 times, most recently from 5fda08c to cd2bc0d Compare January 28, 2026 10:10

OhYee force-pushed the add-breaking-changes-warning branch from 2b7229b to 3f5dcfd Compare January 28, 2026 10:27

OhYee merged commit 5632001 into main Jan 28, 2026
2 checks passed

OhYee deleted the add-breaking-changes-warning branch January 28, 2026 10:33

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(core): add breaking changes warning and logging utility #45

feat(core): add breaking changes warning and logging utility #45

Uh oh!

OhYee commented Jan 27, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 27, 2026

Uh oh!

Copilot AI Jan 27, 2026

Uh oh!

Copilot AI Jan 27, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		raise AttributeError(f"module '{__name__}' has no attribute '{name}'")


		if not os.getenv("DISABLE_BREAKING_CHANGES_WARNING"):

-if not os.getenv("DISABLE_BREAKING_CHANGES_WARNING"):
+_disable_warning_val = os.getenv("DISABLE_BREAKING_CHANGES_WARNING")
+_disable_warning = (
+    _disable_warning_val is not None
+    and _disable_warning_val.strip().lower() in ("1", "true", "yes")
+)
+if not _disable_warning:

-if not os.getenv("DISABLE_BREAKING_CHANGES_WARNING"):
+def _is_early_version(version: str) -> bool:
+    """Return True if the given version string represents an early (pre-1.0.0) version."""
+    parts = version.split(".")
+    if not parts:
+        # Conservatively treat unknown/malformed versions as early
+        return True
+    try:
+        major = int(parts[0])
+    except ValueError:
+        # Conservatively treat non-numeric major versions as early
+        return True
+    return major == 0
+if _is_early_version(__version__) and not os.getenv(
+    "DISABLE_BREAKING_CHANGES_WARNING"
+):

feat(core): add breaking changes warning and logging utility #45

feat(core): add breaking changes warning and logging utility #45

Uh oh!

Conversation

OhYee commented Jan 27, 2026

Fix bugs

Update docs

Add contributor

Others

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants