企业官网建设流程全解析

• 人工智能
• 大模型
• AI Agent
• Agent 框架
• 多智能体
• 工具调用
• MCP 服务

本文基于 Strands Python SDK（strands-py）v1.42.0 的官方变更记录，结合 monorepo 仓库中的源码实现，逐一解读该版本引入的新特性与修复：S3SessionManager新增endpoint_url参数以支持 MinIO/LocalStack 等 S3 兼容后端、Gemini 模型将缓存 token 接入 usage 元数据、A2A 服务器新增agent_card_url可定制 AgentCard、双向流式（bidi）新增Limits支持，以及MetricsClient单例线程安全化等。读完本文，你将掌握这些 API 的正确用法、它们对应的源码位置，以及如何在自己的 Agent 项目中落地这些能力。

版本概览

v1.42.0 是 strands-agents/sdk-python 并入 monorepo 收敛过程中的一个里程碑版本，发布于 2026-06-01。该版本包含约 30 项变更，全部为非破坏性（breaking: false），横跨模型（model）、工具（tool）、多智能体（multiagent）、A2A、遥测（telemetry）、双向流式（bidirectional-streaming）、MCP 等多个领域，并迎来了 6 位新贡献者（tealgreen0503、yatszhash、yoppi、gtholpadi、he-yufeng、yananym）。

从变更类型分布看，本版本以feat和fix为主，另有大量chore/docs/other类仓库治理工作（如合并 strands-agents/docs 与 sdk-typescript 进 monorepo、同步 README、更新 CI 权限等），这些为后续 SDK 的统一演进打好了基础。

核心新特性一：S3SessionManager 支持自定义 endpoint_url

新增参数与典型场景

本版本为 S3SessionManager 新增了endpoint_url构造参数（PR #1934，作者 tealgreen0503）。该参数专门用于两类场景：

• S3 兼容的本地/自托管存储后端：如 MinIO、LocalStack；
• VPC 端点（PrivateLink）：通过 AWS PrivateLink 访问 S3 时，需要将流量导向 VPC endpoint 的 URL。

from strands.session.s3_session_manager import S3SessionManager # 连接 MinIO / LocalStack 等 S3 兼容后端 session_manager = S3SessionManager( session_id="session-123", bucket="my-agent-bucket", prefix="agents", region_name="us-east-1", endpoint_url="http://localhost:9000", # MinIO 默认端口 )

源码实现细节

从源码看，endpoint_url与boto_session、boto_client_config、region_name一起被透传到 boto3 客户端创建处（s3_session_manager.py#L48-L91）：

session = boto_session or boto3.Session(region_name=region_name) # ... self.client = session.client(service_name="s3", config=client_config, endpoint_url=endpoint_url)

值得注意的实现细节包括：

• User-Agent 注入：构造客户端时，SDK 会自动向 boto3 请求追加strands-agents标识。若用户传入了自定义boto_client_config，SDK 会通过merge()保留原有user_agent_extra并追加标识（L79-L88），便于服务端识别流量来源。
• 与 Bedrock 模型的一致设计：同版本中 bedrock.py 的 Bedrock 模型也接受endpoint_url（用于 VPC PrivateLink 访问 Bedrock Runtime），两个模块采用了完全相同的参数语义，形成一致的自定义端点模式。
• 存储结构：S3SessionManager在 bucket 下按session_<id>/agents/agent_<id>/messages/message_<n>.json的层级组织对象（见类 docstring），prefix参数可置于最前用于多租户隔离。

作为RepositorySessionManager与SessionRepository的双重实现，它完整支持会话、Agent、消息的增删改查与分页列举（list_messages支持limit/offset，且读取消息时采用ThreadPoolExecutor并行加载、按索引保持顺序返回，见 L313-L348）。

核心新特性二：Gemini 模型接入缓存 token 元数据

变更内容

PR #2287（作者 yatszhash）为 Gemini 模型打通了缓存 token（cached content token）计量，使其能够透传到事件流的 metadata usage 中；PR #2353（作者 he-yufeng）则处理了safety-blocked metadata（内容被安全策略拦截时的元数据情况）。

源码实现

在 models/gemini.py#L482-L514 中，Gemini 的metadata事件处理逻辑会解析usage_metadata并构造统一的Usage结构：

usage_data: Usage = { "inputTokens": input_tokens, "outputTokens": ( candidates_tokens + thoughts_tokens if candidates_tokens is not None else max(0, total_tokens - input_tokens) ), "totalTokens": total_tokens, } if cached := usage_metadata.cached_content_token_count: usage_data["cacheReadInputTokens"] = cached

这里的核心工程考量是token 桶口径：Gemini 的total_token_count将 prompt、candidates、tool_use_prompt、thoughts 四类 token 折叠在一起，而tool_use_prompt属于输入、thoughts按输出计费，直接做减法会错配。因此实现采用"各桶自加"策略：输入 = prompt + tool_use_prompt，输出 = candidates + thoughts，仅在 candidates 缺失时才回退到减法（L484-L502）。新增的cacheReadInputTokens字段则让上层遥测（见下文MetricsClient的event_loop_cache_read_input_tokens直方图）能精确观测缓存命中带来的成本节省。

Gemini 流式转换器还负责把 Gemini 的message_stop原因映射为 SDK 标准 stop reason：TOOL_USE → tool_use、MAX_TOKENS → max_tokens、SAFETY → guardrail_intervened（L471-L480），这正是"处理 safety-blocked metadata"的具体落点。

配套：vLLM reasoning deltas

同版本中，OpenAI 兼容模型层新增了读取 vLLM reasoning deltas（PR #2354）的能力。结合map_mcp_content_to_tool_result_content（PR #2370）将 MCP content 转 tool result 的方法提升为公共 API，本版本在"多 provider 输出归一化"方向上前进了一步——vLLM 部署下推理内容（reasoning）delta 也能被正确消费。

核心新特性三：A2A 服务器可定制 AgentCard 中的 URL

变更内容

PR #2003（作者 waitasecant）为 A2AServer 新增了agent_card_url属性，用于覆盖 AgentCard 中公布的 URL。

源码实现

A2A（Agent-to-Agent）协议要求每个 Agent 通过AgentCard对外公布自身地址。A2AServer的构造参数host（默认127.0.0.1）、port（默认9000）、http_url用于确定服务可达地址；而新加的agent_card_url属性提供了更灵活的覆盖手段：

@property def agent_card_url(self) -> str: """Get the URL advertised in the AgentCard. Defaults to http_url. Can be overridden to advertise a custom URL (e.g., without trailing slash or with a different base). """ return self._agent_card_url if self._agent_card_url is not None else self.http_url @agent_card_url.setter def agent_card_url(self, url: str) -> None: """Override the URL advertised in the AgentCard.""" self._agent_card_url = url

该属性在构建AgentCard时被引用（server.py#L181-L187），默认回退到http_url。典型使用场景：

• 部署在负载均衡器后时，AgentCard 公布的是外部域名而非内部host:port；
• 需要去除 URL 末尾斜杠或统一 URL 前缀规范时。

from strands.multiagent.a2a.server import A2AServer server = A2AServer(agent=agent, host="0.0.0.0", port=9000) server.agent_card_url = "https://agents.example.com/my-agent" # 覆盖对外公布的地址

核心新特性四：双向流式（bidi）引入 Limits

PR #2360（作者 notowen333）为 strands-py-wasm 的双向流式（bidirectional-streaming）能力新增了Limits，并支持在invoke/stream过程中生效。从源码结构看，Limits用于约束单次调用/流式会话的资源上限（对应 experimental/bidi 目录下的 agent 循环实现），同时 strands-py-wasm 相关 PR（#2361、#2386、#2412）让 wasm 变体在流式与容器继承方面持续对齐。

同组改动中，PR #2412 为 strands-py-wasm 增加了DecoratedTool，用于承载宿主侧（host-side）Python 工具；工具加载器 tools/loader.py 会优先识别模块中装饰了@tool的函数工具实例并批量加载，再回退到模块级工具加载。这两个能力共同完善了 wasm 运行时的工具生态。

关键修复与稳定性改进

MetricsClient 单例线程安全化（PR #2349）

telemetry/metrics.py 中的MetricsClient是管理 OpenTelemetry 指标仪器的单例。本版本采用**双重检查锁定（double-checked locking）**模式确保多线程下安全初始化：

def __new__(cls) -> "MetricsClient": if cls._instance is None: with cls._lock: if cls._instance is None: cls._instance = super().__new__(cls) return cls._instance

同时__init__也通过"先查hasattr(self, "meter")、再持锁复查"的两段式检查，避免并发初始化竞态（L617-L635）。该客户端在初始化时即创建计数器与直方图族，包括事件循环周期、延迟、输入/输出 token，以及随本版本同步引入的event_loop_cache_read_input_tokens、event_loop_cache_write_input_tokens缓存 token 直方图（L637-L662），与前述 Gemini 缓存 token 计量形成完整闭环。

工具结果保持请求顺序（PR #2340）

并发工具调用的结果此前可能存在乱序问题，本版本修复为严格保持请求顺序返回。这与S3SessionManager.list_messages中"并行加载、按索引回填结果"的实现思路（results[key_to_index[key]] = data）一致，说明该版本对"并发执行但顺序归位"这一模式做了系统性加固。

其他值得注意的修复

• 消息内容清洗处理 None 文本（PR #1920）：在消息内容净化逻辑中容忍None文本，避免某些 provider 返回空文本时崩溃。
• 结构化输出校验日志降级（PR #2368）：将校验失败日志从 error 降为 debug，减少无效告警噪音。
• 测试稳定性（PR #2319）：修复 flaky 测试，使其同时接受字符串或数字类型断言。
• http_request / file_editor 工具安全警告（PR #2391）：为这两个 vended 工具补充安全警告文档，提醒使用者其潜在风险。
• CI 权限收敛（PR #2367）：将授权检查任务的权限收敛为contents: read，遵循最小权限原则。

仓库治理：monorepo 收敛

本版本包含多条围绕 monorepo 收敛的chore变更：合并 strands-agents/docs（#2339）与 sdk-typescript（#2350、#2363）进入 monorepo、准备目录布局（#2317）、更新过时引用（#2358）、Python/TypeScript 包分别使用独立 README（#2384）、修复文档合并后的 fast-follow 事项（#2348）。从当前仓库结构可以确认这一收敛结果：harness-py、harness-ts、strands-py、strands-ts、strands-mcp、strands-cli等子项目已在同一仓库下共存，Python 与 TypeScript SDK 的 API 对齐成为后续版本演进的主线。

版本验证与使用建议

1. 升级方式：通过pip install strands-agents==1.42.0安装（对应 PyPI 包 strands-agents v1.42.0）。本版本无破坏性变更，可从更早版本平滑升级。

2. 新特性验证清单：

   • 用 MinIO/LocalStack 初始化S3SessionManager(endpoint_url=...)并跑一次会话持久化；
   • 使用 Gemini 模型时，检查流式事件metadata中的usage.cacheReadInputTokens字段；
   • 部署 A2A 服务时，设置server.agent_card_url并核对下发的 AgentCard；
   • 多线程环境下首次调用MetricsClient()，确认单例只初始化一次、各指标仪器正常创建。

3. 配套测试与文档：本仓库 strands-py/tests、strands-py/tests_integ 中提供了会话管理、模型、多智能体、遥测等模块的单元与集成测试，可作为新 API 用法的行为参考；models/bedrock.py 与 s3_session_manager.py 中的 docstring 是自定义端点参数的权威说明。

小结

v1.42.0 是一个"广度优先"的版本：它没有大幅重构，却在 S3 存储自定义端点、Gemini 缓存成本计量、A2A 协议 URL 定制、wasm 双向流式与工具生态、遥测线程安全等维度同时补强，并以 monorepo 收敛为后续 Python/TypeScript 双 SDK 的同步演进铺路。对于在生产环境使用 Strands Python SDK 的团队，本版本尤其值得关注的是endpoint_url（打通自建对象存储）、cacheReadInputTokens（观测缓存收益）与agent_card_url（规范 Agent 对外暴露地址）三个可直接落地的能力点。

• 人工智能
• 大模型
• AI Agent
• Agent 框架
• 多智能体
• 工具调用
• MCP 服务