1. 项目定位与设计理念

Strands Agents 是一个采用「模型驱动」(model-driven) 方法构建与运行 AI Agent 的轻量级 SDK。它从简单的对话助手延伸到复杂的多 Agent 自主工作流，覆盖本地开发到生产部署。资料来源：README.md:1-13。

整个项目以「简单但可完全定制」(simple agent loop that just works and is fully customizable) 为核心设计理念。资料来源：README.md:18-19。

1.1 核心特性

1.2 社区关注的主要扩展方向

2. Monorepo 顶层布局

仓库采用 monorepo 方式管理，将 Python SDK、TypeScript SDK、文档站、配套工具统一托管。资料来源：README.md:14-26。

harness-sdk/
├── strands-py/        # Python SDK — Agent Loop、模型 Provider、Tools
├── strands-ts/        # TypeScript SDK — Agent Loop、模型 Provider、Tools
├── strands-wasm/      # WASM 构建工具与多包开发指南
├── strands-py-wasm/   # Python 宿主，加载并驱动 WASM 组件
├── strandly/          # 开发者 CLI：本地构建、代码生成、工作区管理
├── site/              # 文档站（Astro/Starlight）
└── designs/           # 重大特性的设计提案（RFC 风格）

资料来源：README.md:14-26。

2.1 各子包职责

资料来源：README.md:14-26、strands-wasm/README.md:5-13。

2.2 文档与设计管理

designs/ 目录遵循 RFC 流程，提案模板包含 Context、Decision、Developer Experience、Alternatives、Consequences、Willingness to Implement 等章节。资料来源：designs/README.md:25-64。

team/ 目录下汇集 TENETS、DECISIONS、API_BAR_RAISING、AGENT_GUIDELINES 等内部文档，贡献者在提出变更前应先阅读。资料来源：team/README.md:1-19。

3. 架构全景

整个系统的核心思想是：将「Agent Loop」抽象为可复用的核心循环，把「Model Provider」「Tool」「Conversation Manager」「Hook」等设计为可插拔的扩展点。下图展示了三端（Python 原生、TypeScript 原生、Python↔WASM）的关系：

graph TD
    subgraph "Python 原生"
        PyUser[Python 用户] --> PyAgent[Agent]
        PyAgent --> PyLoop[Event Loop]
        PyLoop --> PyModel[Model Provider]
        PyLoop --> PyTool[Python Tool]
        PyLoop --> PyHook[Hook 系统]
    end

    subgraph "TypeScript 原生"
        TsUser[TS 用户] --> TsAgent[Agent]
        TsAgent --> TsLoop[Agent Loop]
        TsLoop --> TsModel[Model Provider]
        TsLoop --> TsTool[TS Tool / MCP]
        TsLoop --> TsHook[Hook 系统]
    end

    subgraph "Python ↔ WASM 互操作"
        WasmUser[Python 用户] --> WasmHost[strands-py-wasm 宿主]
        WasmHost -- "加载" --> Component[strands-agent.wasm]
        Component --> WasmLoop[TS Agent Loop]
        WasmLoop -- "tool-provider import" --> WasmHost
        WasmHost -- "执行 Python Tool" --> PyTool2[Python Tool]
        WasmLoop -- "host-log import" --> WasmHost
        WasmHost --> PyLog[Python logging]
    end

资料来源：strands-wasm/README.md:7-13、strands-py-wasm/src/strands/types.py:1-10。

4. Agent Loop 核心架构

4.1 设计目标

Agent Loop 的目标是把「模型思考 → 工具调用 → 结果回填 → 继续思考」这一循环抽象为统一的状态机，并允许通过 Hook、Conversation Manager 等机制进行横切关注点扩展。Python 与 TypeScript 两端共享相同的状态机语义，但各自实现。资料来源：strands-py/README.md:14-16、strands-ts/README.md:14-16。

4.2 核心循环（概念模型）

graph TD
    A[接收用户输入] --> B[组装消息 + 工具规格]
    B --> C[调用 Model Provider 流式输出]
    C --> D{是否产生 toolUse?}
    D -- 否 --> E[输出最终回复]
    D -- 是 --> F[解析工具调用]
    F --> G[执行工具]
    G --> H[回填 toolResult]
    H --> I[调用 Conversation Manager 裁剪上下文]
    I --> C
    E --> J[触发生命周期 Hook]
    J --> K[返回结果]

资料来源：strands-py/src/strands/models/openai.py: format_request、strands-py/src/strands/models/anthropic.py: format_request。

