strands-py 移植指南:从 TypeScript SDK 到 Python SDK 的逐条映射规则与实现解析

发布时间:2026/11/22 23:16:25

strands-py 移植指南:从 TypeScript SDK 到 Python 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点击查看免费下载本文基于 strands-py/docs/PORTING.md 整理Strands 以 TypeScript SDKstrands-ts为规范canonical实现Python SDKstrands-py以复刻 TypeScript 行为、用地道 Python 表达为移植原则。文章逐条展开该文档定义的构造级映射规则construct-to-construct mappings并辅以strands-py源码与测试中的实际实现佐证帮助你在为 strands-py 贡献功能时准确完成跨语言移植。移植总则TypeScript 是规范Python 是复刻移植的核心立场只有一句话TypeScript SDK 是规范canonical一个移植port就是复现 TypeScript 的行为并以地道的 Python 表达出来。strands-py与strands-ts属于同一仓库下的双实现 SDK见 strands-py 与 strands-ts两者的对外能力、事件模型、工具系统与模型接口必须保持行为一致这正是 PORTING.md 存在的原因。PORTING.md 只收录构造到构造construct-to-construct的映射规则即一个 TypeScript 语法结构应该翻译成哪种 Python 结构至于通用语言惯用法例如循环、异常处理、命名习惯默认读者已经掌握文档不赘述。此外凡是因为 Python或当前代码库限制而不得不做的让步统一收敛在 Workarounds 一节中——这类映射并非自由选择而是受既有代码约束的结果。下面按文档顺序逐条展开。一个 TypeScriptinterface按角色映射为三种 Python 形态之一TypeScript 的interface一个结构往往身兼数职而 Python 用不同的构造表达不同角色。因此映射规则取决于该 interface是拿来干什么的1. 行为契约含方法成员→Protocol如果 interface 只声明了方法、描述一段行为契约就映射为 Python 的Protocol隐式实现不需要显式继承# interface Extractor { extract() } - class Extractor(Protocol): def extract(self) - ...: ...strands-py中大量使用此模式。例如 agent/base.py 中的AgentBase(Protocol)定义了所有 Agent 实现必须满足的最小契约invoke_async、stream_async等types.py 中的ContextStrategy(Protocol)声明了name属性与async def apply(context) - bool方法任何实现了这两个成员的对象都能作为上下文削减策略传入管线无需继承任何基类。2. 任意数据形态纯字段、构造后传递→dataclass如果 interface 只是承载数据字段被构造出来、传来传去映射为dataclass其中readonly字段对应dataclass(frozenTrue)# interface ExtractionResult { readonly text: string; ... } - dataclass(frozenTrue) class ExtractionResult: text: str3. 纯构造配置解构一次用于建对象、不作为整体保留→ 显式__init__参数如果 interface 只是构造参数被解构一次用来创建别的对象之后不再整体保留则不引入任何类型直接写成__init__的显式参数字段变成实例属性。必填字段尤其是必填回调用位置参数可选字段放在裸*,之后强制 keyword-only# interface ContextInjectorConfig { render_content: ...; name?: ...; trigger?: ... } - class ContextInjector: def __init__(self, render_content, *, nameNone, triggerNone): self.render_content render_content self.name name self.trigger trigger这样既避免了为一次性配置创建冗余数据类又通过*,让可选参数无法被位置误传语义与 TypeScript 的 destructuring 可选属性完全对齐。带字符串标签的对象字面量联合成员 → frozen dataclass当一个联合union成员是带字符串标签的 TypeScript 对象字面量时映射为 frozen dataclass标签用非 init 默认字段表示# type Deny { type: deny; reason: string } - dataclass(frozenTrue) class Deny: type: str field(defaultdeny, initFalse) reason: str 关键映射点readonly→frozenTrue字面量type:标签 →field(default..., initFalse)运行时存在该字段但不是构造参数工厂函数function deny(reason): Deny坍缩进构造函数deny(x)变成Deny(reasonx)联合别名直接照搬type X A | B→X A | B下游按标签分发switch (action.type)→isinstance判断isinstance(action, Deny)。这个模式在strands-py的干预intervention系统中得到完整落地。interventions/actions.py 中定义了Proceed、Deny、Guide、Confirm、Transform五个 frozen dataclass每个都带有type: str field(default..., initFalse)标签字段并在文件末尾聚合为联合别名InterventionAction Proceed | Deny | Guide | Confirm | Transformactions.py#L117。分发端同样印证了isinstance取代switch的规则interventions/registry.py 中_apply_before_invocation用一连串if isinstance(action, Deny) / elif isinstance(action, Guide) / elif isinstance(action, Transform) / elif isinstance(action, Proceed)完成事件处置Deny 直接设置event.cancel fDENIED: {action.reason}并短路后续 handler与 actions.py 文档字符串中给出的兼容性矩阵一一对应。tool({...})对象字面量 →tool装饰的函数TypeScript SDK 用tool({...})对象字面量声明工具Python 端则用tool装饰一个函数。对象字面量的每个字段都落到函数的一个特定位置TypeScripttool({...})字段Pythontool函数name: summarize_context函数名def summarize_contextdescription: ...函数 docstringinputSchema: z.object({ keepRecent: z.number().int().optional() })类型化参数keep_recent: int \| None None每个字段的.describe(...)docstring 中对应的Args:条目callback: (input, context) {...}函数体context第二个回调参数tool(contextTrue)加上tool_context: ToolContext参数也就是说声明式 schema 及其描述全部坍缩进函数签名 Google 风格 docstring不再有单独 schema 对象。源码实现印证了这一设计的全部细节。tools/decorator.py 是整个映射的落地处docstring 解析FunctionToolMetadata在构造时用docstring_parser.parse(inspect.getdoc(func))解析 docstringdecorator.py#L109-L114Args:条目被提取为param_descriptions字典描述即 description_extract_description_from_docstring会剔除Args:段、保留Returns:/Raises:/Examples:等段作为工具描述decorator.py#L235-L261签名即 inputSchema_create_input_model遍历函数签名把类型注解含Annotated元数据、处理 PEP 563 字符串注解与默认值合成为 Pydantic 模型作为输入校验 schemadecorator.py#L192-L233context 注入tool(contextTrue)默认把tool_context作为注入参数名tool(contextmy_name)可改名decorator.py#L822-L829。_validate_signature会在函数签名中出现ToolContext却未声明context时抛出ValueError(tool(context) must be set if passing in ToolContext param)decorator.py#L177-L190_is_special_parameter则把self、cls、agent与配置的 context 参数排除出输入校验模型decorator.py#L434-L454。一个同时演示签名映射与 context 映射的官方示例decorator.py#L813-L819tool(namecustom_tool, descriptionA tool with a custom name and description, contextTrue) def my_tool(name: str, count: int 1, tool_context: ToolContext) - str: tool_id tool_context[tool_use][toolUseId] return fProcessed {name} {count} times with tool ID {tool_id}ToolContext与ToolSpec类型定义位于 types/tools.pyToolSpec含name、description、inputSchema、可选outputSchema与 MCPannotations这些键与 TypeScript 侧一致。相应的校验测试可见 tests/strands/tools/test_decorator.py例如tool(context)缺失即报错的用例在 test_decorator.py#L1839。外部协议线键wire keys原样保留不做大小写转换凡是属于外部 API 或协议、不属于 SDK 自有表面的键必须逐字符复制不能重新改大小写re-case。max_tokens、input_tokens、tool_use、stop_reason都是第三方拼写照抄即可。这条规则同样延伸到在 docstring 与注释中提及这些键的文本——注释里写键名时也要保持第三方拼写便于按协议文档检索与对照。这一点在源码中有直接体现strands-py的工具类型定义文件开头明确写着These types are modeled after the Bedrock APItypes/tools.py#L1-L6因此toolUseId、inputTokens等 Bedrock 拼写保留原样模型层返回的流式事件与停止原因也使用stop_reason这类第三方拼写。Workarounds兼容性让步与桥接方案以下两条是受 Python或现有代码库限制而做出的让步——与前面的规则不同如果是从头移植你不会这样设计但既然要复用既有代码与生态就只能这样桥接。Python 表面是异步的用工作线程桥接仅同步客户端strands-py对外暴露的方法始终是异步生成器async def stream(...) - AsyncGenerator[...]。底层客户端具体怎么驱动取决于它提供什么能力有异步客户端可用例如 Anthropic 的AsyncAnthropic直接使用配合async with/async for。当 TypeScript API 同时暴露同步与异步两种形态时Python 移植取异步形态。源码证据models/anthropic.py 用anthropic.AsyncAnthropic(**client_args)构造客户端stream()内部async with self.client.messages.stream(**request) as stream:加async for event in stream:消费事件anthropic.py#L936-L944。仅有同步客户端boto3 没有异步客户端保持异步生成器的表面但把阻塞调用放进asyncio.to_thread通过asyncio.Queue加一个回调把事件回传给事件循环并用哨兵值None表示结束。阻塞工作绝不能跑在事件循环线程上。这条规则在 Bedrock 模型中有完整实现。models/bedrock.py 中工作线程侧_stream在独立线程中调用 boto3 的converse_stream/converse注释明确说明This method operates in a separate thread to avoid blocking the async event loop见 bedrock.py#L1419-L1422桥接侧stream()中定义callback(event)用loop.call_soon_threadsafe(queue.put_nowait, event)把事件从工作线程安全投递到事件循环bedrock.py#L1362-L1368asyncio.Queue[StreamEvent | None]承载事件None即结束哨兵消费侧_next_stream_event负责取下一个事件若取消先到则放弃等待并用asyncio.wait(..., return_whenFIRST_COMPLETED)在queue.get()与取消轮询 Future 之间竞争bedrock.py#L99-L133主循环读到None即退出bedrock.py#L1387-L1401。同一桥接手法也用在其他同步后端上例如 storage/s3_storage.py 中put_object/get_object/delete_object全部经asyncio.to_thread包装。共享类型按目标侧既有名称查找绝不改名异常类、内容块类型、流事件类型在两侧各自集中在中央 types 模块里。当源码引用其中一个时使用目标侧已有的名称不要转换标识符。没有统一的后缀规则ProviderTokenCountError在两种语言中保持这个精确名称而ContextWindowOverflowError在 Python 侧叫ContextWindowOverflowException——因为各侧本来就各自这样拼写。逐个对照实际情况解析而不是机械地套用Error一律改名Exception的规则。这与仓库现状完全吻合TypeScript 侧中央错误模块是 strands-ts/src/errors.ts其中export class ProviderTokenCountErrorerrors.ts#L181与export class ContextWindowOverflowErrorerrors.ts#L39并存Python 侧中央错误模块是 strands-py/src/strands/types/exceptions.pyProviderTokenCountError同名保留exceptions.py#L89而上下文溢出异常拼写为ContextWindowOverflowExceptionexceptions.py#L41。即便同名的异常其语义也保持对齐ProviderTokenCountError在两侧都作为模型提供方原生 token 计数 API 失败的内部控制流使用捕获后回退到启发式估算。Python 侧 Bedrock 实现中raise ProviderTokenCountError(Bedrock count_tokens returned None for inputTokens)后由except Exception兜底并return await super().count_tokens(...)回退估算bedrock.py#L1287-L1324与 errors.ts#L175-L186 的文档注释所述机制一一对应。移植对照速查表与落地清单TypeScript 结构Python 目标结构strands-py 落地位置示例interface行为契约Protocol隐式实现agent/base.py、_context_manager/types.pyinterface数据形态dataclassfrozenTrue对应readonlyinterventions/actions.pyinterface纯构造配置显式__init__参数可选参数置于*,后—带标签对象字面量联合成员frozen dataclass field(initFalse)标签字段interventions/actions.pyDenyswitch (x.type)分发isinstance(x, ...)判断interventions/registry.pytool({...})对象字面量tool装饰函数docstring 即 schematools/decorator.py外部协议 wire keys逐字符照抄不改大小写types/tools.py仅同步客户端asyncio.to_threadasyncio.Queue 回调 None哨兵models/bedrock.py共享类型名按目标侧既有名称解析不统一改名types/exceptions.py 对照 strands-ts/src/errors.ts移植一份功能时可以按此清单逐项核对先判定每个 interface 的角色选对 Python 形态再处理联合成员与工具对象随后把 wire keys 原样保真最后检查是否命中两条 Workarounds同步客户端桥接、共享类型名称解析。除此之外参考 STYLE_GUIDE.md 与 TESTING.md 保持代码风格与测试规范与现有strands-py模块一致即可让移植结果既行为等价、又读起来像原生 Python。赞分享人工智能大模型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点击查看免费下载相关推荐Strands TypeScript SDK 依赖治理指南peerDependencies 边界规则与 package-lock 可复现构建Strands TypeScript SDK 依赖治理指南peerDependencies 边界规则与 package lock 可复现构建 导读 本文基于人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务Strands TypeScript SDK 开发指南从编码规范到模型 Provider 的完整实践Strands TypeScript SDK 开发指南从编码规范到模型 Provider 的完整实践 本文是面向在 Strands Agents 仓库中开发人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务Strands SDK 模型路由Model Routing设计解析从设计文档到 Python SDK 落地实现Strands SDK 模型路由Model Routing设计解析从设计文档到 Python SDK 落地实现 模型路由Model Routing是人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务上一篇如何永久备份微信聊天记录免费开源工具WeChatMsg终极使用指南下一篇CANN/catlass INT8转FP16反量化创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/11/20 1:59:57

