尧图网页设计 
ADK Feature Flags 机制全解析用ADK_ENABLE_*/ADK_DISABLE_*掌控 adk-python 的实验性功能【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-pythonADKAgent Development Kit即本仓库 adk-python将尚未稳定、API 可能变化的特性统一收口在特性注册表Feature Registry中通过ADK_ENABLE_NAME/ADK_DISABLE_NAME环境变量或 Python API 按需开关。本文以官方指南 docs/guides/features/feature_registry/index.md 为主线结合 src/google/adk/features 源码与 tests/unittests/features 测试完整讲解特性开关的三级解析顺序、三种生命周期阶段、UserWarning与RuntimeError的触发原理并给出测试隔离与部署可复现的实战方案。为什么需要特性注册表一次警告与一次报错先看两个最典型的“遇见”场景。当你构造某个尚不稳定的对象比如GCSToolset时可能会收到一条UserWarning[EXPERIMENTAL] feature GCS_TOOLSET is enabled.当你主动关闭了某个特性、又去构造对应的类时则会抛出RuntimeErrorRuntimeError: Feature GCS_TOOLSET is not enabled.两者都来自特性注册表但含义完全不同UserWarning只是提示你正在使用一个可用但 API 可能变化的特性一切正常没有任何东西出错RuntimeError表示守卫该类别的开关是关的类拒绝被构造失败是立即且彻底的不会留下半成品对象。注册表存在的根本目的是让 ADK 能把新特性交付给想要它的用户同时不改变其他人的默认行为。每个 flag 都携带一个默认值和一个生命周期阶段见下文。三种生命周期阶段FeatureStage源码 src/google/adk/features/_feature_registry.py 中用FeatureStage枚举定义了三个阶段与官方文档的划分一致阶段枚举值行为Stable稳定FeatureStage.STABLE默认开启、静默运行无任何警告Experimental实验性FeatureStage.EXPERIMENTAL按成熟度默认开或关运行时每个进程警告一次Work in progress开发中FeatureStage.WIP默认关闭仅供 ADK 内部开发使用每个 flag 在注册表中对应一个FeatureConfig见 _feature_registry.py由stage和default_on两个字段组成。中央注册表_FEATURE_REGISTRY_feature_registry.py集中定义了当前版本全部 flag 的阶段与默认值。以本仓库当前版本为例Stable 且默认开BIG_QUERY_TOOLSET、BIG_QUERY_TOOL_CONFIG、DATA_AGENT_TOOLSET、DATA_AGENT_TOOL_CONFIG、SKILL_TOOLSETExperimental 且默认开占大多数GCS_TOOLSET、SPANNER_TOOLSET、COMPUTER_USE、JSON_SCHEMA_FOR_FUNC_DECL、FALLBACK_MODEL、MCP_AGENT_SERVER、PLUGGABLE_AUTH等Experimental 且默认关DYNAMIC_INSTRUCTION_ROUTING、SNAKE_CASE_SKILL_NAMEWIP 且默认关IN_MEMORY_SESSION_SERVICE_LIGHT_COPY。此外还有一个带下划线前缀的私有成员_MCP_GRACEFUL_ERROR_HANDLING_feature_registry.py源码注释明确说明它不属于公共 API 表面只是一个临时的内部 kill-switch通过ADK_ENABLE_MCP_GRACEFUL_ERROR_HANDLING1由内部开启不应对其产生向后兼容义务。注意flag 集合会随版本变化——特性毕业转 Stable时会被移除新特性会加入。务必以你实际安装版本中list(FeatureName)的输出为准下文会展开。快速上手环境变量与 Python API 两种开关方式方式一环境变量作用于整个进程在启动进程之前设置环境变量即可。开启一个特性export ADK_ENABLE_SNAKE_CASE_SKILL_NAME1关闭一个特性export ADK_DISABLE_JSON_SCHEMA_FOR_FUNC_DECL1变量名的规则是ADK_ENABLE_或ADK_DISABLE_前缀加上 flag 的名字而 flag 名字就是FeatureName成员本身拼写的原样如SNAKE_CASE_SKILL_NAME、JSON_SCHEMA_FOR_FUNC_DECL。取值判定是个易错点只有1和true大小写不敏感算“被设置”其余任何值——包括yes、on、0——都视为未设置。这一点由底层工具函数 is_env_enabled 保证其实现为os.environ.get(env_var_name, default).lower() in [true, 1]。也就是说ADK_ENABLE_X0并不会关闭 X而是让解析逻辑“穿透”到下一级规则即注册表默认值要真正关闭一个默认开启的特性必须用ADK_DISABLE_X1。方式二Python API适用于 Notebook、测试等场景在环境变量不方便的地方如 Jupyter Notebook 或单元测试中可以在构造任何读取该 flag 的对象之前用 Python 代码设置from google.adk.features import FeatureName from google.adk.features import is_feature_enabled from google.adk.features import override_feature_enabled override_feature_enabled(FeatureName.SNAKE_CASE_SKILL_NAME, True) assert is_feature_enabled(FeatureName.SNAKE_CASE_SKILL_NAME)FeatureName是一个str枚举class FeatureName(str, Enum)见 _feature_registry.py因此可以直接枚举当前版本的全部 flagfrom google.adk.features import FeatureName print(list(FeatureName))注意FeatureName的成员集合在不同版本间会增删请以你安装的版本为准。工作原理is_feature_enabled的三级解析顺序is_feature_enabled_feature_registry.py按以下优先级解析一个 flag命中即返回程序化覆盖最高优先级如果对该 flag 调用过override_feature_enabled其值直接胜出环境变量先查ADK_ENABLE_NAME值为1或true时返回True再查ADK_DISABLE_NAME同值返回False。两者同时设置时Enable 胜出注册表默认值每个 flag 的FeatureConfig中记录的阶段与默认值即为最终答案。这一顺序带来两个重要推论官方文档与源码实现_feature_registry.py一致ADK_DISABLE_X1无法关掉已被程序化覆盖打开的 flag。因此一个库如果调用了override_feature_enabled就等于把决策权从部署者手中拿走覆盖一旦设置就无法通过公共 API 撤销只能翻转为另一值。所以在测试里调用override_feature_enabled会“泄漏”到同进程中后续的所有测试——这是下文“把 flag 限定在单个测试内”一节的动机。警告只会发一次当某个非 Stable 阶段的 flag 解析结果为“启用”时is_feature_enabled内部会调用_emit_non_stable_warning_once_feature_registry.py发出UserWarning文本以[EXPERIMENTAL] feature或[WIP] feature开头并点名该 flag。实现上用_WARNED_FEATURES集合记录已警告过的 flag_feature_registry.py保证每个 flag 每进程只警告一次——即使它被反复读取。警告纯粹是信息性的看到它不代表任何失败如果觉得它是日志噪音可用标准的warnings过滤器屏蔽例如import warnings warnings.filterwarnings(ignore, messager\[EXPERIMENTAL\] feature .* is enabled.)无缓存每次都实时读取解析过程没有任何缓存每次调用都会重新读取覆盖字典和os.environ源码中直接查询_FEATURE_OVERRIDES与is_env_enabled(enable_var)。因此进程中途修改环境变量是立即生效的。但“生效与否”取决于该 flag 何时被读取——不同特性读取时机不同有的在每次调用时读取有的只在对象构造时读取一次详见下文“一个 flag 到底管住什么”。一个 flag 到底管住什么两种执行风格源码中 flag 的落地有两种风格症状完全不同。风格一受守护的单元gated unit。一些类和函数带有experimental、working_in_progress或stable装饰器定义见 src/google/adk/features/_feature_decorator.py。这些装饰器由_make_feature_decorator统一生成装饰类时包装__init__装饰函数时包装调用本身在真正执行前调用is_feature_enabled若 flag 关闭则抛出RuntimeError: Feature name is not enabled._feature_decorator.py。官方文档点名的GCSToolset、SpannerToolset、ComputerUseTool以及 agent-config 加载器都属于这一类。在仓库中可以看到大量实际用例例如experimental(FeatureName.AGENT_CONFIG)用于 src/google/adk/agents/agent_config.py、src/google/adk/agents/base_agent_config.py 等 agent 配置类experimental(FeatureName.AGENT_STATE)用于 src/google/adk/agents/base_agent.py、src/google/adk/agents/loop_agent.pyexperimental(FeatureName.PLUGGABLE_AUTH)用于 src/google/adk/auth/auth_provider_registry.py 与 src/google/adk/auth/base_auth_provider.pyexperimental(FeatureName.GCS_ADMIN_TOOLSET)用于 src/google/adk/integrations/gcs/admin_toolset.pyexperimental(FeatureName.DAYTONA_ENVIRONMENT)/experimental(FeatureName.E2B_ENVIRONMENT)分别用于 src/google/adk/integrations/daytona/_daytona_environment.py 与 src/google/adk/integrations/e2b/_e2b_environment.py。对象不是“半构建”的——失败是立即且彻底的。就目前发布的版本而言这类被装饰器守护的 flag 默认都是开启的所以只有在你主动禁用某个 flag 之后才会碰到这个RuntimeError。风格二受守护的代码路径gated code path。另一种情况下is_feature_enabled的检查位于一个已经可用的功能内部用于在旧行为与新行为之间做选择。这种风格不会抛异常flag 只是改变行为走向唯一获知方式就是发布说明或源码。仓库中一个现成的例子是SNAKE_CASE_SKILL_NAME在 src/google/adk/skills/models.py 的 skill 名称校验器中flag 开启时允许snake_case与kebab-case两种命名并拒绝混用关闭时则只允许kebab-case——对应技能指南中的说明见 docs/guides/skills/skill/index.md“Skill names are kebab-case by default. Snake_case requires enabling theSNAKE_CASE_SKILL_NAMEfeature”。JSON_SCHEMA_FOR_FUNC_DECL也属于此类源码注释_feature_registry.py展示了它如何在“用 JSON Schema 描述参数”的新行为与“用 Schema 对象描述”的旧行为之间切换。函数与类型速查整个系统只需记住三个名字一个命名 flag、一个读取 flag、一个设置 flag。三者均由 src/google/adk/features/init.py 从google.adk.features导出。符号签名说明FeatureNamestr枚举全部 flag 的集合。成员随版本增删。is_feature_enabled(feature_name: FeatureName) - bool按上述优先级立即解析一个 flag。override_feature_enabled(feature_name: FeatureName, enabled: bool) - None设置进程级最高优先级的覆盖。is_feature_enabled的边界行为对不在注册表中的名字抛出ValueErrorFeature name is not registered.。由于FeatureName成员总是已注册的这只会发生在你传入裸字符串时。对应测试见 tests/unittests/features/test_feature_registry.py。override_feature_enabled的边界行为对未注册的名字抛出同样的ValueError设置后对整个进程的剩余生命周期生效且无法通过公共 API 撤销_feature_registry.py。顺带一提源码内部还提供了一个上下文管理器temporary_feature_override_feature_registry.py进入上下文时临时覆盖 flag、退出时恢复原状但它并未从google.adk.features的__all__中导出见init.py属于内部实现细节公共 API 只承诺上文三个符号使用内部符号需自行承担兼容性风险。高级应用两种需要多想一步的场景场景一把 flag 限定在单个测试内由于override_feature_enabled无法撤销测试里翻转 flag 会污染同进程内后续所有测试。官方推荐的正确做法是改用 pytest 的monkeypatch设置环境变量——monkeypatch会在 teardown 时自动恢复原值def test_snake_case_skill_name(monkeypatch): monkeypatch.setenv(ADK_ENABLE_SNAKE_CASE_SKILL_NAME, 1) # 被测代码通过 is_feature_enabled 读取该 flag。这套做法成立的前提有二一是环境变量每次调用都实时读取、从不缓存二是该测试没有设置过程序化覆盖那会压过环境变量。tests/unittests/features/test_feature_registry.py中大量使用monkeypatch.setenv验证环境变量优先级、警告只发一次等行为例如 test_feature_registry.py可作为参照。场景二让部署结果可复现风险在于后续 ADK 版本可能翻转某个 flag 的默认值导致你下次部署时 agent 行为悄然改变而自己的代码一行未动。解决方案是在部署环境中显式钉住pin你依赖的 flag而不是依赖注册表默认值。两个方向都值得钉ADK_ENABLE_NAME1钉住你依赖的、默认关闭或未来可能变化的特性ADK_DISABLE_NAME1钉住你暂时不想接受的、默认开启的实验特性。配合 CI/CD 的同一份环境配置即可保证升级前后行为一致。已知限制Limitations以下限制与官方文档一致均可在源码中找到对应实现依据覆盖无法清除公共 API 只能把覆盖设为True或False无法移除因此一旦覆盖过某个 flag进程就无法回到“环境变量/默认值”解析模式ADK_ENABLE_X0不会禁用只有1和true视为已设置0等价于“未设置”解析会穿透到注册表默认值真正关闭要用ADK_DISABLE_X1实现见 env_utils.pyflag 集合跨版本不稳定成员随特性毕业而增删指向已不存在 flag 的环境变量会被静默忽略无警告、无报错因为is_feature_enabled只在被实际调用时才对未注册名抛ValueError而环境变量本身不触发调用flag 读取时机因特性而异有的单元在构造时读取有的在每次调用时读取在相关对象已存在之后再设环境变量可能不生效警告没有 per-flag 开关屏蔽实验性警告需要warnings过滤器若不按消息文本精确匹配也会一并屏蔽其他UserWarning。关联指南Skill 指南docs/guides/skills/skill/index.md讲解了一个具体 flag——SNAKE_CASE_SKILL_NAME——及其改变的 skill 命名行为默认kebab-case开启后允许snake_case想从源码层面继续深挖可阅读 src/google/adk/features/_feature_registry.py注册表与解析逻辑、src/google/adk/features/_feature_decorator.py三类装饰器以及 tests/unittests/features/test_feature_registry.py优先级、警告、覆盖行为的完整测试矩阵。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ADK Feature Flags 机制全解析：用 `ADK_ENABLE_*` / `ADK_DISABLE_*` 掌控 adk-python 的实验性功能
ADK Feature Flags 机制全解析用ADK_ENABLE_*/ADK_DISABLE_*掌控 adk-python 的实验性功能【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-pythonADKAgent Development Kit即本仓库 adk-python将尚未稳定、API 可能变化的特性统一收口在特性注册表Feature Registry中通过ADK_ENABLE_NAME/ADK_DISABLE_NAME环境变量或 Python API 按需开关。本文以官方指南 docs/guides/features/feature_registry/index.md 为主线结合 src/google/adk/features 源码与 tests/unittests/features 测试完整讲解特性开关的三级解析顺序、三种生命周期阶段、UserWarning与RuntimeError的触发原理并给出测试隔离与部署可复现的实战方案。为什么需要特性注册表一次警告与一次报错先看两个最典型的“遇见”场景。当你构造某个尚不稳定的对象比如GCSToolset时可能会收到一条UserWarning[EXPERIMENTAL] feature GCS_TOOLSET is enabled.当你主动关闭了某个特性、又去构造对应的类时则会抛出RuntimeErrorRuntimeError: Feature GCS_TOOLSET is not enabled.两者都来自特性注册表但含义完全不同UserWarning只是提示你正在使用一个可用但 API 可能变化的特性一切正常没有任何东西出错RuntimeError表示守卫该类别的开关是关的类拒绝被构造失败是立即且彻底的不会留下半成品对象。注册表存在的根本目的是让 ADK 能把新特性交付给想要它的用户同时不改变其他人的默认行为。每个 flag 都携带一个默认值和一个生命周期阶段见下文。三种生命周期阶段FeatureStage源码 src/google/adk/features/_feature_registry.py 中用FeatureStage枚举定义了三个阶段与官方文档的划分一致阶段枚举值行为Stable稳定FeatureStage.STABLE默认开启、静默运行无任何警告Experimental实验性FeatureStage.EXPERIMENTAL按成熟度默认开或关运行时每个进程警告一次Work in progress开发中FeatureStage.WIP默认关闭仅供 ADK 内部开发使用每个 flag 在注册表中对应一个FeatureConfig见 _feature_registry.py由stage和default_on两个字段组成。中央注册表_FEATURE_REGISTRY_feature_registry.py集中定义了当前版本全部 flag 的阶段与默认值。以本仓库当前版本为例Stable 且默认开BIG_QUERY_TOOLSET、BIG_QUERY_TOOL_CONFIG、DATA_AGENT_TOOLSET、DATA_AGENT_TOOL_CONFIG、SKILL_TOOLSETExperimental 且默认开占大多数GCS_TOOLSET、SPANNER_TOOLSET、COMPUTER_USE、JSON_SCHEMA_FOR_FUNC_DECL、FALLBACK_MODEL、MCP_AGENT_SERVER、PLUGGABLE_AUTH等Experimental 且默认关DYNAMIC_INSTRUCTION_ROUTING、SNAKE_CASE_SKILL_NAMEWIP 且默认关IN_MEMORY_SESSION_SERVICE_LIGHT_COPY。此外还有一个带下划线前缀的私有成员_MCP_GRACEFUL_ERROR_HANDLING_feature_registry.py源码注释明确说明它不属于公共 API 表面只是一个临时的内部 kill-switch通过ADK_ENABLE_MCP_GRACEFUL_ERROR_HANDLING1由内部开启不应对其产生向后兼容义务。注意flag 集合会随版本变化——特性毕业转 Stable时会被移除新特性会加入。务必以你实际安装版本中list(FeatureName)的输出为准下文会展开。快速上手环境变量与 Python API 两种开关方式方式一环境变量作用于整个进程在启动进程之前设置环境变量即可。开启一个特性export ADK_ENABLE_SNAKE_CASE_SKILL_NAME1关闭一个特性export ADK_DISABLE_JSON_SCHEMA_FOR_FUNC_DECL1变量名的规则是ADK_ENABLE_或ADK_DISABLE_前缀加上 flag 的名字而 flag 名字就是FeatureName成员本身拼写的原样如SNAKE_CASE_SKILL_NAME、JSON_SCHEMA_FOR_FUNC_DECL。取值判定是个易错点只有1和true大小写不敏感算“被设置”其余任何值——包括yes、on、0——都视为未设置。这一点由底层工具函数 is_env_enabled 保证其实现为os.environ.get(env_var_name, default).lower() in [true, 1]。也就是说ADK_ENABLE_X0并不会关闭 X而是让解析逻辑“穿透”到下一级规则即注册表默认值要真正关闭一个默认开启的特性必须用ADK_DISABLE_X1。方式二Python API适用于 Notebook、测试等场景在环境变量不方便的地方如 Jupyter Notebook 或单元测试中可以在构造任何读取该 flag 的对象之前用 Python 代码设置from google.adk.features import FeatureName from google.adk.features import is_feature_enabled from google.adk.features import override_feature_enabled override_feature_enabled(FeatureName.SNAKE_CASE_SKILL_NAME, True) assert is_feature_enabled(FeatureName.SNAKE_CASE_SKILL_NAME)FeatureName是一个str枚举class FeatureName(str, Enum)见 _feature_registry.py因此可以直接枚举当前版本的全部 flagfrom google.adk.features import FeatureName print(list(FeatureName))注意FeatureName的成员集合在不同版本间会增删请以你安装的版本为准。工作原理is_feature_enabled的三级解析顺序is_feature_enabled_feature_registry.py按以下优先级解析一个 flag命中即返回程序化覆盖最高优先级如果对该 flag 调用过override_feature_enabled其值直接胜出环境变量先查ADK_ENABLE_NAME值为1或true时返回True再查ADK_DISABLE_NAME同值返回False。两者同时设置时Enable 胜出注册表默认值每个 flag 的FeatureConfig中记录的阶段与默认值即为最终答案。这一顺序带来两个重要推论官方文档与源码实现_feature_registry.py一致ADK_DISABLE_X1无法关掉已被程序化覆盖打开的 flag。因此一个库如果调用了override_feature_enabled就等于把决策权从部署者手中拿走覆盖一旦设置就无法通过公共 API 撤销只能翻转为另一值。所以在测试里调用override_feature_enabled会“泄漏”到同进程中后续的所有测试——这是下文“把 flag 限定在单个测试内”一节的动机。警告只会发一次当某个非 Stable 阶段的 flag 解析结果为“启用”时is_feature_enabled内部会调用_emit_non_stable_warning_once_feature_registry.py发出UserWarning文本以[EXPERIMENTAL] feature或[WIP] feature开头并点名该 flag。实现上用_WARNED_FEATURES集合记录已警告过的 flag_feature_registry.py保证每个 flag 每进程只警告一次——即使它被反复读取。警告纯粹是信息性的看到它不代表任何失败如果觉得它是日志噪音可用标准的warnings过滤器屏蔽例如import warnings warnings.filterwarnings(ignore, messager\[EXPERIMENTAL\] feature .* is enabled.)无缓存每次都实时读取解析过程没有任何缓存每次调用都会重新读取覆盖字典和os.environ源码中直接查询_FEATURE_OVERRIDES与is_env_enabled(enable_var)。因此进程中途修改环境变量是立即生效的。但“生效与否”取决于该 flag 何时被读取——不同特性读取时机不同有的在每次调用时读取有的只在对象构造时读取一次详见下文“一个 flag 到底管住什么”。一个 flag 到底管住什么两种执行风格源码中 flag 的落地有两种风格症状完全不同。风格一受守护的单元gated unit。一些类和函数带有experimental、working_in_progress或stable装饰器定义见 src/google/adk/features/_feature_decorator.py。这些装饰器由_make_feature_decorator统一生成装饰类时包装__init__装饰函数时包装调用本身在真正执行前调用is_feature_enabled若 flag 关闭则抛出RuntimeError: Feature name is not enabled._feature_decorator.py。官方文档点名的GCSToolset、SpannerToolset、ComputerUseTool以及 agent-config 加载器都属于这一类。在仓库中可以看到大量实际用例例如experimental(FeatureName.AGENT_CONFIG)用于 src/google/adk/agents/agent_config.py、src/google/adk/agents/base_agent_config.py 等 agent 配置类experimental(FeatureName.AGENT_STATE)用于 src/google/adk/agents/base_agent.py、src/google/adk/agents/loop_agent.pyexperimental(FeatureName.PLUGGABLE_AUTH)用于 src/google/adk/auth/auth_provider_registry.py 与 src/google/adk/auth/base_auth_provider.pyexperimental(FeatureName.GCS_ADMIN_TOOLSET)用于 src/google/adk/integrations/gcs/admin_toolset.pyexperimental(FeatureName.DAYTONA_ENVIRONMENT)/experimental(FeatureName.E2B_ENVIRONMENT)分别用于 src/google/adk/integrations/daytona/_daytona_environment.py 与 src/google/adk/integrations/e2b/_e2b_environment.py。对象不是“半构建”的——失败是立即且彻底的。就目前发布的版本而言这类被装饰器守护的 flag 默认都是开启的所以只有在你主动禁用某个 flag 之后才会碰到这个RuntimeError。风格二受守护的代码路径gated code path。另一种情况下is_feature_enabled的检查位于一个已经可用的功能内部用于在旧行为与新行为之间做选择。这种风格不会抛异常flag 只是改变行为走向唯一获知方式就是发布说明或源码。仓库中一个现成的例子是SNAKE_CASE_SKILL_NAME在 src/google/adk/skills/models.py 的 skill 名称校验器中flag 开启时允许snake_case与kebab-case两种命名并拒绝混用关闭时则只允许kebab-case——对应技能指南中的说明见 docs/guides/skills/skill/index.md“Skill names are kebab-case by default. Snake_case requires enabling theSNAKE_CASE_SKILL_NAMEfeature”。JSON_SCHEMA_FOR_FUNC_DECL也属于此类源码注释_feature_registry.py展示了它如何在“用 JSON Schema 描述参数”的新行为与“用 Schema 对象描述”的旧行为之间切换。函数与类型速查整个系统只需记住三个名字一个命名 flag、一个读取 flag、一个设置 flag。三者均由 src/google/adk/features/init.py 从google.adk.features导出。符号签名说明FeatureNamestr枚举全部 flag 的集合。成员随版本增删。is_feature_enabled(feature_name: FeatureName) - bool按上述优先级立即解析一个 flag。override_feature_enabled(feature_name: FeatureName, enabled: bool) - None设置进程级最高优先级的覆盖。is_feature_enabled的边界行为对不在注册表中的名字抛出ValueErrorFeature name is not registered.。由于FeatureName成员总是已注册的这只会发生在你传入裸字符串时。对应测试见 tests/unittests/features/test_feature_registry.py。override_feature_enabled的边界行为对未注册的名字抛出同样的ValueError设置后对整个进程的剩余生命周期生效且无法通过公共 API 撤销_feature_registry.py。顺带一提源码内部还提供了一个上下文管理器temporary_feature_override_feature_registry.py进入上下文时临时覆盖 flag、退出时恢复原状但它并未从google.adk.features的__all__中导出见init.py属于内部实现细节公共 API 只承诺上文三个符号使用内部符号需自行承担兼容性风险。高级应用两种需要多想一步的场景场景一把 flag 限定在单个测试内由于override_feature_enabled无法撤销测试里翻转 flag 会污染同进程内后续所有测试。官方推荐的正确做法是改用 pytest 的monkeypatch设置环境变量——monkeypatch会在 teardown 时自动恢复原值def test_snake_case_skill_name(monkeypatch): monkeypatch.setenv(ADK_ENABLE_SNAKE_CASE_SKILL_NAME, 1) # 被测代码通过 is_feature_enabled 读取该 flag。这套做法成立的前提有二一是环境变量每次调用都实时读取、从不缓存二是该测试没有设置过程序化覆盖那会压过环境变量。tests/unittests/features/test_feature_registry.py中大量使用monkeypatch.setenv验证环境变量优先级、警告只发一次等行为例如 test_feature_registry.py可作为参照。场景二让部署结果可复现风险在于后续 ADK 版本可能翻转某个 flag 的默认值导致你下次部署时 agent 行为悄然改变而自己的代码一行未动。解决方案是在部署环境中显式钉住pin你依赖的 flag而不是依赖注册表默认值。两个方向都值得钉ADK_ENABLE_NAME1钉住你依赖的、默认关闭或未来可能变化的特性ADK_DISABLE_NAME1钉住你暂时不想接受的、默认开启的实验特性。配合 CI/CD 的同一份环境配置即可保证升级前后行为一致。已知限制Limitations以下限制与官方文档一致均可在源码中找到对应实现依据覆盖无法清除公共 API 只能把覆盖设为True或False无法移除因此一旦覆盖过某个 flag进程就无法回到“环境变量/默认值”解析模式ADK_ENABLE_X0不会禁用只有1和true视为已设置0等价于“未设置”解析会穿透到注册表默认值真正关闭要用ADK_DISABLE_X1实现见 env_utils.pyflag 集合跨版本不稳定成员随特性毕业而增删指向已不存在 flag 的环境变量会被静默忽略无警告、无报错因为is_feature_enabled只在被实际调用时才对未注册名抛ValueError而环境变量本身不触发调用flag 读取时机因特性而异有的单元在构造时读取有的在每次调用时读取在相关对象已存在之后再设环境变量可能不生效警告没有 per-flag 开关屏蔽实验性警告需要warnings过滤器若不按消息文本精确匹配也会一并屏蔽其他UserWarning。关联指南Skill 指南docs/guides/skills/skill/index.md讲解了一个具体 flag——SNAKE_CASE_SKILL_NAME——及其改变的 skill 命名行为默认kebab-case开启后允许snake_case想从源码层面继续深挖可阅读 src/google/adk/features/_feature_registry.py注册表与解析逻辑、src/google/adk/features/_feature_decorator.py三类装饰器以及 tests/unittests/features/test_feature_registry.py优先级、警告、覆盖行为的完整测试矩阵。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考