Harness SDK Python v1.17.0 版本技术解析：MCP 工具超时、LiteLLM 流式校验与多智能体可靠性改进

人工智能大模型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点击查看免费下载本文基于仓库中的 Python SDK v1.17.0 变更日志2025-11-18 发布展开逐一拆解该版本 4 项功能修复与 1 项行为调整的底层实现。读完你将掌握如何为 MCP 工具设置调用超时、LiteLLM 模型stream参数的合法取值边界、事件循环对缺失用量/指标数据的容错机制、Swarm 交接节点时序修正的原理以及 A2A 协议二进制内容块的 base64 解码链路并能在自己的 Agent 工程中直接应用这些改进。Harness SDK 的 Python 发行版在 v1.17.0 中围绕工具调用可控性、模型流式配置校验、事件流健壮性、多智能体协调与跨协议内容转换五个方向做了集中打磨。虽然单个变更都很克制但它们共同指向生产级 Agent 运行时最常踩坑的几类问题远程工具卡死、非法流式参数静默失败、遥测数据缺失导致下游崩溃、Swarm 交接时序错乱以及 A2A 文件内容块无法被本地模型正确消费。本文结合 strands-py 源码逐一验证这些变更的实际效果。一、版本概览维度内容SDKsdkPython 语言包版本号1.17.0发布日期2025-11-18变更总数5 项1 feat 3 fix 1 other均非破坏性变更新增贡献者AnirudhKonduruPR #11845 项变更的领域分布为MCP 工具层MCPAgentTool超时、模型层LiteLLMstream校验、事件循环/遥测层MetadataEvent容错、多智能体层Swarm 交接时序、A2A 协议层base64 字节内容解码。下文按变更类型逐一深入。二、新功能为 MCPAgentTool 设置调用超时feat #1184这是 v1.17.0 唯一的新增功能由新贡献者 AnirudhKonduru 提交。它允许在创建MCPAgentTool时传入timeout参数为 MCP 工具执行增加超时边界。2.1 API 形态与源码实现在 mcp_agent_tool.py 中构造签名新增了timeout: timedelta | None None参数def __init__( self, mcp_tool: MCPTool, mcp_client: MCPClient, name_override: str | None None, timeout: timedelta | None None, ) - None:该超时在工具流式执行时通过mcp_client.call_tool_async(..., read_timeout_secondsself.timeout, ...)传入底层连接见 mcp_agent_tool.py最终作用于 MCP 会话的call_tool调用。2.2 使用方式与语义边界from datetime import timedelta from strands.tools.mcp import MCPClient client MCPClient(urlhttp://localhost:8000/mcp) with client as c: # 通过 list_tools_sync 拿到的工具是 MCPAgentTool可直接替换 ...timeout的类型是datetime.timedelta而非秒数默认None表示不设置超时。需要特别注意的是官方文档字符串中明确标注的语义边界On the mcp 2.x line, the timeout bounds each request round of a multi round-trip tool call rather than the call as a whole.即在 MCP 2.x 协议线上timeout约束的是多轮往返工具调用中的每一轮请求而不是整个工具调用的总时长。这一点在 mcp_client.py 的_create_call_tool_coroutine文档字符串中也有同样的说明——在使用 task-augmented 执行时MCP Tasks该超时则约束整个任务含轮询而每个生命周期请求使用tasks_config.request_timeout。因此规划超时值时应结合服务器端工具的实际往返轮次来评估避免误以为它是绝对总时限。三、修复LiteLLM 增加 stream 参数校验fix #11833.1 问题背景LiteLLM 模型配置中stream是一个布尔开关决定请求走流式streaming还是非流式non-streaming路径。此前若在配置中传入非布尔值如字符串true会在请求阶段才暴露异常难以定位。v1.17.0 在模型构造与配置更新阶段提前拦截非法值。3.2 校验位置与配置字段在 litellm.py 中LiteLLMConfig明确声明了配置字段及其默认行为class LiteLLMConfig(BaseModelConfig, totalFalse): model_id: str # 例如 openai/gpt-4o、anthropic/claude-3-sonnet params: dict[str, Any] | None stream: bool # 是否使用流式默认 True cache_config: CacheConfig | Nonestream被声明为bool类型文档字符串标注Whether to use streaming. Defaults to True.默认True。LiteLLMModel.__init__与update_config都会先调用validate_config_keys(model_config, self.LiteLLMConfig)做键与类型的校验见 litellm.py从而保证stream在进入请求构建阶段前就是合法布尔值。3.3 流式/非流式请求路径校验之后stream()方法会根据request[stream]的最终取值分派执行路径见 litellm.pyis_streaming request[stream] if is_streaming: async for chunk in self._handle_streaming_response(litellm_request): yield chunk else: async for chunk in self._handle_non_streaming_response(litellm_request): yield chunk代码注释说明format_request会从顶层stream配置与历史遗留的params{stream: ...}路径解析出有效值并记录在请求上两种写法都统一收敛到request[stream]。这保证了顶层配置与params 内联两种风格的行为一致而 v1.17.0 的校验则让非法取值在源头即被拒绝。四、修复MetadataEvent 缺失 usage 与 metrics 时的容错fix #11874.1 问题背景MetadataEvent在事件流中承载模型的用量usage与延迟指标metrics。MetadataEvent类型声明为totalFalse即所有字段都是可选的——某些自定义模型提供方可能只回传 usage 而不回传 metrics或两者皆缺。此前若直接读取这些可选字段可能触发 KeyError 或类型错误进而污染事件循环与遥测上报。4.2 默认值兜底实现修复集中在 event_loop/streaming.py 的extract_usage_metricsusage Usage(**{inputTokens: 0, outputTokens: 0, totalTokens: 0, **event.get(usage, {})}) metrics Metrics(**{latencyMs: 0, **event.get(metrics, {})}) if time_to_first_byte_ms: metrics[timeToFirstByteMs] time_to_first_byte_ms由于Usage与Metrics类型中的字段是必填的Required而MetadataEvent的字段可选函数采用先填默认值、再用事件中的实际值覆盖的策略usage缺失时补全inputTokens/outputTokens/totalTokens 0metrics缺失时补latencyMs 0若提供了time_to_first_byte_ms则额外填充timeToFirstByteMs。这一兜底保证了事件循环对不完整遥测数据零崩溃。4.3 下游消费链process_stream在处理metadatachunk 时调用上述函数见 streaming.py并把解析结果写入ModelStopReason。随后事件循环在 event_loop.py 将usage与metrics附加到 assistant 消息的metadata字段供 hooks、事件订阅与状态持久化统一消费会话恢复时也依赖该 metadata 做增量 token 估算见 event_loop.py。所以这次容错修复实质上是整条遥测与上下文估算链路的稳定性保障。五、行为调整Swarm 仅在当前节点停止后切换交接节点other #11475.1 问题背景Swarm自组织协作式多智能体团队中一个节点在运行期间可能声明要交接handoff给下一个节点。此前交接切换的触发时机不够严谨可能出现节点尚未停止、交接已生效的时序错乱尤其是在节点执行被回滚rollback的场景下交接状态与节点实际命运不一致。5.2 交接状态跟踪实现在 swarm.py 中新增了_InflightTurn数据类用于跟踪进行中的节点轮次dataclass class _InflightTurn: handoff_node: SwarmNode | None handoff_message: str | None shared_context: dict[str, dict[str, Any]] outcome: Literal[open, committed, rolled_back] open其文档字符串揭示了设计意图checkpoint 会在执行循环应用交接转换之前触发因此仅凭EXECUTING状态无法区分节点已提交交接还是节点仅继承了待交接状态。outcome字段由执行循环在轮次命运确定时写入被回滚的轮次仍会保留记录以便下一次 checkpoint 依然知道该节点欠着工作。这套机制让交接切换严格绑定在当前节点停止之后从而消除半途交接导致的竞态。5.3 相关终止条件参考交接只是 Swarm 运行约束的一环swarm.py 的should_continue还同时校验max_handoffs默认 20、max_iterations默认 20、execution_timeout默认 900 秒以及重复交接检测repetitive_handoff_detection_window与repetitive_handoff_min_unique_agents默认关闭。理解 v1.17.0 的时序修正建议连同这些终止条件一起配置以构建稳定的多智能体工作流。六、修复A2A 字节数据先 base64 解码再放入 ContentBlocksfix #11956.1 问题背景A2AAgent2Agent协议中文件类 PartFilePart的字节内容以 base64 编码字符串传输。若将这种编码串直接塞进本地ContentBlock的bytes字段下游模型提供方如多模态图像/视频推理会拿到错误字节导致内容解析失败或乱码。v1.17.0 在内容转换入口统一做了 base64 解码。6.2 解码链路修复位于 multiagent/a2a/executor.py 的_convert_a2a_parts_to_content_blocks。对FilePart的处理逻辑为bytes_data getattr(file_obj, bytes, None) uri_data getattr(file_obj, uri, None) if bytes_data: # A2A bytes are always base64-encoded strings decoded_bytes base64.b64decode(bytes_data) ...解码后的decoded_bytes根据 MIME 类型派生的file_type分别构建ImageContent、VideoContent或DocumentContent且一律使用bytes形式的 sourceImageSource(bytes...)等。若解码失败如数据损坏会抛出带文件名的ValueError便于定位。FileWithUri分支则走 URI 引用路径不涉及解码。6.3 联动说明该修复与仓库中其他 base64 处理一脉相承例如上下文管理器的 retrieval_tool.py 同样对媒体源做base64.b64decode。在 A2A 与本地多模态模型联调时务必确保内容块里的bytes是已解码的原始字节这正是本次变更保证的一致性。七、升级与验证建议7.1 升级路径Python SDK 通过strands-agents包分发PyPI。升级后在既有代码中注意三点MCP 工具超时MCPAgentTool的新参数为可选不传timeout时行为与旧版完全一致无破坏性LiteLLM 配置stream必须传布尔值True/False字符串、整数等非法类型会在构造时被validate_config_keys拒绝Swarm 行为交接切换时机更严格依赖旧时序的业务代码如依赖节点运行中即交接的场景需调整为等待节点停止后再处理交接结果。7.2 验证要点对 MCP 工具设置timeouttimedelta(seconds30)后用会长时间挂起的工具验证超时兜底是否按每轮请求而非整体调用生效给 LiteLLM 传入streamtrue字符串确认构造阶段即抛校验错误用不含metrics的自定义模型流验证事件循环不抛异常且ModelStopReason中的usage/metrics有零值兜底在 Swarm 中启用 checkpoint 并制造回滚场景确认交接只发生在节点停止之后通过 A2A 接收带FilePart.bytes的响应确认本地ContentBlock.bytes已是解码后的原始字节能被多模态模型直接消费。7.3 源码索引变更关键实现文件MCPAgentTool 超时mcp_agent_tool.py、mcp_client.pyLiteLLM stream 校验litellm.pyMetadataEvent 容错streaming.py、event_loop.pySwarm 交接时序swarm.pyA2A base64 解码executor.py总体来看v1.17.0 是一版典型的可靠性加固发布没有激进的新架构而是把生产环境中反复出现的边界问题逐个封堵。对于正在把 Harness SDK Python 用于线上 Agent 服务的团队这版的 MCP 超时能力与遥测容错最值得立即采纳。赞分享人工智能大模型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 Agents Python SDK v0.1.6 深度解析Bedrock 非流式模式、工具名校验与可观测性修复Strands Agents Python SDK v0.1.6 深度解析Bedrock 非流式模式、工具名校验与可观测性修复 Strands Agents人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务【特别体验】 PDFMathTranslate v1.9.1.rc1 版本技术解析与改进亮点【特别体验】 PDFMathTranslate v1.9.1.rc1 版本技术解析与改进亮点 引言学术翻译的技术演进 还在为阅读英文PDF学术论文而头疼吗公AI 应用NLPCLICherry Studio 多模态 AI 图像处理实战三个场景快速跑通识别、生成与编辑Cherry Studio 多模态 AI 图像处理实战三个场景快速跑通识别、生成与编辑 手头有一批本地图片想交给 AI 处理又不想把文件传到别人的服务器CAI 应用大模型桌面应用本地部署RAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考