【GitHub项目实战】DINet 实现音频驱动的数字人口型同步

视频对口型生成技术已成为数字人内容合成中的关键环节。DINet 项目以逐步细化的生成架构和同步感知训练策略,在口型同步度与视觉真实感之间找到良好平衡,适用于低资源环境下的高质量人脸驱动场景。 围绕 DINet 的完整训练与推理流程,本文解析其环境搭建、数据预处理、模型训…

2026/11/23 0:06:39

电工证2级有用嘛,别再乱花钱考错了,在哪考才是关键

电工证2级有用嘛,别再乱花钱考错了,在哪考才是关键 怕考不过白交培训费?我见过太多人拿着假证去工地,结果被查出问题,不仅罚款,连工作都丢了。电工证2级有用嘛?这个问题我见过太多人问,其实关键不是有没有用,而是你考对了没有, 在哪考…

2026/11/23 0:06:39

顺德电工证查询:学历不高怕报不上名?看看真实经历怎么说

顺德电工证查询:学历不高怕报不上名?看看真实经历怎么说 我以前也担心自己学历不够,根本不敢报名考电工证。后来才知道, 顺德电工证查询 的条件其实没那么苛刻,很多人像我一样,学历不高也能顺利通过。今天我就从 真实经历…

2026/11/23 0:06:39

