# https://github.com/strands-agents/harness-sdk 项目说明书

生成时间：2026-06-03 17:07:56 UTC

## 目录

- [概述、Monorepo 布局与 Agent Loop 核心架构](#page-1)
- [工具系统、模型提供商与 MCP/AG-UI 集成](#page-2)
- [多智能体编排、插件生态与双向流式语音](#page-3)
- [部署示例、Session/Hook/Interrupt、Telemetry 与 WASM 互操作](#page-4)

<a id='page-1'></a>

## 概述、Monorepo 布局与 Agent Loop 核心架构

### 相关页面

相关主题：[工具系统、模型提供商与 MCP/AG-UI 集成](#page-2), [多智能体编排、插件生态与双向流式语音](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/strands-agents/harness-sdk/blob/main/README.md)
- [designs/README.md](https://github.com/strands-agents/harness-sdk/blob/main/designs/README.md)
- [team/README.md](https://github.com/strands-agents/harness-sdk/blob/main/team/README.md)
- [strands-py/README.md](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/README.md)
- [strands-ts/README.md](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/README.md)
- [strands-wasm/README.md](https://github.com/strands-agents/harness-sdk/blob/main/strands-wasm/README.md)
- [strands-py-wasm/src/strands/types.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py-wasm/src/strands/types.py)
- [strands-py-wasm/src/strands/_generated/__init__.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py-wasm/src/strands/_generated/__init__.py)
- [strands-py/src/strands/models/openai.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/openai.py)
- [strands-py/src/strands/models/openai_responses.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/openai_responses.py)
- [strands-py/src/strands/models/anthropic.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/anthropic.py)
- [strands-py/src/strands/models/mistral.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/mistral.py)
- [strands-ts/src/models/streaming.ts](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/models/streaming.ts)
- [strands-ts/src/vended-tools/notebook/README.md](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/vended-tools/notebook/README.md)
- [strands-ts/examples/browser-agent/README.md](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/examples/browser-agent/README.md)
- [site/package.json](https://github.com/strands-agents/harness-sdk/blob/main/site/package.json)
</details>

# 概述、Monorepo 布局与 Agent Loop 核心架构

## 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 核心特性

| 特性 | 说明 | 资料来源 |
|------|------|----------|
| 轻量灵活 | 简单可用的 Agent Loop 且完全可定制 | [README.md:18-19]() |
| 模型无关 | 支持 Bedrock、Anthropic、Gemini、LiteLLM、Llama、Ollama、OpenAI、Writer 等 | [README.md:20-21]() |
| 多 Agent 编排 | 支持 Swarm、Graph 等编排模式 | [strands-ts/README.md:21-23]() |
| MCP 集成 | 原生支持 Model Context Protocol | [strands-ts/README.md:20-21]() |
| 流式输出 | 实时流式响应 | [strands-ts/README.md:22-23]() |
| 跨语言 | Python、TypeScript、WASM 三端互操作 | [strands-wasm/README.md]() |

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

| Issue | 提议方向 | 状态 |
|-------|----------|------|
| [#156](https://github.com/strands-agents/harness-sdk/issues/156) | 增加 TypeScript/Node.js SDK | 已落地于 `strands-ts/` |
| [#240](https://github.com/strands-agents/harness-sdk/issues/240) | 增加 Java SDK | 提案中 |
| [#616](https://github.com/strands-agents/harness-sdk/issues/616) | 增加 Go SDK | 提案中 |
| [#1181](https://github.com/strands-agents/harness-sdk/issues/1181) | 支持 Agent Skills | 提案中（`AgentSkills` 已在 `strands-py-wasm` 类型中出现） |
| [#140](https://github.com/strands-agents/harness-sdk/issues/140) | AG-UI 协议适配 | 提案中 |

## 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 各子包职责

| 目录 | 职责 | 产物 |
|------|------|------|
| `strands-py/` | Python 实现 SDK，含 Agent、Event Loop、Model Provider、Tool | `strands-agents` (PyPI) |
| `strands-ts/` | TypeScript 实现 SDK，含 Agent、Provider、Tool、Hook | `@strands/agent` (npm) |
| `strands-wasm/` | WASM 组件构建工具链 | `strands-agent.wasm` |
| `strands-py-wasm/` | 通过 wasmtime-py 驱动 WASM 组件的 Python 宿主 | `strands-agents-wasm` (PyPI) |
| `strandly/` | 开发者 CLI | 本地 PATH 工具 |
| `site/` | 文档站源文件 | [strandsagents.com](https://strandsagents.com) |
| `designs/` | RFC 风格设计提案 | Markdown 文档 |

资料来源：[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）的关系：

```mermaid
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 核心循环（概念模型）

```mermaid
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 关键抽象

| 抽象 | 职责 | Python 侧 | TypeScript 侧 |
|------|------|-----------|---------------|
| `Agent` | 对外门面，承载模型、工具、消息 | `strands-py/src/strands/agent/agent.py` | `strands-ts/src/agent/agent.ts` |
| `Model Provider` | 与具体模型服务对话的适配器 | `strands-py/src/strands/models/*` | `strands-ts/src/models/*` |
| `Tool` | 可被模型调用的功能单元 | Python 装饰器 | Zod Schema 工具 |
| `Event Loop` | 推进状态机、流式产出 | `strands-py/src/strands/event_loop/event_loop.py` | TypeScript 实现 |
| `Conversation Manager` | 上下文窗口与历史管理 | `SlidingWindowConversationManager` / `SummarizingConversationManager` | 同名等价物 |
| `Hook` | 横切点（监控/审计/重试） | Python 钩子系统 | TS Hook 系统 |

资料来源：[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

| Provider | 入口 | 备注 |
|----------|------|------|
| OpenAI Chat Completions | `strands.models.openai.OpenAIModel` | 支持 `tool_choice`、`tool_specs` |
| OpenAI Responses | `strands.models.openai_responses.OpenAIResponsesModel` | 支持原生 `input_tokens.count` |
| Anthropic | `strands.models.anthropic.AnthropicModel` | 透传 `max_tokens` 与 `tool_choice` |
| Mistral | `strands.models.mistral.MistralModel` | `tool_choice` 参数当前被忽略，代码会发出警告 |
| Amazon Bedrock | `BedrockModel`（默认） | 默认区域 `us-west-2`，需 Claude 4 Sonnet 访问权限 |
| Gemini / LiteLLM / Llama / Ollama / Writer | 由社区实现 | 通过统一接口接入 |

资料来源：[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 兼容性矩阵

| Provider | `auto` | `any` | `tool`（指定工具） |
|----------|--------|-------|---------------------|
| OpenAI | ✅ | ✅ | ✅ |
| OpenAI Responses | ✅ | ✅ | ✅ |
| Anthropic | ✅ | ✅ | ✅ |
| Mistral | ⚠️ 接口接受但当前忽略 | ⚠️ | ⚠️ |
| Bedrock | ✅ | ✅ | ✅ |

资料来源：[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]()。

| 类型 | 用途 |
|------|------|
| `ToolUseInputDelta` | 工具调用增量输入（partial JSON） |
| `ReasoningContentDelta` | 推理/思考增量 |
| `CitationsDelta` | 引用信息增量 |
| `Usage` | Token 统计（input/output/total + 缓存相关） |

资料来源：[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]()。

| 方向 | 接口 | 说明 |
|------|------|------|
| Exports（guest 实现，host 调用） | `api` | Agent 构造、流式、会话管理；所有 Model Provider 的 HTTP 调用在 guest 内完成（Bedrock、Anthropic、OpenAI、Gemini） |
| Imports（host 实现，guest 调用） | `tool-provider` | 执行 Python 定义的工具 |
| Imports（host 实现，guest 调用） | `host-log` | 将日志条目路由到 Python 的 `logging` 框架 |

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

### 6.2 桥接数据流

```mermaid
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: 类型列表]`()。

| 联合类型 | 含义 |
|----------|------|
| `ModelInput` | `ModelConfig` 或具体的模型 Provider 实例（Bedrock/Anthropic/OpenAI/Google/Custom） |
| `ConversationManagerInput` | 配置或具体实例（Sliding/Summarizing） |
| `VendedToolInput` | `VendedTool` 或具体 Vended 工具（Bash、FileEditor、HttpRequest、Notebook） |
| `VendedPluginInput` | `VendedPlugin` 或具体插件（AgentSkills、ContextOffloader） |

资料来源：[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]()。

```python
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）](https://github.com/strands-agents/harness-sdk/issues/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 首次设置

```bash
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. 常见失败模式与排错

| 现象 | 触发条件 | 参考资料 |
|------|----------|----------|
| 默认 Bedrock Provider 报凭证错误 | 未配置 AWS 凭证或未在 `us-west-2` 启用 Claude 4 Sonnet | [README.md:35-39]() |
| `tool_choice` 被忽略 | 使用 Mistral Provider，接口接受但当前未生效 | [strands-py/src/strands/models/mistral.py: warn_on_tool_choice_not_supported]() |
| 原生 token 计数失败 | OpenAI Responses Provider 在 `use_native_token_count=True` 路径下出错，会回退到估算 | [strands-py/src/strands/models/openai_responses.py: count_tokens]() |
| WASM 工具未执行 | TS 端发起 `tool-provider` 导入，但 Python 宿主未注册对应工具 | [strands-wasm/README.md:9-13]() |
| 单语言使用需求 | 社区多次请求增加 Go/Java SDK（[#240](https://github.com/strands-agents/harness-sdk/issues/240)、[#616](https://github.com/strands-agents/harness-sdk/issues/616)），目前官方仅提供 Python 与 TypeScript | [README.md:14-26]() |
| AG-UI 集成 | 社区提议将 Strands 事件映射到 AG-UI 协议（[#140](https://github.com/strands-agents/harness-sdk/issues/140)），尚未并入主分支 | [issue #140]() |

## 11. 延伸阅读

- [Quickstart Guide](https://strandsagents.com/)
- [designs/README.md](./designs/README.md) — 设计提案流程
- [team/README.md](./team/README.md) — 内部原则、决策、API 评审与 Agent 指南
- [strands-py/README.md](./strands-py/README.md) — Python SDK 入门
- [strands-ts/README.md](./strands-ts/README.md) — TypeScript SDK 入门
- [strands-wasm/README.md](./strands-wasm/README.md) — WASM 构建与跨包开发
- Issue [#1181](https://github.com/strands-agents/harness-sdk/issues/1181) — Skills 支持
- Issue [#140](https://github.com/strands-agents/harness-sdk/issues/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/`

---

<a id='page-2'></a>

## 工具系统、模型提供商与 MCP/AG-UI 集成

### 相关页面

相关主题：[概述、Monorepo 布局与 Agent Loop 核心架构](#page-1), [多智能体编排、插件生态与双向流式语音](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [strands-py/src/strands/models/openai.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/openai.py)
- [strands-py/src/strands/models/openai_responses.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/openai_responses.py)
- [strands-py/src/strands/models/mistral.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/mistral.py)
- [strands-py/src/strands/models/__init__.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/__init__.py)
- [strands-ts/src/models/streaming.ts](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/models/streaming.ts)
- [strands-ts/src/models/model.ts](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/models/model.ts)
- [strands-py-wasm/src/strands/_generated/__init__.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py-wasm/src/strands/_generated/__init__.py)
- [strands-py-wasm/src/strands/types.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py-wasm/src/strands/types.py)
- [strands-wasm/README.md](https://github.com/strands-agents/harness-sdk/blob/main/strands-wasm/README.md)
- [strands-py/README.md](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/README.md)
- [README.md](https://github.com/strands-agents/harness-sdk/blob/main/README.md)
- [strands-ts/examples/browser-agent/README.md](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/examples/browser-agent/README.md)
- [designs/README.md](https://github.com/strands-agents/harness-sdk/blob/main/designs/README.md)
- [team/README.md](https://github.com/strands-agents/harness-sdk/blob/main/team/README.md)
</details>

# 工具系统、模型提供商与 MCP/AG-UI 集成

## 概述

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]()

---

## 工具系统（Tool System）

### 工具的角色

工具是 Agent 可调用的、带类型化 schema 的函数。模型在推理过程中会发出 `ToolUse` 块，SDK 解析后执行对应的 Python 函数，再把结果以 `ToolResult` 形式回传。工具系统由三部分构成：**装饰器**（如何定义）、**注册表**（如何索引）、**执行器**（如何运行）。

### Python `@tool` 装饰器

`@tool` 装饰器是工具系统的入口。它接受一个普通函数，并通过类型注解和文档字符串自动生成 `ToolSpec`（模型可读的 JSON Schema）。这是 Python 端最常用的工具定义方式。

```python
from strands import Agent, tool

@tool
def word_count(text: str) -> int:
    """Count the number of words in a string."""
    return len(text.split())

agent = Agent(tools=[word_count])
agent("How many words are in 'hello world'?")
```

资料来源：[README.md:54-65]()

### 工具注册表

注册表维护 Agent 可用工具的命名空间，负责把模型返回的 `ToolUse` 块路由到正确的执行函数。`strands-tools` 包中提供开箱即用的工具实现（如 `calculator`），社区和用户也可以使用 `strands-agents-tools` 引入更多工具。

```python
from strands import Agent
from strands_tools import calculator

agent = Agent(tools=[calculator])
agent("What is the square root of 1764")
```

资料来源：[strands-py/README.md:23-30]()

### 工具执行器

执行器决定了一轮推理中多个工具的调用策略。SDK 内置两种执行器：

| 执行器 | 行为 | 适用场景 |
|--------|------|----------|
| `ConcurrentToolExecutor` | 并行触发所有工具调用 | 工具之间无依赖、需要最短时延 |
| `SequentialToolExecutor` | 串行执行，保留顺序 | 工具之间有状态依赖、调试追踪 |

执行器通过 `Agent` 的 `tool_executor` 参数注入，因此可以在不改动工具实现的前提下切换并行/串行语义。

### 工具规范（ToolSpec）

`ToolSpec` 是工具的模型可读描述，由 `name`、`description`、`inputSchema`（JSON Schema）三部分组成。流式响应中的 `toolUseInputDelta` 携带的是工具输入的增量 JSON 字符串，客户端需要在累积后解析。

```typescript
export interface ToolUseInputDelta {
  type: 'toolUseInputDelta'
  input: string  // Partial JSON string
}
```

资料来源：[strands-ts/src/models/streaming.ts:20-30]()

---

## 模型提供商（Model Providers）

### 抽象基类

所有模型提供商都实现 `Model` 抽象接口，核心方法包括：

- `stream()` / `stream_async()`：发起流式推理调用
- `format_request()`：把内部消息格式转换成提供商原生请求体
- `format_chunk()`：把提供商原生事件块转换成统一的 `StreamEvent`
- `count_tokens()`：估算或原生统计 token 数量

资料来源：[strands-py/src/strands/models/__init__.py:1-25]()

### 支持的提供商

`strands-py/src/strands/models/__init__.py` 通过 `__getattr__` 实现**懒加载**，只有当用户实际引用某个提供商类时才会 import 对应的可选依赖（避免强制安装 anthropic、openai、mistralai 等库）。

```python
# str

if name == "AnthropicModel":
    from .anthropic import AnthropicModel
    return AnthropicModel
```

资料来源：[strands-py/src/strands/models/__init__.py:24-50]()

| 提供商 | 类名 | 备注 |
|--------|------|------|
| Amazon Bedrock | `BedrockModel` | 默认提供商，需 AWS 凭证与 us-west-2 模型访问 |
| Anthropic | `AnthropicModel` | 官方 Anthropic API |
| OpenAI（Chat Completions） | `OpenAIModel` | 兼容 `chat.completions.create` 接口 |
| OpenAI（Responses） | `OpenAIResponsesModel` | 使用新版 `responses` API，支持原生 token 计数 |
| Gemini | `GeminiModel` | Google Gemini |
| LiteLLM | `LiteLLMModel` | 统一 100+ 提供商的代理层 |
| Mistral | `MistralModel` | 支持流式与非流式两种调用方式 |
| Ollama | `OllamaModel` | 本地推理 |
| Llama API | `LlamaAPIModel` | Llama API 服务 |
| Llama.cpp | `LlamaCppModel` | 本地 llama.cpp 后端 |
| 自定义 | `Model` 子类 | 用户可继承基类实现任意 HTTP/SDK 提供商 |

资料来源：[strands-py/src/strands/models/__init__.py:24-50]()

### OpenAI Responses 提供商

`OpenAIResponsesModel` 与传统 `OpenAIModel`（基于 `chat.completions`）的区别在于使用 OpenAI 较新的 `responses` API。当 `config.use_native_token_count` 设为 `True` 时，它会直接调用 `client.responses.input_tokens.count()` 进行精确计数；失败时回退到估算。

```python
if self.config.get("use_native_token_count") is not True:
    return await super().count_tokens(messages, tool_specs, system_prompt, system_prompt_content)

request = self._format_request(messages, tool_specs, system_prompt)
count_tokens_fields = {"model", "input", "instructions", "tools"}
request = {k: request[k] for k in request.keys() & count_tokens_fields}
```

资料来源：[strands-py/src/strands/models/openai_responses.py:1-40]()

### Mistral 流式/非流式切换

`MistralModel` 根据 `config["stream"]` 决定走 `chat.stream_async` 还是 `chat.complete_async`。两种路径都返回统一格式的 chunk，使上层 Agent 循环不必关心提供商实现细节。

```python
if not self.config.get("stream", True):
    async with mistralai.Mistral(**self.client_args) as client:
        response = await client.chat.complete_async(**request)
        for event in self._handle_non_streaming_response(response):
            yield self.format_chunk(event)
    return

async with mistralai.Mistral(**self.client_args) as client:
    stream_response = await client.chat.stream_async(**request)
```

资料来源：[strands-py/src/strands/models/mistral.py:1-40]()

### TypeScript 端的 BaseModelConfig

在 TypeScript SDK 中，所有提供商共享 `BaseModelConfig`：

```typescript
export interface BaseModelConfig {
  modelId?: string
  maxTokens?: number
  temperature?: number
  topP?: number
  contextWindowLimit?: number
}
```

其中 `contextWindowLimit` 在 `modelId` 改变时如果原先是自动解析的，会被自动重新解析；显式设置的值会被保留。

资料来源：[strands-ts/src/models/model.ts:1-30]()

### 架构总览

```mermaid
graph TD
    A[Agent Loop] -->|stream/format_request| B[Model Provider]
    B --> C[BedrockModel]
    B --> D[AnthropicModel]
    B --> E[OpenAIModel]
    B --> F[GeminiModel]
    B --> G[MistralModel]
    B --> H[OllamaModel]
    B --> I[LiteLLMModel]
    B --> J[CustomModel]

    A -->|ToolUse block| K[Tool Registry]
    K --> L[Python @tool]
    K --> M[strands_tools]
    K --> N[MCP Server]
    K --> O[Custom Tool]

    K -->|route| P[Tool Executor]
    P --> Q[Concurrent]
    P --> R[Sequential]

    A -->|stream events| S[Event Stream]
    S --> T[AG-UI]
    S --> U[CLI / SDK Client]
```

---

## 流式响应与事件模型

### 统一事件类型

无论底层是 Bedrock、OpenAI 还是 Anthropic，SDK 都会把提供商的原生事件统一转换为以下增量类型（TypeScript 端定义）：

| 类型 | 用途 |
|------|------|
| `TextDelta` | 文本增量 |
| `ToolUseInputDelta` | 工具输入的 JSON 增量 |
| `ReasoningContentDelta` | 推理/思考内容增量（含 signature、redactedContent） |
| `CitationsDelta` | 引用增量，关联到源文本位置 |

资料来源：[strands-ts/src/models/streaming.ts:20-80]()

### Token 使用统计

```typescript
export interface Usage {
  inputTokens: number
  outputTokens: number
  totalTokens: number
  cacheReadInputTokens?: number
  cacheWriteInputTokens?: number
}
```

`accumulateUsage(target, source)` 用于在多次推理调用中累加 token 消耗。Cache 相关字段（`cacheReadInputTokens`、`cacheWriteInputTokens`）支持 prompt caching，可显著降低成本与时延。

资料来源：[strands-ts/src/models/streaming.ts:60-100]()

### 性能指标

```typescript
export interface Metrics {
  latencyMs: number
  timeToFirstByteMs?: number
}
```

`timeToFirstByteMs` 记录从请求发出到首个内容块到达的时延，常用于评估流式体验的"首字延迟"。

资料来源：[strands-ts/src/models/streaming.ts:100-115]()

---

## MCP（Model Context Protocol）集成

### 原生 MCP 支持

SDK 内置 MCP 客户端，使 Agent 能够连接到任意 MCP 服务器并把服务器上声明的工具纳入 Agent 的工具命名空间。`mcp_client.py` 负责：

- 通过 stdio / SSE / 可流式 HTTP 与 MCP 服务器建立传输
- 拉取 `list_tools` 并转换为 SDK 内部 `ToolSpec`
- 把 `ToolUse` 调用转发回 MCP 服务器执行

资料来源：[strands-py/src/strands/tools/mcp/mcp_client.py]()

### WASM 中的 MCP 导出

在 `strands-py-wasm` 的生成类型中可以看到 MCP 相关的 WIT 类型（如 `SseTransport`、`StdioTransport`），说明 WIT 契约同样覆盖了 MCP 传输层，使 WASM 内的 TypeScript Agent 也能桥接 MCP 服务器。

```python
'SessionManager',
'SseTransport',
'StdioTransport',
```

资料来源：[strands-py-wasm/src/strands/_generated/__init__.py:1-50]()

### 价值

MCP 让 Strands 可以"开箱即用"地访问生态中成千上万的预构建工具（如文件系统、GitHub、数据库连接器等），而无需在 SDK 内部为每个工具维护独立适配器。这是 Strands 区别于传统 Agent 框架的重要差异化能力。

资料来源：[strands-py/README.md:18-21]()

---

## AG-UI 集成

### 协议动机

社区讨论（Issue #140）指出，AG-UI Protocol（Agent-GUI Protocol）是一个开放的、基于事件的轻量协议，用于标准化 AI Agent 与前端应用之间的通信。提议的实现方式是把 Strands 的事件流映射到 AG-UI 事件，从而让任何兼容 AG-UI 的前端都能直接驱动一个 Strands Agent。

资料来源：社区 Issue #140（参见顶部 community_context）

### 实现建议（社区方案）

社区提议的核心是**一个映射适配层**：

- 输入：Strands 的 `StreamEvent`（`TextDelta`、`ToolUseInputDelta`、工具执行结果等）
- 输出：AG-UI 事件（`RUN_STARTED`、`TEXT_MESSAGE_CONTENT`、`TOOL_CALL_START` 等）
- 角色：作为中间件挂在 Agent 与 UI 之间，零侵入

### WASM 中"插件化"工具的伏笔

在 `strands-py-wasm/src/strands/types.py` 中可以看到 `VendedPlugin` 和 `VendedTool` 类型：

```python
VendedToolInput = VendedTool | BashTool | FileEditorTool | HttpRequestTool | NotebookTool
VendedPluginInput = VendedPlugin | AgentSkills | ContextOffloader
```

这表明 WASM 组件未来会支持把"工具"和"插件"作为可被宿主注入的实体来分发，这种插件化设计正是与 AG-UI 等协议层结合的理想载体。

资料来源：[strands-py-wasm/src/strands/types.py:1-25]()

### 浏览器中的 Agent 示例

`strands-ts/examples/browser-agent/` 展示了一个直接运行在浏览器中的 Strands Agent。用户在前端配置 API 凭证后即可与 Agent 聊天；Agent 拥有 `update_canvas` 工具，能根据自然语言指令修改 DOM。该例虽然标注"仅供演示、不可生产"（因为执行 LLM 生成的 HTML/CSS/JS 存在安全风险），但其展示了 SDK 跨前端运行的潜力。

```bash
cd strands-ts/examples/browser-agent
npm install
npm run dev
```

资料来源：[strands-ts/examples/browser-agent/README.md:1-30]()

---

## WASM 跨语言运行时

### WIT 契约

`strands-wasm` 文档描述了核心架构：TypeScript SDK 被编译为 WebAssembly 组件（`strands-agent.wasm`），Python 通过 `wasmtime-py` 加载并驱动它。WIT（WebAssembly Interface Types）契约 `wit/agent.wit` 定义了跨边界的所有交互：

- **Exports**（TS 实现，Python 调用）：`api` 接口（agent 构造、流式、对话管理）。所有模型提供商的 HTTP 调用（Bedrock、Anthropic、OpenAI、Gemini）都在 WASM guest 内发生。
- **Imports**（Python 实现，TS 回拨）：`tool-provider` 用于执行 Python 定义的工具，`host-log` 用于把日志条目路由到 Python 的 logging 框架。

资料来源：[strands-wasm/README.md:5-22]()

### Monorepo 结构

| 目录 | 语言 | 角色 |
|------|------|------|
| `wit/` | WIT | guest/host 接口契约 |
| `strands-ts/` | TypeScript | Agent 运行时：事件循环、模型提供商、工具、钩子、流式 |
| `strands-wasm/` | TypeScript | 桥接 TS SDK 到 WIT exports，编译为 WASM 组件 |
| `strands-py-wasm/` | Python | Python 包装器：Agent 类、`@tool` 装饰器、直接的 WASM host |
| `strandly/` | TypeScript | Dev CLI，编排 build / test / lint / CI |
| `dev-docs/` | Markdown | 设计提案与团队决策记录 |

资料来源：[strands-wasm/README.md:30-60]()

### 生成代码

`strandly generate` 从 `wit/agent.wit` 生成类型绑定到 `strands-ts/generated/`、`strands-wasm/generated/`、`strands-py-wasm/src/strands/_generated/`。**生成文件不应手改**；CI 会运行 `strandly generate --check`，若发现与手改差异则失败。

资料来源：[strands-wasm/README.md:60-75]()

### 数据流

```mermaid
graph LR
    User[User Code] -->|@tool decorator| PyAgent[Python Agent]
    PyAgent -->|wasmtime-py| WASM[strands-agent.wasm]
    WASM -->|api export| TSAgent[TS Event Loop]
    TSAgent -->|HTTP| Provider[Model Provider API]
    Provider -->|StreamEvent| TSAgent
    TSAgent -->|tool-provider import| PyAgent
    PyAgent -->|call user function| UserTool[User Tool]
    UserTool -->|result| PyAgent
    PyAgent -->|StreamEvent| User
```

---

## 配置与使用模式

### 安装

```bash
pip install strands-agents strands-agents-tools
```

资料来源：[strands-py/README.md:25-30]()

### 基本 Agent

```python
from strands import Agent
from strands_tools import calculator

agent = Agent(tools=[calculator])
agent("What is the square root of 1764")
```

注意：使用默认 Bedrock 提供商时，需要配置 AWS 凭证并在 us-west-2 区域启用 Claude 4 Sonnet 的模型访问。

资料来源：[strands-py/README.md:23-35]()

### Python 版本要求

Python 3.10+ 是必需基线，这是为了使用结构化类型注解与新语法特性。

资料来源：[strands-py/README.md:32-40]()

### WASM 开发引导

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

`bootstrap` 会安装工具链、把 `strandly` 链接到 PATH、生成类型绑定、构建所有层、安装 `strands-py-wasm`、并运行所有测试。

资料来源：[strands-wasm/README.md:30-50]()

---

## 常见问题与失败模式

| 症状 | 根因 | 解决 |
|------|------|------|
| `ImportError: anthropic` 等可选依赖缺失 | `__init__.py` 使用懒加载但未安装对应库 | `pip install anthropic[bedrock] openai google-generativeai ...` |
| 默认 Bedrock 调用报 AccessDenied | 未在 us-west-2 启用 Claude 4 Sonnet | 在 Bedrock 控制台申请模型访问 |
| 工具调用结果没有回流 | `ToolSpec` 的 `inputSchema` 与函数签名不匹配 | 检查类型注解和文档字符串是否被装饰器正确解析 |
| 流式响应只显示首字 | 客户端没有正确累积 `TextDelta` | 使用 `accumulateUsage` 类似的累加器逻辑 |
| `use_native_token_count=True` 时报错 | OpenAI Responses API 字段裁剪逻辑不匹配 | 检查 `_format_request` 输出是否包含 `model/input/instructions/tools` |
| WASM 启动报"stale generated" | 手动编辑了 `*_generated/` 目录 | 执行 `npm run dev -- generate` 重新生成 |

---

## 社区关注的扩展方向

| 主题 | 关注点 | 状态 |
|------|--------|------|
| Node/TypeScript SDK（Issue #156） | 让前端、IaC、后端同构 TS | 已部分通过 `strands-ts` + WASM 方案覆盖 |
| Go SDK（Issue #616） | Go 生态访问 Strands 服务 | 尚未发布（截至最新 release notes） |
| Agent Skills（Issue #1181） | 任务相关的知识文件按需加载 | 与 WIT 中的 `VendedPlugin`/`AgentSkills` 类型相关，是未来扩展方向 |
| Java SDK（Issue #240） | 企业 Java 生态集成 | 尚未发布 |
| AG-UI Protocol（Issue #140） | 标准化 Agent↔前端通信 | 社区提出"事件映射适配层"方案 |
| Python WASM v0.0.1 | 首次发布 `strands-agents-wasm` | 已发布 |

资料来源：community_context 顶部 issues 与最新发布说明

---

## 设计治理与团队约定

`designs/` 目录用于跟踪重要的 RFC 风格设计提案，模板包含 **Context / Decision / Developer Experience / Alternatives Considered / Consequences / Willingness to Implement** 六段。任何会影响公共 API 的特性都应先在 `designs/` 提交设计文档，再进入实现阶段。

资料来源：[designs/README.md:1-30]()

`team/` 目录则承载内部约定：

| 文档 | 作用 |
|------|------|
| [TENETS.md](team/TENETS.md) | 指导 SDK 设计与实现的核心原则 |
| [DECISIONS.md](team/DECISIONS.md) | 设计与 API 决策的记录（含理由） |
| [API_BAR_RAISING.md](team/API_BAR_RAISING.md) | API 变更的评审流程 |
| [AGENT_GUIDELINES.md](team/AGENT_GUIDELINES.md) | 在 Strands 仓库上操作的 AI Agent 行为约定 |

贡献者在改动 SDK 公共面之前应优先阅读这些文档。

资料来源：[team/README.md:1-30]()

---

## 参见（See Also）

- [Strands Agents 主页（README.md）](https://github.com/strands-agents/harness-sdk/blob/main/README.md)
- [Python SDK 详细文档（strands-py/README.md）](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/README.md)
- [WASM 跨语言架构（strands-wasm/README.md）](https://github.com/strands-agents/harness-sdk/blob/main/strands-wasm/README.md)
- [设计提案流程（designs/README.md）](https://github.com/strands-agents/harness-sdk/blob/main/designs/README.md)
- [团队内部约定（team/README.md）](https://github.com/strands-agents/harness-sdk/blob/main/team/README.md)
- [TypeScript 流式模型定义](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/models/streaming.ts)
- [TypeScript 模型配置](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/models/model.ts)
- [Python 模型懒加载](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/__init__.py)
- [OpenAI Responses 模型](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/openai_responses.py)
- [OpenAI Chat Completions 模型](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/openai.py)
- [Mistral 模型](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/mistral.py)
- [WASM 生成类型](https://github.com/strands-agents/harness-sdk/blob/main/strands-py-wasm/src/strands/_generated/__init__.py)
- [WASM 类型桥接](https://github.com/strands-agents/harness-sdk/blob/main/strands-py-wasm/src/strands/types.py)
- [浏览器 Agent 示例](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/examples/browser-agent/README.md)

---

<a id='page-3'></a>

## 多智能体编排、插件生态与双向流式语音

### 相关页面

相关主题：[概述、Monorepo 布局与 Agent Loop 核心架构](#page-1), [工具系统、模型提供商与 MCP/AG-UI 集成](#page-2), [部署示例、Session/Hook/Interrupt、Telemetry 与 WASM 互操作](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [strands-py/src/strands/multiagent/graph.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/multiagent/graph.py)
- [strands-py/src/strands/multiagent/swarm.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/multiagent/swarm.py)
- [strands-py/src/strands/multiagent/a2a/server.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/multiagent/a2a/server.py)
- [strands-py/src/strands/multiagent/a2a/executor.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/multiagent/a2a/executor.py)
- [strands-py/src/strands/plugins/registry.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/plugins/registry.py)
- [strands-py/src/strands/plugins/plugin.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/plugins/plugin.py)
- [strands-py/src/strands/vended_plugins/skills/agent_skills.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/vended_plugins/skills/agent_skills.py)
- [strands-py/src/strands/vended_plugins/steering/handlers/llm/llm_handler.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/vended_plugins/steering/handlers/llm/llm_handler.py)
- [strands-py/src/strands/vended_plugins/context_offloader/plugin.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/vended_plugins/context_offloader/plugin.py)
- [strands-py/src/strands/experimental/bidi/agent/agent.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/experimental/bidi/agent/agent.py)
- [strands-py/src/strands/experimental/bidi/agent/loop.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/experimental/bidi/agent/loop.py)
- [strands-py/src/strands/experimental/bidi/models/nova_sonic.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/experimental/bidi/models/nova_sonic.py)
- [strands-py-wasm/src/strands/_generated/__init__.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py-wasm/src/strands/_generated/__init__.py)
- [strands-py/src/strands/models/_validation.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/_validation.py)
- [strands-py/src/strands/models/anthropic.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/anthropic.py)
- [strands-py/src/strands/models/openai.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/openai.py)
- [strands-py/src/strands/models/openai_responses.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/openai_responses.py)
- [strands-py/src/strands/models/mistral.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/mistral.py)
- [strands-wasm/README.md](https://github.com/strands-agents/harness-sdk/blob/main/strands-wasm/README.md)
- [strands-ts/examples/browser-agent/README.md](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/examples/browser-agent/README.md)
- [designs/README.md](https://github.com/strands-agents/harness-sdk/blob/main/designs/README.md)
- [team/README.md](https://github.com/strands-agents/harness-sdk/blob/main/team/README.md)
- [README.md](https://github.com/strands-agents/harness-sdk/blob/main/README.md)
</details>

# 多智能体编排、插件生态与双向流式语音

## 概述

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]()

---

## 多智能体编排

多智能体子系统位于 `strands-py/src/strands/multiagent/`，提供两种主流的智能体协作模式：**Graph**（基于有向图）与 **Swarm**（基于群体交接）。同时通过 `a2a/` 子包提供 Agent-to-Agent 协议层，把多智能体协作扩展到进程外或网络边界之外。

### 核心数据模型

通过 WASM 生成的 Python 绑定可以确认该子系统的对外类型面：

| 类别 | 类型符号 | 用途 |
|------|----------|------|
| 编排配置 | `GraphConfig`、`SwarmConfig` | 描述图/群体的运行配置 |
| 编排生命周期 | `MultiAgentInvokeArgs`、`MultiAgentResult`、`MultiAgentStreamEvent` | 调入参、结果、流式事件 |
| 节点 | `AgentNode`、`MultiAgentNode`、`NodeConfig`、`NodeKind`、`NodeResult`、`NodeEventData`、`NodeError`、`NodeStartData` | 图/群体内节点抽象 |
| 边 | `EdgeConfig`、`EdgeHandler` | 图边与边处理函数 |
| Swarm 状态 | `HandoffEvent`、`OrchestrationStatus`、`TerminalStatus` | 群体交接事件、编排状态、终态 |

资料来源：[strands-py-wasm/src/strands/_generated/__init__.py:43-58]()

### Graph 模式

Graph 模式把多智能体协作建模为有向图：每个节点代表一个 `Agent`，边代表节点之间的执行依赖或分支条件。

```mermaid
graph TD
    U[用户输入] --> N1[Node 1: Researcher]
    N1 --> N2[Node 2: Analyzer]
    N1 --> N3[Node 3: Summarizer]
    N2 --> N4[Node 4: Aggregator]
    N3 --> N4
    N4 --> O[最终输出]
```

设计要点：

- **节点抽象**：`AgentNode` 携带 `NodeConfig`，并通过 `NodeKind` 标识节点角色；`NodeStartData`、`NodeEventData` 区分节点开始与运行中事件，`NodeResult` 暴露节点的最终产出。
- **边抽象**：`EdgeConfig` 描述静态边关系，`EdgeHandler` 提供运行期可调用的条件判断与数据传递逻辑。
- **错误传播**：节点级异常通过 `NodeError` 冒泡；整个图的状态由 `OrchestrationStatus` 持续追踪。
- **完成判断**：图结束时返回 `MultiAgentResult`，调用方依据 `TerminalStatus` 决定是否完成业务闭环。

资料来源：[strands-py-wasm/src/strands/_generated/__init__.py:43-58]()

实现位于 [strands-py/src/strands/multiagent/graph.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/multiagent/graph.py)。

### Swarm 模式

Swarm 模式以去中心化方式组织智能体：节点之间通过 *Handoff* 事件相互委派任务，不强制预设执行路径。

```mermaid
graph TD
    ORC[Orchestrator] -->|HandoffEvent| A[Agent A]
    ORC -->|HandoffEvent| B[Agent B]
    A -->|HandoffEvent| B
    B -->|HandoffEvent| ORC
    B -->|TerminalStatus| END[协作结束]
```

- 智能体之间通过 `HandoffEvent` 相互委派任务，事件在 swarm 内被广播。
- `TerminalStatus` 标志一次群体协作的结束，例如所有目标都已达成或达到迭代上限。
- 与 Graph 模式相比，Swarm 不要求开发者预设执行路径，更适合开放式协作场景。

资料来源：[strands-py-wasm/src/strands/_generated/__init__.py:43-46]()

实现位于 [strands-py/src/strands/multiagent/swarm.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/multiagent/swarm.py)。

### 智能体到智能体（A2A）

`strands-py/src/strands/multiagent/a2a/` 子包通过 `server.py` 与 `executor.py` 提供 A2A 协议层。该层使一个智能体可以作为服务端暴露给其他进程，同时也可以作为客户端调用其他智能体，从而把多智能体协作扩展到进程外或网络边界之外。其实现位于：

- [strands-py/src/strands/multiagent/a2a/server.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/multiagent/a2a/server.py)
- [strands-py/src/strands/multiagent/a2a/executor.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/multiagent/a2a/executor.py)

### 社区关注：AG-UI 协议

社区 issue #140 提出基于 [AG-UI 协议](https://github.com/ag-ui-protocol/ag-ui) 把 Strands 事件流映射到前端 GUI。AG-UI 是一种轻量级、事件驱动的智能体-前端通信协议，与 SDK 内置的 `MultiAgentStreamEvent` / `NodeEventData` 等流式事件类型天然契合——开发者可在外层构建一层事件映射器，将多智能体事件转译为 AG-UI 帧。

资料来源：[strands-py-wasm/src/strands/_generated/__init__.py:43-58]()

---

## 插件生态

Strands Agents 通过 `strands-py/src/strands/plugins/` 子系统提供可插拔的扩展点，`registry.py` 负责统一注册，`plugin.py` 定义插件接口。

### 插件接口与核心类型

| 类型 | 角色 |
|------|------|
| `VendedPlugin` | SDK 官方维护的内置插件，开发者可直接启用而无需自行编写 |
| `VendedTool` | 随插件一同发布的官方工具集，遵循与 `ToolSpec` 一致的描述协议 |
| `SkillSource` | 技能（Skill）源定位器，描述按任务应当加载哪些知识/工具集合 |
| `PluginStateEntry` | 插件持久化条目，使插件可以跨会话保留自身状态 |

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

### 内置插件矩阵

| 插件模块 | 作用 | 关键文件 |
|----------|------|----------|
| Skills | 按任务动态加载相关知识/工具 | [strands-py/src/strands/vended_plugins/skills/agent_skills.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/vended_plugins/skills/agent_skills.py) |
| Steering | 在智能体运行过程中注入 LLM 引导指令 | [strands-py/src/strands/vended_plugins/steering/handlers/llm/llm_handler.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/vended_plugins/steering/handlers/llm/llm_handler.py) |
| Context Offloader | 上下文超窗时自动卸载历史 | [strands-py/src/strands/vended_plugins/context_offloader/plugin.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/vended_plugins/context_offloader/plugin.py) |

### 技能（Skills）

社区 issue #1181 长期讨论「Agent Skills」支持方案（参见 [claude.com/blog/skills](https://claude.com/blog/skills)）。在 `strands-py-wasm/src/strands/_generated/__init__.py` 中已经可以看到 `SkillSource` 与 `NotebookTool` 两个符号，说明 SDK 已经在类型层面为按需加载技能做好准备：

```python
from strands._generated import SkillSource, NotebookTool
```

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

技能加载的核心思想是：在 `Agent` 启动或运行中，根据当前任务上下文，从一个或多个 `SkillSource` 中选取相关的 Notebook/知识/工具条目注入到工具集，从而更高效地利用上下文窗口。

### 持久化与会话管理

插件子系统还提供会话/存储抽象，与插件状态紧密耦合：

| 类型 | 角色 |
|------|------|
| `SessionManager` | 会话生命周期管理 |
| `StorageConfig` | 存储后端配置（File / S3 / Custom） |
| `FileStorage` / `S3Storage` / `CustomStorage` | 三种后端实现 |
| `Snapshot` / `SnapshotData` / `SnapshotManifest` / `SnapshotScope` | 快照与清单 |
| `ConversationManagerState` / `SlidingWindowState` / `SummarizingState` | 多种对话窗口状态 |
| `StorageError` / `TriggerError` | 存储与快照触发器异常 |

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

这意味着 `PluginStateEntry` 可以借由 `StorageConfig` 选择不同后端进行持久化，从而在多智能体编排中实现跨节点的插件状态共享。

---

## 双向流式语音（Experimental Bidi）

`strands-py/src/strands/experimental/bidi/` 路径下的模块以 `experimental` 标记，属于尚未稳定的试验性 API。其目标是让智能体能够**持续消费音频输入**并**持续产出音频/文本输出**，典型应用为实时语音助手与对话式 AI 设备。

### 模块划分

| 模块 | 职责 |
|------|------|
| `bidi/agent/agent.py` | Bidi 智能体定义，保留流式会话状态 |
| `bidi/agent/loop.py` | 持续运行的智能体循环，处理端到端事件流 |
| `bidi/models/nova_sonic.py` | Amazon Nova Sonic 语音模型的适配器 |

文件位置：

- [strands-py/src/strands/experimental/bidi/agent/agent.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/experimental/bidi/agent/agent.py)
- [strands-py/src/strands/experimental/bidi/agent/loop.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/experimental/bidi/agent/loop.py)
- [strands-py/src/strands/experimental/bidi/models/nova_sonic.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/experimental/bidi/models/nova_sonic.py)

### 数据流

```mermaid
graph TD
    Mic[麦克风音频] --> Cap[音频捕获]
    Cap --> Loop[bidi/agent/loop.py]
    Loop -->|ModelStreamEvent| Sonic[Nova Sonic 模型]
    Sonic -->|音频 + 文本增量| Loop
    Loop --> Spk[扬声器/前端]
    Loop -->|ToolEvent| Tool[工具调用]
    Tool --> Loop
```

- 输入端将原始音频分片送入 loop。
- loop 与 `nova_sonic.py` 之间通过 `ModelStreamEvent` 双向交换增量。
- 工具调用被建模为同一循环中的事件，从而保证语音流与工具流之间的时序一致性。

`ModelStreamEvent` 等流式事件符号同时出现在 [strands-py-wasm/src/strands/_generated/__init__.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py-wasm/src/strands/_generated/__init__.py) 中，说明 bidi 模型流与多智能体流共享同一套流式抽象。

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

### 浏览器端示例

`strands-ts/examples/browser-agent/` 提供了一个浏览器端 Agent 示例，演示了 LLM 实时流式响应 + 工具调用。该示例虽然使用 TypeScript 编写，但展示了"前端 ↔ 智能体流式通道"的形态——这与 bidi 模块的设计目标高度一致，为后续将 bidi 能力带到浏览器/WASM 端提供了参考实现。

资料来源：[strands-ts/examples/browser-agent/README.md:1-15]()

### 适用范围与注意事项

由于模块位于 `experimental/` 之下：

- API 可能在未来版本中调整，生产部署前应关注版本变更日志。
- Nova Sonic 模型故障（限流、网络）应通过模型层已有的异常处理风格捕获；建议在生产前增加音频编码/采样率校验。
- 由于 WASM 绑定中已经能看到 `AudioConfig` 等相关类型（参见 [strands-py-wasm/src/strands/_generated/__init__.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py-wasm/src/strands/_generated/__init__.py)），可以预期未来 bidi 也会纳入跨语言类型面。

---

## WASM 集成与跨语言支持

`strands-wasm/README.md` 描述了 TypeScript SDK 被编译为 WebAssembly 组件、由 Python 通过 `wasmtime-py` 加载执行的架构。WIT 接口 `wit/agent.wit` 划定主客边界：

- **导出**（Python 调用）：`api` 接口，包含智能体构造、流式响应、会话管理等。所有模型提供方（Bedrock、Anthropic、OpenAI、Gemini）的 HTTP 调用都在 WASM guest 内发生。
- **导入**（TS 回调 Python）：`tool-provider` 在 Python 中执行用户定义的工具；`host-log` 将日志路由到 Python 的 `logging` 框架。

```mermaid
graph TD
    subgraph Python Host
        PY[Python Agent 调用方]
        PYT[用户工具实现]
        LOG[Python logging]
    end
    subgraph WASM Guest
        TS[TS Agent Loop]
        API[api 导出]
        TOOL[tool-provider 导入]
        HOSTLOG[host-log 导入]
    end
    PY --> API
    API --> TS
    TS --> TOOL
    TOOL --> PYT
    PYT --> TOOL
    TOOL --> TS
    TS --> HOSTLOG
    HOSTLOG --> LOG
```

资料来源：[strands-wasm/README.md:1-25]()

这种组件化设计意味着 `strands-py-wasm/src/strands/_generated/__init__.py` 中同时出现 `MultiAgentNode`、`SwarmConfig`、`AudioConfig` 等类型并非偶然——它们是 WIT 接口中"跨边界契约"的一部分，主客双方需要保持一致。

社区对跨语言 SDK 的需求旺盛：

| 诉求 | 编号 | 现状 |
|------|------|------|
| TypeScript/JavaScript/NodeJS SDK | #156 | 已有 `strands-ts` 与 `strands-wasm` 双轨实现 |
| Go SDK | #616 | 暂无 |
| Java SDK | #240 | 暂无 |

WASM 组件化路线为多语言客户端复用同一份核心逻辑提供了可行路径，未来新增语言客户端时，理论上只需要实现 WIT 接口的导入侧即可。

资料来源：[strands-wasm/README.md:1-25]()

---

## 模型提供方与多智能体的衔接

虽然本页主题不展开模型细节，但多智能体/bidi 系统中的"模型"角色是绕不开的。SDK 通过统一的 `Model` 协议屏蔽了不同模型提供方之间的差异：

- `AnthropicModel` / `BedrockModel` / `GoogleModel` / `OpenaiModel` / `CustomModel`（在 [strands-py-wasm/src/strands/_generated/__init__.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py-wasm/src/strands/_generated/__init__.py) 中均可见）
- `ModelConfig`、`ModelParams`、`ModelError`：通用配置、参数与错误
- `ModelEventStream`、`ModelStreamOptions`、`StartStreamArgs`、`CountTokensArgs`：流式与计数调用面

由此，多智能体/插件/bidi 三类上层子系统可以使用同一个模型层，从而避免在编排层重复实现模型差异。具体的工具调用与系统提示词格式化在 `strands-py/src/strands/models/anthropic.py` 等文件中实现，并在生成请求前通过 `strands-py/src/strands/models/_validation.py` 提供的 `validate_config_keys`、`warn_on_tool_choice_not_supported` 等工具进行校验——例如对 Mistral 这样的提供方，传入 `ToolChoice` 会被显式忽略并发出警告。

资料来源：[strands-py/src/strands/models/_validation.py:1-15]()
资料来源：[strands-py/src/strands/models/anthropic.py:1-25]()
资料来源：[strands-py/src/strands/models/openai.py:1-25]()
资料来源：[strands-py/src/strands/models/openai_responses.py:1-15]()
资料来源：[strands-py/src/strands/models/mistral.py:1-15]()

---

## 错误模式与常见失败

| 子系统 | 异常/状态 | 触发场景 | 建议处理 |
|--------|-----------|----------|----------|
| 多智能体 | `NodeError` | 图/群体中某节点抛出未捕获异常 | 检查节点实现与 `EdgeHandler` 条件 |
| 多智能体 | `OrchestrationStatus` / `TerminalStatus` | 整个编排进入中间/终态 | 调用方轮询或订阅 `MultiAgentStreamEvent` |
| 插件/存储 | `StorageError` | `StorageConfig` 指向的后端不可用 | 切换后端或重试（结合 `RetryConfig`） |
| 插件/快照 | `TriggerError` | 快照触发器执行失败 | 复核触发条件与权限 |
| 流式 | `StreamError` | `ModelStreamEvent` / `OutputStream` 写入失败 | 检查连接与背压设置 |
| 重试 | `BackoffStrategy` / `RetryConfig` | 模型/工具调用需要退避重试 | 选用 `ExponentialBackoff`/`LinearBackoff`/`ConstantBackoff`/`JitterKind` |
| 模型配置 | `warnings.warn` | 未声明字段 / 不支持的 `tool_choice` | 参考 [strands-agents/sdk-python#815](https://github.com/strands-agents/sdk-python/issues/815) 调整 |
| Bidi | 模型限流 | Nova Sonic 节流 | 复用通用模型层异常与 `RetryConfig` |

资料来源：[strands-py/src/strands/models/_validation.py:1-15]()
资料来源：[strands-py-wasm/src/strands/_generated/__init__.py:1-130]()

---

## 设计与贡献

按照 `designs/README.md` 的约定，重大特性（影响 SDK 多部分、引入新概念、超出一周工作量）需要先在 `designs/` 下提交 RFC 式设计文档，再进入实现阶段。多智能体与 bidi 这类子系统级特性通常都符合该阈值，因此贡献者在扩展多智能体编排（例如新增 A2A 传输）、新增 Vended 插件（例如 Skills 之外的领域技能）或扩展 bidi 模型提供方之前，应当先走设计文档流程。

资料来源：[designs/README.md:1-25]()

`team/README.md` 汇总了 SDK 的设计理念、API 评审流程与 AI 代理协作规范，贡献插件前应优先阅读 `team/TENETS.md` 与 `team/API_BAR_RAISING.md`，以保证新插件的 API 形态与 SDK 主线一致。

资料来源：[team/README.md:1-15]()

---

## See Also

- 仓库总览与安装：[README.md](https://github.com/strands-agents/harness-sdk/blob/main/README.md)
- 设计提案流程：[designs/README.md](https://github.com/strands-agents/harness-sdk/blob/main/designs/README.md)
- 团队理念与决策记录：[team/README.md](https://github.com/strands-agents/harness-sdk/blob/main/team/README.md)
- WASM 组件化架构：[strands-wasm/README.md](https://github.com/strands-agents/harness-sdk/blob/main/strands-wasm/README.md)
- 跨语言类型面参考：[strands-py-wasm/src/strands/_generated/__init__.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py-wasm/src/strands/_generated/__init__.py)
- 浏览器端 Agent 示例：[strands-ts/examples/browser-agent/README.md](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/examples/browser-agent/README.md)
- 社区议题：
  - Agent Skills 支持 — #1181
  - AG-UI 协议 — #140
  - TypeScript/JS SDK — #156
  - Go SDK — #616
  - Java SDK — #240

---

<a id='page-4'></a>

## 部署示例、Session/Hook/Interrupt、Telemetry 与 WASM 互操作

### 相关页面

相关主题：[概述、Monorepo 布局与 Agent Loop 核心架构](#page-1), [多智能体编排、插件生态与双向流式语音](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/strands-agents/harness-sdk/blob/main/README.md)
- [designs/README.md](https://github.com/strands-agents/harness-sdk/blob/main/designs/README.md)
- [team/README.md](https://github.com/strands-agents/harness-sdk/blob/main/team/README.md)
- [strands-wasm/README.md](https://github.com/strands-agents/harness-sdk/blob/main/strands-wasm/README.md)
- [strands-py-wasm/src/strands/_generated/__init__.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py-wasm/src/strands/_generated/__init__.py)
- [strands-py-wasm/src/strands/types.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py-wasm/src/strands/types.py)
- [strands-py/src/strands/models/anthropic.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/anthropic.py)
- [strands-py/src/strands/models/openai.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/openai.py)
- [strands-py/src/strands/models/openai_responses.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/openai_responses.py)
- [strands-py/src/strands/models/mistral.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/mistral.py)
- [strands-py/src/strands/models/writer.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/writer.py)
- [strands-ts/src/models/streaming.ts](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/models/streaming.ts)
- [site/package.json](https://github.com/strands-agents/harness-sdk/blob/main/site/package.json)
</details>

# 部署示例、Session/Hook/Interrupt、Telemetry 与 WASM 互操作

## 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` 组件的发布形态。

```mermaid
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 协议](https://github.com/ag-ui-protocol/ag-ui) 等多语言前端协议（参见社区 #140）的全栈工程师。
- 关注 TypeScript / Go / Java 等多语言 SDK 路线图（参见社区 #156、#616、#240）的架构师。

### 1.2 仓库关键目录速览

| 目录 | 角色 | 备注 |
| --- | --- | --- |
| `strands-py/` | 传统 Python SDK | `pip install strands-agents` |
| `strands-ts/` | TypeScript SDK 源码 | 经 `strandly` 工具链构建为 WASM |
| `strands-wasm/` | WIT 桥接层 | 定义 `wit/agent.wit` 接口契约 |
| `strands-py-wasm/` | Python WASM 包装 | 通过 `wasmtime-py` 加载组件 |
| `strandly/` | Dev CLI | 编排 build、test、lint 与 CI |
| `designs/` | RFC 设计文档 | 重大特性需先提交设计 |
| `team/` | 团队内部文档 | Tenets、Decisions、API Bar |

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

---

## 2. 部署形态与快速上手

### 2.1 经典 Python 部署

仓库根 `README.md` 给出了最简部署路径：

```bash
# 安装核心包与官方工具集
pip install strands-agents strands-agents-tools
```

```python
from strands import Agent
from strands_tools import calculator

agent = Agent(tools=[calculator])
agent("What is the square root of 1764")
```

> 默认模型提供方为 Amazon Bedrock，需要在 `us-west-2` 区域启用 Claude 4 Sonnet 模型访问并配置 AWS 凭证。其他模型提供方（Anthropic、OpenAI、Gemini、LiteLLM、Llama、Ollama、Writer）的接入细节可参考官方快速开始。

资料来源：[README.md:1-40]()。

### 2.2 WASM 混合部署

`strands-wasm/README.md` 描述了 TypeScript 实现被编译成 WebAssembly 组件，再由 Python 通过 `wasmtime-py` 加载的部署形态。WIT 契约 (`wit/agent.wit`) 明确划定了边界：

- **Exports（TS 实现，Python 调用）**：`api` 接口 —— 智能体构造、流式输出、对话管理。所有模型提供方（Bedrock、Anthropic、OpenAI、Gemini）的 HTTP 调用都发生在 WASM 客机内部。
- **Imports（Python 实现，TS 回调）**：`tool-provider` 用于执行 Python 定义的工具；`host-log` 用于把日志条目路由到 Python 的 logging 框架。

```mermaid
graph TD
    Py[Python 主机<br/>strands-py-wasm] -- "invoke api.*" --> Wasm[strands-agent.wasm]
    Wasm -- "tool-provider.*" --> Tool[Python 工具函数]
    Wasm -- "host-log.*" --> Log[Python logging]
    Wasm --> HTTP[模型提供方 HTTPS]
```

资料来源：[strands-wasm/README.md:9-19]()。

### 2.3 环境准备与首次引导

`strands-wasm/README.md` 推荐的"一键开发启动"流程为：

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

`bootstrap` 步骤会完成：安装工具链 → 把 `strandly` 链接到 `PATH` → 生成类型绑定 → 构建所有层 → 安装 `strands-py-wasm` → 跑全量测试。若该命令无法让本地开发即开即用，应当作为缺陷提报。

资料来源：[strands-wasm/README.md:21-46]()。

### 2.4 CI 守门：`strandly generate --check`

`strands-wasm/README.md` 指出，`strandly generate` 产出的类型绑定分别落入：

- `strands-ts/generated/`（gitignored）
- `strands-wasm/generated/`（gitignored）
- `strands-py-wasm/src/strands/_generated/`（已纳入版本控制）

CI 会执行 `strandly generate --check`，若生成产物过期则构建失败。手工编辑 `_generated/` 在合并评审阶段就会被拦截。

资料来源：[strands-wasm/README.md:60-72]()。

---

## 3. 会话（Session）子系统

### 3.1 概念地图

会话子系统在生成绑定中以 `_generated/__init__.py` 暴露的类型为代表，覆盖了从"对话窗口管理"到"快照存储"的全链路：

| 类型 | 角色 |
| --- | --- |
| `SessionManager` | 顶层会话协调器 |
| `SlidingWindowConversationManager` / `SlidingWindowState` | 滑动窗口策略 |
| `SummarizingConversationManager` / `SummarizingState` | 自动摘要压缩策略 |
| `Snapshot` / `SnapshotData` / `SnapshotManifest` | 会话快照 |
| `SnapshotScope` / `SnapshotLocation` | 快照粒度与位置 |
| `FileStorage` / `S3Storage` / `CustomStorage` | 后端存储实现 |
| `StorageConfig` / `StorageError` | 存储配置与错误类型 |
| `SaveLatestPolicy` / `PluginStateEntry` | 保存策略与插件状态 |
| `RetryStrategyState` | 重试策略状态 |

资料来源：[strands-py-wasm/src/strands/_generated/__init__.py:1-120]()。

### 3.2 WASM 暴露的会话/工具输入别名

`strands-py-wasm/src/strands/types.py` 进一步在 `ModelInput`、`ConversationManagerInput`、`VendedToolInput`、`VendedPluginInput` 这四个别名上做了收敛，便于 Python 端只接受与 WIT 契约一致的对象：

```python
ModelInput = ModelConfig | BedrockModel | AnthropicModel | OpenaiModel | GoogleModel | CustomModel
ConversationManagerInput = ConversationManagerConfig | SlidingWindowConversationManager | SummarizingConversationManager
VendedToolInput = VendedTool | BashTool | FileEditorTool | HttpRequestTool | NotebookTool
VendedPluginInput = VendedPlugin | AgentSkills | ContextOffloader
```

资料来源：[strands-py-wasm/src/strands/types.py:1-30]()。

### 3.3 持久化后端选型

| 后端 | 适用场景 | 备注 |
| --- | --- | --- |
| `FileStorage` | 单机、调试、CI 临时会话 | 默认实现，便于本地复现 |
| `S3Storage` | 多副本、跨可用区、对象审计 | 通过 `S3Location` 描述位置 |
| `CustomStorage` | 接入公司内部对象存储 | 实现 `StorageConfig` 协议即可 |

由于 WASM 客机内部不直接持有文件系统，会话快照的 I/O 必须经由 Python 主机 `import` 接口回流，部署到 FaaS 平台时建议把 `S3Storage` 或 `CustomStorage` 配成唯一默认后端，避免依赖本地盘。

资料来源：[strands-py-wasm/src/strands/_generated/__init__.py:55-90]()。

### 3.4 快照生命周期

```mermaid
graph LR
    Start([Agent 启动]) --> Restore[LoadSnapshotArgs]
    Restore --> Run[推理/工具循环]
    Run --> Save[SaveSnapshotArgs]
    Save --> Manifest[SaveManifestArgs]
    Manifest --> Persist[(存储后端)]
    Persist --> List[ListSnapshotIdsArgs]
    List --> Delete[DeleteSessionArgs]
```

资料来源：[strands-py-wasm/src/strands/_generated/__init__.py:60-110]()。

---

## 4. Hook（钩子）系统

### 4.1 钩子事件一览

生成绑定中显式导出的钩子事件包括：

| 事件 | 触发时机 |
| --- | --- |
| `BeforeInvocationData` | Agent 入口调用前 |
| `BeforeModelCallData` | 模型请求前 |
| `BeforeToolCallData` | 工具执行前 |
| `ToolEventStream` | 工具流式事件 |
| `HandlerState` | 处理器共享状态 |

资料来源：[strands-py-wasm/src/strands/_generated/__init__.py:18-90]()。

### 4.2 典型用途

| 用途 | 推荐钩子 |
| --- | --- |
| 鉴权/审计日志 | `BeforeInvocationData` |
| 输入重写（脱敏、注入检索片段） | `BeforeModelCallData` |
| 工具白名单/黑名单 | `BeforeToolCallData` |
| 输出后处理（结构化校验、PII 过滤） | `HookRedaction`（见下节） |
| 流式中间事件 | `ToolEventStream` |

资料来源：[strands-py-wasm/src/strands/_generated/__init__.py:22-90]()。

### 4.3 重写与重定向能力

- `InputRedaction` / `OutputRedaction` 钩子用于在调用模型前后裁剪敏感字段。
- `HookRedaction` 允许在自定义钩子链路内对事件内容做就地改写，再传给下游。

资料来源：[strands-py-wasm/src/strands/_generated/__init__.py:36-92]()。

---

## 5. Interrupt（中断）子系统

### 5.1 类型清单

中断相关类型在 `_generated/__init__.py` 中以"中断-响应-回执"三件套的形式出现：

| 类型 | 角色 |
| --- | --- |
| `Interrupt` | 中断事件主体 |
| `InterruptResponseBlock` | 中断响应载荷 |
| `ElicitRequest` / `ElicitResponse` | 双向 elicit 协议 |
| `ElicitAction` | elicit 行为枚举 |
| `ElicitationError` | 错误类型 |
| `Interrupt`（同 `HandlerState` 字段） | 状态机回写点 |

资料来源：[strands-py-wasm/src/strands/_generated/__init__.py:42-90]()。

### 5.2 部署注意事项

- 中断/恢复必须与会话子系统协同：恢复时需要先把 `SessionManager` 的状态读出，再把 `InterruptResponseBlock` 灌回。
- 在 WASM 部署中，elicit 的实际数据流仍走 `tool-provider` import 回到 Python 主机，因此 `ElicitRequest` 需在 Python 侧实现"用户回执 → 工具入参"的桥接。
- 与 AG-UI 协议（社区 #140）的整合可借助 `InterruptResponseBlock` 作为 agent → front-end 的统一事件载荷，再由前端包装成 AG-UI 事件流。

资料来源：[strands-py-wasm/src/strands/_generated/__init__.py:42-90]()；社区 #140。

---

## 6. Telemetry（可观测性）

### 6.1 数据模型

| 类型 | 含义 |
| --- | --- |
| `Usage` | 输入/输出/总 token、缓存读写 token |
| `Metrics` | 延迟、首字节时间 |
| `InvocationMetrics` | 单次 Agent 调用的指标聚合 |
| `ToolMetrics` | 工具调用指标 |
| `TraceContext` / `TraceAttribute` / `TraceMetadataEntry` | 分布式追踪 |
| `RedactionEvent` | 脱敏事件 |

资料来源：[strands-py-wasm/src/strands/_generated/__init__.py:65-130]()。

### 6.2 TypeScript 侧 streaming 事件

`strands-ts/src/models/streaming.ts` 详细定义了与 `Usage`、`Metrics` 配套的事件载荷：

```ts
export interface Usage {
  inputTokens: number
  outputTokens: number
  totalTokens: number
  cacheReadInputTokens?: number
  cacheWriteInputTokens?: number
}

export interface Metrics {
  latencyMs: number
  timeToFirstByteMs?: number
}

export function accumulateUsage(target: Usage, source: Usage): void { /* ... */ }
```

资料来源：[strands-ts/src/models/streaming.ts:1-90]()。

### 6.3 流式 delta 分类

`strands-ts/src/models/streaming.ts` 还规范了几种典型 delta 事件：

| Delta 类型 | 用途 |
| --- | --- |
| `ToolUseInputDelta` | 工具输入增量 JSON |
| `ReasoningContentDelta` | 思考/推理增量，可携带签名与重写后的密文 |
| `CitationsDelta` | 引用关联内容 |
| 文本/图片/视频/文档块 | 多模态内容增量 |

资料来源：[strands-ts/src/models/streaming.ts:60-150]()。

### 6.4 与模型提供方的 token 计数路径

- `openai_responses.py` 在 `use_native_token_count` 为 `True` 时直接走 `client.responses.input_tokens.count`；若失败会回退到父类估算实现。
- `openai.py` 在 `format_request` 中统一组装 messages、tools、system prompt 字段，并保证 `tool_calls` 字段不丢失。
- `anthropic.py` 把 `tool_choice` 归一化为 Anthropic 的 `auto` / `any` / `tool` 三态。
- `mistral.py` 与 `writer.py` 都遵循"warn_on_tool_choice_not_supported"约定，对暂不支持 `tool_choice` 的提供方在日志中给出告警，而不是直接抛错。
- 多个提供方都暴露 `stream` / 非流式双通道，便于在 telemetry 维度选择上报粒度。

资料来源：[strands-py/src/strands/models/openai_responses.py:30-70]()；[strands-py/src/strands/models/openai.py:30-90]()；[strands-py/src/strands/models/anthropic.py:30-90]()；[strands-py/src/strands/models/mistral.py:30-90]()；[strands-py/src/strands/models/writer.py:30-100]()。

### 6.5 部署采集建议

| 信号 | 采集点 |
| --- | --- |
| `Usage.cacheReadInputTokens` / `cacheWriteInputTokens` | 模型流尾 |
| `Metrics.timeToFirstByteMs` | 首次 delta 到达 |
| `InvocationMetrics` | `AfterInvocation` 钩子 |
| `ToolMetrics` | `ToolEventStream` 钩子 |
| `TraceContext` | `BeforeInvocationData` 注入根 span |

资料来源：[strands-ts/src/models/streaming.ts:30-110]()；[strands-py-wasm/src/strands/_generated/__init__.py:65-130]()。

---

## 7. WASM 互操作深入

### 7.1 构建流水线总览

```mermaid
graph TD
    Src[strands-ts 源码] --> Bind[生成 WIT 绑定<br/>strandly generate]
    Bind --> WasmBuild[strands-wasm 编译]
    WasmBuild --> Comp[strands-agent.wasm]
    PyWasm[strands-py-wasm 包装] --> Host[Python 主机]
    Comp --> Host
    Host --> App[最终应用]
```

资料来源：[strands-wasm/README.md:25-72]()。

### 7.2 关键测试层级

| 层 | 框架 | 位置 |
| --- | --- | --- |
| TypeScript SDK | vitest | `strands-ts/src/**/__tests__/`（单元）、`strands-ts/test/`（集成） |
| Python 包装 | pytest | `strands-py-wasm/tests/` |

修改代码时应同步补齐测试；修复缺陷时需附上能复现原 issue 的用例。

资料来源：[strands-wasm/README.md:74-82]()。

### 7.3 与多语言 SDK 路线图的关联

| 社区议题 | 关联到 WASM 互操作的原因 |
| --- | --- |
| #156（TypeScript/NodeJS SDK） | `strands-ts` 正是当前 WASM 客机的实现来源 |
| #616（Go SDK） | WIT 契约可作为 Go 端实现的参考 |
| #240（Java SDK） | WIT 生成的 record 类型可映射为 Java record |
| #1181（Agent Skills） | `AgentSkills`、`VendedPlugin` 已在生成绑定中暴露 |
| #140（AG-UI 协议） | `ToolEventStream` / `InterruptResponseBlock` 适合作为 AG-UI 事件载体 |

资料来源：[strands-py-wasm/src/strands/types.py:10-25]()；社区讨论 #156、#616、#240、#1181、#140。

### 7.4 部署陷阱与规避

| 陷阱 | 规避手段 |
| --- | --- |
| 手工改动 `strands-py-wasm/src/strands/_generated/` | CI 守门 `strandly generate --check` 会失败 |
| 在 WASM 客机里直接调用 Python 工具 | 必须通过 `tool-provider` import |
| 让 WASM 内部访问本地文件系统 | 会话/快照 I/O 一律走 Python 主机 import |
| 忽略 `use_native_token_count` 失败回退 | 父类估算逻辑兜底，但应监控回退率 |
| 误以为多语言 SDK 已经直接发布为 pip/npm | 当前 TypeScript 仅作为 WASM 客机，NodeJS 直发包仍在 #156 路线 |

资料来源：[strands-wasm/README.md:60-82]()；[strands-py/src/strands/models/openai_responses.py:30-70]()；社区 #156。

---

## 8. 部署示例：把 Hook + Session + Telemetry 串起来

下面的伪代码综合了会话、钩子与 telemetry 三个子系统（基于已暴露的 WIT 类型），展示一次生产级调用的形状：

```python
from strands import Agent
from strands.session import SessionManager, S3Storage
from strands.hooks import HookRegistry, BeforeModelCallData, AfterInvocationData
from strands.telemetry import Tracer

tracer = Tracer(service="checkout-bot")
sessions = SessionManager(storage=S3Storage(bucket="agents-prod"))

hooks = HookRegistry()
@hooks.before_model_call
def redact_pii(event: BeforeModelCallData):
    # 通过 InputRedaction 替换敏感字段
    event.messages = scrub(event.messages)
    tracer.log("redaction.applied", count=event.redactions)

@hooks.after_invocation
def emit_metrics(event: AfterInvocationData):
    tracer.log("invocation.done",
               usage=event.usage,
               latency_ms=event.metrics.latencyMs,
               ttfb_ms=event.metrics.timeToFirstByteMs)

agent = Agent(tools=[...], session=sessions, hooks=hooks)
result = agent("复核我的订单", session_id="user-42")
```

> 上述导入路径与具体函数签名需以 `strands-py` 实际包结构为准；生成绑定里出现的 `Usage`、`Metrics`、`HookRedaction`、`RedactionEvent` 已经锁定了数据形状，跨层调用时字段名不会改变。

资料来源：[strands-py-wasm/src/strands/_generated/__init__.py:36-130]()；[strands-ts/src/models/streaming.ts:30-110]()。

---

## 9. 团队流程与设计评审

`team/README.md` 强调所有改动都要先对齐团队准则：

| 文档 | 关注点 |
| --- | --- |
| `TENETS.md` | 核心设计原则 |
| `DECISIONS.md` | 历史决策与依据 |
| `API_BAR_RAISING.md` | API 变更评审流程 |
| `AGENT_GUIDELINES.md` | AI Agent 协作约定 |

资料来源：[team/README.md:1-30]()。

`designs/README.md` 给出了提交特性设计的标准流程：

1. 检查仓库 [roadmap](https://github.com/orgs/strands-agents/projects/8/views/1)。
2. 在本仓库创建分支并新增 `designs/NNNN-feature-name.md`。
3. 通过 PR 提交评审并迭代。
4. 批准后实施，并在实现 PR 中引用设计文档。

> 模板包含 Context / Decision / Developer Experience / Alternatives Considered / Consequences / Willingness to Implement 六段，重大特性必须按该格式提交。

资料来源：[designs/README.md:1-50]()。

---

## 10. 常见失败模式与排查

| 现象 | 可能根因 | 排查路径 |
| --- | --- | --- |
| `strandly generate --check` 在 CI 失败 | `_generated/` 与 WIT 不同步 | 重新执行 `npm run dev -- bootstrap` |
| 工具调用未生效 | 工具未通过 `tool-provider` 注册 | 检查 Python 侧 `@tool` 装饰器与 `VendedToolInput` 类型 |
| S3 快照写入失败 | 凭据或桶策略缺失 | 关注 `StorageError` 与 `S3Location` 序列化结果 |
| Token 计数偏低/偏高 | `use_native_token_count` 异常回退 | 检查 `openai_responses.py` 调试日志 |
| Interrupt 恢复卡死 | `ElicitResponse` 未回填至 `HandlerState` | 在 `BeforeInvocationData` 注入并核对 `InterruptResponseBlock` |
| 多语言 SDK 找不到 | 当前仅发布 Python 与 WASM 包装 | 跟踪社区 #156 / #616 / #240 |

资料来源：[strands-wasm/README.md:60-82]()；[strands-py/src/strands/models/openai_responses.py:30-70]()；[strands-py-wasm/src/strands/_generated/__init__.py:42-130]()；社区 #156、#616、#240。

---

## 11. 后续路线与延伸阅读

- **Anthropic Skills 支持**：社区 #1181 关注将 `AgentSkills` 接入 SDK；生成绑定已经预留 `AgentSkills` / `VendedPlugin`，但具体加载机制仍在设计中。
- **多语言 SDK**：#156（Node/TS）、#616（Go）、#240（Java）都希望复用 `strands-wasm` 的 WIT 契约。
- **AG-UI 前端协议**：#140 提出把 Strands 事件映射为 AG-UI，可借助 `ToolEventStream` 与 `InterruptResponseBlock` 落地。
- **Pyodide/WASM 化发布**：`strands-py-wasm` v0.0.1 已经首发，可在受限环境（无服务器函数、浏览器）运行。

资料来源：[strands-py-wasm/src/strands/types.py:10-25]()；社区 #1181、#156、#616、#240、#140。

---

## See Also

- [README.md](https://github.com/strands-agents/harness-sdk/blob/main/README.md) — 顶层特性、安装与快速开始。
- [strands-wasm/README.md](https://github.com/strands-agents/harness-sdk/blob/main/strands-wasm/README.md) — WASM 构建与互操作细节。
- [designs/README.md](https://github.com/strands-agents/harness-sdk/blob/main/designs/README.md) — 重大特性 RFC 流程。
- [team/README.md](https://github.com/strands-agents/harness-sdk/blob/main/team/README.md) — Tenets / Decisions / API Bar。
- [strands-py-wasm/src/strands/types.py](https://github.com/strands-agents/harness-sdk/blob/main/strands-py-wasm/src/strands/types.py) — WASM 类型别名与对外契约。
- [strands-ts/src/models/streaming.ts](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/models/streaming.ts) — 流式事件与 Telemetry 数据模型。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: strands-agents/harness-sdk; human_manual_source: deepwiki_human_wiki -->