4.3 关键抽象

资料来源：strands-py-wasm/src/strands/types.py:1-10、[strands-py-wasm/src/strands/_generated/__init__.py: 中列出的类型名]()。

4.4 多 Agent 编排

TypeScript SDK 提供 Graph 和 Swarm 两种编排模式。Python SDK 通过等价原语支持 Multi-Agent Systems 与 Autonomous Agents。资料来源：strands-ts/README.md:21-23、README.md:22-23。

5. Model Provider 抽象

5.1 设计动机

模型无关性通过将各家 LLM 的差异收敛到统一的「流式 + 工具规格」协议来实现。Model Provider 的 format_request 方法把 Messages、ToolSpec、system_prompt 翻译为对应厂商的请求格式。资料来源：strands-py/src/strands/models/openai.py: format_request、strands-py/src/strands/models/anthropic.py: format_request。

5.2 已支持的模型 Provider

资料来源：strands-py/src/strands/models/openai.py: format_request_messages、strands-py/src/strands/models/openai_responses.py: count_tokens、strands-py/src/strands/models/anthropic.py: format_request、strands-py/src/strands/models/mistral.py: stream、README.md:20-21。

5.3 Tool Choice 兼容性矩阵

资料来源：strands-py/src/strands/models/anthropic.py: _format_tool_choice、strands-py/src/strands/models/mistral.py: warn_on_tool_choice_not_supported。

5.4 流式事件类型（TypeScript 侧）

strands-ts/src/models/streaming.ts 定义了流式事件分片的核心判别联合类型（discriminated union），是 Agent Loop 与 UI 之间的稳定接口。资料来源：strands-ts/src/models/streaming.ts: ToolUseInputDelta, ReasoningContentDelta, CitationsDelta, Usage。

资料来源：strands-ts/src/models/streaming.ts: ToolUseInputDelta, ReasoningContentDelta, CitationsDelta, Usage。

6. WASM 桥接架构

6.1 跨边界契约（WIT）

strands-wasm 描述了一种「TypeScript 编译为 WASM 组件 → Python 宿主通过 wasmtime-py 加载」的双向桥接。WIT 合约位于 wit/agent.wit，明确划定了 guest（TS 实现）与 host（Python 实现）之间的接口边界。资料来源：strands-wasm/README.md:7-13。

资料来源：strands-wasm/README.md:9-13。

6.2 桥接数据流

graph LR
    User[Python 用户] --> Host[strands-py-wasm 宿主]
    Host -- "调用 api.export" --> Guest[strands-agent.wasm]
    Guest -- "stream 事件" --> Host
    Host -- "回调 tool-provider" --> Guest
    Guest -- "调用 tool-provider" --> Host
    Host --> PyTool[Python Tool 实现]
    PyTool --> Host
    Host -- "结果回填" --> Guest
    Guest -- "日志 host-log" --> Host
    Host --> PyLog[Python logging]

资料来源：strands-wasm/README.md:11-13。

6.3 类型同步

strands-py-wasm 的 types.py 通过 WIT 类型生成得到 _generated 目录中的类型，并进一步收敛为输入联合类型（如 ModelInput、VendedToolInput、VendedPluginInput）。这保证了 Python 侧与 TypeScript/WASM 侧的类型一致。资料来源：strands-py-wasm/src/strands/types.py:1-23、[strands-py-wasm/src/strands/_generated/__init__.py: 类型列表]()。

资料来源：strands-py-wasm/src/strands/types.py:1-10。

6.4 引导流程

strands-wasm 提供了 npm run dev -- bootstrap 一键脚本，安装工具链、链接 strandly、生成类型、构建所有层、安装 strands-py-wasm、运行所有测试。资料来源：strands-wasm/README.md:23-31。

7. 工具与 MCP

7.1 Python 工具

Python SDK 提供 @tool 装饰器，可把任意 Python 函数声明为 Agent 可调用的工具。资料来源：README.md:29-39。

from strands import Agent, tool

@tool
def word_count(text: str) -> int:
    return len(text.split())

agent = Agent(tools=[word_count])

7.2 TypeScript 工具与 Zod

TypeScript SDK 使用 Zod Schema 来声明工具，从而获得类型推导与输入校验。资料来源：strands-ts/README.md:18-20。

7.3 Vended Tools 与 Plugins

VendedTool（Vended 工具）由 SDK 提供方预先实现并随 SDK 发布。Notebook 工具允许 Agent 创建、读取、写入、列出、清除持久化的文本笔记，并在 Agent 会话内自动持久化。资料来源：strands-ts/src/vended-tools/notebook/README.md:1-12。