电工证钳工证含金量网上查询怎么查最靠谱

电工证钳工证含金量网上查询怎么查最靠谱 你急需特种作业证才能上岗找工作,可现在网上查询一堆信息真假难辨,电工证钳工证含金量到底怎么样,有没有必要考?别急,今天从商丘转岗从业者的角度,带你看看这两个证的实际价值、报考门槛和备考干货,助你一步到…

2026/11/23 0:06:39

先拿证再付款的电工证内部消息:证书过期了不知道怎么复审延期

先拿证再付款的电工证内部消息:证书过期了不知道怎么复审延期 证书过期了不知道怎么复审延期?这是很多持证人头疼的问题,特别是那些选择“先拿证再付款”的电工证持有者,往往因为信息不对称,错过复审时间,导致证书失效,影响工作和项目进展。今天我以信…

2026/11/23 0:01:39

中国怎么考国际电工证官方报名入口在哪

中国怎么考国际电工证官方报名入口在哪 找工作必须特种作业证,现在电工证已经成了很多蓝领行业的“硬门槛”,尤其是想要在大型工地、电力公司、建筑单位等地方稳定就业,没有电工证根本走不进门槛。如果你也在为怎么考国际电工证发愁,那这篇就告诉你…

2026/11/22 0:09:40

高压电工证还能年审吗良心建议来了,学历不高也能考!

