人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python TypeScript - any model, any cloud.项目地址https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk点击查看免费下载导读本文基于 team/FEATURE_LIFECYCLE.md系统讲解 Strands SDKPython 包strands-agents与 TypeScript 包如何以语义化版本为骨架通过strands.experimental实验模块孵化新特性、按月度评审节奏推进毕业graduation并对旧功能执行带时间线的可预测弃用deprecation。读完本文你将掌握Major/Minor/Patch 各自的边界与pay for play例外规则、实验特性从进入、毕业到移除的三版本节奏、Python/TypeScript 双语言下deprecated的正确落地方式含工具弃用的双层警告机制以及社区信任、发布节奏与回滚策略的完整治理框架。文中所有论断均可在仓库源码与配置中验证。适用范围这份流程约束什么该特性生命周期流程适用于 Strands SDK 的两个核心包Python SDKstrands-py发布名为strands-agentsTypeScript SDKstrands-ts需要注意本流程不适用于 Strands harnessharness-py/harness-ts与 Strands CLIstrands-cli。它们属于 0.x 产品遵循独立规则0.x 下没有 Major 版本概念patch 版本可以携带新特性包括新内置工具与插件minor 版本即视为破坏性变更每个 minor 发布时都会列出破坏了什么以及如何迁移。详见 site/src/content/docs/user-guide/harness/versioning.mdx。适用对象 版本策略 破坏性变更如何处理 strands-py / strands-ts Strict SemVer 需 Major 版本 迁移指南 harness-py / harness-ts 0.x独立规则 每个 minor 列出破坏项与迁移方式 strands-cli 0.x同 harness 同上大版本Major Release的愿景与支持承诺愿景把 Major 当作减债窗口Major 版本不应被看作对社区的惩罚而应视为降低技术债务、移除已弃用功能的机会同时为社区提供平滑升级路径。文档给出的理想目标非常具体让用户从 1.11 升级到 2.0 时只需极少的代码改动、几乎感受不到行为差异。为实现这一点1.11 应当尽量回移植back-port2.0 的 API让用户提前在旧版本上完成适配升级时自然无缝。支持承诺维护者视角每个 Major 版本在下一个 Major 发布后仍需至少维护 6 个月覆盖 bug 修复与安全补丁新特性不会回移植到旧 Major 版本。社区视角带破坏性变更的 Major 需要用户投入精力升级应用因此任何 Major 发布都应有充分的提前通知。语义化版本遵守X.Y.Z 各司其职版本位允许内容典型例子MajorX.0.0破坏性变更、特性移除、任何用户不做任何操作就会影响既有代码的 API 变更移除已弃用多年的旧工具bashMinor1.Y.0新特性、弃用警告、向后兼容的增量、pay for play式破坏性变更见下文例外新增实验特性毕业、对旧 API 加deprecatedPatch1.1.ZBug 修复、安全补丁、文档更新修复某个工具在错误路径上未记日志的问题核心判据一句话用户升级后什么都不改代码是否就不再工作如果是就必须进 Major如果用户必须主动调用新 API 才会遇到破坏则可能属于例外。版本遵守的两类例外例外一快速演进的标准Rapidly Evolving StandardsAI 生态的标准演进速度远超传统软件。当 SDK 需要依赖仍在剧烈变化的标准或库文档明确点名的例子包括OTEL GenAI Semantic Convention、MCP、A2A 协议时严格版本规则可能跟不上行业节奏。此时团队的取舍是优先提供业界标准实现尽可能贴近规范本身对这些依赖不做严格 semver 承诺对生产应用给出最佳实践建议把依赖锁定pin到某个具体 minor 版本。这一策略在strands-py/pyproject.toml的依赖声明中有直观体现——例如mcp1.23.0,2.2、a2a-sdk0.3.0,0.4.0等均通过上下限把快速演进依赖约束在可控区间而strands-agents[a2a]、strands-agents[cedar]等 optional extras 又把这类依赖隔离在按需安装的路径上。例外二Pay for Play付费才玩的 Opt-In 破坏性变更核心原则程序可以调用新 API 来获得新功能但不调用新 API 的程序完全不受影响——旧代码继续按原样工作。适用条件必须全部满足破坏性变更被门控在用户必须显式采用的新功能后面既有代码路径完全不受影响不触碰新特性的用户永远观察不到破坏破坏是明显的且直接关联到用户刚添加的东西。不适用条件任一命中就必须 Major既有代码在用户无任何操作的情况下就坏了变更影响了默认行为用户升级后代码莫名失效找不到明显原因。文档给出的范例把一个TypedDict改成totalFalse在技术上属于破坏性变更既有实现未提供新增的 optional 成员。但如果只有在你新增一个采用新格式的工具后才会遇到这些新成员那么该变更实质上是pay for play——没有采用新工具的用户永远观察不到破坏。理由严格的 semver 遵守会拖慢 SDK 迭代当破坏只影响显式采用新功能的用户、既有代码路径不受影响时对社区的实际影响极小更快交付新特性的收益大于理论上的 semver 违规。特性新增流程Feature Addition Process六个阶段的完整链条设计阶段Design Phase对影响公共 API 的重要特性在 GitHub Discussions 创建讨论帖收集社区意见实现Implementation带着全面的测试与文档进行开发实验发布Experimental Release新特性放入strands.experimental子模块收集反馈并迭代Collect Feedback Iterate收集社区反馈迭代直至满足社区需求与维护者标准月度评审Monthly Review以固定节奏评估实验特性稳定化Stabilization验证通过后在随后的 minor 发布中移入主模块。实验模块在源码中的真实形态在仓库中strands.experimental是真实存在的物理模块strands-py/src/strands/experimental。其__init__.py的模块 docstring 明确写道This module implements experimental features that are subject to change in future revisions without notice.本模块实现的实验特性可能在未来的修订中不经通知而变更。当前实验模块已包含多个正在孵化的子模块例如checkpoint检查点、context_manager上下文管理、steering引导/策展、tools工具以及agent_config的config_to_agent入口——这些正是快速迭代、社区反馈驱动策略的活样本。需要强调的是从源码结构看实验模块内部依旧遵循常规的代码组织与测试纪律对应测试位于strands-py/tests/strands/experimental/下只是对外不承诺向后兼容。什么是 experimental它的法律地位实验模块让维护者可以快速行动、收集反馈、持续迭代社区在整个过程中被欢迎参与测试实验特性被排除在语义化版本标准与 minor 版本间向后兼容保证之外文档一般不建议在生产使用实验特性如果经过充分评估后仍要使用务必 pin 到具体 minor 版本以避免被破坏性变更波及。实验特性的使用方式收集三类反馈发布实验特性的唯一目标是收集社区对以下三点的反馈特性的实用性utility特性的形态shape包括接口与行为特性提供的价值value。因此任何进入实验模块的特性都必须预先定义清晰的退出标准exit criteria——要么晋升为主 SDK要么被正式否决维护者承诺主动为实验特性寻求社区反馈。毕业标准从 experimental 晋升的核心 Checklist文档给出了四大维度共 12 项硬性标准是判断特性能否转正的唯一依据稳定性与成熟度Stability MaturityAPI 稳定预期无破坏性变更核心功能完整且经过测试质量保证Quality Assurance全面的测试覆盖单元、集成、端到端文档完整含示例与 API 参考使用与采纳Usage Adoption至少 23 个真实世界用例得到验证早期采用者的反馈积极没有重大未解决问题或阻塞项价值主张得到清晰证明技术要求Technical Requirements错误处理健壮且一致日志与可观测性已实现依赖稳定且维护良好流程与治理Process Governance已记录从实验版本迁移的路径已为实验版本建立弃用时间线毕业的三版本节奏关键一旦特性满足退出标准且维护者判定可以转正晋升按三个 minor 版本推进Minor 版本实验特性的状态X.Y-1特性仅存在于实验模块/状态X.Y① 实验特性被复制到主 SDK② 实验版本开始用warnings.warn()发出弃用警告③ 新特性文档标记为非实验性并提供迁移指南X.Y1实验特性从实验模块中移除这套节奏保证了主 SDK 已可用、实验版仍有警告、最终实验版消失的平滑过渡用户始终有一个版本窗口完成迁移。弃用流程Deprecation Process给社区留足迁移时间Minor 版本内是纯增量、保持向后兼容的但功能终需移除或重构。弃用流程三步走先提供替代方案引入一个完成同样功能的更好方式弃用旧方式给出清晰警告与迁移指引在新 Major 发布时移除已弃用功能。弃用时间线Major 版本 X ├─ Minor X.Y-1 : 只有旧方式 ├─ Minor X.Y : 新方式加入旧方式加 deprecated(msg) 弃用警告 ├─ Minor X.Y1 : 可选在警告中补充迁移示例或指向文档的链接 └─ Major X1 : 彻底移除旧方式实现标准Python 的正确姿势必须从typing_extensions导入deprecated而不是warnings。原因非常具体warnings.deprecatedPEP 702 的运行时版本要求Python 3.13而 SDK 支持3.10 及以上见 strands-py/pyproject.toml 中requires-python 3.10与完整的 3.103.14 测试矩阵typing_extensions本身已是 SDK 依赖typing-extensions4.13.2,5.0.0直接用它即可在旧 Python 上获得相同的deprecated能力。from typing_extensions import deprecated deprecated( deprecated_function() is deprecated and will be removed in v2.0.0. Use new_function() instead. See migration guide: https://strands-agents.com/migration/deprecated_function ) def deprecated_function() - None: ...一条来自源码的额外细节PEP 702 的检查器如 mypy/ruff 的deprecated规则只认字符串字面量参数f-string 拼接会导致弃用标注失效。仓库中 strands-py/src/strands/vended_tools/_bash.py 对此专门加了注释说明这一约束。实现标准TypeScript 的正确姿势/** * deprecated deprecated_function() is deprecated and will be removed in v2.0.0. Use new_function() instead. See migration guide: https://strands-agents.com/migration/deprecated_function , */ export const deprecated_function () {}专门章节如何弃用一个工具Deprecating a Tool工具tool的弃用是双轨制装饰器与日志缺一不可因为它们触达的受众不同谁也替代不了谁手段触达运行 agent 的用户触达类型检查器、IDE、-W errordeprecated装饰器否是logger.warning日志是否为什么必须双管齐下因为deprecated触发的是DeprecationWarning而 Python 的默认警告过滤器只显示源自__main__模块的该警告其余模块一律忽略。工具由框架SDK 内部调用警告会被归因到 SDK 内部模块从而被抑制——用户什么都看不到。用户真正看到的是日志行。但装饰器仍必须保留它标记调用点供类型检查器与 IDE 识别并在-W error或 pytest 环境下浮出水面。import logging from strands import tool from typing_extensions import deprecated logger logging.getLogger(__name__) _DEPRECATION_MESSAGE ( old_tool is deprecated and will be removed in v2.0.0. Use new_tool instead. See migration guide: https://strands-agents.com/migration/old_tool ) tool deprecated(_DEPRECATION_MESSAGE) def old_tool(query: str) - str: Does the old thing. Args: query: What to look up. logger.warning(tool_nameold_tool | %s, _DEPRECATION_MESSAGE) ...四条铁律装饰器顺序tool必须在最外层这样工具 spec 才能从真实签名构建消息共享通过常量_DEPRECATION_MESSAGE共享文案两份副本不会漂移先记日志再早退日志调用必须在任何 early return 之前保证错误路径也会触发警告日志格式遵循两个 SDK 通用的结构化日志格式形如tool_nameold_tool | message的 key-value 风格与仓库中logger.warning(tool_nameold_tool | %s, ...)的实现一致。工具实例tool instance的特殊处理如果被弃用的是工具实例而非工厂函数它根本无法携带deprecated装饰器。这类情况必须通过模块级__getattr__解析——在__getattr__中发出警告并返回替代品。仓库中的真实落地方案strands.vended_tools.bash正是这一模式的教科书实现。strands-py/src/strands/vended_tools/_bash.py 中make_bash工厂函数被deprecated(...)标注指向替代品make_shell并明确will be removed in v2.0.0bash是工具实例bash make_shell(namebash)无法加装饰器因此在 strands-py/src/strands/vended_tools/init.py 的模块级__getattr__中当有人访问bash时发出DeprecationWarning含stacklevel2让警告指向调用方代码并返回实例模块命名为_bash而非bash正是为了避免公开子模块被 import 绑定到包上从而悄悄遮蔽掉负责发警告的__getattr__bash刻意不进入__all__与文档但保持可导入直到 v2.0.0 移除。另一处仓库实例strands-py/src/strands/models/llamaapi.py 中的LlamaAPIModel类被deprecated标注原因是其底层 Llama API 服务已被 Meta 弃用明确声明will be removed in v2.0.0并给出迁移去向BedrockModel、OllamaModel或OpenAIModel——这同时展示了上游标准演进 → 依赖方弃用的完整链路。沟通要求Communication RequirementsChangelog记录所有弃用项及迁移路径文档更新清晰迁移示例GitHub Issues为重大弃用创建跟踪 IssueGitHub Discussions用于收集社区对拟议变更的反馈。社区信任原则Community Trust Principles可预测性Predictability在弃用警告与移除之间保留足够的版本过渡绝不在 minor/patch 版本移除功能在可行时提供自动化迁移工具、清晰报错或对新行为的自动回退。透明度Transparency所有警告中给出明确的弃用时间线例如will be removed in v2.0.0提供全面的迁移文档通过发布说明保持定期沟通。这两条原则在仓库的弃用消息文案中被严格执行——无论是_bash.py的make_bash、llamaapi.py的LlamaAPIModel还是__getattr__中的警告都包含被弃用 移除版本v2.0.0 替代方案 迁移指南链接四个要素。发布节奏Release Cadence发布类型节奏内容Patch按需用于关键修复紧急 bug 修复、安全补丁Minor固定节奏新特性、弃用警告实验特性可能带破坏性变更Major提前通知破坏性变更、移除已弃用功能回滚策略Rollback Policy若某 minor 发布对社区造成重大影响执行三步流程立即发布 patch 回滚问题变更撤回yank包在技术上可行但一般不鼓励优先向前打补丁forward patch若无法快速提供缓解方案先 revert 再 forward patch是首选路径yank 仅限极端情况如严重安全漏洞事后分析Post-mortem查明根因修订测试与验收标准用于后续发布。从治理文档到工程实践一份速查清单将整份生命周期流程浓缩为可操作的行动清单新增特性GitHub Discussion → 实现含测试与文档→ 进入strands.experimental→ 收集反馈 → 月度评审 → minor 毕业X.Y-1仅实验 /X.Y复制进主模块并发warnings.warn()/X.Y1移除实验版增强既有特性向后兼容改进走 minor优先加新字段/新 flag而非改旧字段pay for play 例外可进 minor否则等 major 并提供迁移指南弃用旧功能先给替代品 →deprecatedPython 从typing_extensions导入 日志双轨 → 到下一个 major 移除弃用工具实例走模块级__getattr__发DeprecationWarning可参考strands.vended_tools的bash实现任何弃用警告中必须含移除版本、替代方案、迁移指南链接回滚forward patch 优先revert 其次yank 仅限极端安全场景。这套机制的最终目标始终如一在快速交付 AI 时代新能力的同时让社区升级路径始终平滑、可预测、有据可依——这正是 team/FEATURE_LIFECYCLE.md 想为 Strands SDK 建立的长期工程秩序。赞分享人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python TypeScript - any model, any cloud.项目地址https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk点击查看免费下载相关推荐Dart SDK版本发布机制揭秘实验特性从Flag引入到退役的完整生命周期Dart SDK版本发布机制揭秘实验特性从Flag引入到退役的完整生命周期 Dart SDK 是 Dart 语言的官方开发工具包包含虚拟机VM、JS 与编程语言编译器语言运行时标准库开发工具VeighNa量化策略全生命周期管理从开发到退役的完整指南VeighNa量化策略全生命周期管理从开发到退役的完整指南 VeighNa作为基于Python的开源量化交易平台开发框架为量化投资者提供了完整的策略生命周期金融科技后端机器学习如何快速提升游戏角色性能智能构建工具的完整实战指南如何快速提升游戏角色性能智能构建工具的完整实战指南 在《流放之路》这款复杂的暗黑风格游戏中每个玩家都曾面临这样的困境投入大量时间研究装备搭配却发现角色伤游戏开发上一篇React-PDF预览打印最佳实践打印预览的最佳方法下一篇一文读懂FinnewsHunter架构从爬虫到知识图谱的全流程解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考