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 <[email protected]>

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).

Update condition checks from truthy evaluation to explicit None checks for tc_args parameter to properly handle empty dictionaries and other falsy values. Update test expectations to use "{}" instead of empty strings for consistent representation of empty tool call arguments. This ensures proper handling of edge cases where tool call arguments might be empty dictionaries or other falsy values that should still be processed rather than skipped. 修复 langgraph 中工具调用参数的一致性处理将条件检查从真值评估更新为显式的 None 检查，以正确处理空字典和其他应该被处理而不是跳过的假值。更新测试期望值，使用 "{}" 代替空字符串来一致地表示空工具调用参数。这确保了正确处理工具调用参数可能是应该被处理而不是跳过的空字典或其他假值的边界情况。 Change-Id: Ifc456cb95db48f85567e799312f7b76ec654c21d Signed-off-by: OhYee <[email protected]>

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 from 5adb1c9 to 7013b63 Compare January 27, 2026 10:10

OhYee force-pushed the add-breaking-changes-warning branch from 7013b63 to 91a71bf Compare January 27, 2026 11:07

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

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!

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

Are you sure you want to change the base?

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

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants