企业官网建设流程全解析

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

本文基于 site/src/content/changelog/sdk/python-v1.56.0.md 变更记录，结合仓库源码（strands-py/）对 v1.56.0（2026-09-15 发布）的核心更新逐一展开：涵盖 shell 工具新增exit_code与超时部分输出、基于 SQLite FTS5 的 BM25 全文检索策略、Bedrock Mantle 模型路由修复、OpenAI prompt-cache 自动会话路由，以及双向流式（bidi）体系的钩子与转录事件升级。读完本文，你将了解这些新能力的调用方式、底层实现原理与适用的实战场景。

版本总览

v1.56.0 是 strands-agents（Python SDK，发布包名strands-agents）的一个全量非破坏性（breaking: false）版本，共包含 24 条变更，覆盖工具（vended-tools）、模型路由（models）、双向流式（bidirectional-streaming）、存储检索（storage）、上下文管理（context-py）、沙箱（sandbox）、MCP（mcp-py）等多个模块。变更类型以feat与fix为主，辅以少量refactor、test与docs。

整体来看，本版本有四个鲜明主题：

1. 工具结果结构化：shell 工具向模型返回exit_code，超时错误中携带部分输出；
2. 检索能力补全：存储层新增 BM25 全文检索策略；
3. 模型路由与成本优化：修复 Bedrock Mantle 的openai.gpt-6-*路由，并让 OpenAI prompt-cache 自动从 session id 派生缓存键；
4. 双向流式（bidi）体系收敛：与Agent/Model对齐钩子与引用语义，新增响应完成钩子与转录完成事件。

下文按主题分组深入解析。

Shell 工具：exit_code字段与超时部分输出

变更内容

v1.56.0 的两条变更直接作用于 shell 工具：

• feat（vended-tools）：在 shell 工具结果中引入exit_code（PR 4269）；
• feat（sandbox）：shell 超时错误中包含部分输出（PR 4325）。

源码实现

在 strands-py/src/strands/vended_tools/shell/types.py 中，ShellOutput是一个TypedDict，定义了三个字段：

class ShellOutput(TypedDict): output: str # 捕获的标准输出 error: str # 捕获的标准错误，无错误时为空 exit_code: int # 命令退出码，非零表示命令失败

shell.py 中的make_shell()工厂返回一个无状态、经由沙箱路由的 shell 工具。每次调用都在全新 shell 中执行，环境变量与工作目录等状态不会跨调用保留，因此命令不应依赖 shell 特定语法（Docker 与本地环境使用sh，SSH 远端使用登录 shell）。成功路径下工具返回：

return {"output": result.stdout, "error": result.stderr, "exit_code": result.exit_code}

超时场景的特别处理

超时时（默认timeout=120秒），工具捕获SandboxTimeoutError，构造一个携带部分输出的ShellOutput，并把 JSON 序列化结果拼进异常消息：

partial: ShellOutput = {"output": e.stdout, "error": e.stderr, "exit_code": 124} e.args = (f"{e}\n{json.dumps(partial)}",) raise

这里有两个值得注意的设计：

• exit_code: 124与 GNUtimeout命令语义一致，模型可以据此把“命令被杀”与“命令本身失败（非零退出码）”区分开；
• 由于模型最终只能看到str(e)，部分输出被以 JSON 形式嵌入异常文本，不会丢失命令在超时前已经产生的 stdout/stderr，对排障与重试决策非常重要。

此外 types.py 还定义了ShellExecutionError，它继承自RuntimeError——既保留了现有except RuntimeError处理器的兼容性，又为调用方提供了可分支的专用异常类型；该异常与 TypeScript 侧strands-ts/src/vended-tools/shell/types.ts中的同名类型互为镜像。

实战要点

• 工具描述（SANDBOX_SHELL_DESCRIPTION）已明确告知模型：非零exit_code意味着命令失败，模型应据此决定是否重试或改用其他策略；
• 若需自定义 shell 工具（如绑定特定沙箱、改名、改描述），可直接调用make_shell(sandbox=..., name=..., description=...)；
• 超时场景不再“黑盒”，模型可读到被杀前已产生的输出，Agent 的排障能力显著增强。

存储检索：新增 BM25 全文检索策略

变更内容

• feat（storage）：新增 bm25 搜索策略（PR 4079）。

设计思路与源码实现

BM25 是经典的信息检索排序算法，综合考虑词频（TF）、逆文档频率（IDF）与文档长度归一化。strands-py 的实现位于 strands-py/src/strands/storage/search/bm25.py，其关键设计是：

1. 以 SQLite FTS5 作为倒排索引载体，零外部依赖——仅使用 Python 标准库sqlite3（现代平台均自带 FTS5 支持）；
2. 写入时建索引：消费者在每次写入存储时调用strategy.index(storage, key, data)，搜索时直接查询预建索引，无需重读存储内容；
3. 不自动回填：只有经过index()写入过的条目可被检索，存量内容不会自动补索引；
4. 索引文件落盘：通过存储实例的base_dir定位 SQLite 数据库文件，默认路径为存储目录旁的.__strands_{basename}-fts5.sqlite；策略标记requires_host_fs = True，不感知沙箱隔离。

查询构建与评分

bm25.py 的_build_query()会把自然语言查询分词后过滤掉停用词（内置约 150 个英文停用词表）与单字符 token，为每个词追加前缀通配符，再用隐式 AND 组合——即所有词都必须以前缀形式出现，再按 BM25 打分排序：

terms = sorted(term for term in tokenize(query) if len(term) > 1 and term not in STOP_WORDS) return " ".join(f"{term}*" for term in terms)

写入时通过hashlib.md5对内容做哈希，内容未变化则跳过重复索引；隐藏文件（key 末段以.开头）也会被跳过。评分结果在_query()中被归一化到 (0, 1) 区间：score = raw_score / (1.0 + raw_score)，返回StorageSearchResult(key=key, score=score)列表。

使用示例

from strands.storage import LocalFileStorage from strands.storage.search.bm25 import Bm25SearchStrategy storage = LocalFileStorage("./memory/") strategy = Bm25SearchStrategy() await strategy.index(storage, "auth.md", b"OAuth2 authentication flow") results = await strategy.search(storage, "authentication flow") await strategy.close()

适用场景

BM25 策略适合在本地文件存储（LocalFileStorage）之上构建低成本、可持久化的全文检索——例如 Agent 的长期记忆、文档库的语义近似关键词检索。其价值在于把检索能力内聚到存储层，无需引入 Elasticsearch 等外部服务。若 SQLite 构建缺少 FTS5，search()会抛出RuntimeError("SQLite build lacks FTS5 support")，实现中已做显式检测。

模型路由：Bedrock Mantleopenai.gpt-6-*修复

变更内容

• fix（models）：将 Bedrock Mantle 的openai.gpt-6-*模型路由到/openai/v1（PR 4267）。

背景与源码实现

Amazon Bedrock 的 OpenAI 兼容端点分为两个家族：bedrock-mantle（默认）与bedrock-runtime（后者固定从/openai/v1提供所有 OpenAI 兼容 API，并支持跨区域推理 profile id）。在 strands-py/src/strands/models/_openai_bedrock.py 中，Mantle 的 base path 是按模型线（model line）划分的——这是 Mantle API 不对外暴露的每模型属性，错误路径会以 HTTP 400 失败：

_OPENAI_PATH_MODEL_PREFIXES: tuple[str, ...] = ( "openai.gpt-5.", "openai.gpt-6-", # v1.56.0 新增 "xai.grok-4.", "google.gemma-4-", )

_resolve_mantle_base_path(model_id)匹配上述前缀时返回/openai/v1，否则回退/v1。源码注释强调：前缀必须精确作用到单个模型线，绝不可扩大到厂商级——同一厂商的不同模型线可能分属两个 base path（google.gemma-4-*在/openai/v1，而google.gemma-3-*在/v1）。集成测试test_mantle_routing会拦截任何路由错误的模型 id。

从 strands-py/src/strands/models/_defaults.py 可以看到 v1.56.0 已为gpt-6-astra配置了 1,050,000 token 的默认上下文窗口，说明该模型线已纳入默认模型配置体系。

配置方式

BedrockMantleConfig支持以下字段：endpoint（"bedrock-mantle"或"bedrock-runtime"，仅后者接受us.openai.*、global.openai.*等跨区域推理 profile）、region（未提供时按 boto3 标准链解析）、boto_session、credentials_provider与expiry（bearer token 生命周期，默认取生成器内建值）。SDK 通过aws_bedrock_token_generator.provide_token按需铸造 token，保证长时间运行的 Agent 能跨越 bearer token 的最大生命周期。

成本优化：OpenAI prompt-cache 自动使用 session id

变更内容

• feat（models/sessions）：自动使用 session id 作为 OpenAI prompt-cache 键（PR 4083）。

源码实现

在 strands-py/src/strands/models/_openai_cache.py 中，_resolve_cache_key(cache_config, agent_metadata)定义了 prompt-cache 路由键的解析优先级：

if cache_config.cache_key is False: return None # 显式退出缓存 if cache_config.cache_key is not None: return cache_config.cache_key # 显式配置优先 # 否则回退到 strands-<session_id>

即：显式配置的cache_key字符串优先；cache_key=False是显式退出；两者都未设置时，自动派生strands-<session_id>作为prompt_cache_key。该逻辑同时被 openai.py、mistral.py 等 OpenAI 兼容 provider 复用。

CacheConfig（定义于 strands-py/src/strands/models/model.py）只暴露cache_key与ttl两个旋钮：cache_key是 provider（OpenAI、LiteLLM、Mistral）用于 prompt-cache 路由的稳定标识；ttl仅在它恰好命中了 OpenAI 合法保留字面量时才透传到请求（prompt_cache_retention只接受特定枚举值，且该参数在 openai 2.54.0 中已弃用，迁移方向为prompt_cache_options.ttl）。

实战价值

对于同一 session 内反复调用模型的 Agent 而言，自动从 session id 派生缓存键意味着无需任何配置即可享受 prompt-cache 命中，显著降低长会话的 token 成本与首字节延迟；若缓存命中带来的行为不符合预期，开发者可用cache_key=False一键退出。

双向流式（bidi）：钩子共享、转录完成事件与语义对齐

v1.56.0 是 bidi 体系（strands-py/src/strands/experimental/bidi/）收敛最多的一次发布，共 8 条相关变更，核心方向是让双向流式能力与常规Agent/Model体系对齐：

其中，转录完成事件在 strands-py/src/strands/experimental/bidi/agent/loop.py 有直接印证——事件循环已处理“完成之后到达的转录不会重新打开当前轮次”的边界情形；而响应完成钩子与生命周期钩子的共享，意味着 bidi 场景可以复用与普通 Agent 相同的观测与干预点。加上 PR 4257 将仓库级会话方法通过LocalAgent共享，bidi 会话管理也向标准 Agent 会话看齐。这些改动共同降低了双向语音/流式场景的开发门槛。

上下文管理（context-py）：会话集成与策略预设

变更内容

• feat（context-py）：新增会话管理器集成（PR 4254）；
• feat（context-py）：移植策略预设（strategy presets）与 agent 重连（agent rewire，PR 4282）。

解读

context-py 模块（strands-py/src/strands/experimental/下的上下文管理实现）在本版本中把上下文策略与会话管理器打通：会话管理器集成让上下文状态可以随会话持久化与恢复；策略预设则提供开箱即用的上下文管理策略组合，“agent rewire”允许在运行期调整 Agent 的上下文接线方式。这两条变更标志着上下文管理从“单一策略”走向“可预设、可接线、可会话化”的工程化形态，适合构建具备长对话记忆与上下文压缩能力的生产 Agent。

其他值得关注的修复与增强

结构化输出：按工具名强制重试（PR 4263）

Python 侧修复了结构化输出重试策略——按工具名（tool name）强制重试，避免因工具识别偏差导致结构化校验反复失败或错误重试，提升 JSON Schema 约束下 Agent 工具调用的稳定性。

AgentResult.to_dict对 bytes 的 JSON 序列化（PR 4313）

修复了AgentResult.to_dict()在结果包含bytes数据时无法 JSON 序列化的问题（strands-py/src/strands/agent/ 相关实现），使 Agent 最终结果可以直接进入 JSON 序列化管线（如落库、传输、遥测）。

后台任务结果经注册的管理工具投递（PR 4347）

修复异步/后台任务场景：后台结果现在通过已注册的管理工具（management tool）投递，而不是绕过工具注册表，保证了工具调用的完整性与权限模型一致。

Mistral：保留请求中的 image blocks（PR 4200）

修复 Mistral provider 在多模态请求中丢失图片块的问题（见 strands-py/src/strands/models/mistral.py），确保视觉输入在请求转发时被完整保留。

TypeScript 侧：web_fetch 工具落地（PR 4153）

本版本为 TypeScript SDK 新增web_fetch工具（对应仓库 harness-ts/src/tools/web-fetch.ts 与strands-ts的 vended-tools），补齐了 TS 侧网页抓取能力，使 Python 与 TypeScript 两套 SDK 的工具集进一步对齐。

其他修复

• skills-py（PR 4192）：避免 YAML 解析错误泄漏，且不再丢弃合法的 skills 配置；
• mcp-py（PR 4131）：在 MCP 2.x 版本上固定原生 OTel trace 连续性（test 类型变更）；
• Anthropic-direct（PR 3568）：为 Anthropic 直连的服务端工具（web search）提供非覆盖式（non-clobbering）接缝，避免与本地工具定义冲突；
• docs（PR 4148）：新增 AI 使用反思博客。

升级建议

v1.56.0 全部变更为非破坏性，Python 用户可直接升级strands-agents至 1.56.0。升级后可重点验证：

1. shell 工具新契约：确认下游解析逻辑兼容新增的exit_code字段与超时部分输出（JSON 文本内嵌在异常消息中）；
2. BM25 检索：为存储接入Bm25SearchStrategy时注意先写入索引再搜索，存量数据不会被自动回填；
3. Bedrock 路由：若使用 Mantle 端点运行openai.gpt-6-*模型，确认请求路径已自动切换至/openai/v1；
4. prompt-cache：默认 session 派生键已生效，可在遥测中观察缓存命中率变化。

总结

strands-agents Python SDK v1.56.0 是一次“工具结果更结构化、检索能力更完整、模型路由更精确、双向流式更成熟”的版本迭代：shell 工具的exit_code与超时部分输出让 Agent 对命令执行结果的理解从“字符串”升级为“结构化事实”；BM25 策略让本地存储获得零依赖的全文检索；Bedrock Mantle 的按模型线路由修复与 OpenAI prompt-cache 的会话自动路由，分别提升了兼容性与成本效益；而 bidi 体系与标准Agent/Model的语义对齐，则为语音与实时流式场景铺平了道路。建议结合上述源码路径深入阅读对应实现，将新能力快速落地到生产 Agent 中。

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