高压电工证还能年审吗良心建议来了,学历不高也能考! 你是不是也担心,自己学历不高,根本报不上高压电工证?其实不然,现在政策已经非常明确, 高压电工证还能年审 ,而且只要符合条件, 学历不是门槛 , 良心建议…

2026/11/22 0:09:40

吴江的电工证免费培训怎么报名?官方报名入口全解析

吴江的电工证免费培训怎么报名?官方报名入口全解析 你急需特种作业证才能上岗找工作,但不知道从哪里下手?别急,现在就给你讲明白【吴江的电工证免费培训】到底怎么操作,以及怎么通过 官方报名入口…

2026/11/22 0:09:40

电工证复审肃州区的真实经历:别被中介坑了,自己搞定更靠谱

电工证复审肃州区的真实经历:别被中介坑了,自己搞定更靠谱 不知道去哪报名怕被中介坑?这几乎是每个需要办理或复审电工证的人的真实经历。尤其在肃州区,信息不透明、流程复杂、中介收费高又不靠谱,让很多电工从业者感到头疼。作为一个在应急管理和特种作…

2026/11/23 0:01:38

南宁哪里可以学电工证值不值得考?怕被中介坑?看这篇就够了

南宁哪里可以学电工证值不值得考?怕被中介坑?看这篇就够了 不知道去哪报名怕被中介坑?南宁哪里可以学电工证值不值得考?这是很多想考电工证的朋友最关心的问题。现实中,不少人在选择培训机构时被各种五花八门的广告信息搞得晕头转向,甚至被坑了钱还没拿…

2026/11/23 0:01:38

建设局特种工证怎么查全国通用的复审流程

建设局特种工证怎么查全国通用的复审流程 证书过期了不知道怎么复审延期,这是很多特种作业从业者常遇到的问题。尤其是在洛阳涧西区从事水利工程工作的你,特种作业操作证不仅是上岗的“通行证”,更是保障安全作业的法律底线。如果操作证过期了,不仅影响工…

2026/11/23 0:01:38

电工证跨考政策值不值得考?学历不高也能考的真相

电工证跨考政策值不值得考?学历不高也能考的真相 你是不是也觉得学历不够,报电工证怕被拒?别急,国家安全生产考试网明文规定, 电工证跨考政策 对学历门槛没有硬性限制,只要你年满18岁,身体健康,能通过实操考试,就能报考。关键是, 值不值得考…

2026/11/22 9:39:14

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/22 5:39:03

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