社区提议的 Skills 支持（#1181） 在 strands-py-wasm 的类型中已出现 AgentSkills，位于 VendedPluginInput 联合类型之中。资料来源：strands-py-wasm/src/strands/types.py: VendedPluginInput。

7.4 MCP 集成

Python 与 TypeScript 两端均内置 MCP 客户端，可直接连接任何 MCP Server，访问其提供的工具集合。资料来源：README.md:24-25、strands-ts/README.md:20-21。

8. 跨端开发工作流

8.1 前置条件

• Node.js 20+
• Python 3.10+

资料来源：strands-wasm/README.md:17-22、README.md:42-45。

8.2 首次设置

git clone https://github.com/strands-agents/sdk-python.git
cd sdk-python
npm install
npm run dev -- bootstrap

资料来源：strands-wasm/README.md:25-31。

8.3 文档站

site/ 使用 Astro 6 + Starlight 构建。site/package.json 中的关键依赖包括 @astrojs/starlight、astro、typedoc、prettier、mdast-util-to-string 等。Prettier 配置中针对 src/content/docs/**/*.ts 单独设置了更窄的 printWidth: 90。资料来源：site/package.json: devDependencies, prettier.overrides。

9. 浏览器端 Agent 示例

strands-ts/examples/browser-agent/ 提供一个跑在浏览器内的 Agent 示例，可通过自然语言命令修改 DOM。该示例支持 OpenAI、Anthropic 与 AWS Bedrock，使用 update_canvas 自定义工具直接执行模型生成的 HTML/CSS/JavaScript。资料来源：strands-ts/examples/browser-agent/README.md:1-12。

⚠️ 该示例仅用于演示，不应用于生产环境——它会以最小过滤执行 LLM 生成的代码。资料来源：strands-ts/examples/browser-agent/README.md:2-5。

10. 常见失败模式与排错

11. 延伸阅读

• Quickstart Guide
• designs/README.md — 设计提案流程
• team/README.md — 内部原则、决策、API 评审与 Agent 指南
• strands-py/README.md — Python SDK 入门
• strands-ts/README.md — TypeScript SDK 入门
• strands-wasm/README.md — WASM 构建与跨包开发
• Issue #1181 — Skills 支持
• Issue #140 — AG-UI 协议

See Also

• 模型 Provider 实现细节：参见各 Provider 文件（openai.py、openai_responses.py、anthropic.py、mistral.py）
• 流式事件类型参考：strands-ts/src/models/streaming.ts
• Vended 工具示例：strands-ts/src/vended-tools/notebook/
• 浏览器端 Agent 示例：strands-ts/examples/browser-agent/

概述

Strands Agents SDK 采用"模型驱动"的设计范式，将 AI Agent 抽象为三个正交的关注点：工具（Agent 可调用的能力）、模型提供商（LLM 的后端实现）、集成协议（如 MCP、AG-UI 等连接 Agent 与外部系统的桥梁）。这种分层让一个最小的 Agent 循环（model + prompt + tools）即可工作，同时允许生产场景中替换任意组件而不影响其他部分。

资料来源：README.md:1-30、strands-py/README.md:1-40

核心设计要点：

• 轻量级 Agent 循环：内置事件循环完全可定制，开发者可以在不修改核心代码的情况下插入钩子、替换工具执行器或切换模型。
• 模型无关：同一份 Agent 代码可以同时运行在 Amazon Bedrock、Anthropic、Gemini、LiteLLM、Llama、Ollama、OpenAI、Writer 或自定义提供商上。
• 多语言可执行体：除了 Python 原生包外，TypeScript SDK 通过 WebAssembly 组件编译后被 Python 宿主加载，形成跨语言运行时。

资料来源：README.md:11-17、strands-wasm/README.md:1-30

概述

Strands Agents SDK 是一个以"模型驱动 + 工具调用"为核心的智能体开发框架。本页面聚焦 SDK 内的三类高阶能力：多智能体编排（multi-agent orchestration）、插件生态（plugin ecosystem）以及双向流式语音（bidirectional streaming voice，简称 *bidi*）。这三类能力既可以独立使用，也可以组合构建端到端的智能体系统——例如一个 swarm 智能体通过 Skills 插件按需加载领域知识，并以 bidi 形式与用户进行实时语音交互。

从仓库结构可以看到，这三类能力在源代码中分别对应三个独立的子包：

