# https://github.com/2FastLabs/agent-squad 项目说明书

生成时间：2026-06-21 12:42:38 UTC

## 目录

- [项目概览](#page-overview)
- [Src 模块](#page-python-src)
- [Src 模块](#page-typescript-src)
- [Src 模块](#page-typescript-src-common-src)

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

## 项目概览

### 相关页面

相关主题：[Src 模块](#page-python-src)

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

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

- [README.md](https://github.com/2FastLabs/agent-squad/blob/main/README.md)
- [examples/text-2-structured-output/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/text-2-structured-output/README.md)
- [examples/ecommerce-support-simulator/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/ecommerce-support-simulator/README.md)
- [examples/chat-demo-app/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/chat-demo-app/README.md)
- [examples/langfuse-demo/readme.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/langfuse-demo/readme.md)
- [python/src/agent_squad/types/__init__.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/types/__init__.py)
- [python/src/agent_squad/agents/bedrock_llm_agent.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_llm_agent.py)
- [python/src/agent_squad/agents/bedrock_inline_agent.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_inline_agent.py)
- [typescript/src/classifiers/classifier.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/classifiers/classifier.ts)
- [typescript/src/retrievers/retriever.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/retrievers/retriever.ts)
- [typescript/src/agents/comprehendFilterAgent.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/agents/comprehendFilterAgent.ts)
</details>

# 项目概览

## 一、项目定位与核心价值

Agent Squad（原名 Multi-Agent Orchestrator）是一个用于管理多个 AI Agent 并处理复杂对话的灵活框架。该框架能够根据上下文和内容将查询动态路由到最合适的 Agent，同时跨多个 Agent 维护对话上下文以保证交互的连贯性 [README.md:1-100]()。

项目的核心价值体现在以下几个方面：

- **智能意图分类**：通过 Classifier 组件分析用户输入，并结合 Agent 特征与历史对话选择最合适的处理单元 [README.md:80-100]()。
- **双语言实现**：框架同时提供 Python 与 TypeScript 两种实现，便于不同技术栈的团队集成 [README.md:60-80]()。
- **灵活的响应模式**：支持流式（streaming）和非流式（non-streaming）两种响应方式 [README.md:60-80]()。
- **可扩展架构**：允许用户轻松集成新 Agent 或自定义现有 Agent，并提供多种预构建组件 [README.md:60-80]()。
- **通用部署能力**：可运行于 AWS Lambda、本地环境或任何云平台 [README.md:60-80]()。

该项目适用于从简单聊天机器人到复杂 AI 系统的多种应用场景。

## 二、高层架构与处理流程

Agent Squad 的核心处理流程由四个步骤组成，如下 Mermaid 图所示：

```mermaid
flowchart TD
    A[用户输入] --> B[Classifier 分类器]
    B --> C{选择最合适的 Agent}
    C --> D[目标 Agent 处理]
    D --> E[更新对话历史]
    E --> F[返回响应给用户]
    B -.使用.-> G[Agent 特征]
    B -.使用.-> H[对话历史]
```

1. 用户输入首先由 Classifier 进行分析 [README.md:80-100]()。
2. Classifier 利用 Agent 特征（Agents' Characteristics）和历史对话（Agents' Conversation history）选择最合适的 Agent [README.md:80-100]()。
3. 被选中的 Agent 处理用户输入 [README.md:80-100]()。
4. 编排器（Orchestrator）保存对话、更新历史，然后将响应返回给用户 [README.md:80-100]()。

在 TypeScript 端，分类器提示模板要求模型提取意图、关键实体、置信度以及是否属于后续对话（Is Followup）等结构化字段 [typescript/src/classifiers/classifier.ts:1-50]()。当用户输入简短回答（如"yes""ok"）时，会被视为后续对话并保持上一次的 Agent 选择 [typescript/src/classifiers/classifier.ts:40-50]()。

## 三、核心组件与扩展能力

### 3.1 Agent 类型与提供商

项目内置了多种 Agent 实现，Python 端通过 `AgentTypes` 与 `AgentProviderType` 等枚举统一抽象了不同模型提供商的接入方式 [python/src/agent_squad/types/__init__.py:1-30]()。预置模型常量包括：

| 模型常量 | 说明 |
|---------|------|
| `BEDROCK_MODEL_ID_CLAUDE_3_HAIKU` | Bedrock 上的 Claude 3 Haiku |
| `BEDROCK_MODEL_ID_CLAUDE_3_SONNET` | Bedrock 上的 Claude 3 Sonnet |
| `BEDROCK_MODEL_ID_CLAUDE_3_5_SONNET` | Bedrock 上的 Claude 3.5 Sonnet |
| `BEDROCK_MODEL_ID_LLAMA_3_70B` | Bedrock 上的 Llama 3 70B |
| `OPENAI_MODEL_ID_GPT_O_MINI` | OpenAI GPT-o-mini |
| `ANTHROPIC_MODEL_ID_CLAUDE_3_5_SONNET` | Anthropic Claude 3.5 Sonnet |

资料来源：[python/src/agent_squad/types/__init__.py:3-15]()。

### 3.2 BedrockLLMAgent 与推理能力

`BedrockLLMAgent` 是其中一个核心实现，它支持流式响应并在响应块中区分 `text` 与 `reasoningContent`（推理内容）[python/src/agent_squad/agents/bedrock_llm_agent.py:1-50]()。当检测到 `reasoningContent` 中的文本时，会通过 `AgentStreamResponse(thinking=...)` 单独输出思考过程，便于上层应用展示链式推理 [python/src/agent_squad/agents/bedrock_llm_agent.py:10-30]()。同时它还支持工具调用（`toolUse`）的解析与多轮执行 [python/src/agent_squad/agents/bedrock_llm_agent.py:40-60]()。

### 3.3 BedrockInlineAgent 与工具处理

`BedrockInlineAgent` 允许在运行时通过 `inline_agent_creation` 工具动态创建子 Agent。其处理器 `inline_agent_tool_handler` 会解析 `action_group_names`、`knowledge_bases`、`description` 和 `user_request` 等参数 [python/src/agent_squad/agents/bedrock_inline_agent.py:1-40]()。这与社区中 #339 提出的"为 Anthropic 和 Bedrock 增加 think 工具"的需求相呼应——通过 `reasoningContent` 字段已能提供结构化思考空间 [python/src/agent_squad/agents/bedrock_llm_agent.py:15-30]()。

### 3.4 内容过滤与检索器

TypeScript 端提供了 `ComprehendFilterAgent`，使用 Amazon Comprehend 进行情感分析、PII 检测和毒性检测，可通过 `sentimentThreshold`、`toxicityThreshold` 等阈值进行调优 [typescript/src/agents/comprehendFilterAgent.ts:1-40]()。此外，框架定义了抽象的 `Retriever` 基类，子类必须实现 `retrieveAndGenerate(text)` 方法 [typescript/src/retrievers/retriever.ts:1-20]()。

## 四、典型应用场景与社区关注点

### 4.1 电商与结构化输出示例

电商支持模拟器（`ecommerce-support-simulator`）展示了三个核心 Agent：订单管理（Claude 3 Sonnet + 订单查询/物流跟踪/退货处理工具）、产品信息（Claude 3 Haiku + 知识库检索）以及人工坐席（基于 SQS）[examples/ecommerce-support-simulator/README.md:1-60]()。`text-2-structured-output` 示例则演示了如何将自然语言转换为结构化 JSON 用于产品搜索 [examples/text-2-structured-output/README.md:1-30]()。

### 4.2 可观测性集成

社区在 #152 中提出了将追踪数据发送到 Langfuse 等可观测性框架的需求。`langfuse-demo` 示例给出了完整方案：追踪整个用户对话、为每个 Agent 交互创建 Span，并记录分类决策、置信度、Token 使用和响应时间 [examples/langfuse-demo/readme.md:1-30]()。这表明框架本身已具备基础可观测性扩展点。

### 4.3 模型上下文协议（MCP）

社区在 #299 中询问 MCP 支持情况，目前仓库尚未正式集成 MCP Server，但 `BedrockInlineAgent` 的工具处理机制为后续接入 MCP 提供了天然的扩展点——只需在工具处理器中分发到 MCP 客户端即可 [python/src/agent_squad/agents/bedrock_inline_agent.py:15-40]()。

## See Also

- [examples/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/README.md) — 全部示例应用索引
- [CONTRIBUTING.md](https://github.com/2FastLabs/agent-squad/blob/main/CONTRIBUTING.md) — 贡献与 Issue-First 策略
- [LICENSE](https://github.com/2FastLabs/agent-squad/blob/main/LICENSE) — Apache 2.0 许可证

---

<a id='page-python-src'></a>

## Src 模块

### 相关页面

相关主题：[项目概览](#page-overview), [Src 模块](#page-typescript-src)

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

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

- [python/src/agent_squad/types/__init__.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/types/__init__.py)
- [python/src/agent_squad/agents/bedrock_inline_agent.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_inline_agent.py)
- [python/src/agent_squad/agents/bedrock_llm_agent.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_llm_agent.py)
- [python/src/agent_squad/agents/bedrock_translator_agent.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_translator_agent.py)
- [typescript/src/agents/bedrockLLMAgent.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/agents/bedrockLLMAgent.ts)
- [typescript/src/classifiers/classifier.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/classifiers/classifier.ts)
- [typescript/src/retrievers/retriever.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/retrievers/retriever.ts)
</details>

# Src 模块

## 概述

`Src` 模块是 Agent Squad（曾用名 Multi-Agent Orchestrator）框架的核心源代码目录，分别以 **Python** 和 **TypeScript** 双语言实现。该模块承载了整个多代理编排系统的核心抽象，包括代理（Agent）实现、分类器（Classifier）、检索器（Retriever）以及共享类型定义。根据项目仓库根目录 [README.md](https://github.com/2FastLabs/agent-squad/blob/main/README.md) 描述，框架采用「分类器选取代理 → 代理处理 → 会话存储」的流程，所有这些能力均由 `src/` 下的源码提供。

框架源码采用分层组织方式：

| 语言 | 主要子目录 | 职责 |
|------|-----------|------|
| Python | `python/src/agent_squad/agents/` | 各类 Agent 实现（Bedrock、Anthropic、Inline、Translator 等） |
| Python | `python/src/agent_squad/types/` | 共享数据类型与会话消息结构 |
| TypeScript | `typescript/src/agents/` | 与 Python 对应的 Agent 实现 |
| TypeScript | `typescript/src/classifiers/` | 意图分类器抽象与实现 |
| TypeScript | `typescript/src/retrievers/` | 知识库检索抽象 |

## Python 端 Agent 实现

`python/src/agent_squad/agents/` 目录提供了多种预构建 Agent，所有类均继承自基类 `Agent`，并实现统一的对话接口。

### BedrockLLMAgent

`bedrock_llm_agent.py` 是最常用的代理实现，负责调用 AWS Bedrock 上的 Claude、Llama 等大模型。它通过 `converse` 流式接口处理工具调用（Tool Use），并将模型返回的 `reasoningContent` 抽取为 `thinking` 字段单独暴露，便于上层做链式思考渲染。资料来源：[python/src/agent_squad/agents/bedrock_llm_agent.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_llm_agent.py) 中 `elif "reasoningContent" in delta:` 段落实现了对 Anthropic 思考内容的区分。该能力与社区 #339 「Add "think" tool capability」诉求契合——框架已原生支持 `thinking` 字段透出。

### BedrockInlineAgent

`bedrock_inline_agent.py` 实现了对 Bedrock Inline Agent 能力的封装，允许 Agent 在运行时动态创建子代理。该文件在初始化时构建 `prompt_template`，将 `knowledge_bases` 与动作组（Action Group）注入到系统提示中，并在 `inline_agent_tool_handler` 中拦截 `inline_agent_creation` 工具调用，从而递归派生子代理。资料来源：[python/src/agent_squad/agents/bedrock_inline_agent.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_inline_agent.py) 中 `if tool_use_name == "inline_agent_creation":` 分支展示了工具委派流程。该模块的 `enableTrace` 标志位为后续接入 Langfuse 等可观测性平台提供了切入点（社区 #152 长期关注此方向）。

### BedrockTranslatorAgent

`bedrock_translator_agent.py` 是一个轻量级、面向单一任务（翻译）的代理示例。它通过强制工具选择（`toolChoice.tool.name = "Translate"`）让模型把结果以结构化 JSON 输出，从而保证翻译结果的可解析性。资料来源：[python/src/agent_squad/agents/bedrock_translator_agent.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_translator_agent.py) 中 `'toolChoice': {"tool": {"name": "Translate"}}` 段落表明该代理使用了「强制工具调用」模式。

## TypeScript 端实现

TypeScript 版本与 Python 保持 API 语义对齐，便于跨语言迁移。

### Bedrock LLM Agent（TS）

`typescript/src/agents/bedrockLLMAgent.ts` 中的 `formatTools` 方法负责把框架内部的 `AgentTools` 数据结构映射成 Bedrock `toolSpec` 格式；`getToolName` 与 `getToolId` 则提供对工具调用块的解析能力。资料来源：[typescript/src/agents/bedrockLLMAgent.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/agents/bedrockLLMAgent.ts) 中 `private formatTools(tools: AgentTools)` 方法实现了 Bedrock 工具规范的格式化逻辑。

### Classifier 抽象

`typescript/src/classifiers/classifier.ts` 定义了分类器的提示词模板，要求模型输出 `selected_agent`、`confidence` 与 `Is Followup` 等结构化字段，并对简短回复（如「yes」「ok」）统一视作追问，保持会话连续性。资料来源：[typescript/src/classifiers/classifier.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/classifiers/classifier.ts) 中 `For short responses like "yes", "ok"...` 段落说明了追问处理规则。

### Retriever 抽象

`typescript/src/retrievers/retriever.ts` 是一个抽象基类，定义了 `retrieveAndGenerate(text)` 接口，所有具体的 Knowledge Base 检索器（如 `AmazonKnowledgeBasesRetriever`）必须实现该方法。资料来源：[typescript/src/retrievers/retriever.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/retrievers/retriever.ts) 中 `abstract retrieveAndGenerate(text: any): Promise<any>;` 表明这是所有检索器的统一契约。

## 类型系统与会话消息

`python/src/agent_squad/types/__init__.py` 集中导出了框架的公共类型，包括：

- `ConversationMessage`：对话消息
- `ParticipantRole`：参与方角色（USER / ASSISTANT / SYSTEM / TOOL）
- `TimestampedMessage`：带时间戳的消息
- `AgentTypes`：代理类型枚举
- `AgentSquadConfig`、`AgentProviderType`：编排器配置
- 多个模型 ID 常量（如 `BEDROCK_MODEL_ID_CLAUDE_3_5_SONNET`、`OPENAI_MODEL_ID_GPT_O_MINI`、`ANTHROPIC_MODEL_ID_CLAUDE_3_5_SONNET`）

资料来源：[python/src/agent_squad/types/__init__.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/types/__init__.py) 中 `__all__` 列表完整暴露了上述公共 API。

## 整体数据流

下图展示了从用户输入到代理响应的完整数据流：

```mermaid
sequenceDiagram
    participant U as 用户
    participant C as Classifier
    participant A as Agent
    participant T as Tool/KB
    U->>C: 提交消息 + 历史
    C-->>U: 返回 selected_agent + confidence
    U->>A: 转发至选定 Agent
    A->>T: 可选调用 Tool / retrieveAndGenerate
    T-->>A: 返回工具结果或检索结果
    A-->>U: 流式输出（含 thinking / text）
```

## 参见

- [README.md](https://github.com/2FastLabs/agent-squad/blob/main/README.md) — 框架总体介绍与架构图
- [examples/chat-demo-app/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/chat-demo-app/README.md) — 演示应用的代理配置示例
- [examples/ecommerce-support-simulator/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/ecommerce-support-simulator/README.md) — 多代理电商客服系统示例
- [examples/langfuse-demo/readme.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/langfuse-demo/readme.md) — 可观测性集成示例（回应社区 #152）
- [examples/text-2-structured-output/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/text-2-structured-output/README.md) — 自然语言到结构化输出的示例

---

<a id='page-typescript-src'></a>

## Src 模块

### 相关页面

相关主题：[Src 模块](#page-python-src), [Src 模块](#page-typescript-src-common-src)

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

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

- [python/src/agent_squad/types/__init__.py](https://github.com/2fastlabs/agent-squad/blob/main/python/src/agent_squad/types/__init__.py)
- [python/src/agent_squad/agents/bedrock_llm_agent.py](https://github.com/2fastlabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_llm_agent.py)
- [python/src/agent_squad/agents/bedrock_inline_agent.py](https://github.com/2fastlabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_inline_agent.py)
- [python/src/agent_squad/agents/bedrock_translator_agent.py](https://github.com/2fastlabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_translator_agent.py)
- [typescript/src/agents/bedrockLLMAgent.ts](https://github.com/2fastlabs/agent-squad/blob/main/typescript/src/agents/bedrockLLMAgent.ts)
- [typescript/src/classifiers/classifier.ts](https://github.com/2fastlabs/agent-squad/blob/main/typescript/src/classifiers/classifier.ts)
- [typescript/src/retrievers/retriever.ts](https://github.com/2fastlabs/agent-squad/blob/main/typescript/src/retrievers/retriever.ts)
</details>

# Src 模块

## 概述

`Src` 模块是 Agent Squad 框架的核心源代码目录,采用 **Python 与 TypeScript 双语言并行实现** 的策略,为多智能体编排系统提供基础构建块。该模块由 `agents`（智能体实现）、`classifiers`（意图分类器）、`retrievers`（检索器）、`types`（共享类型定义）等子包组成,共同支撑从查询路由到智能体调度的完整链路。资料来源：[README.md:1-50]()

模块的入口类型与配置常量集中暴露在 `types/__init__.py` 中,包括 `ConversationMessage`、`ParticipantRole`、`AgentTypes` 等核心数据结构,以及 `BEDROCK_MODEL_ID_CLAUDE_3_HAIKU`、`OPENAI_MODEL_ID_GPT_O_MINI` 等预置模型 ID。资料来源：[python/src/agent_squad/types/__init__.py:1-35]()

## 子模块结构

| 子目录 | 职责 | 代表文件 |
|--------|------|----------|
| `agents/` | 各类智能体实现（Bedrock、Anthropic、Lex、Inline Agent 等） | `bedrock_llm_agent.py` |
| `classifiers/` | 意图分类与智能体路由决策 | `classifier.ts` |
| `retrievers/` | 知识库检索与生成（RAG）抽象 | `retriever.ts` |
| `types/` | 跨语言共享的数据类型与枚举 | `types/__init__.py` |

## 智能体实现（Agents）

`bedrock_llm_agent.py` 是最常用的智能体实现,基于 AWS Bedrock `converse` / `converse_stream` API 封装而成。该实现支持**流式响应**与**非流式响应**两种模式,并在流式处理中区分 `text` 与 `reasoningContent` 两种增量事件——后者对应 Anthropic 模型的"思考"过程,可被单独 yield 为 `AgentStreamResponse(thinking=...)`。资料来源：[python/src/agent_squad/agents/bedrock_llm_agent.py:1-60]()

工具调用（Tool Use）的格式化为 Bedrock 协议:

```python
{
    "toolSpec": {
        "name": tool.name,
        "description": tool.description,
        "inputSchema": {
            "json": {
                "type": "object",
                "properties": tool.properties,
                "required": tool.required,
            }
        }
    }
}
```

该映射逻辑在 TypeScript 端 `bedrockLLMAgent.ts` 的 `formatTools` 方法中保持一致,体现了**双语言实现的 API 兼容性**。资料来源：[typescript/src/agents/bedrockLLMAgent.ts:1-30]()

`bedrock_inline_agent.py` 引入了"内联智能体"（Inline Agent）模式,允许主智能体在运行时通过 `inline_agent_creation` 工具动态创建子智能体,并将其加入 `action_group_names` 与 `knowledge_bases` 配置。`enableTrace` 选项可用于开启调用追踪,为社区 #152 提出的可观测性需求（如 Langfuse 集成）提供基础钩子。资料来源：[python/src/agent_squad/agents/bedrock_inline_agent.py:1-50]()

`bedrock_translator_agent.py` 演示了**工具强制调用模式**（Forced Tool Use）:通过 `toolChoice.tool.name="Translate"` 强制模型将输出收敛到指定工具,从而保证返回结构稳定且符合翻译场景的契约约束。资料来源：[python/src/agent_squad/agents/bedrock_translator_agent.py:1-30]()

## 分类器与检索器

`classifier.ts` 中的系统提示词规定了分类输出需包含 `userinput`、`selected_agent`、`confidence` 三个字段,并要求分类器综合考虑**智能体特性**与**会话历史**。对于简短回答（如 "yes"、"ok"）,分类器需将其识别为前一会话的 follow-up,保持原智能体选择。资料来源：[typescript/src/classifiers/classifier.ts:1-50]()

`retriever.ts` 提供了检索增强生成（RAG）的抽象基类,所有具体检索器（如 `AmazonKnowledgeBasesRetriever`）必须实现 `retrieveAndGenerate(text)` 方法,从而在保持接口一致性的同时允许接入不同的向量数据库或知识库后端。资料来源：[typescript/src/retrievers/retriever.ts:1-15]()

## 架构流程

```mermaid
flowchart LR
    A[用户输入] --> B[Classifier]
    B --> C{路由决策}
    C -->|匹配| D[BedrockLLMAgent]
    C -->|匹配| E[AnthropicAgent]
    C -->|匹配| F[BedrockInlineAgent]
    D --> G[Tool Execution]
    E --> G
    F --> H[Knowledge Base]
    G --> I[响应返回]
    H --> I
    I --> J[更新会话历史]
```

## 失败模式与注意事项

- **工具输入解析失败**:当 `contentBlockStop` 事件中 `tool_use["input"]` 为空字符串时,流式处理会跳过该工具块,可能导致工具未被调用。资料来源：[python/src/agent_squad/agents/bedrock_llm_agent.py:30-45]()
- **分类歧义**:短输入可能被错误路由,需通过自定义 `Classifier` 提示词或提高 follow-up 检测的鲁棒性缓解。资料来源：[typescript/src/classifiers/classifier.ts:20-40]()
- **思考内容流式中断**:当 `reasoningContent` 中仅有 `signature` 而无 `text` 时,需注意累加器 `accumulated_thinking` 的状态保留。资料来源：[python/src/agent_squad/agents/bedrock_llm_agent.py:15-25]()

## 另请参阅

- [README.md](https://github.com/2fastlabs/agent-squad/blob/main/README.md) — 框架总览与架构图
- [examples/langfuse-demo/readme.md](https://github.com/2fastlabs/agent-squad/blob/main/examples/langfuse-demo/readme.md) — 可观测性集成示例（回应社区 #152）
- [examples/ecommerce-support-simulator/README.md](https://github.com/2fastlabs/agent-squad/blob/main/examples/ecommerce-support-simulator/README.md) — 多智能体电商支持系统参考实现

---

<a id='page-typescript-src-common-src'></a>

## Src 模块

### 相关页面

相关主题：[Src 模块](#page-typescript-src)

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

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

- [README.md](https://github.com/2FastLabs/agent-squad/blob/main/README.md)
- [python/src/agent_squad/types/__init__.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/types/__init__.py)
- [python/src/agent_squad/agents/bedrock_llm_agent.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_llm_agent.py)
- [python/src/agent_squad/agents/bedrock_translator_agent.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_translator_agent.py)
- [python/src/agent_squad/agents/bedrock_inline_agent.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_inline_agent.py)
- [typescript/src/agents/bedrockLLMAgent.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/agents/bedrockLLMAgent.ts)
- [typescript/src/classifiers/classifier.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/classifiers/classifier.ts)
- [typescript/src/retrievers/retriever.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/retrievers/retriever.ts)
- [examples/chat-demo-app/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/chat-demo-app/README.md)
- [examples/langfuse-demo/readme.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/langfuse-demo/readme.md)
- [examples/text-2-structured-output/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/text-2-structured-output/README.md)

</details>

# Src 模块

## 项目概述与目录布局

Agent Squad（曾用名 Multi-Agent Orchestrator）是一个用于管理多个 AI 代理并维护多轮会话上下文的灵活框架，仓库同时提供 Python 与 TypeScript 两种实现 资料来源：[README.md:1-20]()。两套语言版本的源码都集中在各自语言下的 `src/` 目录中，其中：

- Python 端源码入口为 `python/src/agent_squad/`，核心子包包括 `agents/`、`classifiers/`、`retrievers/`、`types/` 等；
- TypeScript 端源码入口为 `typescript/src/`，其结构与 Python 端保持一一对应。

这种"双语言平行布局"使同一份架构思想可以在 AWS Lambda、Cloud Functions、Node 服务以及本地环境等多种运行时中复用 资料来源：[README.md:30-45]()。

## 核心子模块组成

### 类型与公共模型

`python/src/agent_squad/types/__init__.py` 集中导出框架运行所依赖的全部公共类型与模型常量，包括 `ConversationMessage`、`ParticipantRole`、`TimestampedMessage`、`RequestMetadata`、`ToolInput`、`AgentTypes`，以及预置的 Bedrock / OpenAI / Anthropic 模型 ID 列表 资料来源：[python/src/agent_squad/types/__init__.py:1-30]()。这些类型在两套语言实现之间通过手动镜像的方式保持一致，是跨语言数据交换的基础。

### Agents 子模块

Agents 子模块负责把"单个可执行代理"封装成统一接口。Python 端实现了多种专用代理，例如：

- `BedrockLLMAgent`：基于 AWS Bedrock Converse API，支持工具调用、流式输出以及对 `reasoningContent`（即"思考"内容）文本和 `signature` 的分流处理 资料来源：[python/src/agent_squad/agents/bedrock_llm_agent.py:1-25]()；
- `BedrockTranslatorAgent`：通过强制 `toolChoice` 指定 `Translate` 工具的方式实现受控翻译流程 资料来源：[python/src/agent_squad/agents/bedrock_translator_agent.py:1-30]()；
- `BedrockInlineAgent`：支持将多个 Action Group 与 Knowledge Base 注入到单个 Bedrock Inline Agent 中 资料来源：[python/src/agent_squad/agents/bedrock_inline_agent.py:1-20]()。

TypeScript 端的 `bedrockLLMAgent.ts` 通过 `formatTools` 把 `AgentTools` 转换为 Bedrock `toolSpec` 结构，从而在协议层面与 Python 端保持一致 资料来源：[typescript/src/agents/bedrockLLMAgent.ts:1-25]()。

### Classifiers 与 Retrievers

`typescript/src/classifiers/classifier.ts` 定义了系统提示词模板，要求模型按 `userinput / selected_agent / confidence / intent / key_entities / need_rag` 等结构化字段返回分类结果，并明确把会话历史与"是否 follow-up"纳入决策 资料来源：[typescript/src/classifiers/classifier.ts:1-30]()。Retrievers 则在 `typescript/src/retrievers/retriever.ts` 中以抽象类 `Retriever` 形式暴露 `retrieveAndGenerate` 接口，便于后续挂接知识库 资料来源：[typescript/src/retrievers/retriever.ts:1-10]()。

## 架构与请求流向

```mermaid
flowchart LR
    User[用户输入] --> Orchestrator[Orchestrator]
    Orchestrator --> Classifier[Classifier]
    Classifier -->|选择 Agent| Agent[Agents/* 子模块]
    Agent -->|Tool / RAG| Retriever[Retrievers]
    Agent --> Bedrock[(AWS Bedrock)]
    Bedrock --> Agent
    Agent --> Orchestrator
    Orchestrator --> User
```

一次完整请求的流向是：用户输入首先进入 Orchestrator，再交给 Classifier 进行意图分类，分类结果会同时参考"代理特征"与"代理历史"以选择最合适的 Agent 资料来源：[README.md:55-75]()。被选中的 Agent 通过 Bedrock 完成推理，必要时调用 Retriever 或自定义工具，最终由 Orchestrator 写回历史并把回复返回用户 资料来源：[examples/chat-demo-app/README.md:1-25]()。

## 扩展点与社区关注点

源码为扩展预留了三类主要入口：新增 Agent 类型、新增 Classifier 实现、新增 Retriever 实现。`examples/text-2-structured-output/` 演示了如何在 Orchestrator 之上注册多个专用代理并自定义输出结构 资料来源：[examples/text-2-structured-output/README.md:1-15]()。在可观测性方面，社区强烈希望把 Orchestrator 与各 Agent 的 trace 推送到 Langfuse 等外部平台，仓库已提供 `examples/langfuse-demo/` 作为参考实现 资料来源：[examples/langfuse-demo/readme.md:1-20]()。另外，Issue #339 提议在 `BedrockLLMAgent` 中引入 Anthropic 的 "think" 工具能力，这与 `bedrock_llm_agent.py` 中已对 `reasoningContent` 文本和 `signature` 进行分流解析的代码路径直接相关 资料来源：[python/src/agent_squad/agents/bedrock_llm_agent.py:1-25]()。社区还在跟踪 Issue #299，期望将 MCP Servers/Tools 接入到 Agents 子模块中作为新的扩展点。

## 总结

`src/` 模块是 Agent Squad 框架的核心实现层，通过 `types/`、`agents/`、`classifiers/`、`retrievers/` 四个子模块的清晰切分，为 Python 与 TypeScript 双语言提供一致的多代理编排能力。开发者若需扩展新模型、新工具或新分类策略，只需遵循既有抽象基类并注册到 Orchestrator 即可。

---

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

---

## Doramagic 踩坑日志

项目：2FastLabs/agent-squad

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/2FastLabs/agent-squad | host_targets=claude

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/2FastLabs/agent-squad | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/2FastLabs/agent-squad | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/2FastLabs/agent-squad | no_demo; severity=medium

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

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/2FastLabs/agent-squad | no_demo; severity=medium

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

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/2FastLabs/agent-squad | issue_or_pr_quality=unknown

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

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/2FastLabs/agent-squad | release_recency=unknown

<!-- canonical_name: 2FastLabs/agent-squad; human_manual_source: deepwiki_human_wiki -->