人工智能大模型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/TENETS.md 是 Strands 团队设计 SDK 时遵循的六条核心原则被用于指导特性设计、代码评审与取舍决策也是理解整个仓库Python SDK、TypeScript SDK、harness、CLI 与文档站点设计脉络的钥匙。本文逐条拆解这六条信条的内涵并结合仓库内的决策记录、实现源码与治理文档说明它们如何在真实代码中落地——读完你会掌握一套可用于自己项目的 API 设计评判标准也能在向 Strands 贡献代码时快速对齐团队的设计语言。信条总览六条原则的定位team/TENETS.md开篇明确了信条的作用帮助团队做出一致决策、解决权衡、维持 SDK 的质量与连贯性。贡献者在提议方案或评审代码时会引用这些原则来引导讨论当两个方案看起来同样合理时选择与信条最契合的那一个。六条信条分别是Simple at any scale任意规模下保持简单Extensible by design设计上可扩展Composability可组合性The obvious path is the happy path显而易见的路径就是最佳路径We are accessible to humans and agents对人类与 AI Agent 同样友好Embrace common standards拥抱通用标准在仓库中信条不是孤立的宣言而是与 team/DECISIONS.md决策记录、team/API_BAR_RAISING.mdAPI 评审机制、team/FEATURE_LIFECYCLE.md特性生命周期、team/COMPLEXITY.md复杂度度量等治理文档互相咬合共同构成一个可执行的工程文化体系。信条一Simple at any scale——同一套抽象从原型到生产这条信条的核心论断是简单的事情应该保持简单驱动周末原型的那套干净抽象应当能无缝扩展到生产负载。团队明确反对企业级等于企业级复杂的预设——Strands 无论面对你的第一个 Agent 还是第一百万个都应当保持平易近人。从 harness 看开箱即用的简化仓库中最直接的落地是 harness-py/ 与 harness-ts/ 两个完全组装好的 Agent。Python 侧只需一次调用即可获得一个带默认配置的完整 Agentfrom strands_harness import create_harness agent create_harness() agent(Find the slowest test in this repo and explain why its slow)TypeScript 侧对应的是import { createHarness } from strands-agents/harness const agent await createHarness() await agent.invoke(Find the slowest test in this repo and explain why its slow)这里的简单并非功能的匮乏而是把复杂度收敛到默认值里。harness-py/src/strands_harness/defaults.py 展示了这一设计默认模型为bedrock/global.anthropic.claude-opus-5上下文管理、缓存策略均默认auto内置工具shell、read、write、edit、web_fetch、web_search、programmatic_tool_caller、subagent按固定顺序注册内置插件todos、environment默认开启。用户零配置即可获得具备模型、工具、内存、会话与上下文管理的生产就绪 Agent。复杂度度量让简单可量化、可评审Simple at any scale如果只是口号就难以执行。team/COMPLEXITY.md 将其变成了可复现的度量每个 PR 都会按其所触及的最复杂函数的认知复杂度cognitive complexity打上标签——complexity/low≤10、complexity/medium11–25、complexity/high25。该文档明确指出It is our first tenet made measurable这是我们第一条信条的可度量化。其评分规则只有两条每次线性流程的中断if、else、循环、catch/except、三元表达式、switch/match、递归、混合布尔运算符计 1 分嵌套会倍增成本——每个结构每多一层嵌套额外计 1 分因此函数顶层的if计 1 分三层嵌套下的同一if计 4 分。作者侧可用仓库提供的命令自查从仓库根目录运行npm run complexity或从strands-py/运行hatch run complexity输出即为 diff 触及的最复杂函数列表。该标签是建议性的永不阻塞合并——因为有些代码就是诚实地复杂例如协议事件转换器、状态机与穷举格式映射强行压平反而损害可读性。信条二Extensible by design——把可扩展性做成默认配置第二条信条主张在 hooks、模型提供方、会话管理器、工具等各个方面尽可能提供配置能力在客户所在的位置提供灵活且易于集成的扩展点。这与决策记录中反复出现的扩展 HookProvider模式一脉相承。Hook 体系可组合的扩展原语Python SDK 的 hooks 模块在 strands-py/src/strands/hooks/init.py 中有完整说明这是一套强类型 hook 系统允许内置组件与用户代码通过类型化事件回调来响应或修改 Agent 行为。其核心接口是HookProvider与HookRegistryfrom strands.hooks import HookProvider, HookRegistry from strands.hooks.events import BeforeInvocationEvent, AfterInvocationEvent class LoggingHooks(HookProvider): def register_hooks(self, registry: HookRegistry) - None: registry.add_callback(BeforeInvocationEvent, self.log_start) registry.add_callback(AfterInvocationEvent, self.log_end) def log_start(self, event: BeforeInvocationEvent) - None: print(fRequest started for {event.agent.name}) def log_end(self, event: AfterInvocationEvent) - None: print(fRequest completed for {event.agent.name}) # 使用 agent Agent(hooks[LoggingHooks()])该模块取代了旧的 callback_handler 方案采用更可组合、类型安全、支持每个事件类型多订阅者的设计。从源码结构看strands-py/src/strands/hooks/registry.py 承载了注册表实现而事件定义集中在 strands-py/src/strands/hooks/events.py包括BeforeInvocationEvent、AfterModelCallEvent、AfterToolCallEvent、AgentInitializedEvent以及多 Agent 场景的AfterMultiAgentInvocationEvent、AfterNodeCallEvent等。扩展点遍及整个 Agent 生命周期通过HookProvider搜索可以确认这套机制渗透到了 Agent 生命周期的各个集成点strands-py/src/strands/agent/agent.pyAgent 主类、strands-py/src/strands/agent/conversation_manager/conversation_manager.py会话管理器、strands-py/src/strands/session/session_manager.pySession 管理、strands-py/src/strands/event_loop/_retry.py重试策略、strands-py/src/strands/multiagent/graph.py 与 strands-py/src/strands/multiagent/swarm.py多 Agent 模式等都通过 hooks 暴露扩展能力。工具、模型提供方、Session 管理器、会话管理器、干预interventions等均有对应扩展点契合在客户所在的位置提供扩展点的承诺。信条三Composability——原语互为积木第三条信条强调原语是彼此构建的积木Strands 的每个特性都是与其他所有特性协同开发的彼此一致且互补。这是可扩展与可组合的区分点前者关注能否插入自定义逻辑后者关注不同扩展点能否无缝协同。决策记录中的组合示例接口应当扩展 HookProviderteam/DECISIONS.md 中有一条专门记录2026 年 1 月 21 日When Internal Interfaces Should Extend HookProvider。团队讨论RetryStrategy时面临两个方案扩展HookProvider或暴露一个带should_retry(exception, attempt) - bool的简单领域接口。最终选择扩展HookProvider理由是在所有与生命周期集成的 Agent 构造参数之间保持统一模式用户实现任一接口只需学习一种组合模型。这正是组合性信条的注释原语是彼此构建的积木。该记录还给出了清晰的选用标准使用简单接口当接口职责单一一两个方法即可表达、无需响应多个生命周期事件、与现有接口的一致性不是优先事项扩展 HookProvider 当能力需要响应多个不同的生命周期事件、用户需要自定义订阅哪些事件或在基类默认回调之外添加回调。组合性的另一层体现在 hooks 系统本身的设计——strands-py/src/strands/hooks/init.py 明确写道提供了一种可组合机制并支持每个事件类型多个订阅者使多个扩展点可以在同一事件上叠加。高层 API 构建在低层 API 之上team/DECISIONS.md 的Provide Both Low-Level and High-Level APIs2026 年 1 月 30 日同样是组合性的体现新特性应当同时提供细粒度控制的低层 API 与带默认值的高层 API。示例是BidiAgentsend/receive是低层原语需要用户自行管理并发、生命周期与事件路由而run方法构建在其上用户只需提供 IO 回调await agent.run(inputs[audio_input], outputs[audio_output, text_output])这正是原语互为积木的直白示范高层 API 复用低层原语而不是另起炉灶。信条四The obvious path is the happy path——显而易见即正确第四条信条主张通过直观命名、有帮助的错误信息与深思熟虑的 API 设计把开发者引向正确模式、避开常见陷阱。它对应决策记录中反复出现的两个核心概念happy path与pit of success成功之坑——让简单路径天然就是正确路径。命名术语只属于它的领域team/DECISIONS.md 的Avoid Overloading Domain Terms in API Naming2026 年 3 月 4 日是命名层面的落地。团队拒绝在 API 中复用已被占用语义的术语Python SDK 使用structured_output_model因为 Pydantic 把自己的 schema 称为 modelTypeScript SDK 选择structuredOutputSchema因为 Zod 的核心术语是 schemaz.object()返回ZodSchema且 Strands SDK 中 model 已经指代 LLM 提供方如BedrockModel、model配置参数文档统一使用 agent loop 而非 event loop因为后者在 Pythonasyncio与 JavaScript/Node.js 中都是已被占用的语言运行时概念。结论是跨语言一致性有价值但不应以牺牲语言内部的清晰度为代价——显而易见的路径首先要求名称不产生歧义。默认值把最常见用法做成默认team/API_BAR_RAISING.md 中API 评审者被要求追问Are the default parameters/behavior the most common?默认参数/行为是否是最常见的If not, why did we choose them?如果不是为什么这样选择。这条评审问题直接服务于 happy path 信条默认值必须引导绝大多数用户走向正确用法。同样在 harness 中harness-py/src/strands_harness/defaults.py 的默认值设计模型、工具、插件、上下文管理策略均给出合理默认让零配置即正确成为可能。语义清晰化Null 与 Undefined 各司其职team/DECISIONS.md 的Null Means Explicit Removal; Undefined Means Apply the Default2026 年 8 月 19 日解决的是最容易产生歧义的传透字段pass-through values如 provider 的params与additional_request_fieldsnull表示显式移除用户刻意将该字段剔除SDK 应将其从请求中删掉既不发送null也不代以 SDK 默认值undefined或缺省字段表示走默认SDK 可自行应用合理默认默认本身也可能是省略该字段Python 中没有undefined缺席的 key 扮演undefined显式None视为null这不改变Agent(modelNone)这类None 即未指定的既有语义。该决策不适用于特性开关MemoryManager(injectionFalse)、sandbox: false这类开关仍以false/False表示显式关闭因为传透字段可能合法携带false如store: false、parallel_tool_calls: false而开关值永远不会被转发两者不能共用同一哨兵值。这一二分让我没指定与我明确不要两种意图各归其位避免用户陷入无法关闭 SDK 管理的默认或每个未指定字段都被当作有意删除的两难。信条五We are accessible to humans and agents——双端可达第五条信条是 Strands 最具辨识度的设计主张SDK 既要让人类理解也要让 AI 编码助手coding assistants同样理解。团队不为人类牺牲精心打磨的 DX同时额外投入确保编码助手能正确帮助用户使用这些接口。面向 Agent 的治理文档这一信条在仓库治理层面最直接的体现是 team/AGENT_GUIDELINES.md——一份专门写给与 Strands 仓库交互的 AI Agent 的指南PR 评审、Issue 分类、文档与自主改进。其核心规则包括Add Value or Stay SilentAgent 没有具体可贡献的内容时不应行动沉默好过噪音Keep It Short输出应简洁用渐进式披露progressive disclosure组织内容Approvals Need Reasoning不批准时必须给出清晰理由批准在初期也应附带简要推理以校准评审者判断Scope Credentials to the Task遵循最小权限原则绝不给 Agent 维护者令牌force-push、删分支、改设置等破坏性操作不可逆Throttle Autonomous Activity自主活动应保持人类可跟进的速度优先在业务时段运行限制同时持有的活跃条目数Own What You Deploy每个自主 Agent 必须有具名的负责人人而非团队负责日志访问、快速禁用流程、错误清理与持续迭代Monitor What Agents DoAgent 的行为应通过既有工具可见PR 历史、评论日志、审计轨迹Maintainers Can Pull the Cord任何维护者都可以立即禁用在其仓库上运行的 Agent无需审批分钟级完成Know That Your Agent Works部署前必须验证 Agent 确实按预期工作质量不达人类标准就应被拒绝。文档末尾附有完整的部署前检查清单涵盖价值、简洁性、最小权限、具名负责人、节流、可见性与即时关停能力——这是对 Agent 友好从口号变为可执行流程的范本。扁平命名空间降低人类与 Agent 双方的检索成本team/DECISIONS.md 的Prefer Flat Namespaces Over Nested Modules2026 年 1 月 16 日同样服务于此信条公共 API 应通过扁平的顶层命名空间暴露常用功能而非要求用户从深层嵌套路径导入。灵感来自 Python 的Flat is better than nestedPEP 20但该原则跨 SDK 语言适用# 推荐从单一模块导出所有 hook 事件 from strands.hooks import MultiAgentInitializedEvent # 避免按用途归类到深层子模块 from strands.hooks.multiagent import MultiAgentInitializedEvent理由与人类与 Agent 双端友好直接相关更少的导入对人类更简单、对 IDE 自动补全与文档更可发现而对编码助手而言扁平导出意味着它更可能在常见位置找到正确符号——当事件名本身已表明分组如MultiAgentInitializedEvent时尤为如此。内部模块组织仍可嵌套以维护代码关键是在公共位置重新导出符号。信条六Embrace common standards——尊重前人拥抱通用标准第六条信条主张尊重已有的事物不重复发明已经被广泛采用或做得更好的东西。在快速演进的 AI 生态中这一条决定了 Strands 对行业标准的依赖策略。依赖演进中的标准team/FEATURE_LIFECYCLE.md 明确指出虽然 SDK 追求稳定但 AI 标准演进迅速。团队偶尔需要依赖仍在演进、未必严格遵循版本化要求的库或标准明确列举的例子包括OTEL GenAI Semantic ConventionOpenTelemetry 生成式 AI 语义约定、MCPModel Context Protocol与 A2AAgent-to-Agent协议。在这些情况下团队优先提供行业标准实现、尽可能贴近规范文档建议生产环境使用此类特性的用户固定到特定 minor 版本作为最佳实践。仓库中确实存在这些标准的实体实现strands-mcp/是 MCP 服务端实现strands-py/src/strands 与 strands-ts/src 中均包含mcp/与a2a/模块如 strands-ts/src/mcptests_integ 目录下还有专门的mcp/与a2a/集成测试目录见 strands-py/tests_integ/mcp 与 strands-py/tests_integ/a2a。兼容性政策承认既有的语义版本约定team/COMPATIBILITY.md 体现了对语义版本semver这一通用标准的尊重明确列出两类不被视为破坏性变更的改动字段转属性Field to Property Conversion将公共可变字段转为带访问器逻辑的属性不算破坏性变更即使新增校验或副作用——因为从调用点看属性访问与直接字段访问在语法和行为上不可区分文档给出了 TypeScript getter/setter 与 Pythonproperty的对照示例如agent.model从字段改为带非空校验的访问器用户代码无需改动联合类型扩展Union Type Extensions向联合类型新增类型或类不算破坏性变更除非联合显式声明不再变化——新的事件类型、结果变体、错误类型与配置选项都会被既有的类型守卫、switch或模式匹配逻辑自然忽略。该政策同时划清了边界它适用于strands-py与strands-ts两个 SDK而 Strands harness 与 Strands CLI 处于 0.x遵循各自独立的版本规则参见 site/src/content/docs/user-guide/harness/versioning.mdx。信条如何驱动日常工程决策API 评审信条是评审标尺team/API_BAR_RAISING.md 定义了确保 SDK API 高质量、一致、面向未来的评审机制其评审问题清单直接以信条为纲是否符合 SDK 信条是否符合 决策记录若以可扩展性为目标什么可定制、什么不可定制抽象层级是否恰当哪些用例未被覆盖为什么默认参数/行为是否是最常见的如果不是为什么评审按变更规模分级最小变更如给不常用方法加参数走常规 PR 评审中等变更如新增客户使用的类先与 API 评审者非正式讨论实质性变更如新增原语或常用抽象需在设计阶段或之后与至少两位 API 评审者开会。PR 通过api/needs-review与api/review-complete标签标记CI 强制api/needs-review的 PR 必须有api/review-complete才能合并。若评审产生了可指导未来设计的决策就沉淀为决策记录——这被视为评审成功的标志。特性生命周期信条决定演进节奏team/FEATURE_LIFECYCLE.md 将简单兼容拥抱标准等信条落实为版本化流程新特性流程设计阶段在 GitHub Discussion 征集意见 → 实现并带完整测试与文档 → 放入strands.experimental子模块 → 收集反馈迭代 → 月度评审 → 验证后于后续 minor 版本稳定化。源码中可见 strands-py/src/strands/experimental 目录其__init__.py明确声明该模块实现实验性特性未来修订中可能在没有通知的情况下变更毕业流程minor 版本 X.Y-1 仅存在于实验模块X.Y 复制进主 SDK 并开始通过warnings.warn()发出弃用警告文档标记非实验并附迁移指南X.Y1 从实验模块移除弃用流程先引入替代方案 → 以deprecated标记旧方式并给出清晰警告与迁移指引 → 新 major 版本移除。Python 侧使用typing_extensions.deprecated非warnings因为后者需 Python 3.13而 SDK 支持 3.10Pay for play 例外门控在新功能之后的、用户不主动采用就完全无感的小型破坏性变更可在 minor 版本内发布——但绝不适用于用户无任何操作代码就坏掉或改变默认行为的情形版本承诺每个 major 版本在下一个 major 发布后至少支持 6 个月含 bug 修复与安全补丁新特性不回溯minor/patch 版本绝不移除特性。这些规则共同确保信条三强调的特性之间互补一致通过统一的实验—稳定化管道实现信条四的 happy path 通过默认即最常见的评审要求实现信条六通过依赖快速演进标准时固定版本的建议实现。六条信条的协同关系与使用建议通观仓库六条信条并非孤立条目而是一个互相支撑的系统Simple at any scale是目标team/COMPLEXITY.md 把它变成 PR 阶段可复现的数字Extensible by design是手段hooks 体系与遍布 Agent 生命周期的扩展点提供了落点Composability约束扩展点之间的关系要求新接口尽量复用既有原语如扩展HookProvider而非另立门户The obvious path is the happy path约束命名、默认值与语义null/undefined 二分把用户导向正确用法We are accessible to humans and agents同时约束 DX 与文档扁平命名空间与 team/AGENT_GUIDELINES.md 分别是两端的落地Embrace common standards决定何时复用行业标准MCP、A2A、OTEL 语义约定、semver而非自造轮子。对贡献者而言team/README.md 给出的工作流值得遵循提出变更前先对照信条检查对齐度查阅 team/DECISIONS.md 看是否已有相关先例涉及公共 API 时走 team/API_BAR_RAISING.md 的评审流程提交 PR 前用npm run complexity或hatch run complexity自查复杂度标签。若你的贡献产生了能指导未来工作的新决策按 team/README.md 的建议将其补充进决策记录——这正是信条体系自我演进的方式。无论你是人类开发者还是 AI 编码助手这套信条都提供了一个一致的评判框架当两个方案看似同样合理时选最契合信条的那个。赞分享人工智能大模型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点击查看免费下载相关推荐Saber与Vue 3兼容性分析Composition API在Saber中的使用实践Saber与Vue 3兼容性分析Composition API在Saber中的使用实践 Saber作为一款基于Vue.js的静态站点生成工具为开发者提供了高开发工具版本控制CLIbravado单元测试指南用BravadoResponseMock模拟响应让测试告别真实网络请求bravado单元测试指南用BravadoResponseMock模拟响应让测试告别真实网络请求 Bravado 是一个用于 Swagger / OpenA人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务Moby 设计原则详解14 条容器引擎开发准则及其在源码中的落地证据Moby 设计原则详解14 条容器引擎开发准则及其在源码中的落地证据 本文以 MobyDocker 引擎的开源核心仓库中的 project/PRINCIP云原生容器运行时虚拟化容器编排上一篇Vue流程图组件Flowchart-Vue终极可视化开发指南下一篇Node.js v22.14.0 JodLTS发布全解读TypeScript 执行增强、process.ref/unref 与 test_runner 快照新 API创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Strands SDK 开发信条（Development Tenets）解读：从设计原则到源码落地
人工智能大模型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/TENETS.md 是 Strands 团队设计 SDK 时遵循的六条核心原则被用于指导特性设计、代码评审与取舍决策也是理解整个仓库Python SDK、TypeScript SDK、harness、CLI 与文档站点设计脉络的钥匙。本文逐条拆解这六条信条的内涵并结合仓库内的决策记录、实现源码与治理文档说明它们如何在真实代码中落地——读完你会掌握一套可用于自己项目的 API 设计评判标准也能在向 Strands 贡献代码时快速对齐团队的设计语言。信条总览六条原则的定位team/TENETS.md开篇明确了信条的作用帮助团队做出一致决策、解决权衡、维持 SDK 的质量与连贯性。贡献者在提议方案或评审代码时会引用这些原则来引导讨论当两个方案看起来同样合理时选择与信条最契合的那一个。六条信条分别是Simple at any scale任意规模下保持简单Extensible by design设计上可扩展Composability可组合性The obvious path is the happy path显而易见的路径就是最佳路径We are accessible to humans and agents对人类与 AI Agent 同样友好Embrace common standards拥抱通用标准在仓库中信条不是孤立的宣言而是与 team/DECISIONS.md决策记录、team/API_BAR_RAISING.mdAPI 评审机制、team/FEATURE_LIFECYCLE.md特性生命周期、team/COMPLEXITY.md复杂度度量等治理文档互相咬合共同构成一个可执行的工程文化体系。信条一Simple at any scale——同一套抽象从原型到生产这条信条的核心论断是简单的事情应该保持简单驱动周末原型的那套干净抽象应当能无缝扩展到生产负载。团队明确反对企业级等于企业级复杂的预设——Strands 无论面对你的第一个 Agent 还是第一百万个都应当保持平易近人。从 harness 看开箱即用的简化仓库中最直接的落地是 harness-py/ 与 harness-ts/ 两个完全组装好的 Agent。Python 侧只需一次调用即可获得一个带默认配置的完整 Agentfrom strands_harness import create_harness agent create_harness() agent(Find the slowest test in this repo and explain why its slow)TypeScript 侧对应的是import { createHarness } from strands-agents/harness const agent await createHarness() await agent.invoke(Find the slowest test in this repo and explain why its slow)这里的简单并非功能的匮乏而是把复杂度收敛到默认值里。harness-py/src/strands_harness/defaults.py 展示了这一设计默认模型为bedrock/global.anthropic.claude-opus-5上下文管理、缓存策略均默认auto内置工具shell、read、write、edit、web_fetch、web_search、programmatic_tool_caller、subagent按固定顺序注册内置插件todos、environment默认开启。用户零配置即可获得具备模型、工具、内存、会话与上下文管理的生产就绪 Agent。复杂度度量让简单可量化、可评审Simple at any scale如果只是口号就难以执行。team/COMPLEXITY.md 将其变成了可复现的度量每个 PR 都会按其所触及的最复杂函数的认知复杂度cognitive complexity打上标签——complexity/low≤10、complexity/medium11–25、complexity/high25。该文档明确指出It is our first tenet made measurable这是我们第一条信条的可度量化。其评分规则只有两条每次线性流程的中断if、else、循环、catch/except、三元表达式、switch/match、递归、混合布尔运算符计 1 分嵌套会倍增成本——每个结构每多一层嵌套额外计 1 分因此函数顶层的if计 1 分三层嵌套下的同一if计 4 分。作者侧可用仓库提供的命令自查从仓库根目录运行npm run complexity或从strands-py/运行hatch run complexity输出即为 diff 触及的最复杂函数列表。该标签是建议性的永不阻塞合并——因为有些代码就是诚实地复杂例如协议事件转换器、状态机与穷举格式映射强行压平反而损害可读性。信条二Extensible by design——把可扩展性做成默认配置第二条信条主张在 hooks、模型提供方、会话管理器、工具等各个方面尽可能提供配置能力在客户所在的位置提供灵活且易于集成的扩展点。这与决策记录中反复出现的扩展 HookProvider模式一脉相承。Hook 体系可组合的扩展原语Python SDK 的 hooks 模块在 strands-py/src/strands/hooks/init.py 中有完整说明这是一套强类型 hook 系统允许内置组件与用户代码通过类型化事件回调来响应或修改 Agent 行为。其核心接口是HookProvider与HookRegistryfrom strands.hooks import HookProvider, HookRegistry from strands.hooks.events import BeforeInvocationEvent, AfterInvocationEvent class LoggingHooks(HookProvider): def register_hooks(self, registry: HookRegistry) - None: registry.add_callback(BeforeInvocationEvent, self.log_start) registry.add_callback(AfterInvocationEvent, self.log_end) def log_start(self, event: BeforeInvocationEvent) - None: print(fRequest started for {event.agent.name}) def log_end(self, event: AfterInvocationEvent) - None: print(fRequest completed for {event.agent.name}) # 使用 agent Agent(hooks[LoggingHooks()])该模块取代了旧的 callback_handler 方案采用更可组合、类型安全、支持每个事件类型多订阅者的设计。从源码结构看strands-py/src/strands/hooks/registry.py 承载了注册表实现而事件定义集中在 strands-py/src/strands/hooks/events.py包括BeforeInvocationEvent、AfterModelCallEvent、AfterToolCallEvent、AgentInitializedEvent以及多 Agent 场景的AfterMultiAgentInvocationEvent、AfterNodeCallEvent等。扩展点遍及整个 Agent 生命周期通过HookProvider搜索可以确认这套机制渗透到了 Agent 生命周期的各个集成点strands-py/src/strands/agent/agent.pyAgent 主类、strands-py/src/strands/agent/conversation_manager/conversation_manager.py会话管理器、strands-py/src/strands/session/session_manager.pySession 管理、strands-py/src/strands/event_loop/_retry.py重试策略、strands-py/src/strands/multiagent/graph.py 与 strands-py/src/strands/multiagent/swarm.py多 Agent 模式等都通过 hooks 暴露扩展能力。工具、模型提供方、Session 管理器、会话管理器、干预interventions等均有对应扩展点契合在客户所在的位置提供扩展点的承诺。信条三Composability——原语互为积木第三条信条强调原语是彼此构建的积木Strands 的每个特性都是与其他所有特性协同开发的彼此一致且互补。这是可扩展与可组合的区分点前者关注能否插入自定义逻辑后者关注不同扩展点能否无缝协同。决策记录中的组合示例接口应当扩展 HookProviderteam/DECISIONS.md 中有一条专门记录2026 年 1 月 21 日When Internal Interfaces Should Extend HookProvider。团队讨论RetryStrategy时面临两个方案扩展HookProvider或暴露一个带should_retry(exception, attempt) - bool的简单领域接口。最终选择扩展HookProvider理由是在所有与生命周期集成的 Agent 构造参数之间保持统一模式用户实现任一接口只需学习一种组合模型。这正是组合性信条的注释原语是彼此构建的积木。该记录还给出了清晰的选用标准使用简单接口当接口职责单一一两个方法即可表达、无需响应多个生命周期事件、与现有接口的一致性不是优先事项扩展 HookProvider 当能力需要响应多个不同的生命周期事件、用户需要自定义订阅哪些事件或在基类默认回调之外添加回调。组合性的另一层体现在 hooks 系统本身的设计——strands-py/src/strands/hooks/init.py 明确写道提供了一种可组合机制并支持每个事件类型多个订阅者使多个扩展点可以在同一事件上叠加。高层 API 构建在低层 API 之上team/DECISIONS.md 的Provide Both Low-Level and High-Level APIs2026 年 1 月 30 日同样是组合性的体现新特性应当同时提供细粒度控制的低层 API 与带默认值的高层 API。示例是BidiAgentsend/receive是低层原语需要用户自行管理并发、生命周期与事件路由而run方法构建在其上用户只需提供 IO 回调await agent.run(inputs[audio_input], outputs[audio_output, text_output])这正是原语互为积木的直白示范高层 API 复用低层原语而不是另起炉灶。信条四The obvious path is the happy path——显而易见即正确第四条信条主张通过直观命名、有帮助的错误信息与深思熟虑的 API 设计把开发者引向正确模式、避开常见陷阱。它对应决策记录中反复出现的两个核心概念happy path与pit of success成功之坑——让简单路径天然就是正确路径。命名术语只属于它的领域team/DECISIONS.md 的Avoid Overloading Domain Terms in API Naming2026 年 3 月 4 日是命名层面的落地。团队拒绝在 API 中复用已被占用语义的术语Python SDK 使用structured_output_model因为 Pydantic 把自己的 schema 称为 modelTypeScript SDK 选择structuredOutputSchema因为 Zod 的核心术语是 schemaz.object()返回ZodSchema且 Strands SDK 中 model 已经指代 LLM 提供方如BedrockModel、model配置参数文档统一使用 agent loop 而非 event loop因为后者在 Pythonasyncio与 JavaScript/Node.js 中都是已被占用的语言运行时概念。结论是跨语言一致性有价值但不应以牺牲语言内部的清晰度为代价——显而易见的路径首先要求名称不产生歧义。默认值把最常见用法做成默认team/API_BAR_RAISING.md 中API 评审者被要求追问Are the default parameters/behavior the most common?默认参数/行为是否是最常见的If not, why did we choose them?如果不是为什么这样选择。这条评审问题直接服务于 happy path 信条默认值必须引导绝大多数用户走向正确用法。同样在 harness 中harness-py/src/strands_harness/defaults.py 的默认值设计模型、工具、插件、上下文管理策略均给出合理默认让零配置即正确成为可能。语义清晰化Null 与 Undefined 各司其职team/DECISIONS.md 的Null Means Explicit Removal; Undefined Means Apply the Default2026 年 8 月 19 日解决的是最容易产生歧义的传透字段pass-through values如 provider 的params与additional_request_fieldsnull表示显式移除用户刻意将该字段剔除SDK 应将其从请求中删掉既不发送null也不代以 SDK 默认值undefined或缺省字段表示走默认SDK 可自行应用合理默认默认本身也可能是省略该字段Python 中没有undefined缺席的 key 扮演undefined显式None视为null这不改变Agent(modelNone)这类None 即未指定的既有语义。该决策不适用于特性开关MemoryManager(injectionFalse)、sandbox: false这类开关仍以false/False表示显式关闭因为传透字段可能合法携带false如store: false、parallel_tool_calls: false而开关值永远不会被转发两者不能共用同一哨兵值。这一二分让我没指定与我明确不要两种意图各归其位避免用户陷入无法关闭 SDK 管理的默认或每个未指定字段都被当作有意删除的两难。信条五We are accessible to humans and agents——双端可达第五条信条是 Strands 最具辨识度的设计主张SDK 既要让人类理解也要让 AI 编码助手coding assistants同样理解。团队不为人类牺牲精心打磨的 DX同时额外投入确保编码助手能正确帮助用户使用这些接口。面向 Agent 的治理文档这一信条在仓库治理层面最直接的体现是 team/AGENT_GUIDELINES.md——一份专门写给与 Strands 仓库交互的 AI Agent 的指南PR 评审、Issue 分类、文档与自主改进。其核心规则包括Add Value or Stay SilentAgent 没有具体可贡献的内容时不应行动沉默好过噪音Keep It Short输出应简洁用渐进式披露progressive disclosure组织内容Approvals Need Reasoning不批准时必须给出清晰理由批准在初期也应附带简要推理以校准评审者判断Scope Credentials to the Task遵循最小权限原则绝不给 Agent 维护者令牌force-push、删分支、改设置等破坏性操作不可逆Throttle Autonomous Activity自主活动应保持人类可跟进的速度优先在业务时段运行限制同时持有的活跃条目数Own What You Deploy每个自主 Agent 必须有具名的负责人人而非团队负责日志访问、快速禁用流程、错误清理与持续迭代Monitor What Agents DoAgent 的行为应通过既有工具可见PR 历史、评论日志、审计轨迹Maintainers Can Pull the Cord任何维护者都可以立即禁用在其仓库上运行的 Agent无需审批分钟级完成Know That Your Agent Works部署前必须验证 Agent 确实按预期工作质量不达人类标准就应被拒绝。文档末尾附有完整的部署前检查清单涵盖价值、简洁性、最小权限、具名负责人、节流、可见性与即时关停能力——这是对 Agent 友好从口号变为可执行流程的范本。扁平命名空间降低人类与 Agent 双方的检索成本team/DECISIONS.md 的Prefer Flat Namespaces Over Nested Modules2026 年 1 月 16 日同样服务于此信条公共 API 应通过扁平的顶层命名空间暴露常用功能而非要求用户从深层嵌套路径导入。灵感来自 Python 的Flat is better than nestedPEP 20但该原则跨 SDK 语言适用# 推荐从单一模块导出所有 hook 事件 from strands.hooks import MultiAgentInitializedEvent # 避免按用途归类到深层子模块 from strands.hooks.multiagent import MultiAgentInitializedEvent理由与人类与 Agent 双端友好直接相关更少的导入对人类更简单、对 IDE 自动补全与文档更可发现而对编码助手而言扁平导出意味着它更可能在常见位置找到正确符号——当事件名本身已表明分组如MultiAgentInitializedEvent时尤为如此。内部模块组织仍可嵌套以维护代码关键是在公共位置重新导出符号。信条六Embrace common standards——尊重前人拥抱通用标准第六条信条主张尊重已有的事物不重复发明已经被广泛采用或做得更好的东西。在快速演进的 AI 生态中这一条决定了 Strands 对行业标准的依赖策略。依赖演进中的标准team/FEATURE_LIFECYCLE.md 明确指出虽然 SDK 追求稳定但 AI 标准演进迅速。团队偶尔需要依赖仍在演进、未必严格遵循版本化要求的库或标准明确列举的例子包括OTEL GenAI Semantic ConventionOpenTelemetry 生成式 AI 语义约定、MCPModel Context Protocol与 A2AAgent-to-Agent协议。在这些情况下团队优先提供行业标准实现、尽可能贴近规范文档建议生产环境使用此类特性的用户固定到特定 minor 版本作为最佳实践。仓库中确实存在这些标准的实体实现strands-mcp/是 MCP 服务端实现strands-py/src/strands 与 strands-ts/src 中均包含mcp/与a2a/模块如 strands-ts/src/mcptests_integ 目录下还有专门的mcp/与a2a/集成测试目录见 strands-py/tests_integ/mcp 与 strands-py/tests_integ/a2a。兼容性政策承认既有的语义版本约定team/COMPATIBILITY.md 体现了对语义版本semver这一通用标准的尊重明确列出两类不被视为破坏性变更的改动字段转属性Field to Property Conversion将公共可变字段转为带访问器逻辑的属性不算破坏性变更即使新增校验或副作用——因为从调用点看属性访问与直接字段访问在语法和行为上不可区分文档给出了 TypeScript getter/setter 与 Pythonproperty的对照示例如agent.model从字段改为带非空校验的访问器用户代码无需改动联合类型扩展Union Type Extensions向联合类型新增类型或类不算破坏性变更除非联合显式声明不再变化——新的事件类型、结果变体、错误类型与配置选项都会被既有的类型守卫、switch或模式匹配逻辑自然忽略。该政策同时划清了边界它适用于strands-py与strands-ts两个 SDK而 Strands harness 与 Strands CLI 处于 0.x遵循各自独立的版本规则参见 site/src/content/docs/user-guide/harness/versioning.mdx。信条如何驱动日常工程决策API 评审信条是评审标尺team/API_BAR_RAISING.md 定义了确保 SDK API 高质量、一致、面向未来的评审机制其评审问题清单直接以信条为纲是否符合 SDK 信条是否符合 决策记录若以可扩展性为目标什么可定制、什么不可定制抽象层级是否恰当哪些用例未被覆盖为什么默认参数/行为是否是最常见的如果不是为什么评审按变更规模分级最小变更如给不常用方法加参数走常规 PR 评审中等变更如新增客户使用的类先与 API 评审者非正式讨论实质性变更如新增原语或常用抽象需在设计阶段或之后与至少两位 API 评审者开会。PR 通过api/needs-review与api/review-complete标签标记CI 强制api/needs-review的 PR 必须有api/review-complete才能合并。若评审产生了可指导未来设计的决策就沉淀为决策记录——这被视为评审成功的标志。特性生命周期信条决定演进节奏team/FEATURE_LIFECYCLE.md 将简单兼容拥抱标准等信条落实为版本化流程新特性流程设计阶段在 GitHub Discussion 征集意见 → 实现并带完整测试与文档 → 放入strands.experimental子模块 → 收集反馈迭代 → 月度评审 → 验证后于后续 minor 版本稳定化。源码中可见 strands-py/src/strands/experimental 目录其__init__.py明确声明该模块实现实验性特性未来修订中可能在没有通知的情况下变更毕业流程minor 版本 X.Y-1 仅存在于实验模块X.Y 复制进主 SDK 并开始通过warnings.warn()发出弃用警告文档标记非实验并附迁移指南X.Y1 从实验模块移除弃用流程先引入替代方案 → 以deprecated标记旧方式并给出清晰警告与迁移指引 → 新 major 版本移除。Python 侧使用typing_extensions.deprecated非warnings因为后者需 Python 3.13而 SDK 支持 3.10Pay for play 例外门控在新功能之后的、用户不主动采用就完全无感的小型破坏性变更可在 minor 版本内发布——但绝不适用于用户无任何操作代码就坏掉或改变默认行为的情形版本承诺每个 major 版本在下一个 major 发布后至少支持 6 个月含 bug 修复与安全补丁新特性不回溯minor/patch 版本绝不移除特性。这些规则共同确保信条三强调的特性之间互补一致通过统一的实验—稳定化管道实现信条四的 happy path 通过默认即最常见的评审要求实现信条六通过依赖快速演进标准时固定版本的建议实现。六条信条的协同关系与使用建议通观仓库六条信条并非孤立条目而是一个互相支撑的系统Simple at any scale是目标team/COMPLEXITY.md 把它变成 PR 阶段可复现的数字Extensible by design是手段hooks 体系与遍布 Agent 生命周期的扩展点提供了落点Composability约束扩展点之间的关系要求新接口尽量复用既有原语如扩展HookProvider而非另立门户The obvious path is the happy path约束命名、默认值与语义null/undefined 二分把用户导向正确用法We are accessible to humans and agents同时约束 DX 与文档扁平命名空间与 team/AGENT_GUIDELINES.md 分别是两端的落地Embrace common standards决定何时复用行业标准MCP、A2A、OTEL 语义约定、semver而非自造轮子。对贡献者而言team/README.md 给出的工作流值得遵循提出变更前先对照信条检查对齐度查阅 team/DECISIONS.md 看是否已有相关先例涉及公共 API 时走 team/API_BAR_RAISING.md 的评审流程提交 PR 前用npm run complexity或hatch run complexity自查复杂度标签。若你的贡献产生了能指导未来工作的新决策按 team/README.md 的建议将其补充进决策记录——这正是信条体系自我演进的方式。无论你是人类开发者还是 AI 编码助手这套信条都提供了一个一致的评判框架当两个方案看似同样合理时选最契合信条的那个。赞分享人工智能大模型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点击查看免费下载相关推荐Saber与Vue 3兼容性分析Composition API在Saber中的使用实践Saber与Vue 3兼容性分析Composition API在Saber中的使用实践 Saber作为一款基于Vue.js的静态站点生成工具为开发者提供了高开发工具版本控制CLIbravado单元测试指南用BravadoResponseMock模拟响应让测试告别真实网络请求bravado单元测试指南用BravadoResponseMock模拟响应让测试告别真实网络请求 Bravado 是一个用于 Swagger / OpenA人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务Moby 设计原则详解14 条容器引擎开发准则及其在源码中的落地证据Moby 设计原则详解14 条容器引擎开发准则及其在源码中的落地证据 本文以 MobyDocker 引擎的开源核心仓库中的 project/PRINCIP云原生容器运行时虚拟化容器编排上一篇Vue流程图组件Flowchart-Vue终极可视化开发指南下一篇Node.js v22.14.0 JodLTS发布全解读TypeScript 执行增强、process.ref/unref 与 test_runner 快照新 API创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