• 多智能体：strands-py/src/strands/multiagent/
• 插件：strands-py/src/strands/plugins/ 与 strands-py/src/strands/vended_plugins/
• 双向语音：strands-py/src/strands/experimental/bidi/

资料来源：README.md:1-25

仓库同时提供 WASM 镜像包 strands-py-wasm，其 _generated/__init__.py 通过 Python 绑定统一暴露上述子系统的核心类型符号，可作为跨模块 API 面的稳定参考。

资料来源：strands-py-wasm/src/strands/_generated/__init__.py:1-130

1. 概述与适用范围

本页面向希望将 Strands Agents SDK 投入生产环境运行的工程师，整合部署所需的四大支柱：会话（Session）持久化、Hook 拦截、Interrupt 异步协作以及 Telemetry 可观测性；同时说明 WebAssembly（WASM）互操作如何让 TypeScript 实现与 Python 主机协同工作，从而满足多语言 SDK 需求。

根据 strands-wasm/README.md 的描述，整个 SDK 已经演化为一个"Python 主机 + TypeScript 编译为 WASM 客机"的混合架构，这意味着部署时不仅要考虑 Python 侧的 strands-agents 运行时，还需要关注 strands-agents-wasm 包及 strands-agent.wasm 组件的发布形态。

graph TD
    A[用户应用] --> B[Python Agent API]
    B --> C[会话/钩子/中断子系统]
    C --> D[WASM 主机绑定]
    D --> E[TypeScript 编译产物<br/>strands-agent.wasm]
    E --> F[模型提供方 HTTP]
    E -.工具回调.-> G[Python 工具]
    C --> H[Telemetry 通道]

资料来源：strands-wasm/README.md:1-30。

1.1 适用读者

• 需要把 Strands Agent 嵌入到已有 Web 服务、CLI 工具或批处理任务中的后端工程师。
• 关注可观测性、合规审计、跨进程恢复能力（会话持久化）的 SRE / 平台工程师。
• 对接 AG-UI 协议 等多语言前端协议（参见社区 #140）的全栈工程师。
• 关注 TypeScript / Go / Java 等多语言 SDK 路线图（参见社区 #156、#616、#240）的架构师。

1.2 仓库关键目录速览

资料来源：strands-wasm/README.md:31-60。

Pitfall Log / 踩坑日志

项目：strands-agents/harness-sdk

摘要：发现 11 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 harness-sdk 与安装入口 strands-agents 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
• 复现命令：pip install strands-agents
• 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
• 证据：identity.distribution | github_repo:983715534 | https://github.com/strands-agents/harness-sdk | repo=harness-sdk; install=strands-agents

2. 安装坑 · 来源证据：[BUG] OpenAIModel tool message content sent as array instead of string breaks OpenAI-compatible endpoints (e.g., Kimi K…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] OpenAIModel tool message content sent as array instead of string breaks OpenAI-compatible endpoints (e.g., Kimi K2.5)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_93fd58414d4847dfb2421a360c7c4b8d | https://github.com/strands-agents/harness-sdk/issues/1696 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：[FEATURE] Support audio input for standard Agent (Specially using Bedrock Provider, Converse API already supports Audio…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[FEATURE] Support audio input for standard Agent (Specially using Bedrock Provider, Converse API already supports AudioBlock).
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_02f95abeeb8747e5a5dd362a16cebba1 | https://github.com/strands-agents/harness-sdk/issues/2614 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 来源证据：[WASM] Python SDK - Gaps and Limitations

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[WASM] Python SDK - Gaps and Limitations
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f4e191d32b4642baa76d35bbdbe52aa4 | https://github.com/strands-agents/harness-sdk/issues/2421 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:983715534 | https://github.com/strands-agents/harness-sdk | README/documentation is current enough for a first validation pass.

6. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:983715534 | https://github.com/strands-agents/harness-sdk | last_activity_observed missing

7. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:983715534 | https://github.com/strands-agents/harness-sdk | no_demo; severity=medium

8. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:983715534 | https://github.com/strands-agents/harness-sdk | no_demo; severity=medium

9. 安全/权限坑 · 来源证据：[WASM] MCP tools

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[WASM] MCP tools
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6ad624f56a6c457b877fc487289c315c | https://github.com/strands-agents/harness-sdk/issues/2456 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

10. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:983715534 | https://github.com/strands-agents/harness-sdk | issue_or_pr_quality=unknown

11. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:983715534 | https://github.com/strands-agents/harness-sdk | release_recency=unknown