# https://github.com/camel-ai/camel 项目说明书
生成时间：2026-05-13 14:07:02 UTC
## 目录
- [项目简介](#page-overview)
- [快速入门指南](#page-quickstart)
- [系统架构设计](#page-architecture)
- [智能体(Agents)](#page-agents)
- [模型集成(Models)](#page-models)
- [工具集(Toolkits)](#page-toolkits)
- [MCP协议集成](#page-mcp)
- [智能体社会(Societies)](#page-societies)
- [智能体劳动力(Workforce)](#page-workforce)
- [记忆系统(Memory)](#page-memory)
## 项目简介
### 相关页面
相关主题：[快速入门指南](#page-quickstart), [系统架构设计](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [examples/usecases/codeforces_question_solver/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/codeforces_question_solver/README.md)
- [examples/usecases/multi_agent_research_assistant/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/multi_agent_research_assistant/README.md)
- [examples/usecases/aci_mcp/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/aci_mcp/README.md)
- [examples/usecases/airbnb_mcp/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/airbnb_mcp/README.md)
- [examples/usecases/cloudfare_mcp_camel/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/cloudfare_mcp_camel/README.md)
- [examples/usecases/chat_with_youtube/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/chat_with_youtube/README.md)
- [examples/usecases/youtube_ocr/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/youtube_ocr/README.md)
- [examples/usecases/pptx_toolkit_usecase/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/pptx_toolkit_usecase/README.md)
# 项目简介
## 项目概述
CAMEL（Communicative Agents for Multi-Agent Learning）是一个开源的多智能体推理框架，旨在通过多智能体协作的方式实现复杂任务的自动化处理。该项目由CAMEL-AI团队开发和维护，作为一个多智能体系统的核心基础设施，为开发者提供了构建、部署和管理智能代理应用的完整解决方案。
CAMEL框架的核心价值在于其**角色扮演机制**（Role Playing）和**自主协作能力**。通过定义不同的智能代理角色，框架能够模拟真实世界中的团队协作场景，使多个AI代理能够像人类团队一样进行分工合作、问题讨论和决策制定。资料来源：[examples/usecases/multi_agent_research_assistant/README.md]()
## 核心设计理念
### 多智能体协作范式
CAMEL采用了一种创新的多智能体协作范式，其核心理念是将复杂任务分解为多个子任务，分配给具有不同专业能力的智能代理来协同完成。这种设计模式借鉴了人类社会中的团队协作模式，每个代理都扮演特定的角色，承担相应的职责，并通过标准化的通信机制进行信息交换和任务协调。
框架支持灵活的代理配置，开发者可以根据实际需求定义代理的数量、角色属性、专业能力和工具集。这种高度可定制化的设计使得CAMEL能够适应各种复杂的应用场景，从简单的问答系统到复杂的多步骤任务执行都能够得到良好的支持。
### 自主任务规划
CAMEL框架内置了强大的自主任务规划能力。当给定一个高层次的任务目标时，框架能够自动分析任务需求，将其分解为可执行的子步骤，并协调多个代理逐步完成。这种端到端的自动化能力大大降低了开发者的工作负担，无需手动定义每个执行步骤的细节。
## 技术架构
CAMEL项目采用了模块化的架构设计，将核心功能划分为多个独立且可组合的组件。
### 系统架构图
```mermaid
graph TD
A[用户应用层] --> B[Agent 管理层]
B --> C[工具包 Toolkit 层]
B --> D[模型交互层]
B --> E[运行时 Runtime 层]
C --> F[Browser Toolkit]
C --> G[MCP 集成]
C --> H[第三方服务集成]
D --> I[OpenAI API]
D --> J[Gemini API]
D --> K[Mistral API]
E --> L[Docker Runtime]
E --> M[云端 Runtime]
```
### 核心组件说明
| 组件名称 | 功能描述 | 依赖关系 |
|---------|---------|---------|
| Agent 管理层 | 管理代理的创建、生命周期和状态 | 依赖模型交互层 |
| Toolkit 层 | 提供各类工具和MCP集成能力 | 被Agent管理层调用 |
| 模型交互层 | 统一封装多种大语言模型API | 被Agent管理层使用 |
| 运行时层 | 提供容器化和云端执行环境 | 支撑整个框架运行 |
资料来源：[examples/usecases/aci_mcp/README.md]()
## 核心功能特性
### 1. 角色扮演系统
CAMEL的角色扮演系统允许开发者为每个代理定义独特的角色属性，包括专业领域、行为模式、沟通风格等。这种设计使得代理能够扮演各种角色，如研究员、开发者、审核员等，形成完整的团队协作结构。
角色定义支持丰富的配置选项，包括系统提示词（System Prompt）、温度参数、工具权限等。框架提供了便捷的API来创建和管理这些角色，使得复杂的多代理场景配置变得简单直观。
### 2. 工具集成生态
CAMEL建立了一个丰富的工具集成生态系统，为代理提供了强大的外部能力支持。
#### 主要工具包类型
| 工具类别 | 功能描述 | 典型应用场景 |
|---------|---------|--------------|
| Browser Toolkit | 浏览器自动化操作 | 网页内容抓取、表单填写 |
| MCP 集成 | 模型上下文协议支持 | 标准化工具调用 |
| PPTX Toolkit | PowerPoint 生成 | 自动演示文稿制作 |
| OCR Toolkit | 文字识别 | 图像和PDF内容提取 |
| 视频处理工具 | 音视频内容分析 | YouTube 内容分析 |
资料来源：[examples/usecases/pptx_toolkit_usecase/README.md]()
### 3. MCP 服务器支持
CAMEL全面支持 Anthropic 的模型上下文协议（Model Context Protocol），这使得框架能够与各种外部服务和工具进行标准化集成。通过MCP协议，开发者可以轻松地将CAMEL代理与外部系统连接，扩展代理的能力边界。
框架提供了便捷的MCP服务器配置机制，支持本地和远程服务器的配置和管理。开发者可以通过JSON配置文件定义多个MCP服务器，框架会自动处理服务器连接和消息路由。
#### MCP 集成架构
```mermaid
graph LR
A[CAMEL Agent] <--> B[MCP Client]
B <--> C[MCP Server]
C --> D[Cloudflare 服务]
C --> E[Airbnb 服务]
C --> F[ACI.dev 服务]
C --> G[自定义服务]
```
资料来源：[examples/usecases/airbnb_mcp/README.md]()
### 4. 多平台集成
CAMEL框架展示了与多种第三方平台的深度集成能力。
#### 支持的平台类型
| 平台名称 | 集成方式 | 功能特性 |
|---------|---------|---------|
| Firecrawl | API 集成 | 网页抓取和数据提取 |
| YouTube | 视频处理 | 字幕提取、OCR分析 |
| Mistral | OCR 处理 | PDF和图像文字识别 |
| Cloudflare | MCP 协议 | 文档查询、Radar数据、浏览器 |
| Airbnb | MCP 协议 | 房源搜索和信息查询 |
| GitHub | API 集成 | 代码仓库对话和分析 |
资料来源：[examples/usecases/chat_with_youtube/README.md]()
## 应用场景
### 代码问题求解
CAMEL可以用于自动解决编程问题。通过整合网络搜索和代码分析能力，多个代理协作完成从问题理解到解决方案生成的完整流程。
### 学术研究报告生成
多代理系统可以协同完成复杂的研究任务：研究员代理负责收集资料，分析师代理处理数据，作家代理生成报告内容，审核代理进行质量把控。这种流水线式的协作模式大大提高了研究效率。
### 自动化演示文稿制作
CAMEL的PPTX Toolkit能够根据用户提供的topic自动生成专业的演示文稿，支持多种幻灯片类型，包括标题页、步骤说明、表格对比、图片展示等。
### 智能网页交互
通过Browser Toolkit和Cloudflare MCP集成，CAMEL代理能够执行复杂的网页操作，包括表单填写、内容搜索、数据提取等任务。
### 视频内容分析
整合YouTube视频处理能力和OCR技术，代理可以分析视频内容、提取字幕信息、回答关于视频内容的问题。
## 部署方式
### Docker 运行时环境
CAMEL支持Docker容器化部署，提供了完整的Dockerfile和运行环境管理脚本。开发者可以快速构建包含CAMEL框架及其依赖的容器镜像，实现一致的开发部署体验。
### 云端服务集成
框架设计了云端运行时支持，能够在远程服务器上执行代理任务。这种设计特别适合需要大量计算资源的场景，以及需要长时间运行的任务。
### 本地开发环境
开发者可以直接在本地Python环境中安装CAMEL包进行开发和测试。框架支持虚拟环境管理，便于项目隔离和依赖管理。
## 开发工具支持
### Streamlit 应用模板
CAMEL提供了多个基于Streamlit的示例应用，展示了如何快速构建交互式的多代理应用界面。这些应用模板覆盖了从简单的聊天界面到复杂的数据分析仪表盘等场景。
### Gradio 部署支持
框架支持将代理应用部署到Hugging Face Spaces等Gradio托管平台，提供了相应的部署脚本和配置指南。
### 数据探索工具
CAMEL附带的数据浏览器工具允许开发者可视化探索CAMEL框架生成的各类数据集，便于调试和结果分析。
## 技术依赖
CAMEL框架的核心依赖包括：
- **Python 版本**：3.10 或 3.12
- **核心包**：streamlit、rich、pydantic
- **AI 模型**：OpenAI GPT系列、Google Gemini、Mistral、各类开源模型
- **工具库**：yt-dlp（视频处理）、ffmpeg（音视频处理）、tesseract（OCR）
资料来源：[examples/usecases/mistral_OCR/README.md]()
## 项目组织结构
```
camel/
├── camel/ # 核心框架代码
│ ├── toolkits/ # 工具包实现
│ ├── agents/ # 代理实现
│ └── runtime/ # 运行时支持
├── examples/ # 示例应用
│ ├── usecases/ # 各类使用场景
│ └── runtimes/ # 运行时示例
├── services/ # 微服务组件
├── apps/ # 应用程序示例
└── README.md # 项目文档
```
## 总结
CAMEL作为一个开源的多智能体推理框架，提供了完整的解决方案来构建基于大语言模型的智能代理系统。其核心优势包括：
- **灵活的代理配置**：支持自定义角色和协作模式
- **丰富的工具集成**：覆盖浏览器自动化、MCP协议、文档处理等多个领域
- **多样的部署选项**：支持Docker、本地和云端部署
- **活跃的社区生态**：持续更新的示例和最佳实践
CAMEL的设计理念和实现方案为开发者提供了一个强大的基础平台，使得构建复杂的多代理应用变得更加简单和高效。无论是学术研究还是工业应用，CAMEL都展现出了广泛的适用性和巨大的发展潜力。
---
## 快速入门指南
### 相关页面
相关主题：[项目简介](#page-overview), [智能体(Agents)](#page-agents)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/get_started/installation.md](https://github.com/camel-ai/camel/blob/main/docs/get_started/installation.md)
- [docs/get_started/setup.md](https://github.com/camel-ai/camel/blob/main/docs/get_started/setup.md)
- [.env.example](https://github.com/camel-ai/camel/blob/main/.env.example)
- [examples/agents/create_chat_agent.py](https://github.com/camel-ai/camel/blob/main/examples/agents/create_chat_agent.py)
- [examples/usecases/codeforces_question_solver/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/codeforces_question_solver/README.md)
- [examples/usecases/multi_agent_research_assistant/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/multi_agent_research_assistant/README.md)
- [examples/usecases/aci_mcp/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/aci_mcp/README.md)
# 快速入门指南
CAMEL（Communicative Agents Framework）是一个多智能体协作框架，旨在通过角色扮演和任务分解实现复杂的 AI 驱动工作流。本指南将帮助您快速了解如何安装、配置并运行 CAMEL 项目。
## 环境要求
| 要求 | 最低版本 | 推荐版本 |
|------|----------|----------|
| Python | 3.10 | 3.12 |
| Docker | 最新稳定版 | 最新稳定版 |
| pip | 22.0+ | 最新 |
CAMEL 支持多种运行环境，包括本地 Python 环境、Docker 容器以及云端部署。资料来源：[docs/get_started/installation.md](https://github.com/camel-ai/camel/blob/main/docs/get_started/installation.md)
## 安装方式
### 方式一：pip 直接安装
```bash
pip install camel-ai
```
### 方式二：安装完整依赖（含所有工具包）
```bash
pip install camel-ai[all]
```
### 方式三：从源码安装
```bash
git clone https://github.com/camel-ai/camel.git
cd camel
pip install -e .
```
资料来源：[docs/get_started/installation.md](https://github.com/camel-ai/camel/blob/main/docs/get_started/installation.md)
## 环境配置
### 配置环境变量
CAMEL 使用 `.env` 文件管理 API 密钥和其他配置。创建项目根目录下的 `.env` 文件：
```env
OPENAI_API_KEY=your_openai_api_key
FIRECRAWL_API_KEY=your_firecrawl_api_key
ACI_API_KEY=your_aci_api_key
GEMINI_API_KEY=your_gemini_api_key
```
> 注意：确保将 `.env` 文件加入 `.gitignore`，避免密钥泄露。资料来源：[.env.example](https://github.com/camel-ai/camel/blob/main/.env.example)
### 模型配置
CAMEL 支持多种模型平台：
| 平台 | 模型类型 | 配置方式 |
|------|----------|----------|
| OpenAI | GPT-4, GPT-3.5 | API Key |
| Google Gemini | Gemini Pro | GEMINI_API_KEY |
| ModelScope | Qwen 系列 | ModelScope API |
| OpenAI 兼容 | 自定义模型 | URL + API Key |
资料来源：[examples/runtimes/ubuntu_docker_runtime/README.md](https://github.com/camel-ai/camel/blob/main/examples/runtimes/ubuntu_docker_runtime/README.md)
## 基础使用示例
### 创建对话代理
CAMEL 的核心是 `ChatAgent`，用于创建可进行对话交互的 AI 代理：
```python
from camel.agents import ChatAgent
from camel.configs import ChatAgentConfig
from camel.models import ModelFactory
from camel.types import ModelPlatformType
# 配置模型
model = ModelFactory.create(
model_platform=ModelPlatformType.OPENAI,
model_type="gpt-4o"
)
# 创建代理配置
agent_config = ChatAgentConfig()
# 创建代理实例
agent = ChatAgent(
model=model,
agent_config=agent_config
)
# 运行对话
response = agent.step("你好，请介绍一下你自己")
print(response.msgs[0].content)
```
资料来源：[examples/agents/create_chat_agent.py](https://github.com/camel-ai/camel/blob/main/examples/agents/create_chat_agent.py)
### 多智能体协作
CAMEL 支持多智能体角色扮演和协作：
```python
from camel.agents import RolePlayingAgent
from camel.models import ModelFactory
from camel.types import ModelPlatformType, RoleType
# 创建助手指务
assistant_agent = RolePlayingAgent(
role_type=RoleType.ASSISTANT,
model=model,
)
# 创建用户代理
user_agent = RolePlayingAgent(
role_type=RoleType.USER,
model=model,
)
```
## 运行示例应用
### 使用 Streamlit 运行应用
CAMEL 提供了多个示例应用，使用 Streamlit 作为前端界面：
```bash
# 进入示例目录
cd examples/usecases/multi_agent_research_assistant
# 安装依赖
pip install -r requirements.txt
# 配置环境变量
cp .env.template .env
# 编辑 .env 文件填入 API 密钥
# 启动应用
streamlit run app.py
```
资料来源：[examples/usecases/multi_agent_research_assistant/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/multi_agent_research_assistant/README.md)
### 使用 Docker 运行
对于需要隔离环境的场景，可以使用 Docker：
```bash
cd examples/runtimes/ubuntu_docker_runtime
# 构建镜像
chmod +x manage_camel_docker.sh
./manage_camel_docker.sh build
# 验证镜像
docker images | grep my-camel
```
资料来源：[examples/runtimes/ubuntu_docker_runtime/README.md](https://github.com/camel-ai/camel/blob/main/examples/runtimes/ubuntu_docker_runtime/README.md)
## 工作流程概览
```mermaid
graph TD
A[安装 CAMEL] --> B[配置环境变量]
B --> C[选择运行方式]
C --> D[本地 Python]
C --> E[Streamlit 应用]
C --> F[Docker 容器]
D --> G[运行示例代码]
E --> H[启动 Web 服务]
F --> I[容器内运行]
G --> J[开发自定义代理]
H --> J
I --> J
J --> K[集成到项目]
```
## 常见应用场景
| 场景 | 说明 | 示例目录 |
|------|------|----------|
| 多智能体研究助手 | 自动生成研究报告 | multi_agent_research_assistant |
| 代码问题求解 | Codeforces/LeetCode | codeforces_question_solver |
| 文档生成 | PowerPoint 演示文稿 | pptx_toolkit_usecase |
| OCR 文档处理 | PDF/图片文字提取 | mistral_OCR |
| MCP 集成 | 第三方服务集成 | aci_mcp, cloudfare_mcp_camel |
资料来源：[examples/usecases/codeforces_question_solver/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/codeforces_question_solver/README.md)
## 下一步
- 深入阅读 [安装指南](./installation.md) 了解详细的安装选项
- 查看 [设置文档](./setup.md) 了解高级配置
- 探索 [示例项目](../examples/) 获取更多使用案例
- 参考 [API 文档](../api/) 了解完整的接口说明
## 故障排除
### 常见问题
| 问题 | 解决方案 |
|------|----------|
| 模块导入错误 | 确保已安装 `camel-ai==0.2.61` 或最新版本 |
| API Key 错误 | 检查 `.env` 文件中的密钥是否正确 |
| Docker 构建失败 | 确保 Docker 已启动并具有足够权限 |
| Python 版本不兼容 | 使用 Python 3.10 或 3.12 |
> 提示：使用 `--debug` 模式运行可以获得详细的日志输出，便于问题排查。资料来源：[examples/usecases/airbnb_mcp/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/airbnb_mcp/README.md)
---
## 系统架构设计
### 相关页面
相关主题：[项目简介](#page-overview), [智能体(Agents)](#page-agents), [模型集成(Models)](#page-models)
相关源码文件
以下源码文件用于生成本页说明：
- [camel/types/enums.py](https://github.com/camel-ai/camel/blob/main/camel/types/enums.py)
- [camel/schemas/base.py](https://github.com/camel-ai/camel/blob/main/camel/schemas/base.py)
- [camel/messages/base.py](https://github.com/camel-ai/camel/blob/main/camel/messages/base.py)
- [camel/utils/commons.py](https://github.com/camel-ai/camel/blob/main/camel/utils/commons.py)
- [camel/toolkits/hybrid_browser_toolkit/ts/src/browser-session.ts](https://github.com/camel-ai/camel/blob/main/camel/toolkits/hybrid_browser_toolkit/ts/src/browser-session.ts)
- [camel/toolkits/hybrid_browser_toolkit/ts/src/config-loader.ts](https://github.com/camel-ai/camel/blob/main/camel/toolkits/hybrid_browser_toolkit/ts/src/config-loader.ts)
- [examples/usecases/multi_agent_research_assistant/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/multi_agent_research_assistant/README.md)
- [examples/runtimes/ubuntu_docker_runtime/README.md](https://github.com/camel-ai/camel/blob/main/examples/runtimes/ubuntu_docker_runtime/README.md)
# 系统架构设计
## 概述
CAMEL（Communicative Agents for Multi-Agent Learning）是一个多智能体协作框架，旨在实现自主协作的AI智能体系统。该框架的核心设计理念是通过角色扮演和任务分解，让多个AI智能体能够自主协作完成复杂任务。
系统架构采用模块化设计，涵盖核心类型系统、消息处理、服务层、工具包集成以及运行时环境等多个层次。这种分层架构确保了系统的可扩展性、可维护性和灵活性。
## 核心架构层次
CAMEL系统的整体架构可以分为以下几个核心层次：
```mermaid
graph TD
A[应用层] --> B[服务层]
B --> C[核心框架层]
C --> D[工具包层]
D --> E[运行时层]
A1[Apps] --> A
A2[Examples] --> A
B1[Agent Services] --> B
B2[MCP Servers] --> B
C1[Types/Enums] --> C
C2[Schemas] --> C
C3[Messages] --> C
C4[Utils] --> C
D1[Browser Toolkit] --> D
D2[其他Toolkits] --> D
E1[Docker Runtime] --> E
E2[Python Runtime] --> E
```
## 类型系统与枚举定义
### 枚举类型架构
类型系统是整个框架的基础，定义了框架内部使用的各种枚举类型和常量。这些枚举类型贯穿于整个框架的各个模块，确保了类型安全性和一致性。
枚举模块定义了智能体类型、模型类型、消息角色、任务状态等核心概念。框架使用这些枚举来规范化各个模块之间的数据交互和状态管理。
### 基础类型定义
基础类型定义了框架中使用的核心数据结构，包括智能体配置、模型参数、工具定义等。这些类型为上层的Schema和Message系统提供了类型支撑。
## Schema系统
### 基础Schema架构
Schema系统是CAMEL框架的核心数据模型层。它定义了智能体、任务、消息等核心实体 的数据结构规范。基础Schema类提供了通用的数据验证和序列化功能，确保数据的一致性和完整性。
### Schema组件关系
```mermaid
graph LR
A[BaseSchema] --> B[AgentSchema]
A --> C[TaskSchema]
A --> D[ToolSchema]
B --> E[角色定义]
B --> F[模型配置]
B --> G[系统提示]
C --> H[任务描述]
C --> I[任务状态]
C --> J[任务结果]
D --> K[工具名称]
D --> L[工具参数]
D --> M[工具描述]
```
## 消息系统
### 消息类型与结构
消息系统是智能体之间通信的核心机制。框架定义了多种消息类型，包括用户消息、助手消息、系统消息等。每种消息类型都有其特定的用途和处理流程。
消息基类定义了消息的基本结构，包括消息ID、内容、时间戳、发送者、接收者等字段。消息系统还支持消息的嵌套和引用，使得复杂的对话结构能够被正确表示和处理。
### 消息流转机制
```mermaid
graph TD
A[User Message] --> B[Message Handler]
B --> C{Message Type}
C -->|Agent Message| D[Agent Processing]
C -->|System Message| E[System Processing]
C -->|Tool Message| F[Tool Processing]
D --> G[Response Generation]
E --> H[System Response]
F --> I[Tool Execution]
G --> J[Message Queue]
H --> J
I --> J
J --> K[Message History]
```
## 工具包层
### 浏览器工具包架构
混合浏览器工具包是CAMEL框架中功能强大的工具之一，它提供了浏览器自动化能力。该工具包采用TypeScript实现，提供了完整的浏览器会话管理功能。
浏览器工具包的核心组件包括浏览器会话管理、元素定位与交互、页面快照与差异检测、配置文件加载等模块。这些组件协同工作，实现了类似Playwright的浏览器自动化功能。
### 配置系统
浏览器工具包使用TypeScript类型定义配置文件结构，支持以下核心配置项：
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| headless | boolean | true | 是否无头模式运行 |
| stealth | StealthConfig | - | 反检测配置 |
| navigationTimeout | number | 30000 | 导航超时时间（毫秒） |
| networkIdleTimeout | number | 5000 | 网络空闲超时（毫秒） |
| screenshotTimeout | number | 15000 | 截图超时时间（毫秒） |
| pageStabilityTimeout | number | 1500 | 页面稳定检测超时 |
反检测配置进一步细分为用户代理、视口尺寸、语言设置等参数，确保浏览器行为尽可能接近真实用户。资料来源：[camel/toolkits/hybrid_browser_toolkit/ts/src/config-loader.ts:1-50]()
### 元素交互机制
浏览器工具包实现了智能的元素定位和交互机制。当页面元素发生动态变化时，系统能够自动检测并定位新的元素。交互过程包括以下步骤：
1. 接收交互指令和目标元素引用
2. 获取当前页面快照
3. 尝试在快照中定位目标元素
4. 如果定位失败，检测页面变化
5. 根据页面差异推断新元素位置
6. 执行交互操作
```mermaid
graph TD
A[Fill Interaction] --> B[Find Element by Ref]
B --> C{Found?}
C -->|Yes| D[Check if Input/Textarea]
C -->|No| E[Wait for Page Diff]
D --> F{Fillable?}
F -->|Yes| G[Execute Fill]
F -->|No| H[Search by Placeholder]
E --> I[Get New Element]
I --> D
G --> J[Check for Dropdowns]
H --> D
J --> K[Return Result]
```
浏览器会话模块负责维护页面的DOM快照，并通过快照差异检测来跟踪页面动态变化。这种机制特别适用于处理SPA（单页应用）和动态加载内容的场景。资料来源：[camel/toolkits/hybrid_browser_toolkit/ts/src/browser-session.ts:1-80]()
## 服务层架构
### Agent服务
Agent服务是框架的核心服务层，负责管理智能体的生命周期和任务执行。服务层提供了统一的接口来创建、配置和调度智能体任务。
服务层支持多种运行时环境，包括Python原生运行时和Docker容器运行时。Docker运行时特别适用于需要隔离执行环境的场景，例如需要特定依赖或系统配置的任务。
### MCP服务器集成
模型上下文协议（MCP）服务器集成允许CAMEL框架连接外部工具和服务。框架通过配置文件管理MCP服务器的连接，支持动态添加和移除服务器。
MCP服务器配置结构如下：
```json
{
"mcpServers": {
"server_name": {
"command": "npx",
"args": ["-y", "@package/mcp-server"]
}
}
}
```
支持的MCP服务器类型包括：
| 服务器类型 | 用途 | 配置方式 |
|------------|------|----------|
| Airbnb | 房源搜索与预订 | npx命令 |
| Cloudflare | 文档查询、雷达数据、浏览器 | SSE远程 |
| ACI | 应用集成与自动化 | API调用 |
| Firecrawl | 网页抓取与数据提取 | API调用 |
## 应用层组件
### 应用目录结构
CAMEL框架的应用层包含多个展示应用和工具应用，结构清晰，便于扩展和维护。
典型应用目录结构：
```
apps/
├── agents/ # 角色扮演API的Gradio演示应用
├── data_explorer/ # 数据集浏览工具
└── README.md
examples/
├── usecases/ # 各场景使用案例
│ ├── multi_agent_research_assistant/
│ ├── codeforces_question_solver/
│ ├── chat_with_github/
│ ├── pptx_toolkit_usecase/
│ ├── mistral_ocr/
│ └── ...
└── runtimes/ # 运行时环境示例
└── ubuntu_docker_runtime/
```
### 多智能体研究助手
多智能体研究助手是一个完整的研究报告生成应用，展示了CAMEL框架在复杂任务中的应用能力。该应用整合了多个智能体角色：
- **研究者智能体**：负责搜索学术论文和最新新闻
- **作者智能体**：负责撰写和编辑报告内容
- **可视化智能体**：可选，负责生成配图
应用流程：
1. 用户输入研究主题
2. 研究者智能体搜索相关信息
3. 聚合信息传递给作者智能体
4. 生成完整报告并保存
5. 可选：生成配图并准备社交媒体内容
资料来源：[examples/usecases/multi_agent_research_assistant/README.md:1-50]()
## 运行时环境
### Docker运行时
Docker运行时环境为框架提供了隔离、可复现的执行环境。该环境特别适用于需要特定系统依赖或需要避免环境冲突的场景。
Docker运行时架构包括：
- **Dockerfile**：定义运行时环境配置
- **管理脚本**：自动化构建和容器管理
- **Python客户端**：与Docker容器内的服务通信
```mermaid
graph TD
A[Host Python Client] --> B[Docker Container]
B --> C[CAMEL Runtime]
B --> D[API Server]
C --> E[Model Services]
D --> F[REST API]
A -->|RPC/API| F
```
### 运行时配置
运行时支持多种模型平台配置，包括OpenAI兼容模型、本地模型等。配置示例：
```python
model = ModelFactory.create(
model_platform=ModelPlatformType.OPENAI_COMPATIBLE_MODEL,
model_type="Qwen/Qwen2.5-72B-Instruct",
url='https://api-inference.modelscope.cn/v1/'
)
```
资料来源：[examples/runtimes/ubuntu_docker_runtime/README.md:1-80]()
## 工具包集成
### 工具包类型概览
CAMEL框架提供了丰富的工具包集成，涵盖多个领域的自动化能力：
| 工具包 | 功能 | 依赖 |
|--------|------|------|
| HybridBrowserToolkit | 浏览器自动化 | Playwright |
| PPTXToolkit | PowerPoint生成 | python-pptx |
| 图像生成工具包 | AI图像生成 | DALL·E/Pexels API |
| OCR工具包 | 文档识别 | Mistral OCR |
| 搜索工具包 | 网络信息检索 | Firecrawl |
### 工具包使用模式
工具包通过统一的接口集成到智能体系统中。每个工具包都定义了清晰的能力边界和参数规范，智能体可以根据任务需求选择合适的工具。
工具调用流程：
1. 任务分析：智能体分析任务需求
2. 工具选择：从可用工具包中选择合适工具
3. 参数准备：根据工具规范准备调用参数
4. 执行调用：通过统一接口执行工具
5. 结果处理：解析返回结果并继续任务
## 扩展机制
### 定制化配置
CAMEL框架支持通过配置文件定制各种行为：
- **智能体配置**：修改`agent_config.py`中的模型参数和系统消息
- **工具配置**：通过`mcp_servers_config.json`管理外部工具连接
- **环境配置**：通过`.env`文件管理API密钥和运行时参数
### 自定义工具包
开发者可以通过继承基础工具包类来创建自定义工具包：
```python
class CustomToolkit(BaseToolkit):
def __init__(self, config: CustomConfig):
super().__init__()
self.config = config
def get_tools(self) -> List[FunctionCallingRecord]:
return [
FunctionCallingRecord(func=self.custom_function)
]
```
## 总结
CAMEL框架的架构设计体现了多智能体系统的核心原则：
- **模块化设计**：各层职责清晰，便于维护和扩展
- **类型安全**：通过TypeScript和Python类型系统确保代码质量
- **灵活集成**：通过MCP和工具包机制支持多种外部服务
- **运行时隔离**：Docker支持确保环境一致性
- **配置驱动**：通过配置文件实现行为定制
这种架构使得开发者能够快速构建复杂的多智能体应用，同时保持代码的可维护性和可扩展性。
---
## 智能体(Agents)
### 相关页面
相关主题：[系统架构设计](#page-architecture), [模型集成(Models)](#page-models), [工具集(Toolkits)](#page-toolkits), [记忆系统(Memory)](#page-memory)
相关源码文件
以下源码文件用于生成本页说明：
- [camel/agents/base.py](https://github.com/camel-ai/camel/blob/main/camel/agents/base.py)
- [camel/agents/chat_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/chat_agent.py)
- [camel/agents/critic_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/critic_agent.py)
- [camel/agents/embodied_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/embodied_agent.py)
- [camel/agents/repo_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/repo_agent.py)
- [camel/agents/task_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/task_agent.py)
- [camel/agents/_types.py](https://github.com/camel-ai/camel/blob/main/camel/agents/_types.py)
# 智能体(Agents)
## 概述
CAMEL-AI 框架中的智能体(Agents)是实现多智能体协作的核心组件。智能体是具有特定角色、能力和工具的自主实体，能够执行对话、推理、搜索等多样化任务。CAMEL 采用角色扮演(Role-Playing)架构，让不同类型的智能体相互协作完成复杂任务。
智能体系统支持多种部署方式，包括通过 MCP (Model Context Protocol) 服务器提供服务，也可直接集成到 Python 应用中。
## 智能体架构
### 核心组件
```
┌─────────────────────────────────────────────────────────┐
│ 智能体系统架构 │
├─────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ ChatAgent │ │ CriticAgent │ │ TaskAgent │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ ┌──────┴────────────────┴────────────────┴──────┐ │
│ │ BaseAgent (基类) │ │
│ └──────────────────────┬────────────────────────┘ │
│ │ │
│ ┌──────────────────────┴────────────────────────┐ │
│ │ AgentMCP Server │ │
│ └───────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
### 智能体类型
CAMEL 框架提供以下核心智能体类型：
| 智能体类型 | 文件位置 | 主要功能 |
|-----------|---------|---------|
| **ChatAgent** | `camel/agents/chat_agent.py` | 通用对话智能体，处理对话交互 |
| **CriticAgent** | `camel/agents/critic_agent.py` | 批评评价智能体，评估和反馈 |
| **TaskAgent** | `camel/agents/task_agent.py` | 任务规划智能体，分解和执行任务 |
| **EmbodiedAgent** | `camel/agents/embodied_agent.py` | 具身智能体，与环境交互 |
| **RepoAgent** | `camel/agents/repo_agent.py` | 仓库分析智能体，处理代码仓库 |
## BaseAgent 基类
所有智能体都继承自 `BaseAgent`，提供核心功能和通用接口。 资料来源：[camel/agents/base.py]()
### 核心特性
- 统一的智能体生命周期管理
- 消息处理和状态维护
- 工具调用和结果处理
- 对话历史记录管理
### 智能体配置
智能体通过配置文件进行定制，包括：
```python
# 来自 agent_config.py 的配置选项
@dataclass
class AgentConfig:
name: str # 智能体名称
model: Model # 使用的模型
tools: List[Tool] # 可用工具列表
system_message: str # 系统提示词
temperature: float = 0.7 # 生成温度
max_tokens: int = 2048 # 最大 token 数
```
## ChatAgent 对话智能体
`ChatAgent` 是 CAMEL 框架中最常用的智能体类型，主要负责处理对话交互。 资料来源：[camel/agents/chat_agent.py]()
### 功能特点
- 支持多轮对话
- 角色扮演能力
- 工具集成
- 消息格式化处理
### 使用示例
```python
from camel.agents import ChatAgent
from camel.models import ModelFactory
from camel.types import ModelPlatformType
# 创建模型
model = ModelFactory.create(
model_platform=ModelPlatformType.OPENAI,
model_type="gpt-4"
)
# 创建对话智能体
agent = ChatAgent(
system_message="你是一个乐于助人的AI助手。",
model=model
)
# 执行对话步骤
response = await agent.step("你好，请介绍一下你自己")
```
## CriticAgent 批评智能体
`CriticAgent` 专门用于评估和反馈，能够分析其他智能体或用户输入的内容并提供改进建议。 资料来源：[camel/agents/critic_agent.py]()
### 应用场景
- 代码审查和反馈
- 内容质量评估
- 对话策略优化
- 任务执行结果验证
## TaskAgent 任务智能体
`TaskAgent` 专注于任务分解和执行规划，能够将复杂任务拆分为可执行的子任务。 资料来源：[camel/agents/task_agent.py]()
### 工作流程
```mermaid
graph TD
A[接收任务] --> B{任务复杂度判断}
B -->|简单任务| C[直接执行]
B -->|复杂任务| D[任务分解]
D --> E[子任务1]
D --> F[子任务2]
D --> G[子任务N]
E --> H[结果汇总]
F --> H
G --> H
H --> I[最终输出]
```
## EmbodiedAgent 具身智能体
`EmbodiedAgent` 具备与物理或虚拟环境交互的能力，适用于需要实际操作的任务场景。 资料来源：[camel/agents/embodied_agent.py]()
### 工具支持
| 工具类型 | 功能描述 |
|---------|---------|
| 浏览器工具 | 网页导航、内容抓取、表单填写 |
| 文件系统工具 | 读写文件、目录操作 |
| 命令行工具 | 执行系统命令 |
| API 工具 | 调用外部服务接口 |
## RepoAgent 仓库智能体
`RepoAgent` 专门用于代码仓库分析和处理，能够理解代码结构、执行代码搜索和代码生成任务。 资料来源：[camel/agents/repo_agent.py]()
### 典型应用
- 代码库理解
- 文档生成
- 代码重构建议
- 仓库结构分析
## MCP 服务器集成
CAMEL 提供了 MCP (Model Context Protocol) 服务器实现，允许通过标准协议与智能体交互。 资料来源：[services/README.md]()
### 可用工具
| 工具名称 | 功能描述 | 参数 |
|---------|---------|------|
| `step` | 执行单次对话步骤 | `name`: 智能体名称, `message`: 消息内容 |
| `reset` | 重置所有智能体状态 | 无 |
| `set_output_language` | 设置输出语言 | `language`: 语言代码 |
| `get_agents_info` | 获取所有智能体信息 | 无 |
| `get_chat_history` | 获取对话历史 | `name`: 智能体名称 |
| `get_agent_info` | 获取特定智能体详情 | `name`: 智能体名称 |
| `get_available_tools` | 获取智能体可用工具 | `name`: 智能体名称 |
### 服务器启动
```bash
# 启动 MCP 服务器
python services/agent_mcp_server.py
```
### 客户端配置
连接 MCP 客户端(如 Claude Desktop 或 Cursor)需要提供 JSON 配置：
```json
{
"camel-agents": {
"command": "/path/to/your/python",
"args": [
"/path/to/camel/services/agent_mcp_server.py"
],
"env": {
"OPENAI_API_KEY": "...",
"OPENROUTER_API_KEY": "...",
"BRAVE_API_KEY": "..."
}
}
}
```
## 预配置智能体类型
CAMEL 框架提供三种预配置的智能体类型：
| 智能体类型 | 配置文件 | 能力描述 |
|-----------|---------|---------|
| **General Agent** | `agent_config.py` | 通用问答助手，处理各类任务 |
| **Search Agent** | `agent_config.py` | 网络搜索能力集成 |
| **Reasoning Agent** | `agent_config.py` | 专门从事推理任务 |
资料来源：[services/README.md]()
## Gradio 应用集成
CAMEL 提供基于 Gradio 的智能体展示应用。 资料来源：[apps/agents/README.md]()
### 快速启动
```bash
python agents.py --api-key=YOUR-OPENAI-API-KEY
```
### 部署到 HuggingFace Spaces
1. 在 CAMEL 仓库中完成开发和调试
2. 为目标提交打标签：`hf_spaces_{X+1}`（X 值需从 HF 仓库同步脚本查询）
3. 执行 `git push --tags`
4. 克隆 HF 仓库到本地
5. 更新标签并运行同步脚本
6. 提交并推送到 HF
7. HF 将自动部署应用
## 智能体通信协议
智能体之间通过消息传递进行通信，支持以下消息类型：
| 消息类型 | 用途 | 数据结构 |
|---------|------|---------|
| `UserMessage` | 用户输入 | `{role, content}` |
| `AssistantMessage` | 智能体回复 | `{role, content, tool_calls}` |
| `SystemMessage` | 系统指令 | `{role, content}` |
| `ToolMessage` | 工具结果 | `{role, content, tool_call_id}` |
## 类型定义
智能体的核心类型定义位于 `camel/agents/_types.py`。 资料来源：[camel/agents/_types.py]()
### 主要枚举类型
- **AgentType**: 智能体类型枚举
- **AgentStatus**: 智能体状态枚举
- **MessageType**: 消息类型枚举
## 配置管理
### 环境变量
| 变量名 | 用途 | 必需 |
|-------|------|------|
| `OPENAI_API_KEY` | OpenAI API 密钥 | 是 |
| `OPENROUTER_API_KEY` | OpenRouter API 密钥 | 否 |
| `BRAVE_API_KEY` | Brave Search API 密钥 | 否 |
### 自定义配置
通过修改 `agent_config.py` 可以自定义：
- 模型选择和参数
- 添加新智能体类型
- 配置工具集
- 调整系统提示词
## 最佳实践
### 1. 智能体选择
根据任务复杂度选择合适的智能体类型：
- **简单对话**: 使用 `ChatAgent`
- **需要评估**: 结合 `CriticAgent`
- **复杂任务**: 使用 `TaskAgent` 进行任务分解
- **代码仓库操作**: 使用 `RepoAgent`
### 2. 工具配置
```python
# 推荐的工具配置模式
tools = [
SearchTool(api_key=brave_api_key),
CalculatorTool(),
# 根据需要添加更多工具
]
```
### 3. 错误处理
智能体执行时应捕获并处理以下异常：
- API 调用超时
- 模型响应格式错误
- 工具执行失败
- 上下文长度超限
## 示例应用
CAMEL 仓库提供了多个使用智能体的示例应用：
| 示例名称 | 路径 | 说明 |
|---------|------|------|
| 多智能体研究助手 | `examples/usecases/multi_agent_research_assistant/` | 学术研究和报告生成 |
| Codeforces 问题解决器 | `examples/usecases/codeforces_question_solver/` | 竞赛编程辅助 |
| GitHub 聊天 | `examples/usecases/chat_with_github/` | 仓库交互 |
| YouTube 聊天 | `examples/usecases/chat_with_youtube/` | 视频内容分析 |
## 扩展阅读
- [CAMEL 框架核心概念](../core_concepts/)
- [工具系统(Toolkits)](../toolkits/)
- [角色扮演(Role-Playing)](../role_playing/)
- [MCP 协议文档](https://docs.anthropic.com/en/docs/agents-and-tools/mcp)
---
## 模型集成(Models)
### 相关页面
相关主题：[系统架构设计](#page-architecture), [智能体(Agents)](#page-agents)
相关源码文件
以下源码文件用于生成本页说明：
- [camel/models/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/models/__init__.py)
- [camel/models/base_model.py](https://github.com/camel-ai/camel/blob/main/camel/models/base_model.py)
- [camel/models/model_factory.py](https://github.com/camel-ai/camel/blob/main/camel/models/model_factory.py)
- [camel/models/model_manager.py](https://github.com/camel-ai/camel/blob/main/camel/models/model_manager.py)
- [camel/models/openai_model.py](https://github.com/camel-ai/camel/blob/main/camel/models/openai_model.py)
- [camel/models/anthropic_model.py](https://github.com/camel-ai/camel/blob/main/camel/models/anthropic_model.py)
- [camel/configs/openai_config.py](https://github.com/camel-ai/camel/blob/main/camel/configs/openai_config.py)
- [camel/configs/anthropic_config.py](https://github.com/camel-ai/camel/blob/main/camel/configs/anthropic_config.py)
# 模型集成(Models)
## 概述
CAMEL-AI 的模型集成模块是整个框架的核心组件之一，负责统一管理和调用各类大语言模型（LLM）。该模块通过抽象层设计，将不同模型提供商的 API 封装为统一接口，使上层应用能够无差别地使用各种模型能力。
模型模块的主要职责包括：
- 提供统一的模型调用接口
- 支持多种模型平台（OpenAI、Anthropic、兼容 OpenAI 接口的模型等）
- 管理模型配置和参数
- 处理模型响应格式化
- 支持流式输出和非流式输出
资料来源：[camel/models/__init__.py]()
## 架构设计
### 整体架构
```mermaid
graph TD
A[用户代码] --> B[ModelFactory]
B --> C{模型平台类型}
C -->|OpenAI| D[OpenAIModel]
C -->|Anthropic| E[AnthropicModel]
C -->|OpenAI兼容| F[OpenAICompatibleModel]
D --> G[BaseModel]
E --> G
F --> G
G --> H[模型API调用层]
H --> I[OpenAI API]
H --> J[Anthropic API]
H --> K[第三方兼容API]
```
### 核心组件关系
```mermaid
classDiagram
class BaseModel {
<>
+run() Message
+run_until_success() Message
-_roll() None
}
class OpenAIModel {
+run() Message
-_extract_text_from_response()
}
class AnthropicModel {
+run() Message
-_extract_text_from_response()
}
class ModelFactory {
+create() BaseModel
}
class ModelManager {
+get_model() BaseModel
+list_models() List~str~
}
BaseModel <|-- OpenAIModel
BaseModel <|-- AnthropicModel
ModelFactory --> BaseModel : creates
ModelManager --> ModelFactory : uses
```
资料来源：[camel/models/base_model.py](), [camel/models/model_factory.py](), [camel/models/model_manager.py]()
## 核心组件详解
### BaseModel（基础模型类）
`BaseModel` 是所有模型实现的抽象基类，定义了模型交互的标准接口。
#### 核心方法
| 方法名 | 返回类型 | 说明 |
|--------|----------|------|
| `run(messages)` | `Message` | 执行单次模型调用 |
| `run_until_success(messages)` | `Message` | 循环调用直至成功 |
| `_roll()` | `None` | 重置模型状态 |
#### 主要属性
| 属性名 | 类型 | 说明 |
|--------|------|------|
| `model_type` | `ModelType` | 模型类型枚举 |
| `model_config_dict` | `Dict[str, Any]` | 模型配置字典 |
| `url` | `str` | API 端点 URL |
资料来源：[camel/models/base_model.py]()
### ModelFactory（模型工厂）
`ModelFactory` 负责根据配置动态创建模型实例，是接入新模型的统一入口点。
#### 工厂方法签名
```python
@classmethod
def create(
cls,
model_platform: "ModelPlatformType",
model_type: "ModelType",
url: Optional[str] = None,
api_key: Optional[str] = None,
config_dict: Optional[Dict[str, Any]] = None,
) -> "BaseModel"
```
#### 参数说明
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `model_platform` | `ModelPlatformType` | 是 | 模型平台类型 |
| `model_type` | `ModelType` | 是 | 具体模型类型 |
| `url` | `str` | 否 | API 端点（兼容模式必填） |
| `api_key` | `str` | 否 | API 密钥 |
| `config_dict` | `Dict[str, Any]` | 否 | 自定义配置 |
资料来源：[camel/models/model_factory.py]()
### ModelManager（模型管理器）
`ModelManager` 提供模型实例的集中管理和缓存功能。
#### 核心功能
- 管理多个模型实例的生命周期
- 支持按名称获取已注册的模型
- 提供模型列表查询接口
资料来源：[camel/models/model_manager.py]()
## 支持的模型平台
### OpenAI 系列
CAMEL 支持完整的 OpenAI 模型体系，包括 GPT-4、GPT-4 Turbo、GPT-3.5 Turbo 等。
#### OpenAIModel 实现
```python
class OpenAIModel(BaseModel):
def __init__(
self,
model_type: ModelType,
model_config_dict: dict,
api_key: str,
url: Optional[str] = None,
...
)
```
#### 支持的模型类型
| 模型类型枚举 | 对应模型 | 说明 |
|--------------|----------|------|
| `GPT_4` | gpt-4 | GPT-4 标准版 |
| `GPT_4_TURBO` | gpt-4-turbo | GPT-4 Turbo |
| `GPT_4O` | gpt-4o | GPT-4 Omni |
| `GPT_4O_MINI` | gpt-4o-mini | GPT-4o 迷你版 |
| `GPT_35_TURBO` | gpt-3.5-turbo | GPT-3.5 Turbo |
资料来源：[camel/models/openai_model.py](), [camel/models/__init__.py]()
### Anthropic 系列
CAMEL 通过 `AnthropicModel` 类支持 Claude 系列模型。
#### AnthropicModel 实现
```python
class AnthropicModel(BaseModel):
def __init__(
self,
model_type: ModelType,
model_config_dict: dict,
api_key: str,
...
)
```
#### 支持的 Claude 模型
| 模型类型枚举 | 对应模型 | 说明 |
|--------------|----------|------|
| `CLAUDE_3_5_SONNET` | claude-sonnet-4-20250514 | Claude 3.5 Sonnet |
| `CLAUDE_3_OPUS` | claude-3-opus-20240229 | Claude 3 Opus |
| `CLAUDE_3_HAIKU` | claude-3-haiku-20240307 | Claude 3 Haiku |
资料来源：[camel/models/anthropic_model.py](), [camel/models/__init__.py]()
### OpenAI 兼容接口
CAMEL 支持任何实现 OpenAI API 兼容接口的模型服务，包括：
- 本地部署模型（如 vLLM、LM Studio）
- 开源模型服务（如 TogetherAI、Anyscale）
- 云厂商兼容端点（如阿里云、百度智能云）
通过设置 `ModelPlatformType.OPENAI_COMPATIBLE_MODEL` 并指定 `url` 参数即可接入。
资料来源：[camel/models/model_factory.py]()
## 配置系统
### OpenAI 配置
`OpenAIConfig` 类提供 OpenAI 模型的详细配置选项。
#### 配置参数表
| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `temperature` | `float` | `1.0` | 采样温度（0-2） |
| `max_tokens` | `int` | `4096` | 最大生成token数 |
| `top_p` | `float` | `1.0` | Top-p 采样 |
| `n` | `int` | `1` | 生成数量 |
| `stop` | `List[str]` | `None` | 停止词列表 |
| `seed` | `int` | `None` | 随机种子 |
| `stream` | `bool` | `False` | 流式输出开关 |
| `response_format` | `dict` | `None` | 响应格式约束 |
| `tools` | `List[dict]` | `None` | 工具函数定义 |
| `tool_choice` | `str` | `None` | 工具选择策略 |
资料来源：[camel/configs/openai_config.py]()
### Anthropic 配置
`AnthropicConfig` 类提供 Claude 模型的详细配置选项。
#### 配置参数表
| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `temperature` | `float` | `1.0` | 采样温度 |
| `max_tokens` | `int` | `4096` | 最大生成token数 |
| `top_p` | `float` | `1.0` | Top-p 采样 |
| `stop_sequences` | `List[str]` | `None` | 停止序列 |
| `stream` | `bool` | `False` | 流式输出开关 |
| `tools` | `List[dict]` | `None` | 工具函数定义 |
资料来源：[camel/configs/anthropic_config.py]()
## 使用指南
### 基础使用流程
```mermaid
sequenceDiagram
participant User
participant Factory as ModelFactory
participant Model as OpenAIModel
participant API as OpenAI API
User->>Factory: create(platform, model_type, api_key)
Factory->>Model: instantiate
User->>Model: run(messages)
Model->>API: POST /chat/completions
API-->>Model: response
Model-->>User: Message object
```
### 基本调用示例
#### 1. 创建 OpenAI 模型实例
```python
from camel.models import ModelFactory, ModelPlatformType, ModelType
model = ModelFactory.create(
model_platform=ModelPlatformType.OPENAI,
model_type=ModelType.GPT_4O,
api_key="your-api-key"
)
```
#### 2. 创建 Anthropic 模型实例
```python
from camel.models import ModelFactory, ModelPlatformType, ModelType
model = ModelFactory.create(
model_platform=ModelPlatformType.ANTHROPIC,
model_type=ModelType.CLAUDE_3_5_SONNET,
api_key="your-api-key"
)
```
#### 3. 使用兼容接口模型
```python
from camel.models import ModelFactory, ModelPlatformType, ModelType
model = ModelFactory.create(
model_platform=ModelPlatformType.OPENAI_COMPATIBLE_MODEL,
model_type=ModelType.GPT_4O,
url="https://api.example.com/v1",
api_key="your-api-key"
)
```
#### 4. 自定义模型配置
```python
from camel.models import ModelFactory, ModelPlatformType, ModelType
from camel.configs import OpenAIConfig
config = OpenAIConfig(
temperature=0.7,
max_tokens=2048,
top_p=0.9
)
model = ModelFactory.create(
model_platform=ModelPlatformType.OPENAI,
model_type=ModelType.GPT_4O,
api_key="your-api-key",
config_dict=config.as_dict()
)
```
#### 5. 执行模型调用
```python
from camel.messages import UserMessage
response = model.run([
UserMessage(content="Hello, how are you?")
])
print(response.content)
```
资料来源：[camel/models/model_factory.py](), [camel/models/openai_model.py]()
### 高级用法
#### 流式输出
```python
config = OpenAIConfig(stream=True)
model = ModelFactory.create(
model_platform=ModelPlatformType.OPENAI,
model_type=ModelType.GPT_4O,
api_key="your-api-key",
config_dict=config.as_dict()
)
response = model.run(messages)
# 处理流式响应
```
#### 函数调用（Tools）
```python
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "获取天气信息",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string"}
}
}
}
}
]
config = OpenAIConfig(tools=tools)
model = ModelFactory.create(
model_platform=ModelPlatformType.OPENAI,
model_type=ModelType.GPT_4O,
api_key="your-api-key",
config_dict=config.as_dict()
)
```
资料来源：[camel/configs/openai_config.py]()
## 模型类型枚举
CAMEL 使用强类型枚举 `ModelType` 管理支持的模型列表。
### 完整枚举值
```python
class ModelType(Enum):
# OpenAI Models
GPT_4 = "gpt-4"
GPT_4_TURBO = "gpt-4-turbo"
GPT_4O = "gpt-4o"
GPT_4O_MINI = "gpt-4o-mini"
GPT_35_TURBO = "gpt-3.5-turbo"
GPT_35_TURBO_16K = "gpt-3.5-turbo-16k"
# Anthropic Models
CLAUDE_3_5_SONNET = "claude-sonnet-4-20250514"
CLAUDE_3_OPUS = "claude-3-opus-20240229"
CLAUDE_3_SONNET = "claude-3-sonnet-20240229"
CLAUDE_3_HAIKU = "claude-3-haiku-20240307"
# ... 其他模型
```
资料来源：[camel/models/__init__.py]()
## 错误处理
### 常见错误及解决方案
| 错误类型 | 可能原因 | 解决方案 |
|----------|----------|----------|
| `AuthenticationError` | API 密钥无效或缺失 | 检查并正确设置 `api_key` |
| `RateLimitError` | 请求频率超限 | 降低调用频率或升级配额 |
| `BadRequestError` | 参数配置错误 | 检查 `config_dict` 参数 |
| `APIConnectionError` | 网络连接问题 | 检查网络和代理设置 |
资料来源：[camel/models/base_model.py](), [camel/models/openai_model.py]()
## 扩展指南
### 添加新模型支持
如需添加新的模型提供商支持，需要：
1. 在 `camel/models/` 目录下创建新的模型实现类（如 `xxx_model.py`）
2. 继承 `BaseModel` 抽象类
3. 实现 `run()` 和 `_extract_text_from_response()` 方法
4. 在 `ModelFactory.create()` 方法中添加创建逻辑
5. 在 `ModelType` 枚举中添加新的模型类型
```python
# 示例：新增模型支持
class XxxModel(BaseModel):
def __init__(self, model_type, model_config_dict, api_key, **kwargs):
super().__init__(model_type, model_config_dict, api_key)
# 初始化特定逻辑
def _extract_text_from_response(self, response) -> str:
# 解析响应
return response.choices[0].message.content
```
资料来源：[camel/models/base_model.py](), [camel/models/model_factory.py]()
## 相关资源
- 模型模块源码：[camel/models/](https://github.com/camel-ai/camel/tree/main/camel/models)
- 配置模块源码：[camel/configs/](https://github.com/camel-ai/camel/tree/main/camel/configs)
- 官方文档：[CAMEL Documentation](https://docs.camel-ai.org/)
---
## 工具集(Toolkits)
### 相关页面
相关主题：[智能体(Agents)](#page-agents), [MCP协议集成](#page-mcp), [智能体劳动力(Workforce)](#page-workforce)
相关源码文件
以下源码文件用于生成本页说明：
- [camel/toolkits/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/__init__.py)
- [camel/toolkits/base.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/base.py)
- [camel/toolkits/function_tool.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/function_tool.py)
- [camel/toolkits/search_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/search_toolkit.py)
- [camel/toolkits/browser_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/browser_toolkit.py)
- [camel/toolkits/file_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/file_toolkit.py)
- [camel/toolkits/github_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/github_toolkit.py)
- [camel/toolkits/slack_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/slack_toolkit.py)
- [camel/toolkits/hybrid_browser_toolkit/ts/src/browser-session.ts](https://github.com/camel-ai/camel/blob/main/camel/toolkits/hybrid_browser_toolkit/ts/src/browser-session.ts)
# 工具集(Toolkits)
## 概述
CAMEL-AI 的工具集（Toolkits）是框架中用于扩展代理（Agent）能力的关键组件库。工具集提供了一系列预构建的功能模块，使代理能够执行搜索、文件操作、浏览器自动化、GitHub集成、Slack通信等多种任务。通过工具集，开发者可以快速为AI代理配备特定领域的工具能力，无需从零开始实现复杂的功能逻辑。
工具集的设计遵循模块化原则，每个工具集都是独立的功能单元，可以单独使用或组合使用。这种设计使得系统具有高度的灵活性和可扩展性，开发者可以根据实际需求选择性地集成所需工具。
## 架构设计
### 核心架构图
```mermaid
graph TD
A[BaseToolkit] --> B[SearchToolkit]
A --> C[BrowserToolkit]
A --> D[FileToolkit]
A --> E[GitHubToolkit]
A --> F[SlackToolkit]
A --> G[FunctionTool]
H[FunctionCall] --> G
I[ToolOutput] --> G
J[Agent] --> K[ToolkitRegistry]
K --> A
```
### 基础类层次结构
CAMEL-AI 的工具集系统建立在一个统一的基础类体系之上。所有工具集都继承自 `BaseToolkit` 基类，该类定义了工具集的标准接口和行为规范。
`BaseToolkit` 是所有工具集的抽象基类，它提供了工具集的核心框架。每个具体的工具集都需要实现其定义的接口方法。基类封装了通用的功能逻辑，如工具注册、参数验证和结果处理等通用流程，使得具体工具集的实现更加简洁和专注于业务逻辑。
`FunctionTool` 是另一个重要的基础组件，它用于将普通函数转换为AI代理可调用的工具。`FunctionTool` 包装了目标函数，添加了参数解析、类型转换和错误处理等功能，使得开发者可以将任意的Python函数暴露给AI代理使用。
## 工具集类型详解
### 1. 搜索工具集（SearchToolkit）
搜索工具集为代理提供了网络搜索能力，使其能够检索最新的信息和数据。
| 方法名 | 功能描述 | 返回类型 |
|--------|----------|----------|
| search | 执行通用网络搜索 | List[SearchResult] |
| news_search | 搜索新闻内容 | List[NewsResult] |
| academic_search | 搜索学术论文 | List[AcademicResult] |
SearchToolkit 支持多种搜索模式，包括网页搜索、新闻搜索和学术论文搜索。开发者可以根据不同的使用场景选择合适的搜索模式。
### 2. 浏览器工具集（BrowserToolkit）
浏览器工具集提供了浏览器自动化能力，支持网页抓取、元素交互和页面导航等功能。
```mermaid
graph LR
A[BrowserSession] --> B[PageNavigation]
B --> C[ElementInteraction]
C --> D[ContentExtraction]
D --> E[SnapshotCapture]
```
BrowserToolkit 的核心是 `BrowserSession` 类，它管理浏览器的生命周期和会话状态。该类提供了丰富的页面操作方法，包括导航到指定URL、点击页面元素、填写表单内容、提取页面文本和截图等。
`browser-session.ts` 文件中实现了浏览器会话的核心逻辑，包括元素定位、表单填写和快照比较等功能。当代理需要与网页交互时，会话管理器会协调各个组件完成操作任务。
### 3. 文件工具集（FileToolkit）
文件工具集提供了文件系统操作能力，支持文件读写、目录管理和路径操作等功能。
| 操作类型 | 支持功能 |
|----------|----------|
| 读取 | 文本文件、JSON、CSV、二进制文件 |
| 写入 | 创建新文件、覆盖文件、追加内容 |
| 目录 | 创建目录、列出内容、删除目录 |
| 元数据 | 获取文件大小、修改时间、权限信息 |
FileToolkit 封装了常见的文件系统操作，为AI代理提供了安全可靠的文件访问能力。所有文件操作都经过严格的路径验证，防止目录遍历攻击。
### 4. GitHub工具集（GitHubToolkit）
GitHub工具集集成了GitHub API，使代理能够执行仓库管理、Issue操作、PR管理和代码搜索等任务。
| 功能模块 | 描述 |
|----------|------|
| 仓库操作 | 创建、克隆、获取仓库信息 |
| Issue管理 | 创建Issue、评论、关闭、标签管理 |
| PR操作 | 创建Pull Request、审查、合并 |
| 代码搜索 | 搜索代码、仓库和用户 |
GitHubToolkit 通过GitHub REST API与GitHub平台进行交互，支持完整的仓库生命周期管理功能。
### 5. Slack工具集（SlackToolkit）
Slack工具集提供了与Slack工作区交互的能力，支持消息发送、频道管理和用户查询等功能。
| 功能 | 说明 |
|------|------|
| 消息发送 | 向指定频道或用户发送消息 |
| 频道管理 | 创建频道、获取频道列表、管理成员 |
| 用户查询 | 获取用户信息、在线状态 |
| 文件上传 | 上传文件到Slack频道 |
SlackToolkit 使用Slack Web API实现所有功能，支持企业级Slack工作区的集成需求。
## 工具调用机制
### 函数调用流程
```mermaid
sequenceDiagram
participant Agent as Agent
participant Toolkit as FunctionTool
participant Function as Target Function
Agent->>Toolkit: 调用工具方法
Toolkit->>Toolkit: 参数解析与验证
Toolkit->>Function: 转发调用请求
Function-->>Toolkit: 返回执行结果
Toolkit->>Toolkit: 结果格式化处理
Toolkit-->>Agent: 返回ToolOutput
```
### 参数处理
FunctionTool 提供了强大的参数处理能力，支持多种数据类型和验证规则。工具的参数定义采用声明式方式，开发者可以通过装饰器或配置指定参数的类型约束、默认值和验证规则。
| 参数特性 | 支持情况 |
|----------|----------|
| 类型注解 | int, str, float, bool, list, dict |
| 默认值 | 支持可选参数 |
| 必填检查 | 支持必填参数验证 |
| 枚举约束 | 支持枚举类型限制 |
## 混合浏览器工具集（HybridBrowserToolkit）
HybridBrowserToolkit 是CAMEL-AI中功能最强大的浏览器自动化工具，它结合了传统浏览器控制和现代化前端交互能力。
### 核心特性
- **多浏览器支持**：支持Chrome、Firefox等主流浏览器
- **智能元素定位**：支持通过ID、类名、XPath、CSS选择器定位元素
- **表单自动化**：支持填写表单、上传文件、选择下拉菜单
- **截图功能**：支持全页面截图和元素截图
- **JavaScript执行**：支持在页面上下文中执行JavaScript代码
### 会话管理
BrowserSession 类负责管理浏览器会话的生命周期。每个会话包含以下状态：
```mermaid
stateDiagram-v2
[*] --> Initialized: 创建会话
Initialized --> Ready: 打开页面
Ready --> Active: 执行操作
Active --> Ready: 操作完成
Active --> Error: 发生错误
Ready --> [*]: 关闭会话
Error --> Ready: 重试
```
### 元素交互
当代理需要与页面元素交互时，系统会执行以下流程：
1. 接收交互指令和目标元素引用
2. 在当前页面快照中查找匹配元素
3. 验证元素可见性和可操作性
4. 执行交互操作（点击、输入、选择等）
5. 等待操作完成并获取结果快照
6. 比较操作前后的页面变化
7. 返回操作结果和差异信息
## 使用示例
### 基础工具集使用
```python
from camel.toolkits import SearchToolkit, FileToolkit
# 创建搜索工具集实例
search_toolkit = SearchToolkit()
# 执行搜索
results = search_toolkit.search(query="人工智能最新进展")
# 创建文件工具集实例
file_toolkit = FileToolkit()
# 读取文件
content = file_toolkit.read_file(path="example.txt")
```
### 自定义函数工具
```python
from camel.toolkits import FunctionTool
# 将普通函数转换为工具
@FunctionTool
def calculate(expression: str) -> float:
"""计算数学表达式"""
return eval(expression)
# 注册到代理
agent = ChatAgent(
tools=[calculate]
)
```
### 浏览器自动化
```python
from camel.toolkits import BrowserToolkit
browser = BrowserToolkit()
# 启动会话
session = await browser.create_session()
# 导航到网页
await session.navigate("https://example.com")
# 填写表单
await session.fill(
ref="search-input",
text="查询内容",
original_placeholder="搜索..."
)
# 获取快照
snapshot = await session.get_snapshot()
```
## 配置与管理
### 工具集注册
CAMEL-AI 提供了统一的工具集注册机制，开发者可以将自定义工具集注册到全局注册表中，供整个应用使用。
```python
from camel.toolkits import ToolkitRegistry
# 获取注册表实例
registry = ToolkitRegistry.get_instance()
# 注册自定义工具集
registry.register("my_toolkit", MyCustomToolkit())
```
### 环境变量配置
部分工具集需要配置外部服务的API密钥或访问凭证。这些配置通常通过环境变量提供：
| 环境变量 | 适用工具集 | 用途 |
|----------|------------|------|
| OPENAI_API_KEY | 所有工具集 | API身份验证 |
| GITHUB_TOKEN | GitHubToolkit | GitHub API访问 |
| SLACK_BOT_TOKEN | SlackToolkit | Slack API访问 |
| SEARCH_API_KEY | SearchToolkit | 搜索服务访问 |
## 与代理系统的集成
工具集与CAMEL-AI的代理系统紧密集成，代理在初始化时可以接收一个或多个工具集作为能力扩展。
```mermaid
graph TD
A[Agent初始化] --> B[加载工具集]
B --> C[工具注册]
C --> D[函数调用接口暴露]
D --> E[运行时调用]
E --> F[结果返回]
```
代理系统会自动处理工具调用的路由、参数序列化和结果反序列化等细节，开发者只需关注业务逻辑的实现。
## 最佳实践
### 工具设计原则
1. **单一职责**：每个工具应专注于完成一个特定任务
2. **清晰的命名**：工具名应准确反映其功能
3. **完善的文档**：提供详细的参数说明和返回值描述
4. **错误处理**：对异常情况进行恰当处理和提示
5. **参数验证**：在执行前验证所有输入参数的有效性
### 性能优化建议
- 复用工具集实例，避免重复创建
- 对于耗时操作，考虑使用异步实现
- 批量操作时使用事务或批处理接口
- 合理设置超时时间，防止长时间阻塞
## 扩展开发
开发者可以通过继承 `BaseToolkit` 类来创建自定义工具集。标准开发流程如下：
1. 创建继承自 `BaseToolkit` 的新类
2. 在 `__init__` 方法中初始化所需的资源和配置
3. 实现具体的功能方法
4. 添加适当的文档字符串
5. 在包入口文件中导出新工具集
自定义工具集可以像内置工具集一样注册到代理中，实现无缝集成。
## 相关资源
- 基础工具类源码：[camel/toolkits/base.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/base.py)
- 函数工具源码：[camel/toolkits/function_tool.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/function_tool.py)
- 浏览器工具集源码：[camel/toolkits/browser_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/browser_toolkit.py)
- 混合浏览器工具集：[camel/toolkits/hybrid_browser_toolkit/ts/src/browser-session.ts](https://github.com/camel-ai/camel/blob/main/camel/toolkits/hybrid_browser_toolkit/ts/src/browser-session.ts)
- 搜索工具集源码：[camel/toolkits/search_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/search_toolkit.py)
- 文件工具集源码：[camel/toolkits/file_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/file_toolkit.py)
- GitHub工具集源码：[camel/toolkits/github_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/github_toolkit.py)
- Slack工具集源码：[camel/toolkits/slack_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/slack_toolkit.py)
---
## MCP协议集成
### 相关页面
相关主题：[工具集(Toolkits)](#page-toolkits), [智能体(Agents)](#page-agents)
相关源码文件
以下源码文件用于生成本页说明：
- [camel/toolkits/mcp_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/mcp_toolkit.py)
- [camel/agents/mcp_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/mcp_agent.py)
- [camel/parsers/mcp_tool_call_parser.py](https://github.com/camel-ai/camel/blob/main/camel/parsers/mcp_tool_call_parser.py)
- [camel/types/mcp_registries.py](https://github.com/camel-ai/camel/blob/main/camel/types/mcp_registries.py)
- [camel/utils/mcp_client.py](https://github.com/camel-ai/camel/blob/main/camel/utils/mcp_client.py)
# MCP协议集成
## 概述
MCP（Model Context Protocol）是一种标准化协议，用于在AI代理（Agent）与外部工具、服务之间建立通信桥梁。CAMEL-AI框架通过模块化的MCP集成方案，使代理能够调用远程工具、访问外部资源，并与其他MCP兼容系统进行交互。
MCP协议集成的核心目标包括：
- 提供统一的工具调用接口
- 支持多种MCP服务器连接
- 实现工具解析与响应处理
- 管理工具注册与生命周期
资料来源：[camel/toolkits/mcp_toolkit.py:1-50]()
## 核心组件
CAMEL-AI的MCP协议集成由以下核心模块组成：
| 组件 | 文件路径 | 功能描述 |
|------|----------|----------|
| MCPToolkit | `camel/toolkits/mcp_toolkit.py` | MCP工具集，提供与MCP服务器交互的主要接口 |
| MCPAgent | `camel/agents/mcp_agent.py` | MCP代理，负责处理MCP协议通信的代理实现 |
| MCPToolCallParser | `camel/parsers/mcp_tool_call_parser.py` | 工具调用解析器，解析MCP协议消息 |
| MCP registries | `camel/types/mcp_registries.py` | MCP类型注册表，管理MCP类型定义 |
| MCPClient | `camel/utils/mcp_client.py` | MCP客户端工具，提供底层通信能力 |
资料来源：[camel/types/mcp_registries.py:1-30]()
### 组件关系图
```mermaid
graph TD
A[MCPAgent] --> B[MCPToolkit]
B --> C[MCPToolCallParser]
B --> D[MCPClient]
D --> E[MCP Registries]
F[MCP Servers] --> D
A --> G[User Application]
```
## 架构设计
### 系统架构
MCP协议集成采用客户端-服务器架构，核心交互流程如下：
```mermaid
sequenceDiagram
participant User as 用户应用
participant Agent as MCPAgent
participant Toolkit as MCPToolkit
participant Client as MCPClient
participant Server as MCP服务器
User->>Agent: 调用工具
Agent->>Toolkit: 解析工具请求
Toolkit->>Client: 发起MCP调用
Client->>Server: 发送协议消息
Server-->>Client: 返回结果
Client-->>Toolkit: 解析响应
Toolkit-->>Agent: 返回工具结果
Agent-->>User: 输出最终结果
```
### 工具调用解析
`MCPToolCallParser`负责解析工具调用请求，其处理流程：
```mermaid
graph LR
A[MCP协议消息] --> B[解析工具名称]
B --> C[提取参数]
C --> D[验证参数类型]
D --> E[生成标准化调用]
```
资料来源：[camel/parsers/mcp_tool_call_parser.py:1-40]()
## MCPAgent详解
`MCPAgent`是MCP协议集成的核心代理类，继承自基础代理接口，提供以下功能：
### 主要职责
- 初始化MCP客户端连接
- 管理工具注册生命周期
- 处理用户请求并转发至MCP服务器
- 解析和返回工具执行结果
### 初始化参数
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| name | str | 是 | 代理名称 |
| mcp_servers_config | dict | 是 | MCP服务器配置 |
| model | Model | 是 | 使用的语言模型 |
| system_message | str | 否 | 系统提示词 |
资料来源：[camel/agents/mcp_agent.py:20-60]()
## MCPToolkit使用指南
`MCPToolkit`提供了与MCP服务器交互的统一接口，简化了工具调用流程。
### 服务器配置
MCP服务器通过JSON配置文件进行定义：
```json
{
"mcpServers": {
"airbnb": {
"command": "npx",
"args": ["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"]
},
"cloudflare": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-cloudflare"]
}
}
}
```
### 工具注册流程
```mermaid
graph TD
A[加载MCP配置] --> B[初始化MCPClient]
B --> C[连接MCP服务器]
C --> D[获取可用工具列表]
D --> E[注册工具到Toolkit]
E --> F[返回MCPToolkit实例]
```
资料来源：[camel/toolkits/mcp_toolkit.py:50-100]()
## MCPClient通信机制
`MCPClient`是底层的通信客户端，负责与MCP服务器进行协议级别的交互。
### 核心方法
| 方法 | 说明 |
|------|------|
| connect | 建立与MCP服务器的连接 |
| disconnect | 关闭连接并清理资源 |
| call_tool | 调用远程工具 |
| list_tools | 获取可用工具列表 |
| get_resources | 获取服务器资源 |
资料来源：[camel/utils/mcp_client.py:30-80]()
### 协议消息格式
MCP协议使用JSON格式进行消息传递，标准请求结构：
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "tool_name",
"arguments": {}
}
}
```
## 实际应用示例
### 多代理研究助手
在`examples/usecases/multi_agent_research_assistant`中，MCP协议用于集成外部搜索和新闻API：
```python
from camel.agents.mcp_agent import MCPAgent
from camel.toolkits.mcp_toolkit import MCPToolkit
# 初始化MCP代理
agent = MCPAgent(
name="research_assistant",
mcp_servers_config=mcp_config,
model=model
)
```
### Cloudflare MCP集成
在`examples/usecases/cloudfare_mcp_camel`中，集成Cloudflare的多个MCP服务：
- **Analytics MCP服务器**：提供全球互联网流量趋势分析
- **DNS Analytics服务器**：提供DNS分析能力
- **Browser服务器**：提供网页抓取和截图功能
资料来源：[examples/usecases/cloudfare_mcp_camel/README.md]()
### Airbnb房源搜索
`examples/usecases/airbnb_mcp`展示了如何集成Airbnb的MCP服务器：
```json
{
"mcpServers": {
"airbnb": {
"command": "npx",
"args": ["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"]
}
}
}
```
资料来源：[examples/usecases/airbnb_mcp/README.md]()
## 最佳实践
### 配置管理
1. **环境变量分离**：将API密钥存储在`.env`文件中，避免硬编码
2. **配置文件版本化**：使用版本控制管理MCP服务器配置
3. **错误处理**：实现完善的异常捕获和重试机制
### 性能优化
| 优化项 | 建议 |
|--------|------|
| 连接复用 | 保持长连接避免频繁建立TCP连接 |
| 缓存策略 | 对不常变化的工具列表进行缓存 |
| 并发控制 | 使用连接池管理并发请求 |
### 安全考虑
- 敏感信息不写入配置文件
- 使用环境变量注入API密钥
- 定期轮换API访问凭证
## 故障排查
| 常见问题 | 可能原因 | 解决方案 |
|----------|----------|----------|
| 连接超时 | MCP服务器未启动 | 检查`mcp-remote`安装状态 |
| 工具调用失败 | 参数格式错误 | 检查MCP服务器返回的错误信息 |
| 响应解析错误 | 协议版本不兼容 | 确保客户端与服务端版本匹配 |
资料来源：[examples/usecases/cloudfare_mcp_camel/README.md]()
## 相关资源
- MCP官方文档：[Model Context Protocol](https://modelcontextprotocol.io/)
- CAMEL-AI官方仓库：[camel-ai/camel](https://github.com/camel-ai/camel)
- MCP Inspector工具：用于调试MCP服务器连接
---
*本文档由CAMEL-AI框架源码自动生成，最后更新于2024年*
---
## 智能体社会(Societies)
### 相关页面
相关主题：[智能体劳动力(Workforce)](#page-workforce), [智能体(Agents)](#page-agents)
相关源码文件
以下源码文件用于生成本页说明：
- [camel/societies/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/societies/__init__.py)
- [camel/societies/role_playing.py](https://github.com/camel-ai/camel/blob/main/camel/societies/role_playing.py)
- [camel/societies/babyagi_playing.py](https://github.com/camel-ai/camel/blob/main/camel/societies/babyagi_playing.py)
- [camel/personas/persona.py](https://github.com/camel-ai/camel/blob/main/camel/personas/persona.py)
- [camel/personas/persona_hub.py](https://github.com/camel-ai/camel/blob/main/camel/personas/persona_hub.py)
# 智能体社会(Societies)
## 概述
CAMEL框架中的**智能体社会(Societies)**模块是实现多智能体协作的核心基础设施。该模块提供了一套完整的多智能体交互机制，支持角色扮演、任务分解、自主执行等多种协作范式。智能体社会允许定义多个具有特定角色和能力的智能体，通过结构化的通信协议实现复杂的协作任务。
智能体社会的设计理念源于社会学中的"社会"概念，模拟人类社会中不同角色之间的交互模式。每个智能体被赋予特定的角色身份（如"AI助手"、"用户代理"等），这些角色定义了智能体的行为模式、决策风格和通信方式。通过这种方式，CAMEL能够构建具有真实感的AI系统交互场景。
## 核心架构
### 模块结构
CAMEL的智能体社会模块位于`camel/societies/`目录下，包含多个核心组件：
| 组件文件 | 功能描述 |
|---------|---------|
| `__init__.py` | 模块导出接口，定义公共API |
| `role_playing.py` | 角色扮演核心实现，支持双智能体协作 |
| `babyagi_playing.py` | BabyAGI范式实现，支持任务分解与执行 |
```
camel/societies/
├── __init__.py # 模块入口
├── role_playing.py # 角色扮演实现
└── babyagi_playing.py # BabyAGI实现
```
### 类层次结构
智能体社会模块采用面向对象设计，核心类包括：
- **RolePlaying**：角色扮演主类，管理两个智能体之间的对话交互
- **BabyAGI**：BabyAGI执行器，实现自主任务分解与执行
- **BaseSociety**：基础抽象类（若存在），定义通用接口
```mermaid
graph TD
A[BaseSociety] --> B[RolePlaying]
A --> C[BabyAGI]
B --> D[AI Assistant Agent]
B --> E[User Agent]
C --> F[Task Agent]
C --> G[Execution Agent]
C --> H[Critique Agent]
```
## 角色扮演系统(Role Playing)
### 系统设计
角色扮演是CAMEL框架中最核心的智能体协作模式。该系统模拟人类社会中的角色交互场景，由两个主要智能体组成：
- **AI助手智能体(AI Assistant Agent)**：扮演AI助手角色，响应用户请求
- **用户代理智能体(User Agent)**：代表最终用户，执行用户指定的任务
这种双智能体设计允许AI系统在没有人类直接干预的情况下自主协作完成任务。
### RolePlaying类详解
`RolePlaying`类是多智能体协作的主入口，提供完整的对话管理功能。
#### 构造函数参数
| 参数名 | 类型 | 必需 | 默认值 | 说明 |
|-------|------|------|--------|------|
| `assistant_agent` | `BaseAgent` | 是 | - | AI助手智能体实例 |
| `user_agent` | `BaseAgent` | 是 | - | 用户代理智能体实例 |
| `task_prompt` | `str` | 是 | - | 任务描述提示词 |
| `task_specify_prompt` | `str` | 否 | None | 任务细化提示词 |
| `with_task_specify` | `bool` | 否 | True | 是否进行任务细化 |
| `max_dialogue` | `int` | 否 | 20 | 最大对话轮数 |
| `turn_limit` | `int` | 否 | None | 单轮交互限制 |
#### 核心方法
| 方法名 | 返回类型 | 功能描述 |
|-------|---------|---------|
| `init_chat()` | `None` | 初始化对话，设置系统提示词 |
| `step()` | `ChatAgentResponse` | 执行单步对话交互 |
| `run()` | `List[BaseMessage]` | 运行完整的角色扮演对话 |
| `get_info()` | `Dict` | 获取当前对话状态信息 |
### 工作流程
角色扮演系统遵循严格的对话协议，确保智能体之间的交互有序进行：
```mermaid
graph TD
A[初始化 init_chat] --> B{检查终止条件}
B -->|未达到限制| C[AI助手生成回复]
C --> D[消息加入对话历史]
D --> E{检查终止条件}
E -->|未达到限制| F[用户代理处理]
F --> D
E -->|达到限制| G[返回对话历史]
B -->|达到限制| G
G --> H[对话结束]
```
### 任务指定机制
角色扮演系统包含任务指定(Task Specification)模块，用于将模糊的用户请求转化为具体的任务描述：
1. **任务分析**：AI助手分析用户意图
2. **任务细化**：将大任务分解为可执行的子任务
3. **目标确认**：用户代理确认任务目标和范围
4. **执行计划**：制定详细的执行步骤
```mermaid
graph LR
A[模糊任务请求] --> B[任务分析]
B --> C[任务细化]
C --> D[子任务分解]
D --> E[执行计划制定]
E --> F[具体可执行任务]
```
## 人物角色系统(Personas)
### Persona类
`Persona`类定义了智能体的身份特征和行为模式。
#### 属性定义
| 属性名 | 类型 | 说明 |
|-------|------|------|
| `name` | `str` | 角色名称 |
| `description` | `str` | 角色描述 |
| `system_instruction` | `str` | 系统级指令 |
| `role_type` | `RoleType` | 角色类型枚举 |
#### 核心功能
- **身份塑造**：定义智能体的角色身份和背景
- **行为约束**：通过系统指令约束智能体的行为模式
- **交互风格**：设定智能体的沟通和响应风格
### PersonaHub
`PersonaHub`是角色仓库，提供预定义的角色模板和自定义接口。
#### 预定义角色类型
| 角色标识 | 角色名称 | 应用场景 |
|---------|---------|---------|
| `ASSISTANT` | AI助手 | 通用问答和任务执行 |
| `USER` | 用户代理 | 代表用户执行任务 |
| `CRITIC` | 批评者 | 评估和审核任务结果 |
| `PLANNER` | 规划者 | 任务规划和分解 |
| `RESEARCHER` | 研究者 | 信息检索和分析 |
#### 角色获取接口
```python
# 从仓库获取预定义角色
persona = PersonaHub.get_persona(persona_type=PersonaType.ASSISTANT)
# 获取带自定义参数的角色
custom_persona = PersonaHub.get_persona(
persona_type=PersonaType.RESEARCHER,
custom_params={"expertise": "quantum computing"}
)
```
## BabyAGI范式
### 概述
BabyAGI是另一种智能体协作范式，与角色扮演不同，它更强调任务的自动分解和迭代执行。该模式模拟了人类解决复杂问题时的思考过程。
### BabyAGIPlaying类
`BabyAGIPlaying`类实现了BabyAGI的核心逻辑。
#### 组成结构
| 组件 | 类型 | 功能 |
|-----|------|------|
| `task_creation_agent` | `BaseAgent` | 负责创建和分解任务 |
| `execution_agent` | `BaseAgent` | 负责执行具体任务 |
| `critique_agent` | `BaseAgent` | 负责评估和反馈 |
#### 执行流程
```mermaid
graph TD
A[接收初始任务] --> B[任务创建智能体分析任务]
B --> C[生成任务列表]
C --> D{任务队列非空?}
D -->|是| E[执行智能体处理任务]
E --> F[批评智能体评估结果]
F --> G{需要新任务?}
G -->|是| H[创建新任务]
H --> C
G -->|否| I[任务完成]
I --> D
D -->|否| J[返回最终结果]
```
### 与角色扮演的区别
| 特性 | 角色扮演 | BabyAGI |
|------|---------|---------|
| 智能体数量 | 2个 | 3个或更多 |
| 通信模式 | 双向对话 | 多向协作 |
| 任务处理 | 协作完成 | 分解执行 |
| 反馈机制 | 有限 | 迭代改进 |
| 适用场景 | 对话交互 | 复杂任务 |
## 使用示例
### 基础角色扮演
```python
from camel.societies import RolePlaying
from camel.agents import ChatAgent
from camel.personas import PersonaHub
# 创建智能体
assistant_persona = PersonaHub.get_persona(PersonaType.ASSISTANT)
user_persona = PersonaHub.get_persona(PersonaType.USER)
assistant_agent = ChatAgent(persona=assistant_persona)
user_agent = ChatAgent(persona=user_persona)
# 初始化角色扮演
society = RolePlaying(
assistant_agent=assistant_agent,
user_agent=user_agent,
task_prompt="帮我分析量子计算的最新发展趋势"
)
# 执行对话
messages = society.run()
```
### BabyAGI任务执行
```python
from camel.societies import BabyAGIPlaying
# 初始化BabyAGI
babyagi = BabyAGIPlaying(
task="完成一份市场调研报告",
max_iterations=10
)
# 执行自主任务分解和执行
results = babyagi.run()
```
## 配置与扩展
### 智能体配置
智能体的行为可通过配置进行定制：
```python
from camel.config import AgentConfig
config = AgentConfig(
model_type="gpt-4",
temperature=0.7,
max_tokens=2000,
tool_use=True
)
```
### 自定义角色创建
```python
from camel.personas import Persona, PersonaType
custom_persona = Persona(
name="数据分析师",
description="专业的金融数据分析助手",
system_instruction="你是一位资深数据分析师，擅长从数据中发现洞见",
role_type=PersonaType.RESEARCHER
)
```
## 最佳实践
### 设计原则
1. **角色清晰**：确保每个智能体的角色定义明确，职责单一
2. **对话管理**：合理设置对话轮数限制，避免无限循环
3. **错误处理**：实现健壮的错误捕获和恢复机制
4. **资源管理**：及时释放不再使用的智能体资源
### 性能优化
- 合理设置`max_dialogue`参数控制对话长度
- 使用流式输出减少响应延迟
- 启用缓存机制避免重复计算
### 安全考虑
- 验证用户输入防止提示词注入攻击
- 限制工具调用的权限范围
- 实现对话内容审核机制
## 总结
CAMEL的智能体社会(Societies)模块提供了一套完整的多智能体协作框架。通过角色扮演和BabyAGI两种核心范式，开发者可以构建复杂的AI应用场景。模块化的设计使得系统易于扩展和定制，满足不同应用需求。人物角色系统为智能体提供了丰富的身份和行为特征，使多智能体交互更加真实和高效。
---
**相关文档**
- [基础对话智能体](../agents/chat_agent.md)
- [工具包(Toolkits)](../toolkits/README.md)
- [模型配置](../config/README.md)
---
## 智能体劳动力(Workforce)
### 相关页面
相关主题：[智能体社会(Societies)](#page-societies), [智能体(Agents)](#page-agents), [记忆系统(Memory)](#page-memory)
相关源码文件
以下源码文件用于生成本页说明：
- [camel/societies/workforce/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/__init__.py)
- [camel/societies/workforce/workforce.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/workforce.py)
- [camel/societies/workforce/worker.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/worker.py)
- [camel/societies/workforce/task_channel.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/task_channel.py)
- [camel/societies/workforce/role_playing_worker.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/role_playing_worker.py)
- [camel/societies/workforce/single_agent_worker.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/single_agent_worker.py)
- [camel/societies/workforce/events.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/events.py)
# 智能体劳动力(Workforce)
## 概述
Workforce 是 CAMEL 框架中的核心组件，用于协调和管理多个智能体(Worker)协同完成复杂任务。它提供了一个灵活的架构，使多个不同类型的 Worker 能够通过任务通道进行通信和协作，从而实现分布式问题解决和工作流自动化。
Workforce 的核心设计理念是将复杂任务分解为多个子任务，分配给专门化的 Worker 执行，并通过事件驱动的方式协调整个工作流程。资料来源：[camel/societies/workforce/__init__.py]()
## 核心架构
Workforce 系统由以下核心组件构成：
```mermaid
graph TD
A[Workforce] --> B[TaskChannel]
A --> C[Worker Pool]
C --> D[RolePlayingWorker]
C --> E[SingleAgentWorker]
C --> F[BaseWorker]
A --> G[EventSystem]
G --> H[WorkforceEvent]
B --> I[任务分发]
D --> J[角色扮演任务]
E --> K[单智能体任务]
```
## 目录结构
```
camel/societies/workforce/
├── __init__.py # 模块初始化，导出主要接口
├── workforce.py # Workforce 主类
├── worker.py # Worker 基类
├── role_playing_worker.py # 角色扮演 Worker
├── single_agent_worker.py # 单智能体 Worker
├── task_channel.py # 任务通道实现
└── events.py # 事件系统定义
```
## 组件详解
### Workforce 主类
Workforce 是整个系统的调度中心，负责管理 Worker 生命周期、任务分发和结果收集。资料来源：[camel/societies/workforce/workforce.py]()
**主要职责：**
- 初始化和管理 Worker 池
- 维护任务通道和事件系统
- 协调多 Worker 间的通信
- 监控任务执行状态
- 处理异常和超时情况
### Worker 基类
Worker 是执行任务的基本单元，提供统一的任务执行接口。资料来源：[camel/societies/workforce/worker.py]()
**Worker 类型对比：**
| Worker 类型 | 说明 | 适用场景 |
|-------------|------|----------|
| BaseWorker | 所有 Worker 的基类，定义通用接口 | 扩展自定义 Worker |
| RolePlayingWorker | 支持角色扮演的 Worker | 需要角色协作的任务 |
| SingleAgentWorker | 单一智能体 Worker | 独立执行的任务 |
### 任务通道 (TaskChannel)
TaskChannel 负责在 Worker 之间传递任务和结果。资料来源：[camel/societies/workforce/task_channel.py]()
**通道类型支持：**
- 同步通道：阻塞式任务传递
- 异步通道：非阻塞式任务传递
- 广播通道：一对多任务分发
### 事件系统 (Events)
事件系统提供 Workforce 内部的通信机制，支持状态变更通知和任务进度追踪。资料来源：[camel/societies/workforce/events.py]()
## 工作流程
### 任务执行流程
```mermaid
sequenceDiagram
participant U as 用户
participant W as Workforce
participant TC as TaskChannel
participant WK as Worker
participant E as EventSystem
U->>W: 提交任务
W->>TC: 创建任务通道
W->>WK: 分发任务
WK->>E: 发送任务开始事件
WK->>W: 执行任务
W->>E: 发布进度事件
WK->>TC: 返回结果
TC->>W: 收集结果
W->>U: 返回最终结果
```
### Worker 协作模式
```mermaid
graph LR
A[任务输入] --> B{Worker选择}
B -->|角色扮演| C[RolePlayingWorker]
B -->|独立执行| D[SingleAgentWorker]
C --> E[协作处理]
D --> F[独立处理]
E --> G[结果聚合]
F --> G
G --> H[结果输出]
```
## API 参考
### Workforce 初始化参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| workers | List[BaseWorker] | 是 | Worker 列表 |
| task_channel_type | str | 否 | 任务通道类型，默认 "default" |
| max_workers | int | 否 | 最大并发 Worker 数 |
| timeout | int | 否 | 任务超时时间(秒) |
### Worker 执行接口
```python
class BaseWorker(ABC):
@abstractmethod
async def execute(self, task: Task) -> Result:
"""执行单个任务"""
pass
@abstractmethod
async def reset(self) -> None:
"""重置 Worker 状态"""
pass
@property
@abstractmethod
def worker_id(self) -> str:
"""获取 Worker 唯一标识"""
pass
```
资料来源：[camel/societies/workforce/worker.py]()
## Worker 类型详解
### RolePlayingWorker
RolePlayingWorker 支持多角色协作模式，适用于需要角色扮演和对话的任务场景。资料来源：[camel/societies/workforce/role_playing_worker.py]()
**配置选项：**
| 选项 | 类型 | 说明 |
|------|------|------|
| role_name | str | 角色名称 |
| role_description | str | 角色描述 |
| model | Model | 使用的语言模型 |
| tools | List[Tool] | 可用工具列表 |
### SingleAgentWorker
SingleAgentWorker 是单一智能体执行器，适合不需要协作的独立任务。资料来源：[camel/societies/workforce/single_agent_worker.py]()
**特点：**
- 独立的执行环境
- 无需与其他 Worker 通信
- 更低的资源消耗
- 适用于简单任务
## 事件类型
WorkforceEvent 定义了系统中的各种事件类型。资料来源：[camel/societies/workforce/events.py]()
| 事件类型 | 触发时机 | 用途 |
|----------|----------|------|
| TASK_STARTED | 任务开始执行 | 记录任务启动 |
| TASK_COMPLETED | 任务完成 | 收集结果 |
| TASK_FAILED | 任务执行失败 | 错误处理 |
| WORKER_REGISTERED | Worker 注册 | 添加到调度池 |
| WORKER_UNREGISTERED | Worker 注销 | 清理资源 |
## 使用示例
### 基本使用
```python
from camel.societies.workforce import Workforce, SingleAgentWorker
from camel.societies.workforce.task_channel import TaskChannel
# 创建 Workforce
workforce = Workforce(
workers=[SingleAgentWorker(...)],
max_workers=4
)
# 提交任务
result = await workforce.execute_task(task)
```
### 角色协作场景
```python
from camel.societies.workforce import (
Workforce,
RolePlayingWorker,
TaskChannel
)
# 创建多角色 Workforce
workforce = Workforce(
workers=[
RolePlayingWorker(role_name="研究员", ...),
RolePlayingWorker(role_name="开发者", ...),
]
)
# 执行协作任务
result = await workforce.execute_collaborative_task(task)
```
## 最佳实践
### 1. Worker 配置建议
- 根据任务复杂度选择合适的 Worker 类型
- 合理设置 Worker 数量避免资源竞争
- 为长时间运行的任务配置超时机制
### 2. 任务分发策略
```mermaid
graph TD
A[任务类型判断] --> B{需要协作?}
B -->|是| C[使用 RolePlayingWorker]
B -->|否| D[使用 SingleAgentWorker]
C --> E[通过 TaskChannel 协调]
D --> F[直接执行]
```
### 3. 错误处理
- 监听 TASK_FAILED 事件进行错误恢复
- 实现 Worker 重试机制
- 设置合理的超时时间
## 与其他模块的集成
Workforce 与 CAMEL 框架中的其他模块紧密集成：
| 模块 | 集成方式 | 说明 |
|------|----------|------|
| ModelFactory | Worker 配置 | 为 Worker 提供模型支持 |
| Toolkits | 工具扩展 | Worker 可调用各种工具 |
| Messages | 通信协议 | Worker 间消息传递 |
| Storage | 状态持久化 | 任务状态存储 |
## 总结
Workforce 是 CAMEL 框架实现多智能体协作的核心基础设施。通过提供统一的任务分发、Worker 管理和事件驱动机制，Workforce 使得构建复杂的智能体协作系统变得简单高效。开发者可以根据具体需求选择合适的 Worker 类型，并通过灵活的配置实现各种协作模式。
---
## 记忆系统(Memory)
### 相关页面
相关主题：[智能体(Agents)](#page-agents)
相关源码文件
以下源码文件用于生成本页说明：
- [camel/memories/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/memories/__init__.py)
- [camel/memories/base.py](https://github.com/camel-ai/camel/blob/main/camel/memories/base.py)
- [camel/memories/agent_memories.py](https://github.com/camel-ai/camel/blob/main/camel/memories/agent_memories.py)
- [camel/memories/blocks/chat_history_block.py](https://github.com/camel-ai/camel/blob/main/camel/memories/blocks/chat_history_block.py)
- [camel/memories/blocks/vectordb_block.py](https://github.com/camel-ai/camel/blob/main/camel/memories/blocks/vectordb_block.py)
- [camel/memories/context_creators/score_based.py](https://github.com/camel-ai/camel/blob/main/camel/memories/context_creators/score_based.py)
- [camel/memories/records.py](https://github.com/camel-ai/camel/blob/main/camel/memories/records.py)
# 记忆系统(Memory)
## 概述
CAMEL记忆系统是框架中用于管理Agent对话上下文和历史信息的核心组件。该系统通过模块化的设计，支持多种记忆存储方式和上下文检索策略，使Agent能够高效地访问和利用历史交互信息。
记忆系统的核心设计理念是将**记忆存储**与**上下文生成**分离，通过可插拔的Block组件和Context Creator实现灵活的内存管理机制。
## 架构总览
```mermaid
graph TB
subgraph "记忆系统核心组件"
AM[AgentMemories]
MC[Memory]
CC[ContextCreator]
end
subgraph "存储块Blocks"
CHB[ChatHistoryBlock]
VDB[VectorDBBlock]
end
subgraph "上下文创建器"
SBC[ScoreBasedContextCreator]
end
subgraph "记录Records"
CHR[ChatHistoryRecord]
MR[MemoryRecord]
end
AM --> MC
AM --> CC
MC --> CHB
MC --> VDB
CC --> SBC
SBC --> MC
CHB --> CHR
VDB --> MR
```
## 核心组件
### 记忆基类 (Memory)
`Memory`是所有记忆组件的抽象基类，定义了记忆系统的核心接口：
```python
class Memory(Generic[MemoryRecord], ABC):
@property
@abstractmethod
def size(self) -> int: ...
@abstractmethod
def read(self, *args, **kwargs) -> List[MemoryRecord]: ...
@abstractmethod
def write(self, *args, **kwargs) -> None: ...
def clear(self) -> None: ...
```
| 方法 | 说明 | 返回值 |
|------|------|--------|
| `size` | 获取当前记忆存储的条目数量 | `int` |
| `read()` | 读取记忆记录 | `List[MemoryRecord]` |
| `write()` | 写入新的记忆记录 | `None` |
| `clear()` | 清除所有记忆 | `None` |
资料来源：[camel/memories/base.py]()
### Agent记忆管理器 (AgentMemories)
`AgentMemories`是Agent级别的记忆容器，负责整合多个记忆组件和上下文创建器：
```python
class AgentMemories:
def __init__(
self,
memories: List[Memory] = [],
context_creator: Optional[ContextCreator] = None,
) -> None:
self.memories: List[Memory] = memories
self.context_creator = context_creator
```
| 属性 | 类型 | 说明 |
|------|------|------|
| `memories` | `List[Memory]` | 关联的记忆块列表 |
| `context_creator` | `Optional[ContextCreator]` | 上下文创建器 |
**核心功能**：
- 管理多个记忆块的读写操作
- 聚合多个Memory组件的记忆内容
- 通过ContextCreator生成上下文摘要
资料来源：[camel/memories/agent_memories.py]()
## 存储块 (Blocks)
存储块是实际存储记忆数据的组件，支持不同的存储后端和检索策略。
### 聊天历史块 (ChatHistoryBlock)
`ChatHistoryBlock`用于存储和管理Agent之间的对话历史记录：
```python
class ChatHistoryBlock(Memory[ChatHistoryRecord]):
def __init__(
self,
window_size: int = 0,
max_tokens: int = 0,
) -> None:
```
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `window_size` | `int` | `0` | 滑动窗口大小，0表示不使用窗口 |
| `max_tokens` | `int` | `0` | 最大token数限制 |
**写入机制**：
- 接收`ChatHistoryRecord`类型的记录
- 支持基于窗口大小或token数量的自动截断
- 保持对话顺序的时间序列
**读取机制**：
- 按时间顺序返回历史记录
- 支持窗口截断和token限制
资料来源：[camel/memories/blocks/chat_history_block.py]()
### 向量数据库块 (VectorDBBlock)
`VectorDBBlock`利用向量数据库实现语义相似度检索：
```python
class VectorDBBlock(Memory[MemoryRecord]):
def __init__(
self,
embedding_model: Optional[EmbeddingModel] = None,
query_processor: Optional[QueryProcessor] = None,
embedding_backend: Optional[EmbeddingModel] = None,
storage: Optional[VectorDB] = None,
k: int = 10,
max_tokens: int = 0,
) -> None:
```
| 参数 | 类型 | 说明 |
|------|------|------|
| `embedding_model` | `Optional[EmbeddingModel]` | 向量嵌入模型 |
| `query_processor` | `Optional[QueryProcessor]` | 查询处理器 |
| `storage` | `Optional[VectorDB]` | 向量数据库存储后端 |
| `k` | `int` | 检索返回的最大结果数 |
| `max_tokens` | `int` | 最大token数限制 |
**检索流程**：
1. 将输入查询转换为向量表示
2. 在向量数据库中进行相似度搜索
3. 返回Top-K个最相关的记忆记录
资料来源：[camel/memories/blocks/vectordb_block.py]()
## 记录类型 (Records)
记录类型定义了记忆系统中各种数据的结构化格式。
### ChatHistoryRecord
```python
@dataclass
class ChatHistoryRecord(MemoryRecord):
role: str
content: str
message_type: RoleType
```
| 字段 | 类型 | 说明 |
|------|------|------|
| `role` | `str` | 消息发送者角色 |
| `content` | `str` | 消息内容 |
| `message_type` | `RoleType` | 角色类型 |
资料来源：[camel/memories/records.py]()
## 上下文创建器 (Context Creators)
上下文创建器负责从记忆系统中提取相关信息，生成供Agent使用的上下文提示。
### 基于评分的上下文创建器 (ScoreBasedContextCreator)
`ScoreBasedContextCreator`通过评分机制选择最相关的记忆片段：
```python
class ScoreBasedContextCreator(ContextCreator):
def __init__(
self,
model: Model,
score_threshold: float = 0.5,
max_context_tokens: int = 4096,
) -> None:
```
| 参数 | 类型 | 说明 |
|------|------|------|
| `model` | `Model` | 用于评分的语言模型 |
| `score_threshold` | `float` | 评分阈值，默认0.5 |
| `max_context_tokens` | `int` | 最大上下文token数 |
**评分机制**：
- 使用LLM评估每条记忆与当前查询的相关性
- 过滤低于阈值的记忆记录
- 按评分排序并截断至token限制
资料来源：[camel/memories/context_creators/score_based.py]()
## 工作流程
### 记忆写入流程
```mermaid
sequenceDiagram
participant Agent
participant AgentMemories
participant Memory
participant Block
Agent->>AgentMemories: 添加新记录
AgentMemories->>Memory: write(record)
Memory->>Block: 存储记录
Block->>Block: 格式化/截断
Block-->>AgentMemories: 确认写入
AgentMemories-->>Agent: 写入完成
```
### 上下文检索流程
```mermaid
sequenceDiagram
participant Query
participant ContextCreator
participant Memory
participant Block
Query->>ContextCreator: 生成上下文请求
ContextCreator->>Memory: read(query)
Memory->>Block: 检索记录
Block-->>Memory: 返回候选记录
Memory-->>ContextCreator: 评分排序
ContextCreator->>ContextCreator: 过滤和截断
ContextCreator-->>Query: 返回上下文
```
## 使用示例
### 基本使用
```python
from camel.memories import AgentMemories, ChatHistoryBlock
from camel.memories.blocks import VectorDBBlock
# 创建记忆块
chat_history = ChatHistoryBlock(window_size=10)
vector_store = VectorDBBlock(k=5)
# 组合成Agent记忆
agent_memories = AgentMemories(
memories=[chat_history, vector_store]
)
# 写入对话记录
agent_memories.memories[0].write(
ChatHistoryRecord(
role="user",
content="Hello, how are you?",
message_type=RoleType.USER
)
)
# 读取记忆
records = agent_memories.memories[0].read()
```
### 带上下文创建器的使用
```python
from camel.memories import AgentMemories, ContextCreator
from camel.memories.context_creators import ScoreBasedContextCreator
# 创建上下文创建器
context_creator = ScoreBasedContextCreator(
model=model,
score_threshold=0.6,
max_context_tokens=4096
)
# 创建带上下文的记忆管理
agent_memories = AgentMemories(
memories=[chat_history, vector_store],
context_creator=context_creator
)
# 生成上下文
context = agent_memories.context_creator.generate_context(
query="What did we discuss about AI?",
memories=agent_memories.memories
)
```
## 模块导出
`camel/memories/__init__.py`模块导出以下公共接口：
| 导出 | 说明 |
|------|------|
| `Memory` | 记忆抽象基类 |
| `AgentMemories` | Agent记忆管理器 |
| `ContextCreator` | 上下文创建器基类 |
| `ChatHistoryRecord` | 聊天历史记录 |
| `MemoryRecord` | 基础记忆记录 |
资料来源：[camel/memories/__init__.py]()
## 设计模式
记忆系统采用了以下设计模式：
1. **策略模式**：通过ContextCreator接口支持多种上下文生成策略
2. **组合模式**：AgentMemories组合多个Memory组件统一管理
3. **工厂模式**：通过参数化配置创建不同类型的存储块
4. **适配器模式**：统一的Memory接口适配不同后端存储
## 扩展指南
### 自定义记忆块
```python
from camel.memories import Memory, MemoryRecord
class CustomMemoryBlock(Memory[CustomRecord]):
def __init__(self, config: CustomConfig) -> None:
self.config = config
self._storage = []
@property
def size(self) -> int:
return len(self._storage)
def read(self, *args, **kwargs) -> List[CustomRecord]:
# 实现读取逻辑
return self._storage
def write(self, *args, **kwargs) -> None:
# 实现写入逻辑
pass
```
### 自定义上下文创建器
```python
from camel.memories import ContextCreator
class CustomContextCreator(ContextCreator):
def __init__(self, model: Model) -> None:
self.model = model
def generate_context(
self,
query: str,
memories: List[Memory]
) -> str:
# 实现自定义上下文生成逻辑
pass
---
---
## Doramagic 踩坑日志
项目：camel-ai/camel
摘要：发现 19 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature Request] Expand WorkforceCallback to support stream chunk events。
## 1. 安装坑 · 来源证据：[Feature Request] Expand WorkforceCallback to support stream chunk events
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature Request] Expand WorkforceCallback to support stream chunk events
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_6e53abdf5bc6401d8d9e105ad6bc199f | https://github.com/camel-ai/camel/issues/3676 | 来源类型 github_issue 暴露的待验证使用条件。
## 2. 安装坑 · 来源证据：[Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5ca8493db7f140ca97d289664d6eb484 | https://github.com/camel-ai/camel/issues/1043 | 来源类型 github_issue 暴露的待验证使用条件。
## 3. 安装坑 · 来源证据：[Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_53427dbbe45a4c2dacf26673addcd0c4 | https://github.com/camel-ai/camel/issues/4045 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。
## 4. 安全/权限坑 · 来源证据：[BUG] Both Bedrock options are broken
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Both Bedrock options are broken
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0dd321222ec44d14aa25d8cde3aeaef9 | https://github.com/camel-ai/camel/issues/4034 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 5. 安全/权限坑 · 来源证据：[Feature Request] Add OrcaRouter as a dedicated model platform
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Add OrcaRouter as a dedicated model platform
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9b8e4797fc294e8e8c795de01b5418da | https://github.com/camel-ai/camel/issues/4047 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 6. 能力坑 · 社区讨论暴露的待验证问题：The best open source general AI agent is on !
- 严重度：medium
- 证据强度：source_linked
- 发现：The best open source general AI agent is on ! Excited to share our new project OWL - an open-source alternative to Manus AI with 6K+ stars and climbing… OWL: github.com/camel-ai/owl
- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
- 证据：social_signal:x | ssig_9705a4152aac4e7db1ec2472633ef681 | https://x.com/CamelAIOrg/status/1899069486587593176 | The best open source general AI agent is on !
## 7. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:615510678 | https://github.com/camel-ai/camel | README/documentation is current enough for a first validation pass.
## 8. 运行坑 · 来源证据：v0.2.91a2
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.2.91a2
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0c6ec0ec1a0a421a9dc7bf0e05814f20 | https://github.com/camel-ai/camel/releases/tag/v0.2.91a2 | 来源类型 github_release 暴露的待验证使用条件。
## 9. 维护坑 · 来源证据：[Question] About the Deprecation of the `reasoning_content` Field in vLLM
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[Question] About the Deprecation of the `reasoning_content` Field in vLLM
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d44976120f444580a5a9afefb7711f0c | https://github.com/camel-ai/camel/issues/3939 | 来源类型 github_issue 暴露的待验证使用条件。
## 10. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:615510678 | https://github.com/camel-ai/camel | last_activity_observed missing
## 11. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:615510678 | https://github.com/camel-ai/camel | no_demo; severity=medium
## 12. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | github_repo:615510678 | https://github.com/camel-ai/camel | No sandbox install has been executed yet; downstream must verify before user use.
## 13. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:615510678 | https://github.com/camel-ai/camel | no_demo; severity=medium
## 14. 安全/权限坑 · 来源证据：v0.2.90
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_aacd3063c35745ea9cf8392274d9c53d | https://github.com/camel-ai/camel/releases/tag/v0.2.90 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。
## 15. 安全/权限坑 · 来源证据：v0.2.90a4
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90a4
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2c18897f1147431ea64419fef84398cc | https://github.com/camel-ai/camel/releases/tag/v0.2.90a4 | 来源类型 github_release 暴露的待验证使用条件。
## 16. 安全/权限坑 · 来源证据：v0.2.90a5
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90a5
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_defae93359fb4942a54fe8deedabdef8 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a5 | 来源类型 github_release 暴露的待验证使用条件。
## 17. 安全/权限坑 · 来源证据：v0.2.90a6
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90a6
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a56ec216a5e84c3799b5d1a4a57ed4b3 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a6 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。
## 18. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:615510678 | https://github.com/camel-ai/camel | issue_or_pr_quality=unknown
## 19. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:615510678 | https://github.com/camel-ai/camel | release_recency=unknown