{
"canonical_name": "camel-ai/camel",
"compilation_id": "pack_c57a5be878674f46ac9152a0211d6ba6",
"created_at": "2026-05-13T14:10:28.572076+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install camel-ai` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install camel-ai",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_f35d839b2c4044f89673b5f7867877d8"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_18a39d1d31b6d0591d535dff8b5f3945",
"canonical_name": "camel-ai/camel",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/camel-ai/camel",
"slug": "camel",
"source_packet_id": "phit_cbc15782d387414eb91801a0731fae6e",
"source_validation_id": "dval_9129c8f1f5da4fde9f5358e1caf44bf6"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 1896,
"github_stars": 16935,
"one_liner_en": "🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org",
"one_liner_zh": "🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "camel",
"title_zh": "camel 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Natural-language Web Actions",
"label_zh": "自然语言网页操作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-natural-language-web-actions",
"type": "core_capability"
},
{
"label_en": "Multi-role Workflow",
"label_zh": "多角色协作流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-multi-role-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_cbc15782d387414eb91801a0731fae6e",
"page_model": {
"artifacts": {
"artifact_slug": "camel",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install camel-ai",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/camel-ai/camel#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"多角色协作流程",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature Request] Expand WorkforceCallback to support stream chunk events",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_6e53abdf5bc6401d8d9e105ad6bc199f | https://github.com/camel-ai/camel/issues/3676 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Feature Request] Expand WorkforceCallback to support stream chunk events",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_5ca8493db7f140ca97d289664d6eb484 | https://github.com/camel-ai/camel/issues/1043 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_53427dbbe45a4c2dacf26673addcd0c4 | https://github.com/camel-ai/camel/issues/4045 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Both Bedrock options are broken",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_0dd321222ec44d14aa25d8cde3aeaef9 | https://github.com/camel-ai/camel/issues/4034 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[BUG] Both Bedrock options are broken",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Add OrcaRouter as a dedicated model platform",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_9b8e4797fc294e8e8c795de01b5418da | https://github.com/camel-ai/camel/issues/4047 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Feature Request] Add OrcaRouter as a dedicated model platform",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "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",
"category": "能力坑",
"evidence": [
"social_signal:x | ssig_9705a4152aac4e7db1ec2472633ef681 | https://x.com/CamelAIOrg/status/1899069486587593176 | The best open source general AI agent is on !"
],
"severity": "medium",
"suggested_check": "Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。",
"title": "社区讨论暴露的待验证问题：The best open source general AI agent is on !",
"user_impact": "这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:615510678 | https://github.com/camel-ai/camel | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.2.91a2",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_0c6ec0ec1a0a421a9dc7bf0e05814f20 | https://github.com/camel-ai/camel/releases/tag/v0.2.91a2 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.2.91a2",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[Question] About the Deprecation of the `reasoning_content` Field in vLLM",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_d44976120f444580a5a9afefb7711f0c | https://github.com/camel-ai/camel/issues/3939 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[Question] About the Deprecation of the `reasoning_content` Field in vLLM",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:615510678 | https://github.com/camel-ai/camel | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:615510678 | https://github.com/camel-ai/camel | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"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."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:615510678 | https://github.com/camel-ai/camel | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_aacd3063c35745ea9cf8392274d9c53d | https://github.com/camel-ai/camel/releases/tag/v0.2.90 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.2.90",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90a4",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_2c18897f1147431ea64419fef84398cc | https://github.com/camel-ai/camel/releases/tag/v0.2.90a4 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.2.90a4",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90a5",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_defae93359fb4942a54fe8deedabdef8 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a5 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.2.90a5",
"user_impact": "可能影响授权、密钥配置或安全边界。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 19 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature Request] Expand WorkforceCallback to support stream chunk events。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 206,
"forks": 1896,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 16935
},
"source_url": "https://github.com/camel-ai/camel",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org",
"title": "camel 能力包",
"trial_prompt": "# camel - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 camel 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目简介。围绕“项目简介”模拟一次用户任务，不展示安装或运行结果。\n2. page-quickstart：快速入门指南。围绕“快速入门指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构设计。围绕“系统架构设计”模拟一次用户任务，不展示安装或运行结果。\n4. page-agents：智能体(Agents)。围绕“智能体(Agents)”模拟一次用户任务，不展示安装或运行结果。\n5. page-models：模型集成(Models)。围绕“模型集成(Models)”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quickstart\n输入：用户提供的“快速入门指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-agents\n输入：用户提供的“智能体(Agents)”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-models\n输入：用户提供的“模型集成(Models)”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quickstart：Step 2 必须围绕“快速入门指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构设计”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-agents：Step 4 必须围绕“智能体(Agents)”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-models：Step 5 必须围绕“模型集成(Models)”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/camel-ai/camel\n- https://github.com/camel-ai/camel#readme\n- .camel/skills/docs-incremental-update/SKILL.md\n- .camel/skills/skill-creator/SKILL.md\n- examples/toolkits/skill_toolkit_example/.camel/skills/code-reviewer/SKILL.md\n- examples/toolkits/skill_toolkit_example/.camel/skills/data-analyzer/SKILL.md\n- examples/toolkits/skill_toolkit_example/.camel/skills/report-writer/SKILL.md\n- README.md\n- pyproject.toml\n- camel/__init__.py\n- docs/get_started/installation.md\n- docs/get_started/setup.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 camel 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: [Question] when using VLLM / gemma4 / unsloath studio and the right jinj（https://github.com/camel-ai/camel/issues/4045）；github/github_issue: [Feature Request] Refactor to use `api_keys_required` and `dependencies_（https://github.com/camel-ai/camel/issues/1043）；github/github_issue: [Feature Request] Add OrcaRouter as a dedicated model platform（https://github.com/camel-ai/camel/issues/4047）；github/github_issue: [Question] About the Deprecation of the `reasoning_content` Field in vLL（https://github.com/camel-ai/camel/issues/3939）；github/github_issue: [BUG] Both Bedrock options are broken（https://github.com/camel-ai/camel/issues/4034）；github/github_issue: [Feature Request] Expand WorkforceCallback to support stream chunk event（https://github.com/camel-ai/camel/issues/3676）；github/github_release: v0.2.91a2（https://github.com/camel-ai/camel/releases/tag/v0.2.91a2）；github/github_release: v0.2.91a0（https://github.com/camel-ai/camel/releases/tag/v0.2.91a0）；github/github_release: v0.2.90（https://github.com/camel-ai/camel/releases/tag/v0.2.90）；github/github_release: v0.2.90a6（https://github.com/camel-ai/camel/releases/tag/v0.2.90a6）；github/github_release: v0.2.90a5（https://github.com/camel-ai/camel/releases/tag/v0.2.90a5）；github/github_release: v0.2.90a4（https://github.com/camel-ai/camel/releases/tag/v0.2.90a4）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "[Question] when using VLLM / gemma4 / unsloath studio and the right jinj",
"url": "https://github.com/camel-ai/camel/issues/4045"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Feature Request] Refactor to use `api_keys_required` and `dependencies_",
"url": "https://github.com/camel-ai/camel/issues/1043"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Feature Request] Add OrcaRouter as a dedicated model platform",
"url": "https://github.com/camel-ai/camel/issues/4047"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Question] About the Deprecation of the `reasoning_content` Field in vLL",
"url": "https://github.com/camel-ai/camel/issues/3939"
},
{
"kind": "github_issue",
"source": "github",
"title": "[BUG] Both Bedrock options are broken",
"url": "https://github.com/camel-ai/camel/issues/4034"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Feature Request] Expand WorkforceCallback to support stream chunk event",
"url": "https://github.com/camel-ai/camel/issues/3676"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.2.91a2",
"url": "https://github.com/camel-ai/camel/releases/tag/v0.2.91a2"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.2.91a0",
"url": "https://github.com/camel-ai/camel/releases/tag/v0.2.91a0"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.2.90",
"url": "https://github.com/camel-ai/camel/releases/tag/v0.2.90"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.2.90a6",
"url": "https://github.com/camel-ai/camel/releases/tag/v0.2.90a6"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.2.90a5",
"url": "https://github.com/camel-ai/camel/releases/tag/v0.2.90a5"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.2.90a4",
"url": "https://github.com/camel-ai/camel/releases/tag/v0.2.90a4"
}
],
"status": "已收录 13 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org",
"effort": "安装已验证",
"forks": 1896,
"icon": "code",
"name": "camel 能力包",
"risk": "可发布",
"slug": "camel",
"stars": 16935,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"多角色协作流程",
"评测体系"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/camel-ai/camel 项目说明书\n\n生成时间：2026-05-13 14:07:02 UTC\n\n## 目录\n\n- [项目简介](#page-overview)\n- [快速入门指南](#page-quickstart)\n- [系统架构设计](#page-architecture)\n- [智能体(Agents)](#page-agents)\n- [模型集成(Models)](#page-models)\n- [工具集(Toolkits)](#page-toolkits)\n- [MCP协议集成](#page-mcp)\n- [智能体社会(Societies)](#page-societies)\n- [智能体劳动力(Workforce)](#page-workforce)\n- [记忆系统(Memory)](#page-memory)\n\n\n\n## 项目简介\n\n### 相关页面\n\n相关主题：[快速入门指南](#page-quickstart), [系统架构设计](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/usecases/codeforces_question_solver/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/codeforces_question_solver/README.md)\n- [examples/usecases/multi_agent_research_assistant/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/multi_agent_research_assistant/README.md)\n- [examples/usecases/aci_mcp/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/aci_mcp/README.md)\n- [examples/usecases/airbnb_mcp/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/airbnb_mcp/README.md)\n- [examples/usecases/cloudfare_mcp_camel/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/cloudfare_mcp_camel/README.md)\n- [examples/usecases/chat_with_youtube/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/chat_with_youtube/README.md)\n- [examples/usecases/youtube_ocr/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/youtube_ocr/README.md)\n- [examples/usecases/pptx_toolkit_usecase/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/pptx_toolkit_usecase/README.md)\n \n\n# 项目简介\n\n## 项目概述\n\nCAMEL（Communicative Agents for Multi-Agent Learning）是一个开源的多智能体推理框架，旨在通过多智能体协作的方式实现复杂任务的自动化处理。该项目由CAMEL-AI团队开发和维护，作为一个多智能体系统的核心基础设施，为开发者提供了构建、部署和管理智能代理应用的完整解决方案。\n\nCAMEL框架的核心价值在于其**角色扮演机制**（Role Playing）和**自主协作能力**。通过定义不同的智能代理角色，框架能够模拟真实世界中的团队协作场景，使多个AI代理能够像人类团队一样进行分工合作、问题讨论和决策制定。资料来源：[examples/usecases/multi_agent_research_assistant/README.md]()\n\n## 核心设计理念\n\n### 多智能体协作范式\n\nCAMEL采用了一种创新的多智能体协作范式，其核心理念是将复杂任务分解为多个子任务，分配给具有不同专业能力的智能代理来协同完成。这种设计模式借鉴了人类社会中的团队协作模式，每个代理都扮演特定的角色，承担相应的职责，并通过标准化的通信机制进行信息交换和任务协调。\n\n框架支持灵活的代理配置，开发者可以根据实际需求定义代理的数量、角色属性、专业能力和工具集。这种高度可定制化的设计使得CAMEL能够适应各种复杂的应用场景，从简单的问答系统到复杂的多步骤任务执行都能够得到良好的支持。\n\n### 自主任务规划\n\nCAMEL框架内置了强大的自主任务规划能力。当给定一个高层次的任务目标时，框架能够自动分析任务需求，将其分解为可执行的子步骤，并协调多个代理逐步完成。这种端到端的自动化能力大大降低了开发者的工作负担，无需手动定义每个执行步骤的细节。\n\n## 技术架构\n\nCAMEL项目采用了模块化的架构设计，将核心功能划分为多个独立且可组合的组件。\n\n### 系统架构图\n\n```mermaid\ngraph TD\n A[用户应用层] --> B[Agent 管理层]\n B --> C[工具包 Toolkit 层]\n B --> D[模型交互层]\n B --> E[运行时 Runtime 层]\n C --> F[Browser Toolkit]\n C --> G[MCP 集成]\n C --> H[第三方服务集成]\n D --> I[OpenAI API]\n D --> J[Gemini API]\n D --> K[Mistral API]\n E --> L[Docker Runtime]\n E --> M[云端 Runtime]\n```\n\n### 核心组件说明\n\n| 组件名称 | 功能描述 | 依赖关系 |\n|---------|---------|---------|\n| Agent 管理层 | 管理代理的创建、生命周期和状态 | 依赖模型交互层 |\n| Toolkit 层 | 提供各类工具和MCP集成能力 | 被Agent管理层调用 |\n| 模型交互层 | 统一封装多种大语言模型API | 被Agent管理层使用 |\n| 运行时层 | 提供容器化和云端执行环境 | 支撑整个框架运行 |\n\n资料来源：[examples/usecases/aci_mcp/README.md]()\n\n## 核心功能特性\n\n### 1. 角色扮演系统\n\nCAMEL的角色扮演系统允许开发者为每个代理定义独特的角色属性，包括专业领域、行为模式、沟通风格等。这种设计使得代理能够扮演各种角色，如研究员、开发者、审核员等，形成完整的团队协作结构。\n\n角色定义支持丰富的配置选项，包括系统提示词（System Prompt）、温度参数、工具权限等。框架提供了便捷的API来创建和管理这些角色，使得复杂的多代理场景配置变得简单直观。\n\n### 2. 工具集成生态\n\nCAMEL建立了一个丰富的工具集成生态系统，为代理提供了强大的外部能力支持。\n\n#### 主要工具包类型\n\n| 工具类别 | 功能描述 | 典型应用场景 |\n|---------|---------|--------------|\n| Browser Toolkit | 浏览器自动化操作 | 网页内容抓取、表单填写 |\n| MCP 集成 | 模型上下文协议支持 | 标准化工具调用 |\n| PPTX Toolkit | PowerPoint 生成 | 自动演示文稿制作 |\n| OCR Toolkit | 文字识别 | 图像和PDF内容提取 |\n| 视频处理工具 | 音视频内容分析 | YouTube 内容分析 |\n\n资料来源：[examples/usecases/pptx_toolkit_usecase/README.md]()\n\n### 3. MCP 服务器支持\n\nCAMEL全面支持 Anthropic 的模型上下文协议（Model Context Protocol），这使得框架能够与各种外部服务和工具进行标准化集成。通过MCP协议，开发者可以轻松地将CAMEL代理与外部系统连接，扩展代理的能力边界。\n\n框架提供了便捷的MCP服务器配置机制，支持本地和远程服务器的配置和管理。开发者可以通过JSON配置文件定义多个MCP服务器，框架会自动处理服务器连接和消息路由。\n\n#### MCP 集成架构\n\n```mermaid\ngraph LR\n A[CAMEL Agent] <--> B[MCP Client]\n B <--> C[MCP Server]\n C --> D[Cloudflare 服务]\n C --> E[Airbnb 服务]\n C --> F[ACI.dev 服务]\n C --> G[自定义服务]\n```\n\n资料来源：[examples/usecases/airbnb_mcp/README.md]()\n\n### 4. 多平台集成\n\nCAMEL框架展示了与多种第三方平台的深度集成能力。\n\n#### 支持的平台类型\n\n| 平台名称 | 集成方式 | 功能特性 |\n|---------|---------|---------|\n| Firecrawl | API 集成 | 网页抓取和数据提取 |\n| YouTube | 视频处理 | 字幕提取、OCR分析 |\n| Mistral | OCR 处理 | PDF和图像文字识别 |\n| Cloudflare | MCP 协议 | 文档查询、Radar数据、浏览器 |\n| Airbnb | MCP 协议 | 房源搜索和信息查询 |\n| GitHub | API 集成 | 代码仓库对话和分析 |\n\n资料来源：[examples/usecases/chat_with_youtube/README.md]()\n\n## 应用场景\n\n### 代码问题求解\n\nCAMEL可以用于自动解决编程问题。通过整合网络搜索和代码分析能力，多个代理协作完成从问题理解到解决方案生成的完整流程。\n\n### 学术研究报告生成\n\n多代理系统可以协同完成复杂的研究任务：研究员代理负责收集资料，分析师代理处理数据，作家代理生成报告内容，审核代理进行质量把控。这种流水线式的协作模式大大提高了研究效率。\n\n### 自动化演示文稿制作\n\nCAMEL的PPTX Toolkit能够根据用户提供的topic自动生成专业的演示文稿，支持多种幻灯片类型，包括标题页、步骤说明、表格对比、图片展示等。\n\n### 智能网页交互\n\n通过Browser Toolkit和Cloudflare MCP集成，CAMEL代理能够执行复杂的网页操作，包括表单填写、内容搜索、数据提取等任务。\n\n### 视频内容分析\n\n整合YouTube视频处理能力和OCR技术，代理可以分析视频内容、提取字幕信息、回答关于视频内容的问题。\n\n## 部署方式\n\n### Docker 运行时环境\n\nCAMEL支持Docker容器化部署，提供了完整的Dockerfile和运行环境管理脚本。开发者可以快速构建包含CAMEL框架及其依赖的容器镜像，实现一致的开发部署体验。\n\n### 云端服务集成\n\n框架设计了云端运行时支持，能够在远程服务器上执行代理任务。这种设计特别适合需要大量计算资源的场景，以及需要长时间运行的任务。\n\n### 本地开发环境\n\n开发者可以直接在本地Python环境中安装CAMEL包进行开发和测试。框架支持虚拟环境管理，便于项目隔离和依赖管理。\n\n## 开发工具支持\n\n### Streamlit 应用模板\n\nCAMEL提供了多个基于Streamlit的示例应用，展示了如何快速构建交互式的多代理应用界面。这些应用模板覆盖了从简单的聊天界面到复杂的数据分析仪表盘等场景。\n\n### Gradio 部署支持\n\n框架支持将代理应用部署到Hugging Face Spaces等Gradio托管平台，提供了相应的部署脚本和配置指南。\n\n### 数据探索工具\n\nCAMEL附带的数据浏览器工具允许开发者可视化探索CAMEL框架生成的各类数据集，便于调试和结果分析。\n\n## 技术依赖\n\nCAMEL框架的核心依赖包括：\n\n- **Python 版本**：3.10 或 3.12\n- **核心包**：streamlit、rich、pydantic\n- **AI 模型**：OpenAI GPT系列、Google Gemini、Mistral、各类开源模型\n- **工具库**：yt-dlp（视频处理）、ffmpeg（音视频处理）、tesseract（OCR）\n\n资料来源：[examples/usecases/mistral_OCR/README.md]()\n\n## 项目组织结构\n\n```\ncamel/\n├── camel/ # 核心框架代码\n│ ├── toolkits/ # 工具包实现\n│ ├── agents/ # 代理实现\n│ └── runtime/ # 运行时支持\n├── examples/ # 示例应用\n│ ├── usecases/ # 各类使用场景\n│ └── runtimes/ # 运行时示例\n├── services/ # 微服务组件\n├── apps/ # 应用程序示例\n└── README.md # 项目文档\n```\n\n## 总结\n\nCAMEL作为一个开源的多智能体推理框架，提供了完整的解决方案来构建基于大语言模型的智能代理系统。其核心优势包括：\n\n- **灵活的代理配置**：支持自定义角色和协作模式\n- **丰富的工具集成**：覆盖浏览器自动化、MCP协议、文档处理等多个领域\n- **多样的部署选项**：支持Docker、本地和云端部署\n- **活跃的社区生态**：持续更新的示例和最佳实践\n\nCAMEL的设计理念和实现方案为开发者提供了一个强大的基础平台，使得构建复杂的多代理应用变得更加简单和高效。无论是学术研究还是工业应用，CAMEL都展现出了广泛的适用性和巨大的发展潜力。\n\n---\n\n\n\n## 快速入门指南\n\n### 相关页面\n\n相关主题：[项目简介](#page-overview), [智能体(Agents)](#page-agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/get_started/installation.md](https://github.com/camel-ai/camel/blob/main/docs/get_started/installation.md)\n- [docs/get_started/setup.md](https://github.com/camel-ai/camel/blob/main/docs/get_started/setup.md)\n- [.env.example](https://github.com/camel-ai/camel/blob/main/.env.example)\n- [examples/agents/create_chat_agent.py](https://github.com/camel-ai/camel/blob/main/examples/agents/create_chat_agent.py)\n- [examples/usecases/codeforces_question_solver/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/codeforces_question_solver/README.md)\n- [examples/usecases/multi_agent_research_assistant/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/multi_agent_research_assistant/README.md)\n- [examples/usecases/aci_mcp/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/aci_mcp/README.md)\n \n\n# 快速入门指南\n\nCAMEL（Communicative Agents Framework）是一个多智能体协作框架，旨在通过角色扮演和任务分解实现复杂的 AI 驱动工作流。本指南将帮助您快速了解如何安装、配置并运行 CAMEL 项目。\n\n## 环境要求\n\n| 要求 | 最低版本 | 推荐版本 |\n|------|----------|----------|\n| Python | 3.10 | 3.12 |\n| Docker | 最新稳定版 | 最新稳定版 |\n| pip | 22.0+ | 最新 |\n\nCAMEL 支持多种运行环境，包括本地 Python 环境、Docker 容器以及云端部署。资料来源：[docs/get_started/installation.md](https://github.com/camel-ai/camel/blob/main/docs/get_started/installation.md)\n\n## 安装方式\n\n### 方式一：pip 直接安装\n\n```bash\npip install camel-ai\n```\n\n### 方式二：安装完整依赖（含所有工具包）\n\n```bash\npip install camel-ai[all]\n```\n\n### 方式三：从源码安装\n\n```bash\ngit clone https://github.com/camel-ai/camel.git\ncd camel\npip install -e .\n```\n\n资料来源：[docs/get_started/installation.md](https://github.com/camel-ai/camel/blob/main/docs/get_started/installation.md)\n\n## 环境配置\n\n### 配置环境变量\n\nCAMEL 使用 `.env` 文件管理 API 密钥和其他配置。创建项目根目录下的 `.env` 文件：\n\n```env\nOPENAI_API_KEY=your_openai_api_key\nFIRECRAWL_API_KEY=your_firecrawl_api_key\nACI_API_KEY=your_aci_api_key\nGEMINI_API_KEY=your_gemini_api_key\n```\n\n> 注意：确保将 `.env` 文件加入 `.gitignore`，避免密钥泄露。资料来源：[.env.example](https://github.com/camel-ai/camel/blob/main/.env.example)\n\n### 模型配置\n\nCAMEL 支持多种模型平台：\n\n| 平台 | 模型类型 | 配置方式 |\n|------|----------|----------|\n| OpenAI | GPT-4, GPT-3.5 | API Key |\n| Google Gemini | Gemini Pro | GEMINI_API_KEY |\n| ModelScope | Qwen 系列 | ModelScope API |\n| OpenAI 兼容 | 自定义模型 | URL + API Key |\n\n资料来源：[examples/runtimes/ubuntu_docker_runtime/README.md](https://github.com/camel-ai/camel/blob/main/examples/runtimes/ubuntu_docker_runtime/README.md)\n\n## 基础使用示例\n\n### 创建对话代理\n\nCAMEL 的核心是 `ChatAgent`，用于创建可进行对话交互的 AI 代理：\n\n```python\nfrom camel.agents import ChatAgent\nfrom camel.configs import ChatAgentConfig\nfrom camel.models import ModelFactory\nfrom camel.types import ModelPlatformType\n\n# 配置模型\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=\"gpt-4o\"\n)\n\n# 创建代理配置\nagent_config = ChatAgentConfig()\n\n# 创建代理实例\nagent = ChatAgent(\n model=model,\n agent_config=agent_config\n)\n\n# 运行对话\nresponse = agent.step(\"你好，请介绍一下你自己\")\nprint(response.msgs[0].content)\n```\n\n资料来源：[examples/agents/create_chat_agent.py](https://github.com/camel-ai/camel/blob/main/examples/agents/create_chat_agent.py)\n\n### 多智能体协作\n\nCAMEL 支持多智能体角色扮演和协作：\n\n```python\nfrom camel.agents import RolePlayingAgent\nfrom camel.models import ModelFactory\nfrom camel.types import ModelPlatformType, RoleType\n\n# 创建助手指务\nassistant_agent = RolePlayingAgent(\n role_type=RoleType.ASSISTANT,\n model=model,\n)\n\n# 创建用户代理\nuser_agent = RolePlayingAgent(\n role_type=RoleType.USER,\n model=model,\n)\n```\n\n## 运行示例应用\n\n### 使用 Streamlit 运行应用\n\nCAMEL 提供了多个示例应用，使用 Streamlit 作为前端界面：\n\n```bash\n# 进入示例目录\ncd examples/usecases/multi_agent_research_assistant\n\n# 安装依赖\npip install -r requirements.txt\n\n# 配置环境变量\ncp .env.template .env\n# 编辑 .env 文件填入 API 密钥\n\n# 启动应用\nstreamlit run app.py\n```\n\n资料来源：[examples/usecases/multi_agent_research_assistant/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/multi_agent_research_assistant/README.md)\n\n### 使用 Docker 运行\n\n对于需要隔离环境的场景，可以使用 Docker：\n\n```bash\ncd examples/runtimes/ubuntu_docker_runtime\n\n# 构建镜像\nchmod +x manage_camel_docker.sh\n./manage_camel_docker.sh build\n\n# 验证镜像\ndocker images | grep my-camel\n```\n\n资料来源：[examples/runtimes/ubuntu_docker_runtime/README.md](https://github.com/camel-ai/camel/blob/main/examples/runtimes/ubuntu_docker_runtime/README.md)\n\n## 工作流程概览\n\n```mermaid\ngraph TD\n A[安装 CAMEL] --> B[配置环境变量]\n B --> C[选择运行方式]\n C --> D[本地 Python]\n C --> E[Streamlit 应用]\n C --> F[Docker 容器]\n D --> G[运行示例代码]\n E --> H[启动 Web 服务]\n F --> I[容器内运行]\n G --> J[开发自定义代理]\n H --> J\n I --> J\n J --> K[集成到项目]\n```\n\n## 常见应用场景\n\n| 场景 | 说明 | 示例目录 |\n|------|------|----------|\n| 多智能体研究助手 | 自动生成研究报告 | multi_agent_research_assistant |\n| 代码问题求解 | Codeforces/LeetCode | codeforces_question_solver |\n| 文档生成 | PowerPoint 演示文稿 | pptx_toolkit_usecase |\n| OCR 文档处理 | PDF/图片文字提取 | mistral_OCR |\n| MCP 集成 | 第三方服务集成 | aci_mcp, cloudfare_mcp_camel |\n\n资料来源：[examples/usecases/codeforces_question_solver/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/codeforces_question_solver/README.md)\n\n## 下一步\n\n- 深入阅读 [安装指南](./installation.md) 了解详细的安装选项\n- 查看 [设置文档](./setup.md) 了解高级配置\n- 探索 [示例项目](../examples/) 获取更多使用案例\n- 参考 [API 文档](../api/) 了解完整的接口说明\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 模块导入错误 | 确保已安装 `camel-ai==0.2.61` 或最新版本 |\n| API Key 错误 | 检查 `.env` 文件中的密钥是否正确 |\n| Docker 构建失败 | 确保 Docker 已启动并具有足够权限 |\n| Python 版本不兼容 | 使用 Python 3.10 或 3.12 |\n\n> 提示：使用 `--debug` 模式运行可以获得详细的日志输出，便于问题排查。资料来源：[examples/usecases/airbnb_mcp/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/airbnb_mcp/README.md)\n\n---\n\n\n\n## 系统架构设计\n\n### 相关页面\n\n相关主题：[项目简介](#page-overview), [智能体(Agents)](#page-agents), [模型集成(Models)](#page-models)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/types/enums.py](https://github.com/camel-ai/camel/blob/main/camel/types/enums.py)\n- [camel/schemas/base.py](https://github.com/camel-ai/camel/blob/main/camel/schemas/base.py)\n- [camel/messages/base.py](https://github.com/camel-ai/camel/blob/main/camel/messages/base.py)\n- [camel/utils/commons.py](https://github.com/camel-ai/camel/blob/main/camel/utils/commons.py)\n- [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)\n- [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)\n- [examples/usecases/multi_agent_research_assistant/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/multi_agent_research_assistant/README.md)\n- [examples/runtimes/ubuntu_docker_runtime/README.md](https://github.com/camel-ai/camel/blob/main/examples/runtimes/ubuntu_docker_runtime/README.md)\n \n\n# 系统架构设计\n\n## 概述\n\nCAMEL（Communicative Agents for Multi-Agent Learning）是一个多智能体协作框架，旨在实现自主协作的AI智能体系统。该框架的核心设计理念是通过角色扮演和任务分解，让多个AI智能体能够自主协作完成复杂任务。\n\n系统架构采用模块化设计，涵盖核心类型系统、消息处理、服务层、工具包集成以及运行时环境等多个层次。这种分层架构确保了系统的可扩展性、可维护性和灵活性。\n\n## 核心架构层次\n\nCAMEL系统的整体架构可以分为以下几个核心层次：\n\n```mermaid\ngraph TD\n A[应用层] --> B[服务层]\n B --> C[核心框架层]\n C --> D[工具包层]\n D --> E[运行时层]\n \n A1[Apps] --> A\n A2[Examples] --> A\n B1[Agent Services] --> B\n B2[MCP Servers] --> B\n C1[Types/Enums] --> C\n C2[Schemas] --> C\n C3[Messages] --> C\n C4[Utils] --> C\n D1[Browser Toolkit] --> D\n D2[其他Toolkits] --> D\n E1[Docker Runtime] --> E\n E2[Python Runtime] --> E\n```\n\n## 类型系统与枚举定义\n\n### 枚举类型架构\n\n类型系统是整个框架的基础，定义了框架内部使用的各种枚举类型和常量。这些枚举类型贯穿于整个框架的各个模块，确保了类型安全性和一致性。\n\n枚举模块定义了智能体类型、模型类型、消息角色、任务状态等核心概念。框架使用这些枚举来规范化各个模块之间的数据交互和状态管理。\n\n### 基础类型定义\n\n基础类型定义了框架中使用的核心数据结构，包括智能体配置、模型参数、工具定义等。这些类型为上层的Schema和Message系统提供了类型支撑。\n\n## Schema系统\n\n### 基础Schema架构\n\nSchema系统是CAMEL框架的核心数据模型层。它定义了智能体、任务、消息等核心实体 的数据结构规范。基础Schema类提供了通用的数据验证和序列化功能，确保数据的一致性和完整性。\n\n### Schema组件关系\n\n```mermaid\ngraph LR\n A[BaseSchema] --> B[AgentSchema]\n A --> C[TaskSchema]\n A --> D[ToolSchema]\n \n B --> E[角色定义]\n B --> F[模型配置]\n B --> G[系统提示]\n \n C --> H[任务描述]\n C --> I[任务状态]\n C --> J[任务结果]\n \n D --> K[工具名称]\n D --> L[工具参数]\n D --> M[工具描述]\n```\n\n## 消息系统\n\n### 消息类型与结构\n\n消息系统是智能体之间通信的核心机制。框架定义了多种消息类型，包括用户消息、助手消息、系统消息等。每种消息类型都有其特定的用途和处理流程。\n\n消息基类定义了消息的基本结构，包括消息ID、内容、时间戳、发送者、接收者等字段。消息系统还支持消息的嵌套和引用，使得复杂的对话结构能够被正确表示和处理。\n\n### 消息流转机制\n\n```mermaid\ngraph TD\n A[User Message] --> B[Message Handler]\n B --> C{Message Type}\n C -->|Agent Message| D[Agent Processing]\n C -->|System Message| E[System Processing]\n C -->|Tool Message| F[Tool Processing]\n \n D --> G[Response Generation]\n E --> H[System Response]\n F --> I[Tool Execution]\n \n G --> J[Message Queue]\n H --> J\n I --> J\n \n J --> K[Message History]\n```\n\n## 工具包层\n\n### 浏览器工具包架构\n\n混合浏览器工具包是CAMEL框架中功能强大的工具之一，它提供了浏览器自动化能力。该工具包采用TypeScript实现，提供了完整的浏览器会话管理功能。\n\n浏览器工具包的核心组件包括浏览器会话管理、元素定位与交互、页面快照与差异检测、配置文件加载等模块。这些组件协同工作，实现了类似Playwright的浏览器自动化功能。\n\n### 配置系统\n\n浏览器工具包使用TypeScript类型定义配置文件结构，支持以下核心配置项：\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| headless | boolean | true | 是否无头模式运行 |\n| stealth | StealthConfig | - | 反检测配置 |\n| navigationTimeout | number | 30000 | 导航超时时间（毫秒） |\n| networkIdleTimeout | number | 5000 | 网络空闲超时（毫秒） |\n| screenshotTimeout | number | 15000 | 截图超时时间（毫秒） |\n| pageStabilityTimeout | number | 1500 | 页面稳定检测超时 |\n\n反检测配置进一步细分为用户代理、视口尺寸、语言设置等参数，确保浏览器行为尽可能接近真实用户。资料来源：[camel/toolkits/hybrid_browser_toolkit/ts/src/config-loader.ts:1-50]()\n\n### 元素交互机制\n\n浏览器工具包实现了智能的元素定位和交互机制。当页面元素发生动态变化时，系统能够自动检测并定位新的元素。交互过程包括以下步骤：\n\n1. 接收交互指令和目标元素引用\n2. 获取当前页面快照\n3. 尝试在快照中定位目标元素\n4. 如果定位失败，检测页面变化\n5. 根据页面差异推断新元素位置\n6. 执行交互操作\n\n```mermaid\ngraph TD\n A[Fill Interaction] --> B[Find Element by Ref]\n B --> C{Found?}\n C -->|Yes| D[Check if Input/Textarea]\n C -->|No| E[Wait for Page Diff]\n D --> F{Fillable?}\n F -->|Yes| G[Execute Fill]\n F -->|No| H[Search by Placeholder]\n E --> I[Get New Element]\n I --> D\n G --> J[Check for Dropdowns]\n H --> D\n J --> K[Return Result]\n```\n\n浏览器会话模块负责维护页面的DOM快照，并通过快照差异检测来跟踪页面动态变化。这种机制特别适用于处理SPA（单页应用）和动态加载内容的场景。资料来源：[camel/toolkits/hybrid_browser_toolkit/ts/src/browser-session.ts:1-80]()\n\n## 服务层架构\n\n### Agent服务\n\nAgent服务是框架的核心服务层，负责管理智能体的生命周期和任务执行。服务层提供了统一的接口来创建、配置和调度智能体任务。\n\n服务层支持多种运行时环境，包括Python原生运行时和Docker容器运行时。Docker运行时特别适用于需要隔离执行环境的场景，例如需要特定依赖或系统配置的任务。\n\n### MCP服务器集成\n\n模型上下文协议（MCP）服务器集成允许CAMEL框架连接外部工具和服务。框架通过配置文件管理MCP服务器的连接，支持动态添加和移除服务器。\n\nMCP服务器配置结构如下：\n\n```json\n{\n \"mcpServers\": {\n \"server_name\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@package/mcp-server\"]\n }\n }\n}\n```\n\n支持的MCP服务器类型包括：\n\n| 服务器类型 | 用途 | 配置方式 |\n|------------|------|----------|\n| Airbnb | 房源搜索与预订 | npx命令 |\n| Cloudflare | 文档查询、雷达数据、浏览器 | SSE远程 |\n| ACI | 应用集成与自动化 | API调用 |\n| Firecrawl | 网页抓取与数据提取 | API调用 |\n\n## 应用层组件\n\n### 应用目录结构\n\nCAMEL框架的应用层包含多个展示应用和工具应用，结构清晰，便于扩展和维护。\n\n典型应用目录结构：\n\n```\napps/\n├── agents/ # 角色扮演API的Gradio演示应用\n├── data_explorer/ # 数据集浏览工具\n└── README.md\n\nexamples/\n├── usecases/ # 各场景使用案例\n│ ├── multi_agent_research_assistant/\n│ ├── codeforces_question_solver/\n│ ├── chat_with_github/\n│ ├── pptx_toolkit_usecase/\n│ ├── mistral_ocr/\n│ └── ...\n└── runtimes/ # 运行时环境示例\n └── ubuntu_docker_runtime/\n```\n\n### 多智能体研究助手\n\n多智能体研究助手是一个完整的研究报告生成应用，展示了CAMEL框架在复杂任务中的应用能力。该应用整合了多个智能体角色：\n\n- **研究者智能体**：负责搜索学术论文和最新新闻\n- **作者智能体**：负责撰写和编辑报告内容\n- **可视化智能体**：可选，负责生成配图\n\n应用流程：\n\n1. 用户输入研究主题\n2. 研究者智能体搜索相关信息\n3. 聚合信息传递给作者智能体\n4. 生成完整报告并保存\n5. 可选：生成配图并准备社交媒体内容\n\n资料来源：[examples/usecases/multi_agent_research_assistant/README.md:1-50]()\n\n## 运行时环境\n\n### Docker运行时\n\nDocker运行时环境为框架提供了隔离、可复现的执行环境。该环境特别适用于需要特定系统依赖或需要避免环境冲突的场景。\n\nDocker运行时架构包括：\n\n- **Dockerfile**：定义运行时环境配置\n- **管理脚本**：自动化构建和容器管理\n- **Python客户端**：与Docker容器内的服务通信\n\n```mermaid\ngraph TD\n A[Host Python Client] --> B[Docker Container]\n B --> C[CAMEL Runtime]\n B --> D[API Server]\n C --> E[Model Services]\n D --> F[REST API]\n \n A -->|RPC/API| F\n```\n\n### 运行时配置\n\n运行时支持多种模型平台配置，包括OpenAI兼容模型、本地模型等。配置示例：\n\n```python\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI_COMPATIBLE_MODEL,\n model_type=\"Qwen/Qwen2.5-72B-Instruct\",\n url='https://api-inference.modelscope.cn/v1/'\n)\n```\n\n资料来源：[examples/runtimes/ubuntu_docker_runtime/README.md:1-80]()\n\n## 工具包集成\n\n### 工具包类型概览\n\nCAMEL框架提供了丰富的工具包集成，涵盖多个领域的自动化能力：\n\n| 工具包 | 功能 | 依赖 |\n|--------|------|------|\n| HybridBrowserToolkit | 浏览器自动化 | Playwright |\n| PPTXToolkit | PowerPoint生成 | python-pptx |\n| 图像生成工具包 | AI图像生成 | DALL·E/Pexels API |\n| OCR工具包 | 文档识别 | Mistral OCR |\n| 搜索工具包 | 网络信息检索 | Firecrawl |\n\n### 工具包使用模式\n\n工具包通过统一的接口集成到智能体系统中。每个工具包都定义了清晰的能力边界和参数规范，智能体可以根据任务需求选择合适的工具。\n\n工具调用流程：\n\n1. 任务分析：智能体分析任务需求\n2. 工具选择：从可用工具包中选择合适工具\n3. 参数准备：根据工具规范准备调用参数\n4. 执行调用：通过统一接口执行工具\n5. 结果处理：解析返回结果并继续任务\n\n## 扩展机制\n\n### 定制化配置\n\nCAMEL框架支持通过配置文件定制各种行为：\n\n- **智能体配置**：修改`agent_config.py`中的模型参数和系统消息\n- **工具配置**：通过`mcp_servers_config.json`管理外部工具连接\n- **环境配置**：通过`.env`文件管理API密钥和运行时参数\n\n### 自定义工具包\n\n开发者可以通过继承基础工具包类来创建自定义工具包：\n\n```python\nclass CustomToolkit(BaseToolkit):\n def __init__(self, config: CustomConfig):\n super().__init__()\n self.config = config\n \n def get_tools(self) -> List[FunctionCallingRecord]:\n return [\n FunctionCallingRecord(func=self.custom_function)\n ]\n```\n\n## 总结\n\nCAMEL框架的架构设计体现了多智能体系统的核心原则：\n\n- **模块化设计**：各层职责清晰，便于维护和扩展\n- **类型安全**：通过TypeScript和Python类型系统确保代码质量\n- **灵活集成**：通过MCP和工具包机制支持多种外部服务\n- **运行时隔离**：Docker支持确保环境一致性\n- **配置驱动**：通过配置文件实现行为定制\n\n这种架构使得开发者能够快速构建复杂的多智能体应用，同时保持代码的可维护性和可扩展性。\n\n---\n\n\n\n## 智能体(Agents)\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-architecture), [模型集成(Models)](#page-models), [工具集(Toolkits)](#page-toolkits), [记忆系统(Memory)](#page-memory)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/agents/base.py](https://github.com/camel-ai/camel/blob/main/camel/agents/base.py)\n- [camel/agents/chat_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/chat_agent.py)\n- [camel/agents/critic_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/critic_agent.py)\n- [camel/agents/embodied_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/embodied_agent.py)\n- [camel/agents/repo_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/repo_agent.py)\n- [camel/agents/task_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/task_agent.py)\n- [camel/agents/_types.py](https://github.com/camel-ai/camel/blob/main/camel/agents/_types.py)\n \n\n# 智能体(Agents)\n\n## 概述\n\nCAMEL-AI 框架中的智能体(Agents)是实现多智能体协作的核心组件。智能体是具有特定角色、能力和工具的自主实体，能够执行对话、推理、搜索等多样化任务。CAMEL 采用角色扮演(Role-Playing)架构，让不同类型的智能体相互协作完成复杂任务。\n\n智能体系统支持多种部署方式，包括通过 MCP (Model Context Protocol) 服务器提供服务，也可直接集成到 Python 应用中。\n\n## 智能体架构\n\n### 核心组件\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ 智能体系统架构 │\n├─────────────────────────────────────────────────────────┤\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │\n│ │ ChatAgent │ │ CriticAgent │ │ TaskAgent │ │\n│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │\n│ │ │ │ │\n│ ┌──────┴────────────────┴────────────────┴──────┐ │\n│ │ BaseAgent (基类) │ │\n│ └──────────────────────┬────────────────────────┘ │\n│ │ │\n│ ┌──────────────────────┴────────────────────────┐ │\n│ │ AgentMCP Server │ │\n│ └───────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n```\n\n### 智能体类型\n\nCAMEL 框架提供以下核心智能体类型：\n\n| 智能体类型 | 文件位置 | 主要功能 |\n|-----------|---------|---------|\n| **ChatAgent** | `camel/agents/chat_agent.py` | 通用对话智能体，处理对话交互 |\n| **CriticAgent** | `camel/agents/critic_agent.py` | 批评评价智能体，评估和反馈 |\n| **TaskAgent** | `camel/agents/task_agent.py` | 任务规划智能体，分解和执行任务 |\n| **EmbodiedAgent** | `camel/agents/embodied_agent.py` | 具身智能体，与环境交互 |\n| **RepoAgent** | `camel/agents/repo_agent.py` | 仓库分析智能体，处理代码仓库 |\n\n## BaseAgent 基类\n\n所有智能体都继承自 `BaseAgent`，提供核心功能和通用接口。 资料来源：[camel/agents/base.py]()\n\n### 核心特性\n\n- 统一的智能体生命周期管理\n- 消息处理和状态维护\n- 工具调用和结果处理\n- 对话历史记录管理\n\n### 智能体配置\n\n智能体通过配置文件进行定制，包括：\n\n```python\n# 来自 agent_config.py 的配置选项\n@dataclass\nclass AgentConfig:\n name: str # 智能体名称\n model: Model # 使用的模型\n tools: List[Tool] # 可用工具列表\n system_message: str # 系统提示词\n temperature: float = 0.7 # 生成温度\n max_tokens: int = 2048 # 最大 token 数\n```\n\n## ChatAgent 对话智能体\n\n`ChatAgent` 是 CAMEL 框架中最常用的智能体类型，主要负责处理对话交互。 资料来源：[camel/agents/chat_agent.py]()\n\n### 功能特点\n\n- 支持多轮对话\n- 角色扮演能力\n- 工具集成\n- 消息格式化处理\n\n### 使用示例\n\n```python\nfrom camel.agents import ChatAgent\nfrom camel.models import ModelFactory\nfrom camel.types import ModelPlatformType\n\n# 创建模型\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=\"gpt-4\"\n)\n\n# 创建对话智能体\nagent = ChatAgent(\n system_message=\"你是一个乐于助人的AI助手。\",\n model=model\n)\n\n# 执行对话步骤\nresponse = await agent.step(\"你好，请介绍一下你自己\")\n```\n\n## CriticAgent 批评智能体\n\n`CriticAgent` 专门用于评估和反馈，能够分析其他智能体或用户输入的内容并提供改进建议。 资料来源：[camel/agents/critic_agent.py]()\n\n### 应用场景\n\n- 代码审查和反馈\n- 内容质量评估\n- 对话策略优化\n- 任务执行结果验证\n\n## TaskAgent 任务智能体\n\n`TaskAgent` 专注于任务分解和执行规划，能够将复杂任务拆分为可执行的子任务。 资料来源：[camel/agents/task_agent.py]()\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[接收任务] --> B{任务复杂度判断}\n B -->|简单任务| C[直接执行]\n B -->|复杂任务| D[任务分解]\n D --> E[子任务1]\n D --> F[子任务2]\n D --> G[子任务N]\n E --> H[结果汇总]\n F --> H\n G --> H\n H --> I[最终输出]\n```\n\n## EmbodiedAgent 具身智能体\n\n`EmbodiedAgent` 具备与物理或虚拟环境交互的能力，适用于需要实际操作的任务场景。 资料来源：[camel/agents/embodied_agent.py]()\n\n### 工具支持\n\n| 工具类型 | 功能描述 |\n|---------|---------|\n| 浏览器工具 | 网页导航、内容抓取、表单填写 |\n| 文件系统工具 | 读写文件、目录操作 |\n| 命令行工具 | 执行系统命令 |\n| API 工具 | 调用外部服务接口 |\n\n## RepoAgent 仓库智能体\n\n`RepoAgent` 专门用于代码仓库分析和处理，能够理解代码结构、执行代码搜索和代码生成任务。 资料来源：[camel/agents/repo_agent.py]()\n\n### 典型应用\n\n- 代码库理解\n- 文档生成\n- 代码重构建议\n- 仓库结构分析\n\n## MCP 服务器集成\n\nCAMEL 提供了 MCP (Model Context Protocol) 服务器实现，允许通过标准协议与智能体交互。 资料来源：[services/README.md]()\n\n### 可用工具\n\n| 工具名称 | 功能描述 | 参数 |\n|---------|---------|------|\n| `step` | 执行单次对话步骤 | `name`: 智能体名称, `message`: 消息内容 |\n| `reset` | 重置所有智能体状态 | 无 |\n| `set_output_language` | 设置输出语言 | `language`: 语言代码 |\n| `get_agents_info` | 获取所有智能体信息 | 无 |\n| `get_chat_history` | 获取对话历史 | `name`: 智能体名称 |\n| `get_agent_info` | 获取特定智能体详情 | `name`: 智能体名称 |\n| `get_available_tools` | 获取智能体可用工具 | `name`: 智能体名称 |\n\n### 服务器启动\n\n```bash\n# 启动 MCP 服务器\npython services/agent_mcp_server.py\n```\n\n### 客户端配置\n\n连接 MCP 客户端(如 Claude Desktop 或 Cursor)需要提供 JSON 配置：\n\n```json\n{\n \"camel-agents\": {\n \"command\": \"/path/to/your/python\",\n \"args\": [\n \"/path/to/camel/services/agent_mcp_server.py\"\n ],\n \"env\": {\n \"OPENAI_API_KEY\": \"...\",\n \"OPENROUTER_API_KEY\": \"...\",\n \"BRAVE_API_KEY\": \"...\"\n }\n }\n}\n```\n\n## 预配置智能体类型\n\nCAMEL 框架提供三种预配置的智能体类型：\n\n| 智能体类型 | 配置文件 | 能力描述 |\n|-----------|---------|---------|\n| **General Agent** | `agent_config.py` | 通用问答助手，处理各类任务 |\n| **Search Agent** | `agent_config.py` | 网络搜索能力集成 |\n| **Reasoning Agent** | `agent_config.py` | 专门从事推理任务 |\n\n资料来源：[services/README.md]()\n\n## Gradio 应用集成\n\nCAMEL 提供基于 Gradio 的智能体展示应用。 资料来源：[apps/agents/README.md]()\n\n### 快速启动\n\n```bash\npython agents.py --api-key=YOUR-OPENAI-API-KEY\n```\n\n### 部署到 HuggingFace Spaces\n\n1. 在 CAMEL 仓库中完成开发和调试\n2. 为目标提交打标签：`hf_spaces_{X+1}`（X 值需从 HF 仓库同步脚本查询）\n3. 执行 `git push --tags`\n4. 克隆 HF 仓库到本地\n5. 更新标签并运行同步脚本\n6. 提交并推送到 HF\n7. HF 将自动部署应用\n\n## 智能体通信协议\n\n智能体之间通过消息传递进行通信，支持以下消息类型：\n\n| 消息类型 | 用途 | 数据结构 |\n|---------|------|---------|\n| `UserMessage` | 用户输入 | `{role, content}` |\n| `AssistantMessage` | 智能体回复 | `{role, content, tool_calls}` |\n| `SystemMessage` | 系统指令 | `{role, content}` |\n| `ToolMessage` | 工具结果 | `{role, content, tool_call_id}` |\n\n## 类型定义\n\n智能体的核心类型定义位于 `camel/agents/_types.py`。 资料来源：[camel/agents/_types.py]()\n\n### 主要枚举类型\n\n- **AgentType**: 智能体类型枚举\n- **AgentStatus**: 智能体状态枚举\n- **MessageType**: 消息类型枚举\n\n## 配置管理\n\n### 环境变量\n\n| 变量名 | 用途 | 必需 |\n|-------|------|------|\n| `OPENAI_API_KEY` | OpenAI API 密钥 | 是 |\n| `OPENROUTER_API_KEY` | OpenRouter API 密钥 | 否 |\n| `BRAVE_API_KEY` | Brave Search API 密钥 | 否 |\n\n### 自定义配置\n\n通过修改 `agent_config.py` 可以自定义：\n\n- 模型选择和参数\n- 添加新智能体类型\n- 配置工具集\n- 调整系统提示词\n\n## 最佳实践\n\n### 1. 智能体选择\n\n根据任务复杂度选择合适的智能体类型：\n\n- **简单对话**: 使用 `ChatAgent`\n- **需要评估**: 结合 `CriticAgent`\n- **复杂任务**: 使用 `TaskAgent` 进行任务分解\n- **代码仓库操作**: 使用 `RepoAgent`\n\n### 2. 工具配置\n\n```python\n# 推荐的工具配置模式\ntools = [\n SearchTool(api_key=brave_api_key),\n CalculatorTool(),\n # 根据需要添加更多工具\n]\n```\n\n### 3. 错误处理\n\n智能体执行时应捕获并处理以下异常：\n\n- API 调用超时\n- 模型响应格式错误\n- 工具执行失败\n- 上下文长度超限\n\n## 示例应用\n\nCAMEL 仓库提供了多个使用智能体的示例应用：\n\n| 示例名称 | 路径 | 说明 |\n|---------|------|------|\n| 多智能体研究助手 | `examples/usecases/multi_agent_research_assistant/` | 学术研究和报告生成 |\n| Codeforces 问题解决器 | `examples/usecases/codeforces_question_solver/` | 竞赛编程辅助 |\n| GitHub 聊天 | `examples/usecases/chat_with_github/` | 仓库交互 |\n| YouTube 聊天 | `examples/usecases/chat_with_youtube/` | 视频内容分析 |\n\n## 扩展阅读\n\n- [CAMEL 框架核心概念](../core_concepts/)\n- [工具系统(Toolkits)](../toolkits/)\n- [角色扮演(Role-Playing)](../role_playing/)\n- [MCP 协议文档](https://docs.anthropic.com/en/docs/agents-and-tools/mcp)\n\n---\n\n\n\n## 模型集成(Models)\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-architecture), [智能体(Agents)](#page-agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/models/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/models/__init__.py)\n- [camel/models/base_model.py](https://github.com/camel-ai/camel/blob/main/camel/models/base_model.py)\n- [camel/models/model_factory.py](https://github.com/camel-ai/camel/blob/main/camel/models/model_factory.py)\n- [camel/models/model_manager.py](https://github.com/camel-ai/camel/blob/main/camel/models/model_manager.py)\n- [camel/models/openai_model.py](https://github.com/camel-ai/camel/blob/main/camel/models/openai_model.py)\n- [camel/models/anthropic_model.py](https://github.com/camel-ai/camel/blob/main/camel/models/anthropic_model.py)\n- [camel/configs/openai_config.py](https://github.com/camel-ai/camel/blob/main/camel/configs/openai_config.py)\n- [camel/configs/anthropic_config.py](https://github.com/camel-ai/camel/blob/main/camel/configs/anthropic_config.py)\n \n\n# 模型集成(Models)\n\n## 概述\n\nCAMEL-AI 的模型集成模块是整个框架的核心组件之一，负责统一管理和调用各类大语言模型（LLM）。该模块通过抽象层设计，将不同模型提供商的 API 封装为统一接口，使上层应用能够无差别地使用各种模型能力。\n\n模型模块的主要职责包括：\n\n- 提供统一的模型调用接口\n- 支持多种模型平台（OpenAI、Anthropic、兼容 OpenAI 接口的模型等）\n- 管理模型配置和参数\n- 处理模型响应格式化\n- 支持流式输出和非流式输出\n\n资料来源：[camel/models/__init__.py]()\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[用户代码] --> B[ModelFactory]\n B --> C{模型平台类型}\n C -->|OpenAI| D[OpenAIModel]\n C -->|Anthropic| E[AnthropicModel]\n C -->|OpenAI兼容| F[OpenAICompatibleModel]\n D --> G[BaseModel]\n E --> G\n F --> G\n G --> H[模型API调用层]\n H --> I[OpenAI API]\n H --> J[Anthropic API]\n H --> K[第三方兼容API]\n```\n\n### 核心组件关系\n\n```mermaid\nclassDiagram\n class BaseModel {\n <>\n +run() Message\n +run_until_success() Message\n -_roll() None\n }\n \n class OpenAIModel {\n +run() Message\n -_extract_text_from_response()\n }\n \n class AnthropicModel {\n +run() Message\n -_extract_text_from_response()\n }\n \n class ModelFactory {\n +create() BaseModel\n }\n \n class ModelManager {\n +get_model() BaseModel\n +list_models() List~str~\n }\n \n BaseModel <|-- OpenAIModel\n BaseModel <|-- AnthropicModel\n ModelFactory --> BaseModel : creates\n ModelManager --> ModelFactory : uses\n```\n\n资料来源：[camel/models/base_model.py](), [camel/models/model_factory.py](), [camel/models/model_manager.py]()\n\n## 核心组件详解\n\n### BaseModel（基础模型类）\n\n`BaseModel` 是所有模型实现的抽象基类，定义了模型交互的标准接口。\n\n#### 核心方法\n\n| 方法名 | 返回类型 | 说明 |\n|--------|----------|------|\n| `run(messages)` | `Message` | 执行单次模型调用 |\n| `run_until_success(messages)` | `Message` | 循环调用直至成功 |\n| `_roll()` | `None` | 重置模型状态 |\n\n#### 主要属性\n\n| 属性名 | 类型 | 说明 |\n|--------|------|------|\n| `model_type` | `ModelType` | 模型类型枚举 |\n| `model_config_dict` | `Dict[str, Any]` | 模型配置字典 |\n| `url` | `str` | API 端点 URL |\n\n资料来源：[camel/models/base_model.py]()\n\n### ModelFactory（模型工厂）\n\n`ModelFactory` 负责根据配置动态创建模型实例，是接入新模型的统一入口点。\n\n#### 工厂方法签名\n\n```python\n@classmethod\ndef create(\n cls,\n model_platform: \"ModelPlatformType\",\n model_type: \"ModelType\",\n url: Optional[str] = None,\n api_key: Optional[str] = None,\n config_dict: Optional[Dict[str, Any]] = None,\n) -> \"BaseModel\"\n```\n\n#### 参数说明\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `model_platform` | `ModelPlatformType` | 是 | 模型平台类型 |\n| `model_type` | `ModelType` | 是 | 具体模型类型 |\n| `url` | `str` | 否 | API 端点（兼容模式必填） |\n| `api_key` | `str` | 否 | API 密钥 |\n| `config_dict` | `Dict[str, Any]` | 否 | 自定义配置 |\n\n资料来源：[camel/models/model_factory.py]()\n\n### ModelManager（模型管理器）\n\n`ModelManager` 提供模型实例的集中管理和缓存功能。\n\n#### 核心功能\n\n- 管理多个模型实例的生命周期\n- 支持按名称获取已注册的模型\n- 提供模型列表查询接口\n\n资料来源：[camel/models/model_manager.py]()\n\n## 支持的模型平台\n\n### OpenAI 系列\n\nCAMEL 支持完整的 OpenAI 模型体系，包括 GPT-4、GPT-4 Turbo、GPT-3.5 Turbo 等。\n\n#### OpenAIModel 实现\n\n```python\nclass OpenAIModel(BaseModel):\n def __init__(\n self,\n model_type: ModelType,\n model_config_dict: dict,\n api_key: str,\n url: Optional[str] = None,\n ...\n )\n```\n\n#### 支持的模型类型\n\n| 模型类型枚举 | 对应模型 | 说明 |\n|--------------|----------|------|\n| `GPT_4` | gpt-4 | GPT-4 标准版 |\n| `GPT_4_TURBO` | gpt-4-turbo | GPT-4 Turbo |\n| `GPT_4O` | gpt-4o | GPT-4 Omni |\n| `GPT_4O_MINI` | gpt-4o-mini | GPT-4o 迷你版 |\n| `GPT_35_TURBO` | gpt-3.5-turbo | GPT-3.5 Turbo |\n\n资料来源：[camel/models/openai_model.py](), [camel/models/__init__.py]()\n\n### Anthropic 系列\n\nCAMEL 通过 `AnthropicModel` 类支持 Claude 系列模型。\n\n#### AnthropicModel 实现\n\n```python\nclass AnthropicModel(BaseModel):\n def __init__(\n self,\n model_type: ModelType,\n model_config_dict: dict,\n api_key: str,\n ...\n )\n```\n\n#### 支持的 Claude 模型\n\n| 模型类型枚举 | 对应模型 | 说明 |\n|--------------|----------|------|\n| `CLAUDE_3_5_SONNET` | claude-sonnet-4-20250514 | Claude 3.5 Sonnet |\n| `CLAUDE_3_OPUS` | claude-3-opus-20240229 | Claude 3 Opus |\n| `CLAUDE_3_HAIKU` | claude-3-haiku-20240307 | Claude 3 Haiku |\n\n资料来源：[camel/models/anthropic_model.py](), [camel/models/__init__.py]()\n\n### OpenAI 兼容接口\n\nCAMEL 支持任何实现 OpenAI API 兼容接口的模型服务，包括：\n\n- 本地部署模型（如 vLLM、LM Studio）\n- 开源模型服务（如 TogetherAI、Anyscale）\n- 云厂商兼容端点（如阿里云、百度智能云）\n\n通过设置 `ModelPlatformType.OPENAI_COMPATIBLE_MODEL` 并指定 `url` 参数即可接入。\n\n资料来源：[camel/models/model_factory.py]()\n\n## 配置系统\n\n### OpenAI 配置\n\n`OpenAIConfig` 类提供 OpenAI 模型的详细配置选项。\n\n#### 配置参数表\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `temperature` | `float` | `1.0` | 采样温度（0-2） |\n| `max_tokens` | `int` | `4096` | 最大生成token数 |\n| `top_p` | `float` | `1.0` | Top-p 采样 |\n| `n` | `int` | `1` | 生成数量 |\n| `stop` | `List[str]` | `None` | 停止词列表 |\n| `seed` | `int` | `None` | 随机种子 |\n| `stream` | `bool` | `False` | 流式输出开关 |\n| `response_format` | `dict` | `None` | 响应格式约束 |\n| `tools` | `List[dict]` | `None` | 工具函数定义 |\n| `tool_choice` | `str` | `None` | 工具选择策略 |\n\n资料来源：[camel/configs/openai_config.py]()\n\n### Anthropic 配置\n\n`AnthropicConfig` 类提供 Claude 模型的详细配置选项。\n\n#### 配置参数表\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `temperature` | `float` | `1.0` | 采样温度 |\n| `max_tokens` | `int` | `4096` | 最大生成token数 |\n| `top_p` | `float` | `1.0` | Top-p 采样 |\n| `stop_sequences` | `List[str]` | `None` | 停止序列 |\n| `stream` | `bool` | `False` | 流式输出开关 |\n| `tools` | `List[dict]` | `None` | 工具函数定义 |\n\n资料来源：[camel/configs/anthropic_config.py]()\n\n## 使用指南\n\n### 基础使用流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant Factory as ModelFactory\n participant Model as OpenAIModel\n participant API as OpenAI API\n \n User->>Factory: create(platform, model_type, api_key)\n Factory->>Model: instantiate\n User->>Model: run(messages)\n Model->>API: POST /chat/completions\n API-->>Model: response\n Model-->>User: Message object\n```\n\n### 基本调用示例\n\n#### 1. 创建 OpenAI 模型实例\n\n```python\nfrom camel.models import ModelFactory, ModelPlatformType, ModelType\n\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=ModelType.GPT_4O,\n api_key=\"your-api-key\"\n)\n```\n\n#### 2. 创建 Anthropic 模型实例\n\n```python\nfrom camel.models import ModelFactory, ModelPlatformType, ModelType\n\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.ANTHROPIC,\n model_type=ModelType.CLAUDE_3_5_SONNET,\n api_key=\"your-api-key\"\n)\n```\n\n#### 3. 使用兼容接口模型\n\n```python\nfrom camel.models import ModelFactory, ModelPlatformType, ModelType\n\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI_COMPATIBLE_MODEL,\n model_type=ModelType.GPT_4O,\n url=\"https://api.example.com/v1\",\n api_key=\"your-api-key\"\n)\n```\n\n#### 4. 自定义模型配置\n\n```python\nfrom camel.models import ModelFactory, ModelPlatformType, ModelType\nfrom camel.configs import OpenAIConfig\n\nconfig = OpenAIConfig(\n temperature=0.7,\n max_tokens=2048,\n top_p=0.9\n)\n\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=ModelType.GPT_4O,\n api_key=\"your-api-key\",\n config_dict=config.as_dict()\n)\n```\n\n#### 5. 执行模型调用\n\n```python\nfrom camel.messages import UserMessage\n\nresponse = model.run([\n UserMessage(content=\"Hello, how are you?\")\n])\n\nprint(response.content)\n```\n\n资料来源：[camel/models/model_factory.py](), [camel/models/openai_model.py]()\n\n### 高级用法\n\n#### 流式输出\n\n```python\nconfig = OpenAIConfig(stream=True)\n\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=ModelType.GPT_4O,\n api_key=\"your-api-key\",\n config_dict=config.as_dict()\n)\n\nresponse = model.run(messages)\n# 处理流式响应\n```\n\n#### 函数调用（Tools）\n\n```python\ntools = [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_weather\",\n \"description\": \"获取天气信息\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\"type\": \"string\"}\n }\n }\n }\n }\n]\n\nconfig = OpenAIConfig(tools=tools)\n\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=ModelType.GPT_4O,\n api_key=\"your-api-key\",\n config_dict=config.as_dict()\n)\n```\n\n资料来源：[camel/configs/openai_config.py]()\n\n## 模型类型枚举\n\nCAMEL 使用强类型枚举 `ModelType` 管理支持的模型列表。\n\n### 完整枚举值\n\n```python\nclass ModelType(Enum):\n # OpenAI Models\n GPT_4 = \"gpt-4\"\n GPT_4_TURBO = \"gpt-4-turbo\"\n GPT_4O = \"gpt-4o\"\n GPT_4O_MINI = \"gpt-4o-mini\"\n GPT_35_TURBO = \"gpt-3.5-turbo\"\n GPT_35_TURBO_16K = \"gpt-3.5-turbo-16k\"\n \n # Anthropic Models\n CLAUDE_3_5_SONNET = \"claude-sonnet-4-20250514\"\n CLAUDE_3_OPUS = \"claude-3-opus-20240229\"\n CLAUDE_3_SONNET = \"claude-3-sonnet-20240229\"\n CLAUDE_3_HAIKU = \"claude-3-haiku-20240307\"\n \n # ... 其他模型\n```\n\n资料来源：[camel/models/__init__.py]()\n\n## 错误处理\n\n### 常见错误及解决方案\n\n| 错误类型 | 可能原因 | 解决方案 |\n|----------|----------|----------|\n| `AuthenticationError` | API 密钥无效或缺失 | 检查并正确设置 `api_key` |\n| `RateLimitError` | 请求频率超限 | 降低调用频率或升级配额 |\n| `BadRequestError` | 参数配置错误 | 检查 `config_dict` 参数 |\n| `APIConnectionError` | 网络连接问题 | 检查网络和代理设置 |\n\n资料来源：[camel/models/base_model.py](), [camel/models/openai_model.py]()\n\n## 扩展指南\n\n### 添加新模型支持\n\n如需添加新的模型提供商支持，需要：\n\n1. 在 `camel/models/` 目录下创建新的模型实现类（如 `xxx_model.py`）\n2. 继承 `BaseModel` 抽象类\n3. 实现 `run()` 和 `_extract_text_from_response()` 方法\n4. 在 `ModelFactory.create()` 方法中添加创建逻辑\n5. 在 `ModelType` 枚举中添加新的模型类型\n\n```python\n# 示例：新增模型支持\nclass XxxModel(BaseModel):\n def __init__(self, model_type, model_config_dict, api_key, **kwargs):\n super().__init__(model_type, model_config_dict, api_key)\n # 初始化特定逻辑\n \n def _extract_text_from_response(self, response) -> str:\n # 解析响应\n return response.choices[0].message.content\n```\n\n资料来源：[camel/models/base_model.py](), [camel/models/model_factory.py]()\n\n## 相关资源\n\n- 模型模块源码：[camel/models/](https://github.com/camel-ai/camel/tree/main/camel/models)\n- 配置模块源码：[camel/configs/](https://github.com/camel-ai/camel/tree/main/camel/configs)\n- 官方文档：[CAMEL Documentation](https://docs.camel-ai.org/)\n\n---\n\n\n\n## 工具集(Toolkits)\n\n### 相关页面\n\n相关主题：[智能体(Agents)](#page-agents), [MCP协议集成](#page-mcp), [智能体劳动力(Workforce)](#page-workforce)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/toolkits/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/__init__.py)\n- [camel/toolkits/base.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/base.py)\n- [camel/toolkits/function_tool.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/function_tool.py)\n- [camel/toolkits/search_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/search_toolkit.py)\n- [camel/toolkits/browser_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/browser_toolkit.py)\n- [camel/toolkits/file_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/file_toolkit.py)\n- [camel/toolkits/github_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/github_toolkit.py)\n- [camel/toolkits/slack_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/slack_toolkit.py)\n- [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)\n \n\n# 工具集(Toolkits)\n\n## 概述\n\nCAMEL-AI 的工具集（Toolkits）是框架中用于扩展代理（Agent）能力的关键组件库。工具集提供了一系列预构建的功能模块，使代理能够执行搜索、文件操作、浏览器自动化、GitHub集成、Slack通信等多种任务。通过工具集，开发者可以快速为AI代理配备特定领域的工具能力，无需从零开始实现复杂的功能逻辑。\n\n工具集的设计遵循模块化原则，每个工具集都是独立的功能单元，可以单独使用或组合使用。这种设计使得系统具有高度的灵活性和可扩展性，开发者可以根据实际需求选择性地集成所需工具。\n\n## 架构设计\n\n### 核心架构图\n\n```mermaid\ngraph TD\n A[BaseToolkit] --> B[SearchToolkit]\n A --> C[BrowserToolkit]\n A --> D[FileToolkit]\n A --> E[GitHubToolkit]\n A --> F[SlackToolkit]\n A --> G[FunctionTool]\n \n H[FunctionCall] --> G\n I[ToolOutput] --> G\n \n J[Agent] --> K[ToolkitRegistry]\n K --> A\n```\n\n### 基础类层次结构\n\nCAMEL-AI 的工具集系统建立在一个统一的基础类体系之上。所有工具集都继承自 `BaseToolkit` 基类，该类定义了工具集的标准接口和行为规范。\n\n`BaseToolkit` 是所有工具集的抽象基类，它提供了工具集的核心框架。每个具体的工具集都需要实现其定义的接口方法。基类封装了通用的功能逻辑，如工具注册、参数验证和结果处理等通用流程，使得具体工具集的实现更加简洁和专注于业务逻辑。\n\n`FunctionTool` 是另一个重要的基础组件，它用于将普通函数转换为AI代理可调用的工具。`FunctionTool` 包装了目标函数，添加了参数解析、类型转换和错误处理等功能，使得开发者可以将任意的Python函数暴露给AI代理使用。\n\n## 工具集类型详解\n\n### 1. 搜索工具集（SearchToolkit）\n\n搜索工具集为代理提供了网络搜索能力，使其能够检索最新的信息和数据。\n\n| 方法名 | 功能描述 | 返回类型 |\n|--------|----------|----------|\n| search | 执行通用网络搜索 | List[SearchResult] |\n| news_search | 搜索新闻内容 | List[NewsResult] |\n| academic_search | 搜索学术论文 | List[AcademicResult] |\n\nSearchToolkit 支持多种搜索模式，包括网页搜索、新闻搜索和学术论文搜索。开发者可以根据不同的使用场景选择合适的搜索模式。\n\n### 2. 浏览器工具集（BrowserToolkit）\n\n浏览器工具集提供了浏览器自动化能力，支持网页抓取、元素交互和页面导航等功能。\n\n```mermaid\ngraph LR\n A[BrowserSession] --> B[PageNavigation]\n B --> C[ElementInteraction]\n C --> D[ContentExtraction]\n D --> E[SnapshotCapture]\n```\n\nBrowserToolkit 的核心是 `BrowserSession` 类，它管理浏览器的生命周期和会话状态。该类提供了丰富的页面操作方法，包括导航到指定URL、点击页面元素、填写表单内容、提取页面文本和截图等。\n\n`browser-session.ts` 文件中实现了浏览器会话的核心逻辑，包括元素定位、表单填写和快照比较等功能。当代理需要与网页交互时，会话管理器会协调各个组件完成操作任务。\n\n### 3. 文件工具集（FileToolkit）\n\n文件工具集提供了文件系统操作能力，支持文件读写、目录管理和路径操作等功能。\n\n| 操作类型 | 支持功能 |\n|----------|----------|\n| 读取 | 文本文件、JSON、CSV、二进制文件 |\n| 写入 | 创建新文件、覆盖文件、追加内容 |\n| 目录 | 创建目录、列出内容、删除目录 |\n| 元数据 | 获取文件大小、修改时间、权限信息 |\n\nFileToolkit 封装了常见的文件系统操作，为AI代理提供了安全可靠的文件访问能力。所有文件操作都经过严格的路径验证，防止目录遍历攻击。\n\n### 4. GitHub工具集（GitHubToolkit）\n\nGitHub工具集集成了GitHub API，使代理能够执行仓库管理、Issue操作、PR管理和代码搜索等任务。\n\n| 功能模块 | 描述 |\n|----------|------|\n| 仓库操作 | 创建、克隆、获取仓库信息 |\n| Issue管理 | 创建Issue、评论、关闭、标签管理 |\n| PR操作 | 创建Pull Request、审查、合并 |\n| 代码搜索 | 搜索代码、仓库和用户 |\n\nGitHubToolkit 通过GitHub REST API与GitHub平台进行交互，支持完整的仓库生命周期管理功能。\n\n### 5. Slack工具集（SlackToolkit）\n\nSlack工具集提供了与Slack工作区交互的能力，支持消息发送、频道管理和用户查询等功能。\n\n| 功能 | 说明 |\n|------|------|\n| 消息发送 | 向指定频道或用户发送消息 |\n| 频道管理 | 创建频道、获取频道列表、管理成员 |\n| 用户查询 | 获取用户信息、在线状态 |\n| 文件上传 | 上传文件到Slack频道 |\n\nSlackToolkit 使用Slack Web API实现所有功能，支持企业级Slack工作区的集成需求。\n\n## 工具调用机制\n\n### 函数调用流程\n\n```mermaid\nsequenceDiagram\n participant Agent as Agent\n participant Toolkit as FunctionTool\n participant Function as Target Function\n \n Agent->>Toolkit: 调用工具方法\n Toolkit->>Toolkit: 参数解析与验证\n Toolkit->>Function: 转发调用请求\n Function-->>Toolkit: 返回执行结果\n Toolkit->>Toolkit: 结果格式化处理\n Toolkit-->>Agent: 返回ToolOutput\n```\n\n### 参数处理\n\nFunctionTool 提供了强大的参数处理能力，支持多种数据类型和验证规则。工具的参数定义采用声明式方式，开发者可以通过装饰器或配置指定参数的类型约束、默认值和验证规则。\n\n| 参数特性 | 支持情况 |\n|----------|----------|\n| 类型注解 | int, str, float, bool, list, dict |\n| 默认值 | 支持可选参数 |\n| 必填检查 | 支持必填参数验证 |\n| 枚举约束 | 支持枚举类型限制 |\n\n## 混合浏览器工具集（HybridBrowserToolkit）\n\nHybridBrowserToolkit 是CAMEL-AI中功能最强大的浏览器自动化工具，它结合了传统浏览器控制和现代化前端交互能力。\n\n### 核心特性\n\n- **多浏览器支持**：支持Chrome、Firefox等主流浏览器\n- **智能元素定位**：支持通过ID、类名、XPath、CSS选择器定位元素\n- **表单自动化**：支持填写表单、上传文件、选择下拉菜单\n- **截图功能**：支持全页面截图和元素截图\n- **JavaScript执行**：支持在页面上下文中执行JavaScript代码\n\n### 会话管理\n\nBrowserSession 类负责管理浏览器会话的生命周期。每个会话包含以下状态：\n\n```mermaid\nstateDiagram-v2\n [*] --> Initialized: 创建会话\n Initialized --> Ready: 打开页面\n Ready --> Active: 执行操作\n Active --> Ready: 操作完成\n Active --> Error: 发生错误\n Ready --> [*]: 关闭会话\n Error --> Ready: 重试\n```\n\n### 元素交互\n\n当代理需要与页面元素交互时，系统会执行以下流程：\n\n1. 接收交互指令和目标元素引用\n2. 在当前页面快照中查找匹配元素\n3. 验证元素可见性和可操作性\n4. 执行交互操作（点击、输入、选择等）\n5. 等待操作完成并获取结果快照\n6. 比较操作前后的页面变化\n7. 返回操作结果和差异信息\n\n## 使用示例\n\n### 基础工具集使用\n\n```python\nfrom camel.toolkits import SearchToolkit, FileToolkit\n\n# 创建搜索工具集实例\nsearch_toolkit = SearchToolkit()\n\n# 执行搜索\nresults = search_toolkit.search(query=\"人工智能最新进展\")\n\n# 创建文件工具集实例\nfile_toolkit = FileToolkit()\n\n# 读取文件\ncontent = file_toolkit.read_file(path=\"example.txt\")\n```\n\n### 自定义函数工具\n\n```python\nfrom camel.toolkits import FunctionTool\n\n# 将普通函数转换为工具\n@FunctionTool\ndef calculate(expression: str) -> float:\n \"\"\"计算数学表达式\"\"\"\n return eval(expression)\n\n# 注册到代理\nagent = ChatAgent(\n tools=[calculate]\n)\n```\n\n### 浏览器自动化\n\n```python\nfrom camel.toolkits import BrowserToolkit\n\nbrowser = BrowserToolkit()\n\n# 启动会话\nsession = await browser.create_session()\n\n# 导航到网页\nawait session.navigate(\"https://example.com\")\n\n# 填写表单\nawait session.fill(\n ref=\"search-input\",\n text=\"查询内容\",\n original_placeholder=\"搜索...\"\n)\n\n# 获取快照\nsnapshot = await session.get_snapshot()\n```\n\n## 配置与管理\n\n### 工具集注册\n\nCAMEL-AI 提供了统一的工具集注册机制，开发者可以将自定义工具集注册到全局注册表中，供整个应用使用。\n\n```python\nfrom camel.toolkits import ToolkitRegistry\n\n# 获取注册表实例\nregistry = ToolkitRegistry.get_instance()\n\n# 注册自定义工具集\nregistry.register(\"my_toolkit\", MyCustomToolkit())\n```\n\n### 环境变量配置\n\n部分工具集需要配置外部服务的API密钥或访问凭证。这些配置通常通过环境变量提供：\n\n| 环境变量 | 适用工具集 | 用途 |\n|----------|------------|------|\n| OPENAI_API_KEY | 所有工具集 | API身份验证 |\n| GITHUB_TOKEN | GitHubToolkit | GitHub API访问 |\n| SLACK_BOT_TOKEN | SlackToolkit | Slack API访问 |\n| SEARCH_API_KEY | SearchToolkit | 搜索服务访问 |\n\n## 与代理系统的集成\n\n工具集与CAMEL-AI的代理系统紧密集成，代理在初始化时可以接收一个或多个工具集作为能力扩展。\n\n```mermaid\ngraph TD\n A[Agent初始化] --> B[加载工具集]\n B --> C[工具注册]\n C --> D[函数调用接口暴露]\n D --> E[运行时调用]\n E --> F[结果返回]\n```\n\n代理系统会自动处理工具调用的路由、参数序列化和结果反序列化等细节，开发者只需关注业务逻辑的实现。\n\n## 最佳实践\n\n### 工具设计原则\n\n1. **单一职责**：每个工具应专注于完成一个特定任务\n2. **清晰的命名**：工具名应准确反映其功能\n3. **完善的文档**：提供详细的参数说明和返回值描述\n4. **错误处理**：对异常情况进行恰当处理和提示\n5. **参数验证**：在执行前验证所有输入参数的有效性\n\n### 性能优化建议\n\n- 复用工具集实例，避免重复创建\n- 对于耗时操作，考虑使用异步实现\n- 批量操作时使用事务或批处理接口\n- 合理设置超时时间，防止长时间阻塞\n\n## 扩展开发\n\n开发者可以通过继承 `BaseToolkit` 类来创建自定义工具集。标准开发流程如下：\n\n1. 创建继承自 `BaseToolkit` 的新类\n2. 在 `__init__` 方法中初始化所需的资源和配置\n3. 实现具体的功能方法\n4. 添加适当的文档字符串\n5. 在包入口文件中导出新工具集\n\n自定义工具集可以像内置工具集一样注册到代理中，实现无缝集成。\n\n## 相关资源\n\n- 基础工具类源码：[camel/toolkits/base.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/base.py)\n- 函数工具源码：[camel/toolkits/function_tool.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/function_tool.py)\n- 浏览器工具集源码：[camel/toolkits/browser_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/browser_toolkit.py)\n- 混合浏览器工具集：[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)\n- 搜索工具集源码：[camel/toolkits/search_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/search_toolkit.py)\n- 文件工具集源码：[camel/toolkits/file_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/file_toolkit.py)\n- GitHub工具集源码：[camel/toolkits/github_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/github_toolkit.py)\n- Slack工具集源码：[camel/toolkits/slack_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/slack_toolkit.py)\n\n---\n\n\n\n## MCP协议集成\n\n### 相关页面\n\n相关主题：[工具集(Toolkits)](#page-toolkits), [智能体(Agents)](#page-agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/toolkits/mcp_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/mcp_toolkit.py)\n- [camel/agents/mcp_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/mcp_agent.py)\n- [camel/parsers/mcp_tool_call_parser.py](https://github.com/camel-ai/camel/blob/main/camel/parsers/mcp_tool_call_parser.py)\n- [camel/types/mcp_registries.py](https://github.com/camel-ai/camel/blob/main/camel/types/mcp_registries.py)\n- [camel/utils/mcp_client.py](https://github.com/camel-ai/camel/blob/main/camel/utils/mcp_client.py)\n \n\n# MCP协议集成\n\n## 概述\n\nMCP（Model Context Protocol）是一种标准化协议，用于在AI代理（Agent）与外部工具、服务之间建立通信桥梁。CAMEL-AI框架通过模块化的MCP集成方案，使代理能够调用远程工具、访问外部资源，并与其他MCP兼容系统进行交互。\n\nMCP协议集成的核心目标包括：\n- 提供统一的工具调用接口\n- 支持多种MCP服务器连接\n- 实现工具解析与响应处理\n- 管理工具注册与生命周期\n\n资料来源：[camel/toolkits/mcp_toolkit.py:1-50]()\n\n## 核心组件\n\nCAMEL-AI的MCP协议集成由以下核心模块组成：\n\n| 组件 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| MCPToolkit | `camel/toolkits/mcp_toolkit.py` | MCP工具集，提供与MCP服务器交互的主要接口 |\n| MCPAgent | `camel/agents/mcp_agent.py` | MCP代理，负责处理MCP协议通信的代理实现 |\n| MCPToolCallParser | `camel/parsers/mcp_tool_call_parser.py` | 工具调用解析器，解析MCP协议消息 |\n| MCP registries | `camel/types/mcp_registries.py` | MCP类型注册表，管理MCP类型定义 |\n| MCPClient | `camel/utils/mcp_client.py` | MCP客户端工具，提供底层通信能力 |\n\n资料来源：[camel/types/mcp_registries.py:1-30]()\n\n### 组件关系图\n\n```mermaid\ngraph TD\n A[MCPAgent] --> B[MCPToolkit]\n B --> C[MCPToolCallParser]\n B --> D[MCPClient]\n D --> E[MCP Registries]\n F[MCP Servers] --> D\n A --> G[User Application]\n```\n\n## 架构设计\n\n### 系统架构\n\nMCP协议集成采用客户端-服务器架构，核心交互流程如下：\n\n```mermaid\nsequenceDiagram\n participant User as 用户应用\n participant Agent as MCPAgent\n participant Toolkit as MCPToolkit\n participant Client as MCPClient\n participant Server as MCP服务器\n\n User->>Agent: 调用工具\n Agent->>Toolkit: 解析工具请求\n Toolkit->>Client: 发起MCP调用\n Client->>Server: 发送协议消息\n Server-->>Client: 返回结果\n Client-->>Toolkit: 解析响应\n Toolkit-->>Agent: 返回工具结果\n Agent-->>User: 输出最终结果\n```\n\n### 工具调用解析\n\n`MCPToolCallParser`负责解析工具调用请求，其处理流程：\n\n```mermaid\ngraph LR\n A[MCP协议消息] --> B[解析工具名称]\n B --> C[提取参数]\n C --> D[验证参数类型]\n D --> E[生成标准化调用]\n```\n\n资料来源：[camel/parsers/mcp_tool_call_parser.py:1-40]()\n\n## MCPAgent详解\n\n`MCPAgent`是MCP协议集成的核心代理类，继承自基础代理接口，提供以下功能：\n\n### 主要职责\n\n- 初始化MCP客户端连接\n- 管理工具注册生命周期\n- 处理用户请求并转发至MCP服务器\n- 解析和返回工具执行结果\n\n### 初始化参数\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| name | str | 是 | 代理名称 |\n| mcp_servers_config | dict | 是 | MCP服务器配置 |\n| model | Model | 是 | 使用的语言模型 |\n| system_message | str | 否 | 系统提示词 |\n\n资料来源：[camel/agents/mcp_agent.py:20-60]()\n\n## MCPToolkit使用指南\n\n`MCPToolkit`提供了与MCP服务器交互的统一接口，简化了工具调用流程。\n\n### 服务器配置\n\nMCP服务器通过JSON配置文件进行定义：\n\n```json\n{\n \"mcpServers\": {\n \"airbnb\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@openbnb/mcp-server-airbnb\", \"--ignore-robots-txt\"]\n },\n \"cloudflare\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-cloudflare\"]\n }\n }\n}\n```\n\n### 工具注册流程\n\n```mermaid\ngraph TD\n A[加载MCP配置] --> B[初始化MCPClient]\n B --> C[连接MCP服务器]\n C --> D[获取可用工具列表]\n D --> E[注册工具到Toolkit]\n E --> F[返回MCPToolkit实例]\n```\n\n资料来源：[camel/toolkits/mcp_toolkit.py:50-100]()\n\n## MCPClient通信机制\n\n`MCPClient`是底层的通信客户端，负责与MCP服务器进行协议级别的交互。\n\n### 核心方法\n\n| 方法 | 说明 |\n|------|------|\n| connect | 建立与MCP服务器的连接 |\n| disconnect | 关闭连接并清理资源 |\n| call_tool | 调用远程工具 |\n| list_tools | 获取可用工具列表 |\n| get_resources | 获取服务器资源 |\n\n资料来源：[camel/utils/mcp_client.py:30-80]()\n\n### 协议消息格式\n\nMCP协议使用JSON格式进行消息传递，标准请求结构：\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"tool_name\",\n \"arguments\": {}\n }\n}\n```\n\n## 实际应用示例\n\n### 多代理研究助手\n\n在`examples/usecases/multi_agent_research_assistant`中，MCP协议用于集成外部搜索和新闻API：\n\n```python\nfrom camel.agents.mcp_agent import MCPAgent\nfrom camel.toolkits.mcp_toolkit import MCPToolkit\n\n# 初始化MCP代理\nagent = MCPAgent(\n name=\"research_assistant\",\n mcp_servers_config=mcp_config,\n model=model\n)\n```\n\n### Cloudflare MCP集成\n\n在`examples/usecases/cloudfare_mcp_camel`中，集成Cloudflare的多个MCP服务：\n\n- **Analytics MCP服务器**：提供全球互联网流量趋势分析\n- **DNS Analytics服务器**：提供DNS分析能力\n- **Browser服务器**：提供网页抓取和截图功能\n\n资料来源：[examples/usecases/cloudfare_mcp_camel/README.md]()\n\n### Airbnb房源搜索\n\n`examples/usecases/airbnb_mcp`展示了如何集成Airbnb的MCP服务器：\n\n```json\n{\n \"mcpServers\": {\n \"airbnb\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@openbnb/mcp-server-airbnb\", \"--ignore-robots-txt\"]\n }\n }\n}\n```\n\n资料来源：[examples/usecases/airbnb_mcp/README.md]()\n\n## 最佳实践\n\n### 配置管理\n\n1. **环境变量分离**：将API密钥存储在`.env`文件中，避免硬编码\n2. **配置文件版本化**：使用版本控制管理MCP服务器配置\n3. **错误处理**：实现完善的异常捕获和重试机制\n\n### 性能优化\n\n| 优化项 | 建议 |\n|--------|------|\n| 连接复用 | 保持长连接避免频繁建立TCP连接 |\n| 缓存策略 | 对不常变化的工具列表进行缓存 |\n| 并发控制 | 使用连接池管理并发请求 |\n\n### 安全考虑\n\n- 敏感信息不写入配置文件\n- 使用环境变量注入API密钥\n- 定期轮换API访问凭证\n\n## 故障排查\n\n| 常见问题 | 可能原因 | 解决方案 |\n|----------|----------|----------|\n| 连接超时 | MCP服务器未启动 | 检查`mcp-remote`安装状态 |\n| 工具调用失败 | 参数格式错误 | 检查MCP服务器返回的错误信息 |\n| 响应解析错误 | 协议版本不兼容 | 确保客户端与服务端版本匹配 |\n\n资料来源：[examples/usecases/cloudfare_mcp_camel/README.md]()\n\n## 相关资源\n\n- MCP官方文档：[Model Context Protocol](https://modelcontextprotocol.io/)\n- CAMEL-AI官方仓库：[camel-ai/camel](https://github.com/camel-ai/camel)\n- MCP Inspector工具：用于调试MCP服务器连接\n\n---\n\n*本文档由CAMEL-AI框架源码自动生成，最后更新于2024年*\n\n---\n\n\n\n## 智能体社会(Societies)\n\n### 相关页面\n\n相关主题：[智能体劳动力(Workforce)](#page-workforce), [智能体(Agents)](#page-agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/societies/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/societies/__init__.py)\n- [camel/societies/role_playing.py](https://github.com/camel-ai/camel/blob/main/camel/societies/role_playing.py)\n- [camel/societies/babyagi_playing.py](https://github.com/camel-ai/camel/blob/main/camel/societies/babyagi_playing.py)\n- [camel/personas/persona.py](https://github.com/camel-ai/camel/blob/main/camel/personas/persona.py)\n- [camel/personas/persona_hub.py](https://github.com/camel-ai/camel/blob/main/camel/personas/persona_hub.py)\n \n\n# 智能体社会(Societies)\n\n## 概述\n\nCAMEL框架中的**智能体社会(Societies)**模块是实现多智能体协作的核心基础设施。该模块提供了一套完整的多智能体交互机制，支持角色扮演、任务分解、自主执行等多种协作范式。智能体社会允许定义多个具有特定角色和能力的智能体，通过结构化的通信协议实现复杂的协作任务。\n\n智能体社会的设计理念源于社会学中的\"社会\"概念，模拟人类社会中不同角色之间的交互模式。每个智能体被赋予特定的角色身份（如\"AI助手\"、\"用户代理\"等），这些角色定义了智能体的行为模式、决策风格和通信方式。通过这种方式，CAMEL能够构建具有真实感的AI系统交互场景。\n\n## 核心架构\n\n### 模块结构\n\nCAMEL的智能体社会模块位于`camel/societies/`目录下，包含多个核心组件：\n\n| 组件文件 | 功能描述 |\n|---------|---------|\n| `__init__.py` | 模块导出接口，定义公共API |\n| `role_playing.py` | 角色扮演核心实现，支持双智能体协作 |\n| `babyagi_playing.py` | BabyAGI范式实现，支持任务分解与执行 |\n\n```\ncamel/societies/\n├── __init__.py # 模块入口\n├── role_playing.py # 角色扮演实现\n└── babyagi_playing.py # BabyAGI实现\n```\n\n### 类层次结构\n\n智能体社会模块采用面向对象设计，核心类包括：\n\n- **RolePlaying**：角色扮演主类，管理两个智能体之间的对话交互\n- **BabyAGI**：BabyAGI执行器，实现自主任务分解与执行\n- **BaseSociety**：基础抽象类（若存在），定义通用接口\n\n```mermaid\ngraph TD\n A[BaseSociety] --> B[RolePlaying]\n A --> C[BabyAGI]\n B --> D[AI Assistant Agent]\n B --> E[User Agent]\n C --> F[Task Agent]\n C --> G[Execution Agent]\n C --> H[Critique Agent]\n```\n\n## 角色扮演系统(Role Playing)\n\n### 系统设计\n\n角色扮演是CAMEL框架中最核心的智能体协作模式。该系统模拟人类社会中的角色交互场景，由两个主要智能体组成：\n\n- **AI助手智能体(AI Assistant Agent)**：扮演AI助手角色，响应用户请求\n- **用户代理智能体(User Agent)**：代表最终用户，执行用户指定的任务\n\n这种双智能体设计允许AI系统在没有人类直接干预的情况下自主协作完成任务。\n\n### RolePlaying类详解\n\n`RolePlaying`类是多智能体协作的主入口，提供完整的对话管理功能。\n\n#### 构造函数参数\n\n| 参数名 | 类型 | 必需 | 默认值 | 说明 |\n|-------|------|------|--------|------|\n| `assistant_agent` | `BaseAgent` | 是 | - | AI助手智能体实例 |\n| `user_agent` | `BaseAgent` | 是 | - | 用户代理智能体实例 |\n| `task_prompt` | `str` | 是 | - | 任务描述提示词 |\n| `task_specify_prompt` | `str` | 否 | None | 任务细化提示词 |\n| `with_task_specify` | `bool` | 否 | True | 是否进行任务细化 |\n| `max_dialogue` | `int` | 否 | 20 | 最大对话轮数 |\n| `turn_limit` | `int` | 否 | None | 单轮交互限制 |\n\n#### 核心方法\n\n| 方法名 | 返回类型 | 功能描述 |\n|-------|---------|---------|\n| `init_chat()` | `None` | 初始化对话，设置系统提示词 |\n| `step()` | `ChatAgentResponse` | 执行单步对话交互 |\n| `run()` | `List[BaseMessage]` | 运行完整的角色扮演对话 |\n| `get_info()` | `Dict` | 获取当前对话状态信息 |\n\n### 工作流程\n\n角色扮演系统遵循严格的对话协议，确保智能体之间的交互有序进行：\n\n```mermaid\ngraph TD\n A[初始化 init_chat] --> B{检查终止条件}\n B -->|未达到限制| C[AI助手生成回复]\n C --> D[消息加入对话历史]\n D --> E{检查终止条件}\n E -->|未达到限制| F[用户代理处理]\n F --> D\n E -->|达到限制| G[返回对话历史]\n B -->|达到限制| G\n G --> H[对话结束]\n```\n\n### 任务指定机制\n\n角色扮演系统包含任务指定(Task Specification)模块，用于将模糊的用户请求转化为具体的任务描述：\n\n1. **任务分析**：AI助手分析用户意图\n2. **任务细化**：将大任务分解为可执行的子任务\n3. **目标确认**：用户代理确认任务目标和范围\n4. **执行计划**：制定详细的执行步骤\n\n```mermaid\ngraph LR\n A[模糊任务请求] --> B[任务分析]\n B --> C[任务细化]\n C --> D[子任务分解]\n D --> E[执行计划制定]\n E --> F[具体可执行任务]\n```\n\n## 人物角色系统(Personas)\n\n### Persona类\n\n`Persona`类定义了智能体的身份特征和行为模式。\n\n#### 属性定义\n\n| 属性名 | 类型 | 说明 |\n|-------|------|------|\n| `name` | `str` | 角色名称 |\n| `description` | `str` | 角色描述 |\n| `system_instruction` | `str` | 系统级指令 |\n| `role_type` | `RoleType` | 角色类型枚举 |\n\n#### 核心功能\n\n- **身份塑造**：定义智能体的角色身份和背景\n- **行为约束**：通过系统指令约束智能体的行为模式\n- **交互风格**：设定智能体的沟通和响应风格\n\n### PersonaHub\n\n`PersonaHub`是角色仓库，提供预定义的角色模板和自定义接口。\n\n#### 预定义角色类型\n\n| 角色标识 | 角色名称 | 应用场景 |\n|---------|---------|---------|\n| `ASSISTANT` | AI助手 | 通用问答和任务执行 |\n| `USER` | 用户代理 | 代表用户执行任务 |\n| `CRITIC` | 批评者 | 评估和审核任务结果 |\n| `PLANNER` | 规划者 | 任务规划和分解 |\n| `RESEARCHER` | 研究者 | 信息检索和分析 |\n\n#### 角色获取接口\n\n```python\n# 从仓库获取预定义角色\npersona = PersonaHub.get_persona(persona_type=PersonaType.ASSISTANT)\n\n# 获取带自定义参数的角色\ncustom_persona = PersonaHub.get_persona(\n persona_type=PersonaType.RESEARCHER,\n custom_params={\"expertise\": \"quantum computing\"}\n)\n```\n\n## BabyAGI范式\n\n### 概述\n\nBabyAGI是另一种智能体协作范式，与角色扮演不同，它更强调任务的自动分解和迭代执行。该模式模拟了人类解决复杂问题时的思考过程。\n\n### BabyAGIPlaying类\n\n`BabyAGIPlaying`类实现了BabyAGI的核心逻辑。\n\n#### 组成结构\n\n| 组件 | 类型 | 功能 |\n|-----|------|------|\n| `task_creation_agent` | `BaseAgent` | 负责创建和分解任务 |\n| `execution_agent` | `BaseAgent` | 负责执行具体任务 |\n| `critique_agent` | `BaseAgent` | 负责评估和反馈 |\n\n#### 执行流程\n\n```mermaid\ngraph TD\n A[接收初始任务] --> B[任务创建智能体分析任务]\n B --> C[生成任务列表]\n C --> D{任务队列非空?}\n D -->|是| E[执行智能体处理任务]\n E --> F[批评智能体评估结果]\n F --> G{需要新任务?}\n G -->|是| H[创建新任务]\n H --> C\n G -->|否| I[任务完成]\n I --> D\n D -->|否| J[返回最终结果]\n```\n\n### 与角色扮演的区别\n\n| 特性 | 角色扮演 | BabyAGI |\n|------|---------|---------|\n| 智能体数量 | 2个 | 3个或更多 |\n| 通信模式 | 双向对话 | 多向协作 |\n| 任务处理 | 协作完成 | 分解执行 |\n| 反馈机制 | 有限 | 迭代改进 |\n| 适用场景 | 对话交互 | 复杂任务 |\n\n## 使用示例\n\n### 基础角色扮演\n\n```python\nfrom camel.societies import RolePlaying\nfrom camel.agents import ChatAgent\nfrom camel.personas import PersonaHub\n\n# 创建智能体\nassistant_persona = PersonaHub.get_persona(PersonaType.ASSISTANT)\nuser_persona = PersonaHub.get_persona(PersonaType.USER)\n\nassistant_agent = ChatAgent(persona=assistant_persona)\nuser_agent = ChatAgent(persona=user_persona)\n\n# 初始化角色扮演\nsociety = RolePlaying(\n assistant_agent=assistant_agent,\n user_agent=user_agent,\n task_prompt=\"帮我分析量子计算的最新发展趋势\"\n)\n\n# 执行对话\nmessages = society.run()\n```\n\n### BabyAGI任务执行\n\n```python\nfrom camel.societies import BabyAGIPlaying\n\n# 初始化BabyAGI\nbabyagi = BabyAGIPlaying(\n task=\"完成一份市场调研报告\",\n max_iterations=10\n)\n\n# 执行自主任务分解和执行\nresults = babyagi.run()\n```\n\n## 配置与扩展\n\n### 智能体配置\n\n智能体的行为可通过配置进行定制：\n\n```python\nfrom camel.config import AgentConfig\n\nconfig = AgentConfig(\n model_type=\"gpt-4\",\n temperature=0.7,\n max_tokens=2000,\n tool_use=True\n)\n```\n\n### 自定义角色创建\n\n```python\nfrom camel.personas import Persona, PersonaType\n\ncustom_persona = Persona(\n name=\"数据分析师\",\n description=\"专业的金融数据分析助手\",\n system_instruction=\"你是一位资深数据分析师，擅长从数据中发现洞见\",\n role_type=PersonaType.RESEARCHER\n)\n```\n\n## 最佳实践\n\n### 设计原则\n\n1. **角色清晰**：确保每个智能体的角色定义明确，职责单一\n2. **对话管理**：合理设置对话轮数限制，避免无限循环\n3. **错误处理**：实现健壮的错误捕获和恢复机制\n4. **资源管理**：及时释放不再使用的智能体资源\n\n### 性能优化\n\n- 合理设置`max_dialogue`参数控制对话长度\n- 使用流式输出减少响应延迟\n- 启用缓存机制避免重复计算\n\n### 安全考虑\n\n- 验证用户输入防止提示词注入攻击\n- 限制工具调用的权限范围\n- 实现对话内容审核机制\n\n## 总结\n\nCAMEL的智能体社会(Societies)模块提供了一套完整的多智能体协作框架。通过角色扮演和BabyAGI两种核心范式，开发者可以构建复杂的AI应用场景。模块化的设计使得系统易于扩展和定制，满足不同应用需求。人物角色系统为智能体提供了丰富的身份和行为特征，使多智能体交互更加真实和高效。\n\n---\n\n**相关文档**\n\n- [基础对话智能体](../agents/chat_agent.md)\n- [工具包(Toolkits)](../toolkits/README.md)\n- [模型配置](../config/README.md)\n\n---\n\n\n\n## 智能体劳动力(Workforce)\n\n### 相关页面\n\n相关主题：[智能体社会(Societies)](#page-societies), [智能体(Agents)](#page-agents), [记忆系统(Memory)](#page-memory)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/societies/workforce/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/__init__.py)\n- [camel/societies/workforce/workforce.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/workforce.py)\n- [camel/societies/workforce/worker.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/worker.py)\n- [camel/societies/workforce/task_channel.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/task_channel.py)\n- [camel/societies/workforce/role_playing_worker.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/role_playing_worker.py)\n- [camel/societies/workforce/single_agent_worker.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/single_agent_worker.py)\n- [camel/societies/workforce/events.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/events.py)\n \n\n# 智能体劳动力(Workforce)\n\n## 概述\n\nWorkforce 是 CAMEL 框架中的核心组件，用于协调和管理多个智能体(Worker)协同完成复杂任务。它提供了一个灵活的架构，使多个不同类型的 Worker 能够通过任务通道进行通信和协作，从而实现分布式问题解决和工作流自动化。\n\nWorkforce 的核心设计理念是将复杂任务分解为多个子任务，分配给专门化的 Worker 执行，并通过事件驱动的方式协调整个工作流程。资料来源：[camel/societies/workforce/__init__.py]()\n\n## 核心架构\n\nWorkforce 系统由以下核心组件构成：\n\n```mermaid\ngraph TD\n A[Workforce] --> B[TaskChannel]\n A --> C[Worker Pool]\n C --> D[RolePlayingWorker]\n C --> E[SingleAgentWorker]\n C --> F[BaseWorker]\n A --> G[EventSystem]\n G --> H[WorkforceEvent]\n B --> I[任务分发]\n D --> J[角色扮演任务]\n E --> K[单智能体任务]\n```\n\n## 目录结构\n\n```\ncamel/societies/workforce/\n├── __init__.py # 模块初始化，导出主要接口\n├── workforce.py # Workforce 主类\n├── worker.py # Worker 基类\n├── role_playing_worker.py # 角色扮演 Worker\n├── single_agent_worker.py # 单智能体 Worker\n├── task_channel.py # 任务通道实现\n└── events.py # 事件系统定义\n```\n\n## 组件详解\n\n### Workforce 主类\n\nWorkforce 是整个系统的调度中心，负责管理 Worker 生命周期、任务分发和结果收集。资料来源：[camel/societies/workforce/workforce.py]()\n\n**主要职责：**\n\n- 初始化和管理 Worker 池\n- 维护任务通道和事件系统\n- 协调多 Worker 间的通信\n- 监控任务执行状态\n- 处理异常和超时情况\n\n### Worker 基类\n\nWorker 是执行任务的基本单元，提供统一的任务执行接口。资料来源：[camel/societies/workforce/worker.py]()\n\n**Worker 类型对比：**\n\n| Worker 类型 | 说明 | 适用场景 |\n|-------------|------|----------|\n| BaseWorker | 所有 Worker 的基类，定义通用接口 | 扩展自定义 Worker |\n| RolePlayingWorker | 支持角色扮演的 Worker | 需要角色协作的任务 |\n| SingleAgentWorker | 单一智能体 Worker | 独立执行的任务 |\n\n### 任务通道 (TaskChannel)\n\nTaskChannel 负责在 Worker 之间传递任务和结果。资料来源：[camel/societies/workforce/task_channel.py]()\n\n**通道类型支持：**\n\n- 同步通道：阻塞式任务传递\n- 异步通道：非阻塞式任务传递\n- 广播通道：一对多任务分发\n\n### 事件系统 (Events)\n\n事件系统提供 Workforce 内部的通信机制，支持状态变更通知和任务进度追踪。资料来源：[camel/societies/workforce/events.py]()\n\n## 工作流程\n\n### 任务执行流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant W as Workforce\n participant TC as TaskChannel\n participant WK as Worker\n participant E as EventSystem\n\n U->>W: 提交任务\n W->>TC: 创建任务通道\n W->>WK: 分发任务\n WK->>E: 发送任务开始事件\n WK->>W: 执行任务\n W->>E: 发布进度事件\n WK->>TC: 返回结果\n TC->>W: 收集结果\n W->>U: 返回最终结果\n```\n\n### Worker 协作模式\n\n```mermaid\ngraph LR\n A[任务输入] --> B{Worker选择}\n B -->|角色扮演| C[RolePlayingWorker]\n B -->|独立执行| D[SingleAgentWorker]\n C --> E[协作处理]\n D --> F[独立处理]\n E --> G[结果聚合]\n F --> G\n G --> H[结果输出]\n```\n\n## API 参考\n\n### Workforce 初始化参数\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| workers | List[BaseWorker] | 是 | Worker 列表 |\n| task_channel_type | str | 否 | 任务通道类型，默认 \"default\" |\n| max_workers | int | 否 | 最大并发 Worker 数 |\n| timeout | int | 否 | 任务超时时间(秒) |\n\n### Worker 执行接口\n\n```python\nclass BaseWorker(ABC):\n @abstractmethod\n async def execute(self, task: Task) -> Result:\n \"\"\"执行单个任务\"\"\"\n pass\n \n @abstractmethod\n async def reset(self) -> None:\n \"\"\"重置 Worker 状态\"\"\"\n pass\n \n @property\n @abstractmethod\n def worker_id(self) -> str:\n \"\"\"获取 Worker 唯一标识\"\"\"\n pass\n```\n\n资料来源：[camel/societies/workforce/worker.py]()\n\n## Worker 类型详解\n\n### RolePlayingWorker\n\nRolePlayingWorker 支持多角色协作模式，适用于需要角色扮演和对话的任务场景。资料来源：[camel/societies/workforce/role_playing_worker.py]()\n\n**配置选项：**\n\n| 选项 | 类型 | 说明 |\n|------|------|------|\n| role_name | str | 角色名称 |\n| role_description | str | 角色描述 |\n| model | Model | 使用的语言模型 |\n| tools | List[Tool] | 可用工具列表 |\n\n### SingleAgentWorker\n\nSingleAgentWorker 是单一智能体执行器，适合不需要协作的独立任务。资料来源：[camel/societies/workforce/single_agent_worker.py]()\n\n**特点：**\n\n- 独立的执行环境\n- 无需与其他 Worker 通信\n- 更低的资源消耗\n- 适用于简单任务\n\n## 事件类型\n\nWorkforceEvent 定义了系统中的各种事件类型。资料来源：[camel/societies/workforce/events.py]()\n\n| 事件类型 | 触发时机 | 用途 |\n|----------|----------|------|\n| TASK_STARTED | 任务开始执行 | 记录任务启动 |\n| TASK_COMPLETED | 任务完成 | 收集结果 |\n| TASK_FAILED | 任务执行失败 | 错误处理 |\n| WORKER_REGISTERED | Worker 注册 | 添加到调度池 |\n| WORKER_UNREGISTERED | Worker 注销 | 清理资源 |\n\n## 使用示例\n\n### 基本使用\n\n```python\nfrom camel.societies.workforce import Workforce, SingleAgentWorker\nfrom camel.societies.workforce.task_channel import TaskChannel\n\n# 创建 Workforce\nworkforce = Workforce(\n workers=[SingleAgentWorker(...)],\n max_workers=4\n)\n\n# 提交任务\nresult = await workforce.execute_task(task)\n```\n\n### 角色协作场景\n\n```python\nfrom camel.societies.workforce import (\n Workforce,\n RolePlayingWorker,\n TaskChannel\n)\n\n# 创建多角色 Workforce\nworkforce = Workforce(\n workers=[\n RolePlayingWorker(role_name=\"研究员\", ...),\n RolePlayingWorker(role_name=\"开发者\", ...),\n ]\n)\n\n# 执行协作任务\nresult = await workforce.execute_collaborative_task(task)\n```\n\n## 最佳实践\n\n### 1. Worker 配置建议\n\n- 根据任务复杂度选择合适的 Worker 类型\n- 合理设置 Worker 数量避免资源竞争\n- 为长时间运行的任务配置超时机制\n\n### 2. 任务分发策略\n\n```mermaid\ngraph TD\n A[任务类型判断] --> B{需要协作?}\n B -->|是| C[使用 RolePlayingWorker]\n B -->|否| D[使用 SingleAgentWorker]\n C --> E[通过 TaskChannel 协调]\n D --> F[直接执行]\n```\n\n### 3. 错误处理\n\n- 监听 TASK_FAILED 事件进行错误恢复\n- 实现 Worker 重试机制\n- 设置合理的超时时间\n\n## 与其他模块的集成\n\nWorkforce 与 CAMEL 框架中的其他模块紧密集成：\n\n| 模块 | 集成方式 | 说明 |\n|------|----------|------|\n| ModelFactory | Worker 配置 | 为 Worker 提供模型支持 |\n| Toolkits | 工具扩展 | Worker 可调用各种工具 |\n| Messages | 通信协议 | Worker 间消息传递 |\n| Storage | 状态持久化 | 任务状态存储 |\n\n## 总结\n\nWorkforce 是 CAMEL 框架实现多智能体协作的核心基础设施。通过提供统一的任务分发、Worker 管理和事件驱动机制，Workforce 使得构建复杂的智能体协作系统变得简单高效。开发者可以根据具体需求选择合适的 Worker 类型，并通过灵活的配置实现各种协作模式。\n\n---\n\n\n\n## 记忆系统(Memory)\n\n### 相关页面\n\n相关主题：[智能体(Agents)](#page-agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/memories/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/memories/__init__.py)\n- [camel/memories/base.py](https://github.com/camel-ai/camel/blob/main/camel/memories/base.py)\n- [camel/memories/agent_memories.py](https://github.com/camel-ai/camel/blob/main/camel/memories/agent_memories.py)\n- [camel/memories/blocks/chat_history_block.py](https://github.com/camel-ai/camel/blob/main/camel/memories/blocks/chat_history_block.py)\n- [camel/memories/blocks/vectordb_block.py](https://github.com/camel-ai/camel/blob/main/camel/memories/blocks/vectordb_block.py)\n- [camel/memories/context_creators/score_based.py](https://github.com/camel-ai/camel/blob/main/camel/memories/context_creators/score_based.py)\n- [camel/memories/records.py](https://github.com/camel-ai/camel/blob/main/camel/memories/records.py)\n \n\n# 记忆系统(Memory)\n\n## 概述\n\nCAMEL记忆系统是框架中用于管理Agent对话上下文和历史信息的核心组件。该系统通过模块化的设计，支持多种记忆存储方式和上下文检索策略，使Agent能够高效地访问和利用历史交互信息。\n\n记忆系统的核心设计理念是将**记忆存储**与**上下文生成**分离，通过可插拔的Block组件和Context Creator实现灵活的内存管理机制。\n\n## 架构总览\n\n```mermaid\ngraph TB\n subgraph \"记忆系统核心组件\"\n AM[AgentMemories]\n MC[Memory]\n CC[ContextCreator]\n end\n \n subgraph \"存储块Blocks\"\n CHB[ChatHistoryBlock]\n VDB[VectorDBBlock]\n end\n \n subgraph \"上下文创建器\"\n SBC[ScoreBasedContextCreator]\n end\n \n subgraph \"记录Records\"\n CHR[ChatHistoryRecord]\n MR[MemoryRecord]\n end\n \n AM --> MC\n AM --> CC\n MC --> CHB\n MC --> VDB\n CC --> SBC\n SBC --> MC\n CHB --> CHR\n VDB --> MR\n```\n\n## 核心组件\n\n### 记忆基类 (Memory)\n\n`Memory`是所有记忆组件的抽象基类，定义了记忆系统的核心接口：\n\n```python\nclass Memory(Generic[MemoryRecord], ABC):\n @property\n @abstractmethod\n def size(self) -> int: ...\n \n @abstractmethod\n def read(self, *args, **kwargs) -> List[MemoryRecord]: ...\n \n @abstractmethod\n def write(self, *args, **kwargs) -> None: ...\n \n def clear(self) -> None: ...\n```\n\n| 方法 | 说明 | 返回值 |\n|------|------|--------|\n| `size` | 获取当前记忆存储的条目数量 | `int` |\n| `read()` | 读取记忆记录 | `List[MemoryRecord]` |\n| `write()` | 写入新的记忆记录 | `None` |\n| `clear()` | 清除所有记忆 | `None` |\n\n资料来源：[camel/memories/base.py]()\n\n### Agent记忆管理器 (AgentMemories)\n\n`AgentMemories`是Agent级别的记忆容器，负责整合多个记忆组件和上下文创建器：\n\n```python\nclass AgentMemories:\n def __init__(\n self,\n memories: List[Memory] = [],\n context_creator: Optional[ContextCreator] = None,\n ) -> None:\n self.memories: List[Memory] = memories\n self.context_creator = context_creator\n```\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `memories` | `List[Memory]` | 关联的记忆块列表 |\n| `context_creator` | `Optional[ContextCreator]` | 上下文创建器 |\n\n**核心功能**：\n- 管理多个记忆块的读写操作\n- 聚合多个Memory组件的记忆内容\n- 通过ContextCreator生成上下文摘要\n\n资料来源：[camel/memories/agent_memories.py]()\n\n## 存储块 (Blocks)\n\n存储块是实际存储记忆数据的组件，支持不同的存储后端和检索策略。\n\n### 聊天历史块 (ChatHistoryBlock)\n\n`ChatHistoryBlock`用于存储和管理Agent之间的对话历史记录：\n\n```python\nclass ChatHistoryBlock(Memory[ChatHistoryRecord]):\n def __init__(\n self,\n window_size: int = 0,\n max_tokens: int = 0,\n ) -> None:\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `window_size` | `int` | `0` | 滑动窗口大小，0表示不使用窗口 |\n| `max_tokens` | `int` | `0` | 最大token数限制 |\n\n**写入机制**：\n- 接收`ChatHistoryRecord`类型的记录\n- 支持基于窗口大小或token数量的自动截断\n- 保持对话顺序的时间序列\n\n**读取机制**：\n- 按时间顺序返回历史记录\n- 支持窗口截断和token限制\n\n资料来源：[camel/memories/blocks/chat_history_block.py]()\n\n### 向量数据库块 (VectorDBBlock)\n\n`VectorDBBlock`利用向量数据库实现语义相似度检索：\n\n```python\nclass VectorDBBlock(Memory[MemoryRecord]):\n def __init__(\n self,\n embedding_model: Optional[EmbeddingModel] = None,\n query_processor: Optional[QueryProcessor] = None,\n embedding_backend: Optional[EmbeddingModel] = None,\n storage: Optional[VectorDB] = None,\n k: int = 10,\n max_tokens: int = 0,\n ) -> None:\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `embedding_model` | `Optional[EmbeddingModel]` | 向量嵌入模型 |\n| `query_processor` | `Optional[QueryProcessor]` | 查询处理器 |\n| `storage` | `Optional[VectorDB]` | 向量数据库存储后端 |\n| `k` | `int` | 检索返回的最大结果数 |\n| `max_tokens` | `int` | 最大token数限制 |\n\n**检索流程**：\n1. 将输入查询转换为向量表示\n2. 在向量数据库中进行相似度搜索\n3. 返回Top-K个最相关的记忆记录\n\n资料来源：[camel/memories/blocks/vectordb_block.py]()\n\n## 记录类型 (Records)\n\n记录类型定义了记忆系统中各种数据的结构化格式。\n\n### ChatHistoryRecord\n\n```python\n@dataclass\nclass ChatHistoryRecord(MemoryRecord):\n role: str\n content: str\n message_type: RoleType\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `role` | `str` | 消息发送者角色 |\n| `content` | `str` | 消息内容 |\n| `message_type` | `RoleType` | 角色类型 |\n\n资料来源：[camel/memories/records.py]()\n\n## 上下文创建器 (Context Creators)\n\n上下文创建器负责从记忆系统中提取相关信息，生成供Agent使用的上下文提示。\n\n### 基于评分的上下文创建器 (ScoreBasedContextCreator)\n\n`ScoreBasedContextCreator`通过评分机制选择最相关的记忆片段：\n\n```python\nclass ScoreBasedContextCreator(ContextCreator):\n def __init__(\n self,\n model: Model,\n score_threshold: float = 0.5,\n max_context_tokens: int = 4096,\n ) -> None:\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model` | `Model` | 用于评分的语言模型 |\n| `score_threshold` | `float` | 评分阈值，默认0.5 |\n| `max_context_tokens` | `int` | 最大上下文token数 |\n\n**评分机制**：\n- 使用LLM评估每条记忆与当前查询的相关性\n- 过滤低于阈值的记忆记录\n- 按评分排序并截断至token限制\n\n资料来源：[camel/memories/context_creators/score_based.py]()\n\n## 工作流程\n\n### 记忆写入流程\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant AgentMemories\n participant Memory\n participant Block\n \n Agent->>AgentMemories: 添加新记录\n AgentMemories->>Memory: write(record)\n Memory->>Block: 存储记录\n Block->>Block: 格式化/截断\n Block-->>AgentMemories: 确认写入\n AgentMemories-->>Agent: 写入完成\n```\n\n### 上下文检索流程\n\n```mermaid\nsequenceDiagram\n participant Query\n participant ContextCreator\n participant Memory\n participant Block\n \n Query->>ContextCreator: 生成上下文请求\n ContextCreator->>Memory: read(query)\n Memory->>Block: 检索记录\n Block-->>Memory: 返回候选记录\n Memory-->>ContextCreator: 评分排序\n ContextCreator->>ContextCreator: 过滤和截断\n ContextCreator-->>Query: 返回上下文\n```\n\n## 使用示例\n\n### 基本使用\n\n```python\nfrom camel.memories import AgentMemories, ChatHistoryBlock\nfrom camel.memories.blocks import VectorDBBlock\n\n# 创建记忆块\nchat_history = ChatHistoryBlock(window_size=10)\nvector_store = VectorDBBlock(k=5)\n\n# 组合成Agent记忆\nagent_memories = AgentMemories(\n memories=[chat_history, vector_store]\n)\n\n# 写入对话记录\nagent_memories.memories[0].write(\n ChatHistoryRecord(\n role=\"user\",\n content=\"Hello, how are you?\",\n message_type=RoleType.USER\n )\n)\n\n# 读取记忆\nrecords = agent_memories.memories[0].read()\n```\n\n### 带上下文创建器的使用\n\n```python\nfrom camel.memories import AgentMemories, ContextCreator\nfrom camel.memories.context_creators import ScoreBasedContextCreator\n\n# 创建上下文创建器\ncontext_creator = ScoreBasedContextCreator(\n model=model,\n score_threshold=0.6,\n max_context_tokens=4096\n)\n\n# 创建带上下文的记忆管理\nagent_memories = AgentMemories(\n memories=[chat_history, vector_store],\n context_creator=context_creator\n)\n\n# 生成上下文\ncontext = agent_memories.context_creator.generate_context(\n query=\"What did we discuss about AI?\",\n memories=agent_memories.memories\n)\n```\n\n## 模块导出\n\n`camel/memories/__init__.py`模块导出以下公共接口：\n\n| 导出 | 说明 |\n|------|------|\n| `Memory` | 记忆抽象基类 |\n| `AgentMemories` | Agent记忆管理器 |\n| `ContextCreator` | 上下文创建器基类 |\n| `ChatHistoryRecord` | 聊天历史记录 |\n| `MemoryRecord` | 基础记忆记录 |\n\n资料来源：[camel/memories/__init__.py]()\n\n## 设计模式\n\n记忆系统采用了以下设计模式：\n\n1. **策略模式**：通过ContextCreator接口支持多种上下文生成策略\n2. **组合模式**：AgentMemories组合多个Memory组件统一管理\n3. **工厂模式**：通过参数化配置创建不同类型的存储块\n4. **适配器模式**：统一的Memory接口适配不同后端存储\n\n## 扩展指南\n\n### 自定义记忆块\n\n```python\nfrom camel.memories import Memory, MemoryRecord\n\nclass CustomMemoryBlock(Memory[CustomRecord]):\n def __init__(self, config: CustomConfig) -> None:\n self.config = config\n self._storage = []\n \n @property\n def size(self) -> int:\n return len(self._storage)\n \n def read(self, *args, **kwargs) -> List[CustomRecord]:\n # 实现读取逻辑\n return self._storage\n \n def write(self, *args, **kwargs) -> None:\n # 实现写入逻辑\n pass\n```\n\n### 自定义上下文创建器\n\n```python\nfrom camel.memories import ContextCreator\n\nclass CustomContextCreator(ContextCreator):\n def __init__(self, model: Model) -> None:\n self.model = model\n \n def generate_context(\n self,\n query: str,\n memories: List[Memory]\n ) -> str:\n # 实现自定义上下文生成逻辑\n pass\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：camel-ai/camel\n\n摘要：发现 19 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature Request] Expand WorkforceCallback to support stream chunk events。\n\n## 1. 安装坑 · 来源证据：[Feature Request] Expand WorkforceCallback to support stream chunk events\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature Request] Expand WorkforceCallback to support stream chunk events\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6e53abdf5bc6401d8d9e105ad6bc199f | https://github.com/camel-ai/camel/issues/3676 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：[Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5ca8493db7f140ca97d289664d6eb484 | https://github.com/camel-ai/camel/issues/1043 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：[Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_53427dbbe45a4c2dacf26673addcd0c4 | https://github.com/camel-ai/camel/issues/4045 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 4. 安全/权限坑 · 来源证据：[BUG] Both Bedrock options are broken\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Both Bedrock options are broken\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0dd321222ec44d14aa25d8cde3aeaef9 | https://github.com/camel-ai/camel/issues/4034 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安全/权限坑 · 来源证据：[Feature Request] Add OrcaRouter as a dedicated model platform\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Add OrcaRouter as a dedicated model platform\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9b8e4797fc294e8e8c795de01b5418da | https://github.com/camel-ai/camel/issues/4047 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 能力坑 · 社区讨论暴露的待验证问题：The best open source general AI agent is on !\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：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\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：social_signal:x | ssig_9705a4152aac4e7db1ec2472633ef681 | https://x.com/CamelAIOrg/status/1899069486587593176 | The best open source general AI agent is on !\n\n## 7. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:615510678 | https://github.com/camel-ai/camel | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 来源证据：v0.2.91a2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.2.91a2\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0c6ec0ec1a0a421a9dc7bf0e05814f20 | https://github.com/camel-ai/camel/releases/tag/v0.2.91a2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 来源证据：[Question] About the Deprecation of the `reasoning_content` Field in vLLM\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[Question] About the Deprecation of the `reasoning_content` Field in vLLM\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d44976120f444580a5a9afefb7711f0c | https://github.com/camel-ai/camel/issues/3939 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:615510678 | https://github.com/camel-ai/camel | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:615510678 | https://github.com/camel-ai/camel | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:615510678 | https://github.com/camel-ai/camel | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：v0.2.90\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_aacd3063c35745ea9cf8392274d9c53d | https://github.com/camel-ai/camel/releases/tag/v0.2.90 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：v0.2.90a4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90a4\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2c18897f1147431ea64419fef84398cc | https://github.com/camel-ai/camel/releases/tag/v0.2.90a4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：v0.2.90a5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90a5\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_defae93359fb4942a54fe8deedabdef8 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a5 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：v0.2.90a6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90a6\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a56ec216a5e84c3799b5d1a4a57ed4b3 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a6 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 18. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:615510678 | https://github.com/camel-ai/camel | issue_or_pr_quality=unknown\n\n## 19. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:615510678 | https://github.com/camel-ai/camel | release_recency=unknown\n\n\n",
"markdown_key": "camel",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:615510678",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/camel-ai/camel"
},
{
"evidence_id": "art_1716b42359b64649a65142c90327a91b",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/camel-ai/camel#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "camel 说明书",
"toc": [
"https://github.com/camel-ai/camel 项目说明书",
"目录",
"项目简介",
"项目概述",
"核心设计理念",
"技术架构",
"核心功能特性",
"应用场景",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "4d195355329dd5d023cc9d1b546fcf5e0eb88f8d",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"uv.lock",
"docs/conf.py",
"docs/README.md",
"docs/key_modules/tools.md",
"docs/key_modules/Benchmark.md",
"docs/key_modules/tasks.md",
"docs/key_modules/societies.md",
"docs/key_modules/society.md",
"docs/key_modules/runtimes.md",
"docs/key_modules/browsertoolkit.md",
"docs/key_modules/datagen.md",
"docs/key_modules/memory.md",
"docs/key_modules/terminaltoolkit.md",
"docs/key_modules/messages.md",
"docs/key_modules/retrievers.md",
"docs/key_modules/embeddings.md",
"docs/key_modules/workforce.md",
"docs/key_modules/prompts.md",
"docs/key_modules/models.md",
"docs/key_modules/agents.md",
"docs/key_modules/interpreters.md",
"docs/key_modules/loaders.md",
"docs/key_modules/storages.md",
"docs/mcp/overview.md",
"docs/mcp/camel_toolkits_as_an_mcp_server.md",
"docs/mcp/connecting_existing_mcp_tools.md",
"docs/mcp/mcp_hub.md",
"docs/mcp/export_camel_agent_as_mcp_server.md",
"docs/mcp/camel_agents_as_an_mcp_clients.md",
"docs/mintlify/convert_notebook2mdx.py",
"docs/mintlify/build_api_docs.py",
"docs/mintlify/docs.json",
"docs/reference/camel.loaders.jina_url_reader.md",
"docs/reference/camel.loaders.scrapegraph_reader.md",
"docs/reference/camel.runtimes.daytona_runtime.md",
"docs/reference/camel.toolkits.slack_toolkit.md",
"docs/reference/camel.toolkits.hybrid_browser_toolkit.hybrid_browser_toolkit.md",
"docs/reference/camel.memories.context_creators.score_based.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# hybrid-browser-toolkit-ts - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 hybrid-browser-toolkit-ts 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **AI 研究者或研究型 Agent 构建者**：README 明确围绕研究、实验或论文工作流展开。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.camel/skills/docs-incremental-update/SKILL.md`, `.camel/skills/skill-creator/SKILL.md`, `examples/toolkits/skill_toolkit_example/.camel/skills/code-reviewer/SKILL.md`, `examples/toolkits/skill_toolkit_example/.camel/skills/data-analyzer/SKILL.md` 等 Claim：`clm_0005` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.camel/skills/docs-incremental-update/SKILL.md`, `.camel/skills/skill-creator/SKILL.md`, `examples/toolkits/skill_toolkit_example/.camel/skills/code-reviewer/SKILL.md`, `examples/toolkits/skill_toolkit_example/.camel/skills/data-analyzer/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`camel/toolkits/open_api_specs/biztoc/ai-plugin.json`, `camel/toolkits/open_api_specs/outschool/ai-plugin.json`, `camel/toolkits/open_api_specs/web_scraper/ai-plugin.json` Claim：`clm_0002` unverified 0.25\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 怎么开始\n\n- `pip install camel-ai` 证据：`README.md` Claim：`clm_0006` supported 0.86, `clm_0007` supported 0.86\n- `pip install 'camel-ai[web_tools]'` 证据：`README.md` Claim：`clm_0007` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：仅建议沙盒试装\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：仅建议沙盒试装\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：AI 研究者或研究型 Agent 构建者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.camel/skills/docs-incremental-update/SKILL.md`, `.camel/skills/skill-creator/SKILL.md`, `examples/toolkits/skill_toolkit_example/.camel/skills/code-reviewer/SKILL.md`, `examples/toolkits/skill_toolkit_example/.camel/skills/data-analyzer/SKILL.md` 等 Claim：`clm_0005` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.camel/skills/docs-incremental-update/SKILL.md`, `.camel/skills/skill-creator/SKILL.md`, `examples/toolkits/skill_toolkit_example/.camel/skills/code-reviewer/SKILL.md`, `examples/toolkits/skill_toolkit_example/.camel/skills/data-analyzer/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0006` supported 0.86, `clm_0007` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.camel/skills/docs-incremental-update/SKILL.md`, `.camel/skills/skill-creator/SKILL.md`, `camel/toolkits/open_api_specs/biztoc/ai-plugin.json`, `camel/toolkits/open_api_specs/outschool/ai-plugin.json` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`camel/toolkits/open_api_specs/biztoc/ai-plugin.json`, `camel/toolkits/open_api_specs/outschool/ai-plugin.json`, `camel/toolkits/open_api_specs/web_scraper/ai-plugin.json`\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.camel/skills/docs-incremental-update/SKILL.md`, `.camel/skills/skill-creator/SKILL.md`, `camel/toolkits/open_api_specs/biztoc/ai-plugin.json`, `camel/toolkits/open_api_specs/outschool/ai-plugin.json` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `camel/toolkits/open_api_specs/biztoc/ai-plugin.json`, `camel/toolkits/open_api_specs/outschool/ai-plugin.json`, `camel/toolkits/open_api_specs/web_scraper/ai-plugin.json`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0008` inferred 0.45\n- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`camel/toolkits/open_api_specs/biztoc/ai-plugin.json`, `camel/toolkits/open_api_specs/outschool/ai-plugin.json`, `camel/toolkits/open_api_specs/web_scraper/ai-plugin.json` Claim：`clm_0009` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0010` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.camel/skills/docs-incremental-update/SKILL.md`, `.camel/skills/skill-creator/SKILL.md`, `examples/toolkits/skill_toolkit_example/.camel/skills/code-reviewer/SKILL.md`, `examples/toolkits/skill_toolkit_example/.camel/skills/data-analyzer/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`camel/toolkits/open_api_specs/biztoc/ai-plugin.json`, `camel/toolkits/open_api_specs/outschool/ai-plugin.json`, `camel/toolkits/open_api_specs/web_scraper/ai-plugin.json`\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 上下文规模\n\n- 文件总数：2037\n- 重要文件覆盖：40/2037\n- 证据索引条目：80\n- 角色 / Skill 条目：5\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 hybrid-browser-toolkit-ts 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 hybrid-browser-toolkit-ts 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 hybrid-browser-toolkit-ts 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 5 个角色 / Skill / 项目文档条目。\n\n- **docs-incremental-update**（skill）： 激活提示：当用户任务与“docs-incremental-update”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.camel/skills/docs-incremental-update/SKILL.md`\n- **skill-creator**（skill）：Guide for creating effective skills. Use when creating a new skill or updating an existing skill that extends agent capabilities with specialized knowledge, workflows, or tool integrations. 激活提示：当用户任务与“skill-creator”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.camel/skills/skill-creator/SKILL.md`\n- **code-reviewer**（skill）：Review code for quality, bugs, and improvements. Use when user wants code review or quality assessment. 激活提示：当用户任务与“code-reviewer”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`examples/toolkits/skill_toolkit_example/.camel/skills/code-reviewer/SKILL.md`\n- **data-analyzer**（skill）：Analyze datasets and extract insights. Use when user needs to understand data patterns, statistics, or trends. 激活提示：当用户任务与“data-analyzer”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`examples/toolkits/skill_toolkit_example/.camel/skills/data-analyzer/SKILL.md`\n- **report-writer**（skill）：Generate professional reports from analysis results. Use when user needs to create formatted documents summarizing findings. 激活提示：当用户任务与“report-writer”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`examples/toolkits/skill_toolkit_example/.camel/skills/report-writer/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **How to update the documentation**（documentation）：Helpful article here https://towardsdatascience.com/documenting-python-code-with-sphinx-554e1d6c4f6d . 证据：`docs/README.md`\n- **Concept**（documentation）：Agents in CAMEL are autonomous entities capable of performing specific tasks through interaction with language models and other components. Each agent is designed with a particular role and capability, allowing them to work independently or collaboratively to achieve complex goals. 证据：`docs/key_modules/agents.md`\n- **docs code map tooling**（documentation）：This folder keeps Mintlify documentation in sync with CAMEL source code. 证据：`docs/mintlify/scripts/docs_sync/README.md`\n- **Install CAMEL with Docker**（documentation）：Docker offers an easy way to create a consistent and isolated virtual environment, containers, for setting up the dependencies of CAMEL. This guide will show you how to quickly set up CAMEL, run the examples, and also develop on it, with Docker. 证据：`.container/README.md`\n- **Readme**（documentation）：! Documentation docs-image docs-url ! Discord discord-image discord-url ! X x-image x-url ! Reddit reddit-image reddit-url ! Wechat wechat-image wechat-url ! Hugging Face huggingface-image huggingface-url ! Star star-image star-url ! Package License package-license-image package-license-url ! PyPI Download package-download-image package-download-url ! join-us-image join-us 证据：`README.md`\n- **CAMEL Model Context Protocol MCP Server**（documentation）：CAMEL Model Context Protocol MCP Server 证据：`services/README.md`\n- **Agents app showcases Role Playing API as a Gradio web app**（documentation）：Agents app showcases Role Playing API as a Gradio web app 证据：`apps/agents/README.md`\n- **Data Explorer tool to browse Camel dataset**（documentation）：Data Explorer tool to browse Camel dataset 证据：`apps/data_explorer/README.md`\n- **Mock Website Benchmarks for Web Agent Testing**（documentation）：Mock Website Benchmarks for Web Agent Testing 证据：`camel/benchmarks/mock_website/README.md`\n- **Ubuntu Docker Runtime Example**（documentation）：This example demonstrates how to use the CAMEL framework with Docker runtime in an Ubuntu environment, including role-playing capabilities with the Qwen model. 证据：`examples/runtimes/ubuntu_docker_runtime/README.md`\n- **CAMEL-AI with ACI Integration Examples**（documentation）： B[Agent 管理层]\n B --> C[工具包 Toolkit 层]\n B --> D[模型交互层]\n B --> E[运行时 Runtime 层]\n C --> F[Browser Toolkit]\n C --> G[MCP 集成]\n C --> H[第三方服务集成]\n D --> I[OpenAI API]\n D --> J[Gemini API]\n D --> K[Mistral API]\n E --> L[Docker Runtime]\n E --> M[云端 Runtime]\n```\n\n### 核心组件说明\n\n| 组件名称 | 功能描述 | 依赖关系 |\n|---------|---------|---------|\n| Agent 管理层 | 管理代理的创建、生命周期和状态 | 依赖模型交互层 |\n| Toolkit 层 | 提供各类工具和MCP集成能力 | 被Agent管理层调用 |\n| 模型交互层 | 统一封装多种大语言模型API | 被Agent管理层使用 |\n| 运行时层 | 提供容器化和云端执行环境 | 支撑整个框架运行 |\n\n资料来源：[examples/usecases/aci_mcp/README.md]()\n\n## 核心功能特性\n\n### 1. 角色扮演系统\n\nCAMEL的角色扮演系统允许开发者为每个代理定义独特的角色属性，包括专业领域、行为模式、沟通风格等。这种设计使得代理能够扮演各种角色，如研究员、开发者、审核员等，形成完整的团队协作结构。\n\n角色定义支持丰富的配置选项，包括系统提示词（System Prompt）、温度参数、工具权限等。框架提供了便捷的API来创建和管理这些角色，使得复杂的多代理场景配置变得简单直观。\n\n### 2. 工具集成生态\n\nCAMEL建立了一个丰富的工具集成生态系统，为代理提供了强大的外部能力支持。\n\n#### 主要工具包类型\n\n| 工具类别 | 功能描述 | 典型应用场景 |\n|---------|---------|--------------|\n| Browser Toolkit | 浏览器自动化操作 | 网页内容抓取、表单填写 |\n| MCP 集成 | 模型上下文协议支持 | 标准化工具调用 |\n| PPTX Toolkit | PowerPoint 生成 | 自动演示文稿制作 |\n| OCR Toolkit | 文字识别 | 图像和PDF内容提取 |\n| 视频处理工具 | 音视频内容分析 | YouTube 内容分析 |\n\n资料来源：[examples/usecases/pptx_toolkit_usecase/README.md]()\n\n### 3. MCP 服务器支持\n\nCAMEL全面支持 Anthropic 的模型上下文协议（Model Context Protocol），这使得框架能够与各种外部服务和工具进行标准化集成。通过MCP协议，开发者可以轻松地将CAMEL代理与外部系统连接，扩展代理的能力边界。\n\n框架提供了便捷的MCP服务器配置机制，支持本地和远程服务器的配置和管理。开发者可以通过JSON配置文件定义多个MCP服务器，框架会自动处理服务器连接和消息路由。\n\n#### MCP 集成架构\n\n```mermaid\ngraph LR\n A[CAMEL Agent] <--> B[MCP Client]\n B <--> C[MCP Server]\n C --> D[Cloudflare 服务]\n C --> E[Airbnb 服务]\n C --> F[ACI.dev 服务]\n C --> G[自定义服务]\n```\n\n资料来源：[examples/usecases/airbnb_mcp/README.md]()\n\n### 4. 多平台集成\n\nCAMEL框架展示了与多种第三方平台的深度集成能力。\n\n#### 支持的平台类型\n\n| 平台名称 | 集成方式 | 功能特性 |\n|---------|---------|---------|\n| Firecrawl | API 集成 | 网页抓取和数据提取 |\n| YouTube | 视频处理 | 字幕提取、OCR分析 |\n| Mistral | OCR 处理 | PDF和图像文字识别 |\n| Cloudflare | MCP 协议 | 文档查询、Radar数据、浏览器 |\n| Airbnb | MCP 协议 | 房源搜索和信息查询 |\n| GitHub | API 集成 | 代码仓库对话和分析 |\n\n资料来源：[examples/usecases/chat_with_youtube/README.md]()\n\n## 应用场景\n\n### 代码问题求解\n\nCAMEL可以用于自动解决编程问题。通过整合网络搜索和代码分析能力，多个代理协作完成从问题理解到解决方案生成的完整流程。\n\n### 学术研究报告生成\n\n多代理系统可以协同完成复杂的研究任务：研究员代理负责收集资料，分析师代理处理数据，作家代理生成报告内容，审核代理进行质量把控。这种流水线式的协作模式大大提高了研究效率。\n\n### 自动化演示文稿制作\n\nCAMEL的PPTX Toolkit能够根据用户提供的topic自动生成专业的演示文稿，支持多种幻灯片类型，包括标题页、步骤说明、表格对比、图片展示等。\n\n### 智能网页交互\n\n通过Browser Toolkit和Cloudflare MCP集成，CAMEL代理能够执行复杂的网页操作，包括表单填写、内容搜索、数据提取等任务。\n\n### 视频内容分析\n\n整合YouTube视频处理能力和OCR技术，代理可以分析视频内容、提取字幕信息、回答关于视频内容的问题。\n\n## 部署方式\n\n### Docker 运行时环境\n\nCAMEL支持Docker容器化部署，提供了完整的Dockerfile和运行环境管理脚本。开发者可以快速构建包含CAMEL框架及其依赖的容器镜像，实现一致的开发部署体验。\n\n### 云端服务集成\n\n框架设计了云端运行时支持，能够在远程服务器上执行代理任务。这种设计特别适合需要大量计算资源的场景，以及需要长时间运行的任务。\n\n### 本地开发环境\n\n开发者可以直接在本地Python环境中安装CAMEL包进行开发和测试。框架支持虚拟环境管理，便于项目隔离和依赖管理。\n\n## 开发工具支持\n\n### Streamlit 应用模板\n\nCAMEL提供了多个基于Streamlit的示例应用，展示了如何快速构建交互式的多代理应用界面。这些应用模板覆盖了从简单的聊天界面到复杂的数据分析仪表盘等场景。\n\n### Gradio 部署支持\n\n框架支持将代理应用部署到Hugging Face Spaces等Gradio托管平台，提供了相应的部署脚本和配置指南。\n\n### 数据探索工具\n\nCAMEL附带的数据浏览器工具允许开发者可视化探索CAMEL框架生成的各类数据集，便于调试和结果分析。\n\n## 技术依赖\n\nCAMEL框架的核心依赖包括：\n\n- **Python 版本**：3.10 或 3.12\n- **核心包**：streamlit、rich、pydantic\n- **AI 模型**：OpenAI GPT系列、Google Gemini、Mistral、各类开源模型\n- **工具库**：yt-dlp（视频处理）、ffmpeg（音视频处理）、tesseract（OCR）\n\n资料来源：[examples/usecases/mistral_OCR/README.md]()\n\n## 项目组织结构\n\n```\ncamel/\n├── camel/ # 核心框架代码\n│ ├── toolkits/ # 工具包实现\n│ ├── agents/ # 代理实现\n│ └── runtime/ # 运行时支持\n├── examples/ # 示例应用\n│ ├── usecases/ # 各类使用场景\n│ └── runtimes/ # 运行时示例\n├── services/ # 微服务组件\n├── apps/ # 应用程序示例\n└── README.md # 项目文档\n```\n\n## 总结\n\nCAMEL作为一个开源的多智能体推理框架，提供了完整的解决方案来构建基于大语言模型的智能代理系统。其核心优势包括：\n\n- **灵活的代理配置**：支持自定义角色和协作模式\n- **丰富的工具集成**：覆盖浏览器自动化、MCP协议、文档处理等多个领域\n- **多样的部署选项**：支持Docker、本地和云端部署\n- **活跃的社区生态**：持续更新的示例和最佳实践\n\nCAMEL的设计理念和实现方案为开发者提供了一个强大的基础平台，使得构建复杂的多代理应用变得更加简单和高效。无论是学术研究还是工业应用，CAMEL都展现出了广泛的适用性和巨大的发展潜力。\n\n---\n\n\n\n## 快速入门指南\n\n### 相关页面\n\n相关主题：[项目简介](#page-overview), [智能体(Agents)](#page-agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/get_started/installation.md](https://github.com/camel-ai/camel/blob/main/docs/get_started/installation.md)\n- [docs/get_started/setup.md](https://github.com/camel-ai/camel/blob/main/docs/get_started/setup.md)\n- [.env.example](https://github.com/camel-ai/camel/blob/main/.env.example)\n- [examples/agents/create_chat_agent.py](https://github.com/camel-ai/camel/blob/main/examples/agents/create_chat_agent.py)\n- [examples/usecases/codeforces_question_solver/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/codeforces_question_solver/README.md)\n- [examples/usecases/multi_agent_research_assistant/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/multi_agent_research_assistant/README.md)\n- [examples/usecases/aci_mcp/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/aci_mcp/README.md)\n \n\n# 快速入门指南\n\nCAMEL（Communicative Agents Framework）是一个多智能体协作框架，旨在通过角色扮演和任务分解实现复杂的 AI 驱动工作流。本指南将帮助您快速了解如何安装、配置并运行 CAMEL 项目。\n\n## 环境要求\n\n| 要求 | 最低版本 | 推荐版本 |\n|------|----------|----------|\n| Python | 3.10 | 3.12 |\n| Docker | 最新稳定版 | 最新稳定版 |\n| pip | 22.0+ | 最新 |\n\nCAMEL 支持多种运行环境，包括本地 Python 环境、Docker 容器以及云端部署。资料来源：[docs/get_started/installation.md](https://github.com/camel-ai/camel/blob/main/docs/get_started/installation.md)\n\n## 安装方式\n\n### 方式一：pip 直接安装\n\n```bash\npip install camel-ai\n```\n\n### 方式二：安装完整依赖（含所有工具包）\n\n```bash\npip install camel-ai[all]\n```\n\n### 方式三：从源码安装\n\n```bash\ngit clone https://github.com/camel-ai/camel.git\ncd camel\npip install -e .\n```\n\n资料来源：[docs/get_started/installation.md](https://github.com/camel-ai/camel/blob/main/docs/get_started/installation.md)\n\n## 环境配置\n\n### 配置环境变量\n\nCAMEL 使用 `.env` 文件管理 API 密钥和其他配置。创建项目根目录下的 `.env` 文件：\n\n```env\nOPENAI_API_KEY=your_openai_api_key\nFIRECRAWL_API_KEY=your_firecrawl_api_key\nACI_API_KEY=your_aci_api_key\nGEMINI_API_KEY=your_gemini_api_key\n```\n\n> 注意：确保将 `.env` 文件加入 `.gitignore`，避免密钥泄露。资料来源：[.env.example](https://github.com/camel-ai/camel/blob/main/.env.example)\n\n### 模型配置\n\nCAMEL 支持多种模型平台：\n\n| 平台 | 模型类型 | 配置方式 |\n|------|----------|----------|\n| OpenAI | GPT-4, GPT-3.5 | API Key |\n| Google Gemini | Gemini Pro | GEMINI_API_KEY |\n| ModelScope | Qwen 系列 | ModelScope API |\n| OpenAI 兼容 | 自定义模型 | URL + API Key |\n\n资料来源：[examples/runtimes/ubuntu_docker_runtime/README.md](https://github.com/camel-ai/camel/blob/main/examples/runtimes/ubuntu_docker_runtime/README.md)\n\n## 基础使用示例\n\n### 创建对话代理\n\nCAMEL 的核心是 `ChatAgent`，用于创建可进行对话交互的 AI 代理：\n\n```python\nfrom camel.agents import ChatAgent\nfrom camel.configs import ChatAgentConfig\nfrom camel.models import ModelFactory\nfrom camel.types import ModelPlatformType\n\n# 配置模型\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=\"gpt-4o\"\n)\n\n# 创建代理配置\nagent_config = ChatAgentConfig()\n\n# 创建代理实例\nagent = ChatAgent(\n model=model,\n agent_config=agent_config\n)\n\n# 运行对话\nresponse = agent.step(\"你好，请介绍一下你自己\")\nprint(response.msgs[0].content)\n```\n\n资料来源：[examples/agents/create_chat_agent.py](https://github.com/camel-ai/camel/blob/main/examples/agents/create_chat_agent.py)\n\n### 多智能体协作\n\nCAMEL 支持多智能体角色扮演和协作：\n\n```python\nfrom camel.agents import RolePlayingAgent\nfrom camel.models import ModelFactory\nfrom camel.types import ModelPlatformType, RoleType\n\n# 创建助手指务\nassistant_agent = RolePlayingAgent(\n role_type=RoleType.ASSISTANT,\n model=model,\n)\n\n# 创建用户代理\nuser_agent = RolePlayingAgent(\n role_type=RoleType.USER,\n model=model,\n)\n```\n\n## 运行示例应用\n\n### 使用 Streamlit 运行应用\n\nCAMEL 提供了多个示例应用，使用 Streamlit 作为前端界面：\n\n```bash\n# 进入示例目录\ncd examples/usecases/multi_agent_research_assistant\n\n# 安装依赖\npip install -r requirements.txt\n\n# 配置环境变量\ncp .env.template .env\n# 编辑 .env 文件填入 API 密钥\n\n# 启动应用\nstreamlit run app.py\n```\n\n资料来源：[examples/usecases/multi_agent_research_assistant/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/multi_agent_research_assistant/README.md)\n\n### 使用 Docker 运行\n\n对于需要隔离环境的场景，可以使用 Docker：\n\n```bash\ncd examples/runtimes/ubuntu_docker_runtime\n\n# 构建镜像\nchmod +x manage_camel_docker.sh\n./manage_camel_docker.sh build\n\n# 验证镜像\ndocker images | grep my-camel\n```\n\n资料来源：[examples/runtimes/ubuntu_docker_runtime/README.md](https://github.com/camel-ai/camel/blob/main/examples/runtimes/ubuntu_docker_runtime/README.md)\n\n## 工作流程概览\n\n```mermaid\ngraph TD\n A[安装 CAMEL] --> B[配置环境变量]\n B --> C[选择运行方式]\n C --> D[本地 Python]\n C --> E[Streamlit 应用]\n C --> F[Docker 容器]\n D --> G[运行示例代码]\n E --> H[启动 Web 服务]\n F --> I[容器内运行]\n G --> J[开发自定义代理]\n H --> J\n I --> J\n J --> K[集成到项目]\n```\n\n## 常见应用场景\n\n| 场景 | 说明 | 示例目录 |\n|------|------|----------|\n| 多智能体研究助手 | 自动生成研究报告 | multi_agent_research_assistant |\n| 代码问题求解 | Codeforces/LeetCode | codeforces_question_solver |\n| 文档生成 | PowerPoint 演示文稿 | pptx_toolkit_usecase |\n| OCR 文档处理 | PDF/图片文字提取 | mistral_OCR |\n| MCP 集成 | 第三方服务集成 | aci_mcp, cloudfare_mcp_camel |\n\n资料来源：[examples/usecases/codeforces_question_solver/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/codeforces_question_solver/README.md)\n\n## 下一步\n\n- 深入阅读 [安装指南](./installation.md) 了解详细的安装选项\n- 查看 [设置文档](./setup.md) 了解高级配置\n- 探索 [示例项目](../examples/) 获取更多使用案例\n- 参考 [API 文档](../api/) 了解完整的接口说明\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 模块导入错误 | 确保已安装 `camel-ai==0.2.61` 或最新版本 |\n| API Key 错误 | 检查 `.env` 文件中的密钥是否正确 |\n| Docker 构建失败 | 确保 Docker 已启动并具有足够权限 |\n| Python 版本不兼容 | 使用 Python 3.10 或 3.12 |\n\n> 提示：使用 `--debug` 模式运行可以获得详细的日志输出，便于问题排查。资料来源：[examples/usecases/airbnb_mcp/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/airbnb_mcp/README.md)\n\n---\n\n\n\n## 系统架构设计\n\n### 相关页面\n\n相关主题：[项目简介](#page-overview), [智能体(Agents)](#page-agents), [模型集成(Models)](#page-models)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/types/enums.py](https://github.com/camel-ai/camel/blob/main/camel/types/enums.py)\n- [camel/schemas/base.py](https://github.com/camel-ai/camel/blob/main/camel/schemas/base.py)\n- [camel/messages/base.py](https://github.com/camel-ai/camel/blob/main/camel/messages/base.py)\n- [camel/utils/commons.py](https://github.com/camel-ai/camel/blob/main/camel/utils/commons.py)\n- [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)\n- [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)\n- [examples/usecases/multi_agent_research_assistant/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/multi_agent_research_assistant/README.md)\n- [examples/runtimes/ubuntu_docker_runtime/README.md](https://github.com/camel-ai/camel/blob/main/examples/runtimes/ubuntu_docker_runtime/README.md)\n \n\n# 系统架构设计\n\n## 概述\n\nCAMEL（Communicative Agents for Multi-Agent Learning）是一个多智能体协作框架，旨在实现自主协作的AI智能体系统。该框架的核心设计理念是通过角色扮演和任务分解，让多个AI智能体能够自主协作完成复杂任务。\n\n系统架构采用模块化设计，涵盖核心类型系统、消息处理、服务层、工具包集成以及运行时环境等多个层次。这种分层架构确保了系统的可扩展性、可维护性和灵活性。\n\n## 核心架构层次\n\nCAMEL系统的整体架构可以分为以下几个核心层次：\n\n```mermaid\ngraph TD\n A[应用层] --> B[服务层]\n B --> C[核心框架层]\n C --> D[工具包层]\n D --> E[运行时层]\n \n A1[Apps] --> A\n A2[Examples] --> A\n B1[Agent Services] --> B\n B2[MCP Servers] --> B\n C1[Types/Enums] --> C\n C2[Schemas] --> C\n C3[Messages] --> C\n C4[Utils] --> C\n D1[Browser Toolkit] --> D\n D2[其他Toolkits] --> D\n E1[Docker Runtime] --> E\n E2[Python Runtime] --> E\n```\n\n## 类型系统与枚举定义\n\n### 枚举类型架构\n\n类型系统是整个框架的基础，定义了框架内部使用的各种枚举类型和常量。这些枚举类型贯穿于整个框架的各个模块，确保了类型安全性和一致性。\n\n枚举模块定义了智能体类型、模型类型、消息角色、任务状态等核心概念。框架使用这些枚举来规范化各个模块之间的数据交互和状态管理。\n\n### 基础类型定义\n\n基础类型定义了框架中使用的核心数据结构，包括智能体配置、模型参数、工具定义等。这些类型为上层的Schema和Message系统提供了类型支撑。\n\n## Schema系统\n\n### 基础Schema架构\n\nSchema系统是CAMEL框架的核心数据模型层。它定义了智能体、任务、消息等核心实体 的数据结构规范。基础Schema类提供了通用的数据验证和序列化功能，确保数据的一致性和完整性。\n\n### Schema组件关系\n\n```mermaid\ngraph LR\n A[BaseSchema] --> B[AgentSchema]\n A --> C[TaskSchema]\n A --> D[ToolSchema]\n \n B --> E[角色定义]\n B --> F[模型配置]\n B --> G[系统提示]\n \n C --> H[任务描述]\n C --> I[任务状态]\n C --> J[任务结果]\n \n D --> K[工具名称]\n D --> L[工具参数]\n D --> M[工具描述]\n```\n\n## 消息系统\n\n### 消息类型与结构\n\n消息系统是智能体之间通信的核心机制。框架定义了多种消息类型，包括用户消息、助手消息、系统消息等。每种消息类型都有其特定的用途和处理流程。\n\n消息基类定义了消息的基本结构，包括消息ID、内容、时间戳、发送者、接收者等字段。消息系统还支持消息的嵌套和引用，使得复杂的对话结构能够被正确表示和处理。\n\n### 消息流转机制\n\n```mermaid\ngraph TD\n A[User Message] --> B[Message Handler]\n B --> C{Message Type}\n C -->|Agent Message| D[Agent Processing]\n C -->|System Message| E[System Processing]\n C -->|Tool Message| F[Tool Processing]\n \n D --> G[Response Generation]\n E --> H[System Response]\n F --> I[Tool Execution]\n \n G --> J[Message Queue]\n H --> J\n I --> J\n \n J --> K[Message History]\n```\n\n## 工具包层\n\n### 浏览器工具包架构\n\n混合浏览器工具包是CAMEL框架中功能强大的工具之一，它提供了浏览器自动化能力。该工具包采用TypeScript实现，提供了完整的浏览器会话管理功能。\n\n浏览器工具包的核心组件包括浏览器会话管理、元素定位与交互、页面快照与差异检测、配置文件加载等模块。这些组件协同工作，实现了类似Playwright的浏览器自动化功能。\n\n### 配置系统\n\n浏览器工具包使用TypeScript类型定义配置文件结构，支持以下核心配置项：\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| headless | boolean | true | 是否无头模式运行 |\n| stealth | StealthConfig | - | 反检测配置 |\n| navigationTimeout | number | 30000 | 导航超时时间（毫秒） |\n| networkIdleTimeout | number | 5000 | 网络空闲超时（毫秒） |\n| screenshotTimeout | number | 15000 | 截图超时时间（毫秒） |\n| pageStabilityTimeout | number | 1500 | 页面稳定检测超时 |\n\n反检测配置进一步细分为用户代理、视口尺寸、语言设置等参数，确保浏览器行为尽可能接近真实用户。资料来源：[camel/toolkits/hybrid_browser_toolkit/ts/src/config-loader.ts:1-50]()\n\n### 元素交互机制\n\n浏览器工具包实现了智能的元素定位和交互机制。当页面元素发生动态变化时，系统能够自动检测并定位新的元素。交互过程包括以下步骤：\n\n1. 接收交互指令和目标元素引用\n2. 获取当前页面快照\n3. 尝试在快照中定位目标元素\n4. 如果定位失败，检测页面变化\n5. 根据页面差异推断新元素位置\n6. 执行交互操作\n\n```mermaid\ngraph TD\n A[Fill Interaction] --> B[Find Element by Ref]\n B --> C{Found?}\n C -->|Yes| D[Check if Input/Textarea]\n C -->|No| E[Wait for Page Diff]\n D --> F{Fillable?}\n F -->|Yes| G[Execute Fill]\n F -->|No| H[Search by Placeholder]\n E --> I[Get New Element]\n I --> D\n G --> J[Check for Dropdowns]\n H --> D\n J --> K[Return Result]\n```\n\n浏览器会话模块负责维护页面的DOM快照，并通过快照差异检测来跟踪页面动态变化。这种机制特别适用于处理SPA（单页应用）和动态加载内容的场景。资料来源：[camel/toolkits/hybrid_browser_toolkit/ts/src/browser-session.ts:1-80]()\n\n## 服务层架构\n\n### Agent服务\n\nAgent服务是框架的核心服务层，负责管理智能体的生命周期和任务执行。服务层提供了统一的接口来创建、配置和调度智能体任务。\n\n服务层支持多种运行时环境，包括Python原生运行时和Docker容器运行时。Docker运行时特别适用于需要隔离执行环境的场景，例如需要特定依赖或系统配置的任务。\n\n### MCP服务器集成\n\n模型上下文协议（MCP）服务器集成允许CAMEL框架连接外部工具和服务。框架通过配置文件管理MCP服务器的连接，支持动态添加和移除服务器。\n\nMCP服务器配置结构如下：\n\n```json\n{\n \"mcpServers\": {\n \"server_name\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@package/mcp-server\"]\n }\n }\n}\n```\n\n支持的MCP服务器类型包括：\n\n| 服务器类型 | 用途 | 配置方式 |\n|------------|------|----------|\n| Airbnb | 房源搜索与预订 | npx命令 |\n| Cloudflare | 文档查询、雷达数据、浏览器 | SSE远程 |\n| ACI | 应用集成与自动化 | API调用 |\n| Firecrawl | 网页抓取与数据提取 | API调用 |\n\n## 应用层组件\n\n### 应用目录结构\n\nCAMEL框架的应用层包含多个展示应用和工具应用，结构清晰，便于扩展和维护。\n\n典型应用目录结构：\n\n```\napps/\n├── agents/ # 角色扮演API的Gradio演示应用\n├── data_explorer/ # 数据集浏览工具\n└── README.md\n\nexamples/\n├── usecases/ # 各场景使用案例\n│ ├── multi_agent_research_assistant/\n│ ├── codeforces_question_solver/\n│ ├── chat_with_github/\n│ ├── pptx_toolkit_usecase/\n│ ├── mistral_ocr/\n│ └── ...\n└── runtimes/ # 运行时环境示例\n └── ubuntu_docker_runtime/\n```\n\n### 多智能体研究助手\n\n多智能体研究助手是一个完整的研究报告生成应用，展示了CAMEL框架在复杂任务中的应用能力。该应用整合了多个智能体角色：\n\n- **研究者智能体**：负责搜索学术论文和最新新闻\n- **作者智能体**：负责撰写和编辑报告内容\n- **可视化智能体**：可选，负责生成配图\n\n应用流程：\n\n1. 用户输入研究主题\n2. 研究者智能体搜索相关信息\n3. 聚合信息传递给作者智能体\n4. 生成完整报告并保存\n5. 可选：生成配图并准备社交媒体内容\n\n资料来源：[examples/usecases/multi_agent_research_assistant/README.md:1-50]()\n\n## 运行时环境\n\n### Docker运行时\n\nDocker运行时环境为框架提供了隔离、可复现的执行环境。该环境特别适用于需要特定系统依赖或需要避免环境冲突的场景。\n\nDocker运行时架构包括：\n\n- **Dockerfile**：定义运行时环境配置\n- **管理脚本**：自动化构建和容器管理\n- **Python客户端**：与Docker容器内的服务通信\n\n```mermaid\ngraph TD\n A[Host Python Client] --> B[Docker Container]\n B --> C[CAMEL Runtime]\n B --> D[API Server]\n C --> E[Model Services]\n D --> F[REST API]\n \n A -->|RPC/API| F\n```\n\n### 运行时配置\n\n运行时支持多种模型平台配置，包括OpenAI兼容模型、本地模型等。配置示例：\n\n```python\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI_COMPATIBLE_MODEL,\n model_type=\"Qwen/Qwen2.5-72B-Instruct\",\n url='https://api-inference.modelscope.cn/v1/'\n)\n```\n\n资料来源：[examples/runtimes/ubuntu_docker_runtime/README.md:1-80]()\n\n## 工具包集成\n\n### 工具包类型概览\n\nCAMEL框架提供了丰富的工具包集成，涵盖多个领域的自动化能力：\n\n| 工具包 | 功能 | 依赖 |\n|--------|------|------|\n| HybridBrowserToolkit | 浏览器自动化 | Playwright |\n| PPTXToolkit | PowerPoint生成 | python-pptx |\n| 图像生成工具包 | AI图像生成 | DALL·E/Pexels API |\n| OCR工具包 | 文档识别 | Mistral OCR |\n| 搜索工具包 | 网络信息检索 | Firecrawl |\n\n### 工具包使用模式\n\n工具包通过统一的接口集成到智能体系统中。每个工具包都定义了清晰的能力边界和参数规范，智能体可以根据任务需求选择合适的工具。\n\n工具调用流程：\n\n1. 任务分析：智能体分析任务需求\n2. 工具选择：从可用工具包中选择合适工具\n3. 参数准备：根据工具规范准备调用参数\n4. 执行调用：通过统一接口执行工具\n5. 结果处理：解析返回结果并继续任务\n\n## 扩展机制\n\n### 定制化配置\n\nCAMEL框架支持通过配置文件定制各种行为：\n\n- **智能体配置**：修改`agent_config.py`中的模型参数和系统消息\n- **工具配置**：通过`mcp_servers_config.json`管理外部工具连接\n- **环境配置**：通过`.env`文件管理API密钥和运行时参数\n\n### 自定义工具包\n\n开发者可以通过继承基础工具包类来创建自定义工具包：\n\n```python\nclass CustomToolkit(BaseToolkit):\n def __init__(self, config: CustomConfig):\n super().__init__()\n self.config = config\n \n def get_tools(self) -> List[FunctionCallingRecord]:\n return [\n FunctionCallingRecord(func=self.custom_function)\n ]\n```\n\n## 总结\n\nCAMEL框架的架构设计体现了多智能体系统的核心原则：\n\n- **模块化设计**：各层职责清晰，便于维护和扩展\n- **类型安全**：通过TypeScript和Python类型系统确保代码质量\n- **灵活集成**：通过MCP和工具包机制支持多种外部服务\n- **运行时隔离**：Docker支持确保环境一致性\n- **配置驱动**：通过配置文件实现行为定制\n\n这种架构使得开发者能够快速构建复杂的多智能体应用，同时保持代码的可维护性和可扩展性。\n\n---\n\n\n\n## 智能体(Agents)\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-architecture), [模型集成(Models)](#page-models), [工具集(Toolkits)](#page-toolkits), [记忆系统(Memory)](#page-memory)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/agents/base.py](https://github.com/camel-ai/camel/blob/main/camel/agents/base.py)\n- [camel/agents/chat_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/chat_agent.py)\n- [camel/agents/critic_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/critic_agent.py)\n- [camel/agents/embodied_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/embodied_agent.py)\n- [camel/agents/repo_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/repo_agent.py)\n- [camel/agents/task_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/task_agent.py)\n- [camel/agents/_types.py](https://github.com/camel-ai/camel/blob/main/camel/agents/_types.py)\n \n\n# 智能体(Agents)\n\n## 概述\n\nCAMEL-AI 框架中的智能体(Agents)是实现多智能体协作的核心组件。智能体是具有特定角色、能力和工具的自主实体，能够执行对话、推理、搜索等多样化任务。CAMEL 采用角色扮演(Role-Playing)架构，让不同类型的智能体相互协作完成复杂任务。\n\n智能体系统支持多种部署方式，包括通过 MCP (Model Context Protocol) 服务器提供服务，也可直接集成到 Python 应用中。\n\n## 智能体架构\n\n### 核心组件\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ 智能体系统架构 │\n├─────────────────────────────────────────────────────────┤\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │\n│ │ ChatAgent │ │ CriticAgent │ │ TaskAgent │ │\n│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │\n│ │ │ │ │\n│ ┌──────┴────────────────┴────────────────┴──────┐ │\n│ │ BaseAgent (基类) │ │\n│ └──────────────────────┬────────────────────────┘ │\n│ │ │\n│ ┌──────────────────────┴────────────────────────┐ │\n│ │ AgentMCP Server │ │\n│ └───────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n```\n\n### 智能体类型\n\nCAMEL 框架提供以下核心智能体类型：\n\n| 智能体类型 | 文件位置 | 主要功能 |\n|-----------|---------|---------|\n| **ChatAgent** | `camel/agents/chat_agent.py` | 通用对话智能体，处理对话交互 |\n| **CriticAgent** | `camel/agents/critic_agent.py` | 批评评价智能体，评估和反馈 |\n| **TaskAgent** | `camel/agents/task_agent.py` | 任务规划智能体，分解和执行任务 |\n| **EmbodiedAgent** | `camel/agents/embodied_agent.py` | 具身智能体，与环境交互 |\n| **RepoAgent** | `camel/agents/repo_agent.py` | 仓库分析智能体，处理代码仓库 |\n\n## BaseAgent 基类\n\n所有智能体都继承自 `BaseAgent`，提供核心功能和通用接口。 资料来源：[camel/agents/base.py]()\n\n### 核心特性\n\n- 统一的智能体生命周期管理\n- 消息处理和状态维护\n- 工具调用和结果处理\n- 对话历史记录管理\n\n### 智能体配置\n\n智能体通过配置文件进行定制，包括：\n\n```python\n# 来自 agent_config.py 的配置选项\n@dataclass\nclass AgentConfig:\n name: str # 智能体名称\n model: Model # 使用的模型\n tools: List[Tool] # 可用工具列表\n system_message: str # 系统提示词\n temperature: float = 0.7 # 生成温度\n max_tokens: int = 2048 # 最大 token 数\n```\n\n## ChatAgent 对话智能体\n\n`ChatAgent` 是 CAMEL 框架中最常用的智能体类型，主要负责处理对话交互。 资料来源：[camel/agents/chat_agent.py]()\n\n### 功能特点\n\n- 支持多轮对话\n- 角色扮演能力\n- 工具集成\n- 消息格式化处理\n\n### 使用示例\n\n```python\nfrom camel.agents import ChatAgent\nfrom camel.models import ModelFactory\nfrom camel.types import ModelPlatformType\n\n# 创建模型\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=\"gpt-4\"\n)\n\n# 创建对话智能体\nagent = ChatAgent(\n system_message=\"你是一个乐于助人的AI助手。\",\n model=model\n)\n\n# 执行对话步骤\nresponse = await agent.step(\"你好，请介绍一下你自己\")\n```\n\n## CriticAgent 批评智能体\n\n`CriticAgent` 专门用于评估和反馈，能够分析其他智能体或用户输入的内容并提供改进建议。 资料来源：[camel/agents/critic_agent.py]()\n\n### 应用场景\n\n- 代码审查和反馈\n- 内容质量评估\n- 对话策略优化\n- 任务执行结果验证\n\n## TaskAgent 任务智能体\n\n`TaskAgent` 专注于任务分解和执行规划，能够将复杂任务拆分为可执行的子任务。 资料来源：[camel/agents/task_agent.py]()\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[接收任务] --> B{任务复杂度判断}\n B -->|简单任务| C[直接执行]\n B -->|复杂任务| D[任务分解]\n D --> E[子任务1]\n D --> F[子任务2]\n D --> G[子任务N]\n E --> H[结果汇总]\n F --> H\n G --> H\n H --> I[最终输出]\n```\n\n## EmbodiedAgent 具身智能体\n\n`EmbodiedAgent` 具备与物理或虚拟环境交互的能力，适用于需要实际操作的任务场景。 资料来源：[camel/agents/embodied_agent.py]()\n\n### 工具支持\n\n| 工具类型 | 功能描述 |\n|---------|---------|\n| 浏览器工具 | 网页导航、内容抓取、表单填写 |\n| 文件系统工具 | 读写文件、目录操作 |\n| 命令行工具 | 执行系统命令 |\n| API 工具 | 调用外部服务接口 |\n\n## RepoAgent 仓库智能体\n\n`RepoAgent` 专门用于代码仓库分析和处理，能够理解代码结构、执行代码搜索和代码生成任务。 资料来源：[camel/agents/repo_agent.py]()\n\n### 典型应用\n\n- 代码库理解\n- 文档生成\n- 代码重构建议\n- 仓库结构分析\n\n## MCP 服务器集成\n\nCAMEL 提供了 MCP (Model Context Protocol) 服务器实现，允许通过标准协议与智能体交互。 资料来源：[services/README.md]()\n\n### 可用工具\n\n| 工具名称 | 功能描述 | 参数 |\n|---------|---------|------|\n| `step` | 执行单次对话步骤 | `name`: 智能体名称, `message`: 消息内容 |\n| `reset` | 重置所有智能体状态 | 无 |\n| `set_output_language` | 设置输出语言 | `language`: 语言代码 |\n| `get_agents_info` | 获取所有智能体信息 | 无 |\n| `get_chat_history` | 获取对话历史 | `name`: 智能体名称 |\n| `get_agent_info` | 获取特定智能体详情 | `name`: 智能体名称 |\n| `get_available_tools` | 获取智能体可用工具 | `name`: 智能体名称 |\n\n### 服务器启动\n\n```bash\n# 启动 MCP 服务器\npython services/agent_mcp_server.py\n```\n\n### 客户端配置\n\n连接 MCP 客户端(如 Claude Desktop 或 Cursor)需要提供 JSON 配置：\n\n```json\n{\n \"camel-agents\": {\n \"command\": \"/path/to/your/python\",\n \"args\": [\n \"/path/to/camel/services/agent_mcp_server.py\"\n ],\n \"env\": {\n \"OPENAI_API_KEY\": \"...\",\n \"OPENROUTER_API_KEY\": \"...\",\n \"BRAVE_API_KEY\": \"...\"\n }\n }\n}\n```\n\n## 预配置智能体类型\n\nCAMEL 框架提供三种预配置的智能体类型：\n\n| 智能体类型 | 配置文件 | 能力描述 |\n|-----------|---------|---------|\n| **General Agent** | `agent_config.py` | 通用问答助手，处理各类任务 |\n| **Search Agent** | `agent_config.py` | 网络搜索能力集成 |\n| **Reasoning Agent** | `agent_config.py` | 专门从事推理任务 |\n\n资料来源：[services/README.md]()\n\n## Gradio 应用集成\n\nCAMEL 提供基于 Gradio 的智能体展示应用。 资料来源：[apps/agents/README.md]()\n\n### 快速启动\n\n```bash\npython agents.py --api-key=YOUR-OPENAI-API-KEY\n```\n\n### 部署到 HuggingFace Spaces\n\n1. 在 CAMEL 仓库中完成开发和调试\n2. 为目标提交打标签：`hf_spaces_{X+1}`（X 值需从 HF 仓库同步脚本查询）\n3. 执行 `git push --tags`\n4. 克隆 HF 仓库到本地\n5. 更新标签并运行同步脚本\n6. 提交并推送到 HF\n7. HF 将自动部署应用\n\n## 智能体通信协议\n\n智能体之间通过消息传递进行通信，支持以下消息类型：\n\n| 消息类型 | 用途 | 数据结构 |\n|---------|------|---------|\n| `UserMessage` | 用户输入 | `{role, content}` |\n| `AssistantMessage` | 智能体回复 | `{role, content, tool_calls}` |\n| `SystemMessage` | 系统指令 | `{role, content}` |\n| `ToolMessage` | 工具结果 | `{role, content, tool_call_id}` |\n\n## 类型定义\n\n智能体的核心类型定义位于 `camel/agents/_types.py`。 资料来源：[camel/agents/_types.py]()\n\n### 主要枚举类型\n\n- **AgentType**: 智能体类型枚举\n- **AgentStatus**: 智能体状态枚举\n- **MessageType**: 消息类型枚举\n\n## 配置管理\n\n### 环境变量\n\n| 变量名 | 用途 | 必需 |\n|-------|------|------|\n| `OPENAI_API_KEY` | OpenAI API 密钥 | 是 |\n| `OPENROUTER_API_KEY` | OpenRouter API 密钥 | 否 |\n| `BRAVE_API_KEY` | Brave Search API 密钥 | 否 |\n\n### 自定义配置\n\n通过修改 `agent_config.py` 可以自定义：\n\n- 模型选择和参数\n- 添加新智能体类型\n- 配置工具集\n- 调整系统提示词\n\n## 最佳实践\n\n### 1. 智能体选择\n\n根据任务复杂度选择合适的智能体类型：\n\n- **简单对话**: 使用 `ChatAgent`\n- **需要评估**: 结合 `CriticAgent`\n- **复杂任务**: 使用 `TaskAgent` 进行任务分解\n- **代码仓库操作**: 使用 `RepoAgent`\n\n### 2. 工具配置\n\n```python\n# 推荐的工具配置模式\ntools = [\n SearchTool(api_key=brave_api_key),\n CalculatorTool(),\n # 根据需要添加更多工具\n]\n```\n\n### 3. 错误处理\n\n智能体执行时应捕获并处理以下异常：\n\n- API 调用超时\n- 模型响应格式错误\n- 工具执行失败\n- 上下文长度超限\n\n## 示例应用\n\nCAMEL 仓库提供了多个使用智能体的示例应用：\n\n| 示例名称 | 路径 | 说明 |\n|---------|------|------|\n| 多智能体研究助手 | `examples/usecases/multi_agent_research_assistant/` | 学术研究和报告生成 |\n| Codeforces 问题解决器 | `examples/usecases/codeforces_question_solver/` | 竞赛编程辅助 |\n| GitHub 聊天 | `examples/usecases/chat_with_github/` | 仓库交互 |\n| YouTube 聊天 | `examples/usecases/chat_with_youtube/` | 视频内容分析 |\n\n## 扩展阅读\n\n- [CAMEL 框架核心概念](../core_concepts/)\n- [工具系统(Toolkits)](../toolkits/)\n- [角色扮演(Role-Playing)](../role_playing/)\n- [MCP 协议文档](https://docs.anthropic.com/en/docs/agents-and-tools/mcp)\n\n---\n\n\n\n## 模型集成(Models)\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-architecture), [智能体(Agents)](#page-agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/models/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/models/__init__.py)\n- [camel/models/base_model.py](https://github.com/camel-ai/camel/blob/main/camel/models/base_model.py)\n- [camel/models/model_factory.py](https://github.com/camel-ai/camel/blob/main/camel/models/model_factory.py)\n- [camel/models/model_manager.py](https://github.com/camel-ai/camel/blob/main/camel/models/model_manager.py)\n- [camel/models/openai_model.py](https://github.com/camel-ai/camel/blob/main/camel/models/openai_model.py)\n- [camel/models/anthropic_model.py](https://github.com/camel-ai/camel/blob/main/camel/models/anthropic_model.py)\n- [camel/configs/openai_config.py](https://github.com/camel-ai/camel/blob/main/camel/configs/openai_config.py)\n- [camel/configs/anthropic_config.py](https://github.com/camel-ai/camel/blob/main/camel/configs/anthropic_config.py)\n \n\n# 模型集成(Models)\n\n## 概述\n\nCAMEL-AI 的模型集成模块是整个框架的核心组件之一，负责统一管理和调用各类大语言模型（LLM）。该模块通过抽象层设计，将不同模型提供商的 API 封装为统一接口，使上层应用能够无差别地使用各种模型能力。\n\n模型模块的主要职责包括：\n\n- 提供统一的模型调用接口\n- 支持多种模型平台（OpenAI、Anthropic、兼容 OpenAI 接口的模型等）\n- 管理模型配置和参数\n- 处理模型响应格式化\n- 支持流式输出和非流式输出\n\n资料来源：[camel/models/__init__.py]()\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[用户代码] --> B[ModelFactory]\n B --> C{模型平台类型}\n C -->|OpenAI| D[OpenAIModel]\n C -->|Anthropic| E[AnthropicModel]\n C -->|OpenAI兼容| F[OpenAICompatibleModel]\n D --> G[BaseModel]\n E --> G\n F --> G\n G --> H[模型API调用层]\n H --> I[OpenAI API]\n H --> J[Anthropic API]\n H --> K[第三方兼容API]\n```\n\n### 核心组件关系\n\n```mermaid\nclassDiagram\n class BaseModel {\n <>\n +run() Message\n +run_until_success() Message\n -_roll() None\n }\n \n class OpenAIModel {\n +run() Message\n -_extract_text_from_response()\n }\n \n class AnthropicModel {\n +run() Message\n -_extract_text_from_response()\n }\n \n class ModelFactory {\n +create() BaseModel\n }\n \n class ModelManager {\n +get_model() BaseModel\n +list_models() List~str~\n }\n \n BaseModel <|-- OpenAIModel\n BaseModel <|-- AnthropicModel\n ModelFactory --> BaseModel : creates\n ModelManager --> ModelFactory : uses\n```\n\n资料来源：[camel/models/base_model.py](), [camel/models/model_factory.py](), [camel/models/model_manager.py]()\n\n## 核心组件详解\n\n### BaseModel（基础模型类）\n\n`BaseModel` 是所有模型实现的抽象基类，定义了模型交互的标准接口。\n\n#### 核心方法\n\n| 方法名 | 返回类型 | 说明 |\n|--------|----------|------|\n| `run(messages)` | `Message` | 执行单次模型调用 |\n| `run_until_success(messages)` | `Message` | 循环调用直至成功 |\n| `_roll()` | `None` | 重置模型状态 |\n\n#### 主要属性\n\n| 属性名 | 类型 | 说明 |\n|--------|------|------|\n| `model_type` | `ModelType` | 模型类型枚举 |\n| `model_config_dict` | `Dict[str, Any]` | 模型配置字典 |\n| `url` | `str` | API 端点 URL |\n\n资料来源：[camel/models/base_model.py]()\n\n### ModelFactory（模型工厂）\n\n`ModelFactory` 负责根据配置动态创建模型实例，是接入新模型的统一入口点。\n\n#### 工厂方法签名\n\n```python\n@classmethod\ndef create(\n cls,\n model_platform: \"ModelPlatformType\",\n model_type: \"ModelType\",\n url: Optional[str] = None,\n api_key: Optional[str] = None,\n config_dict: Optional[Dict[str, Any]] = None,\n) -> \"BaseModel\"\n```\n\n#### 参数说明\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `model_platform` | `ModelPlatformType` | 是 | 模型平台类型 |\n| `model_type` | `ModelType` | 是 | 具体模型类型 |\n| `url` | `str` | 否 | API 端点（兼容模式必填） |\n| `api_key` | `str` | 否 | API 密钥 |\n| `config_dict` | `Dict[str, Any]` | 否 | 自定义配置 |\n\n资料来源：[camel/models/model_factory.py]()\n\n### ModelManager（模型管理器）\n\n`ModelManager` 提供模型实例的集中管理和缓存功能。\n\n#### 核心功能\n\n- 管理多个模型实例的生命周期\n- 支持按名称获取已注册的模型\n- 提供模型列表查询接口\n\n资料来源：[camel/models/model_manager.py]()\n\n## 支持的模型平台\n\n### OpenAI 系列\n\nCAMEL 支持完整的 OpenAI 模型体系，包括 GPT-4、GPT-4 Turbo、GPT-3.5 Turbo 等。\n\n#### OpenAIModel 实现\n\n```python\nclass OpenAIModel(BaseModel):\n def __init__(\n self,\n model_type: ModelType,\n model_config_dict: dict,\n api_key: str,\n url: Optional[str] = None,\n ...\n )\n```\n\n#### 支持的模型类型\n\n| 模型类型枚举 | 对应模型 | 说明 |\n|--------------|----------|------|\n| `GPT_4` | gpt-4 | GPT-4 标准版 |\n| `GPT_4_TURBO` | gpt-4-turbo | GPT-4 Turbo |\n| `GPT_4O` | gpt-4o | GPT-4 Omni |\n| `GPT_4O_MINI` | gpt-4o-mini | GPT-4o 迷你版 |\n| `GPT_35_TURBO` | gpt-3.5-turbo | GPT-3.5 Turbo |\n\n资料来源：[camel/models/openai_model.py](), [camel/models/__init__.py]()\n\n### Anthropic 系列\n\nCAMEL 通过 `AnthropicModel` 类支持 Claude 系列模型。\n\n#### AnthropicModel 实现\n\n```python\nclass AnthropicModel(BaseModel):\n def __init__(\n self,\n model_type: ModelType,\n model_config_dict: dict,\n api_key: str,\n ...\n )\n```\n\n#### 支持的 Claude 模型\n\n| 模型类型枚举 | 对应模型 | 说明 |\n|--------------|----------|------|\n| `CLAUDE_3_5_SONNET` | claude-sonnet-4-20250514 | Claude 3.5 Sonnet |\n| `CLAUDE_3_OPUS` | claude-3-opus-20240229 | Claude 3 Opus |\n| `CLAUDE_3_HAIKU` | claude-3-haiku-20240307 | Claude 3 Haiku |\n\n资料来源：[camel/models/anthropic_model.py](), [camel/models/__init__.py]()\n\n### OpenAI 兼容接口\n\nCAMEL 支持任何实现 OpenAI API 兼容接口的模型服务，包括：\n\n- 本地部署模型（如 vLLM、LM Studio）\n- 开源模型服务（如 TogetherAI、Anyscale）\n- 云厂商兼容端点（如阿里云、百度智能云）\n\n通过设置 `ModelPlatformType.OPENAI_COMPATIBLE_MODEL` 并指定 `url` 参数即可接入。\n\n资料来源：[camel/models/model_factory.py]()\n\n## 配置系统\n\n### OpenAI 配置\n\n`OpenAIConfig` 类提供 OpenAI 模型的详细配置选项。\n\n#### 配置参数表\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `temperature` | `float` | `1.0` | 采样温度（0-2） |\n| `max_tokens` | `int` | `4096` | 最大生成token数 |\n| `top_p` | `float` | `1.0` | Top-p 采样 |\n| `n` | `int` | `1` | 生成数量 |\n| `stop` | `List[str]` | `None` | 停止词列表 |\n| `seed` | `int` | `None` | 随机种子 |\n| `stream` | `bool` | `False` | 流式输出开关 |\n| `response_format` | `dict` | `None` | 响应格式约束 |\n| `tools` | `List[dict]` | `None` | 工具函数定义 |\n| `tool_choice` | `str` | `None` | 工具选择策略 |\n\n资料来源：[camel/configs/openai_config.py]()\n\n### Anthropic 配置\n\n`AnthropicConfig` 类提供 Claude 模型的详细配置选项。\n\n#### 配置参数表\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `temperature` | `float` | `1.0` | 采样温度 |\n| `max_tokens` | `int` | `4096` | 最大生成token数 |\n| `top_p` | `float` | `1.0` | Top-p 采样 |\n| `stop_sequences` | `List[str]` | `None` | 停止序列 |\n| `stream` | `bool` | `False` | 流式输出开关 |\n| `tools` | `List[dict]` | `None` | 工具函数定义 |\n\n资料来源：[camel/configs/anthropic_config.py]()\n\n## 使用指南\n\n### 基础使用流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant Factory as ModelFactory\n participant Model as OpenAIModel\n participant API as OpenAI API\n \n User->>Factory: create(platform, model_type, api_key)\n Factory->>Model: instantiate\n User->>Model: run(messages)\n Model->>API: POST /chat/completions\n API-->>Model: response\n Model-->>User: Message object\n```\n\n### 基本调用示例\n\n#### 1. 创建 OpenAI 模型实例\n\n```python\nfrom camel.models import ModelFactory, ModelPlatformType, ModelType\n\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=ModelType.GPT_4O,\n api_key=\"your-api-key\"\n)\n```\n\n#### 2. 创建 Anthropic 模型实例\n\n```python\nfrom camel.models import ModelFactory, ModelPlatformType, ModelType\n\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.ANTHROPIC,\n model_type=ModelType.CLAUDE_3_5_SONNET,\n api_key=\"your-api-key\"\n)\n```\n\n#### 3. 使用兼容接口模型\n\n```python\nfrom camel.models import ModelFactory, ModelPlatformType, ModelType\n\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI_COMPATIBLE_MODEL,\n model_type=ModelType.GPT_4O,\n url=\"https://api.example.com/v1\",\n api_key=\"your-api-key\"\n)\n```\n\n#### 4. 自定义模型配置\n\n```python\nfrom camel.models import ModelFactory, ModelPlatformType, ModelType\nfrom camel.configs import OpenAIConfig\n\nconfig = OpenAIConfig(\n temperature=0.7,\n max_tokens=2048,\n top_p=0.9\n)\n\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=ModelType.GPT_4O,\n api_key=\"your-api-key\",\n config_dict=config.as_dict()\n)\n```\n\n#### 5. 执行模型调用\n\n```python\nfrom camel.messages import UserMessage\n\nresponse = model.run([\n UserMessage(content=\"Hello, how are you?\")\n])\n\nprint(response.content)\n```\n\n资料来源：[camel/models/model_factory.py](), [camel/models/openai_model.py]()\n\n### 高级用法\n\n#### 流式输出\n\n```python\nconfig = OpenAIConfig(stream=True)\n\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=ModelType.GPT_4O,\n api_key=\"your-api-key\",\n config_dict=config.as_dict()\n)\n\nresponse = model.run(messages)\n# 处理流式响应\n```\n\n#### 函数调用（Tools）\n\n```python\ntools = [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_weather\",\n \"description\": \"获取天气信息\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\"type\": \"string\"}\n }\n }\n }\n }\n]\n\nconfig = OpenAIConfig(tools=tools)\n\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=ModelType.GPT_4O,\n api_key=\"your-api-key\",\n config_dict=config.as_dict()\n)\n```\n\n资料来源：[camel/configs/openai_config.py]()\n\n## 模型类型枚举\n\nCAMEL 使用强类型枚举 `ModelType` 管理支持的模型列表。\n\n### 完整枚举值\n\n```python\nclass ModelType(Enum):\n # OpenAI Models\n GPT_4 = \"gpt-4\"\n GPT_4_TURBO = \"gpt-4-turbo\"\n GPT_4O = \"gpt-4o\"\n GPT_4O_MINI = \"gpt-4o-mini\"\n GPT_35_TURBO = \"gpt-3.5-turbo\"\n GPT_35_TURBO_16K = \"gpt-3.5-turbo-16k\"\n \n # Anthropic Models\n CLAUDE_3_5_SONNET = \"claude-sonnet-4-20250514\"\n CLAUDE_3_OPUS = \"claude-3-opus-20240229\"\n CLAUDE_3_SONNET = \"claude-3-sonnet-20240229\"\n CLAUDE_3_HAIKU = \"claude-3-haiku-20240307\"\n \n # ... 其他模型\n```\n\n资料来源：[camel/models/__init__.py]()\n\n## 错误处理\n\n### 常见错误及解决方案\n\n| 错误类型 | 可能原因 | 解决方案 |\n|----------|----------|----------|\n| `AuthenticationError` | API 密钥无效或缺失 | 检查并正确设置 `api_key` |\n| `RateLimitError` | 请求频率超限 | 降低调用频率或升级配额 |\n| `BadRequestError` | 参数配置错误 | 检查 `config_dict` 参数 |\n| `APIConnectionError` | 网络连接问题 | 检查网络和代理设置 |\n\n资料来源：[camel/models/base_model.py](), [camel/models/openai_model.py]()\n\n## 扩展指南\n\n### 添加新模型支持\n\n如需添加新的模型提供商支持，需要：\n\n1. 在 `camel/models/` 目录下创建新的模型实现类（如 `xxx_model.py`）\n2. 继承 `BaseModel` 抽象类\n3. 实现 `run()` 和 `_extract_text_from_response()` 方法\n4. 在 `ModelFactory.create()` 方法中添加创建逻辑\n5. 在 `ModelType` 枚举中添加新的模型类型\n\n```python\n# 示例：新增模型支持\nclass XxxModel(BaseModel):\n def __init__(self, model_type, model_config_dict, api_key, **kwargs):\n super().__init__(model_type, model_config_dict, api_key)\n # 初始化特定逻辑\n \n def _extract_text_from_response(self, response) -> str:\n # 解析响应\n return response.choices[0].message.content\n```\n\n资料来源：[camel/models/base_model.py](), [camel/models/model_factory.py]()\n\n## 相关资源\n\n- 模型模块源码：[camel/models/](https://github.com/camel-ai/camel/tree/main/camel/models)\n- 配置模块源码：[camel/configs/](https://github.com/camel-ai/camel/tree/main/camel/configs)\n- 官方文档：[CAMEL Documentation](https://docs.camel-ai.org/)\n\n---\n\n\n\n## 工具集(Toolkits)\n\n### 相关页面\n\n相关主题：[智能体(Agents)](#page-agents), [MCP协议集成](#page-mcp), [智能体劳动力(Workforce)](#page-workforce)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/toolkits/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/__init__.py)\n- [camel/toolkits/base.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/base.py)\n- [camel/toolkits/function_tool.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/function_tool.py)\n- [camel/toolkits/search_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/search_toolkit.py)\n- [camel/toolkits/browser_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/browser_toolkit.py)\n- [camel/toolkits/file_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/file_toolkit.py)\n- [camel/toolkits/github_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/github_toolkit.py)\n- [camel/toolkits/slack_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/slack_toolkit.py)\n- [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)\n \n\n# 工具集(Toolkits)\n\n## 概述\n\nCAMEL-AI 的工具集（Toolkits）是框架中用于扩展代理（Agent）能力的关键组件库。工具集提供了一系列预构建的功能模块，使代理能够执行搜索、文件操作、浏览器自动化、GitHub集成、Slack通信等多种任务。通过工具集，开发者可以快速为AI代理配备特定领域的工具能力，无需从零开始实现复杂的功能逻辑。\n\n工具集的设计遵循模块化原则，每个工具集都是独立的功能单元，可以单独使用或组合使用。这种设计使得系统具有高度的灵活性和可扩展性，开发者可以根据实际需求选择性地集成所需工具。\n\n## 架构设计\n\n### 核心架构图\n\n```mermaid\ngraph TD\n A[BaseToolkit] --> B[SearchToolkit]\n A --> C[BrowserToolkit]\n A --> D[FileToolkit]\n A --> E[GitHubToolkit]\n A --> F[SlackToolkit]\n A --> G[FunctionTool]\n \n H[FunctionCall] --> G\n I[ToolOutput] --> G\n \n J[Agent] --> K[ToolkitRegistry]\n K --> A\n```\n\n### 基础类层次结构\n\nCAMEL-AI 的工具集系统建立在一个统一的基础类体系之上。所有工具集都继承自 `BaseToolkit` 基类，该类定义了工具集的标准接口和行为规范。\n\n`BaseToolkit` 是所有工具集的抽象基类，它提供了工具集的核心框架。每个具体的工具集都需要实现其定义的接口方法。基类封装了通用的功能逻辑，如工具注册、参数验证和结果处理等通用流程，使得具体工具集的实现更加简洁和专注于业务逻辑。\n\n`FunctionTool` 是另一个重要的基础组件，它用于将普通函数转换为AI代理可调用的工具。`FunctionTool` 包装了目标函数，添加了参数解析、类型转换和错误处理等功能，使得开发者可以将任意的Python函数暴露给AI代理使用。\n\n## 工具集类型详解\n\n### 1. 搜索工具集（SearchToolkit）\n\n搜索工具集为代理提供了网络搜索能力，使其能够检索最新的信息和数据。\n\n| 方法名 | 功能描述 | 返回类型 |\n|--------|----------|----------|\n| search | 执行通用网络搜索 | List[SearchResult] |\n| news_search | 搜索新闻内容 | List[NewsResult] |\n| academic_search | 搜索学术论文 | List[AcademicResult] |\n\nSearchToolkit 支持多种搜索模式，包括网页搜索、新闻搜索和学术论文搜索。开发者可以根据不同的使用场景选择合适的搜索模式。\n\n### 2. 浏览器工具集（BrowserToolkit）\n\n浏览器工具集提供了浏览器自动化能力，支持网页抓取、元素交互和页面导航等功能。\n\n```mermaid\ngraph LR\n A[BrowserSession] --> B[PageNavigation]\n B --> C[ElementInteraction]\n C --> D[ContentExtraction]\n D --> E[SnapshotCapture]\n```\n\nBrowserToolkit 的核心是 `BrowserSession` 类，它管理浏览器的生命周期和会话状态。该类提供了丰富的页面操作方法，包括导航到指定URL、点击页面元素、填写表单内容、提取页面文本和截图等。\n\n`browser-session.ts` 文件中实现了浏览器会话的核心逻辑，包括元素定位、表单填写和快照比较等功能。当代理需要与网页交互时，会话管理器会协调各个组件完成操作任务。\n\n### 3. 文件工具集（FileToolkit）\n\n文件工具集提供了文件系统操作能力，支持文件读写、目录管理和路径操作等功能。\n\n| 操作类型 | 支持功能 |\n|----------|----------|\n| 读取 | 文本文件、JSON、CSV、二进制文件 |\n| 写入 | 创建新文件、覆盖文件、追加内容 |\n| 目录 | 创建目录、列出内容、删除目录 |\n| 元数据 | 获取文件大小、修改时间、权限信息 |\n\nFileToolkit 封装了常见的文件系统操作，为AI代理提供了安全可靠的文件访问能力。所有文件操作都经过严格的路径验证，防止目录遍历攻击。\n\n### 4. GitHub工具集（GitHubToolkit）\n\nGitHub工具集集成了GitHub API，使代理能够执行仓库管理、Issue操作、PR管理和代码搜索等任务。\n\n| 功能模块 | 描述 |\n|----------|------|\n| 仓库操作 | 创建、克隆、获取仓库信息 |\n| Issue管理 | 创建Issue、评论、关闭、标签管理 |\n| PR操作 | 创建Pull Request、审查、合并 |\n| 代码搜索 | 搜索代码、仓库和用户 |\n\nGitHubToolkit 通过GitHub REST API与GitHub平台进行交互，支持完整的仓库生命周期管理功能。\n\n### 5. Slack工具集（SlackToolkit）\n\nSlack工具集提供了与Slack工作区交互的能力，支持消息发送、频道管理和用户查询等功能。\n\n| 功能 | 说明 |\n|------|------|\n| 消息发送 | 向指定频道或用户发送消息 |\n| 频道管理 | 创建频道、获取频道列表、管理成员 |\n| 用户查询 | 获取用户信息、在线状态 |\n| 文件上传 | 上传文件到Slack频道 |\n\nSlackToolkit 使用Slack Web API实现所有功能，支持企业级Slack工作区的集成需求。\n\n## 工具调用机制\n\n### 函数调用流程\n\n```mermaid\nsequenceDiagram\n participant Agent as Agent\n participant Toolkit as FunctionTool\n participant Function as Target Function\n \n Agent->>Toolkit: 调用工具方法\n Toolkit->>Toolkit: 参数解析与验证\n Toolkit->>Function: 转发调用请求\n Function-->>Toolkit: 返回执行结果\n Toolkit->>Toolkit: 结果格式化处理\n Toolkit-->>Agent: 返回ToolOutput\n```\n\n### 参数处理\n\nFunctionTool 提供了强大的参数处理能力，支持多种数据类型和验证规则。工具的参数定义采用声明式方式，开发者可以通过装饰器或配置指定参数的类型约束、默认值和验证规则。\n\n| 参数特性 | 支持情况 |\n|----------|----------|\n| 类型注解 | int, str, float, bool, list, dict |\n| 默认值 | 支持可选参数 |\n| 必填检查 | 支持必填参数验证 |\n| 枚举约束 | 支持枚举类型限制 |\n\n## 混合浏览器工具集（HybridBrowserToolkit）\n\nHybridBrowserToolkit 是CAMEL-AI中功能最强大的浏览器自动化工具，它结合了传统浏览器控制和现代化前端交互能力。\n\n### 核心特性\n\n- **多浏览器支持**：支持Chrome、Firefox等主流浏览器\n- **智能元素定位**：支持通过ID、类名、XPath、CSS选择器定位元素\n- **表单自动化**：支持填写表单、上传文件、选择下拉菜单\n- **截图功能**：支持全页面截图和元素截图\n- **JavaScript执行**：支持在页面上下文中执行JavaScript代码\n\n### 会话管理\n\nBrowserSession 类负责管理浏览器会话的生命周期。每个会话包含以下状态：\n\n```mermaid\nstateDiagram-v2\n [*] --> Initialized: 创建会话\n Initialized --> Ready: 打开页面\n Ready --> Active: 执行操作\n Active --> Ready: 操作完成\n Active --> Error: 发生错误\n Ready --> [*]: 关闭会话\n Error --> Ready: 重试\n```\n\n### 元素交互\n\n当代理需要与页面元素交互时，系统会执行以下流程：\n\n1. 接收交互指令和目标元素引用\n2. 在当前页面快照中查找匹配元素\n3. 验证元素可见性和可操作性\n4. 执行交互操作（点击、输入、选择等）\n5. 等待操作完成并获取结果快照\n6. 比较操作前后的页面变化\n7. 返回操作结果和差异信息\n\n## 使用示例\n\n### 基础工具集使用\n\n```python\nfrom camel.toolkits import SearchToolkit, FileToolkit\n\n# 创建搜索工具集实例\nsearch_toolkit = SearchToolkit()\n\n# 执行搜索\nresults = search_toolkit.search(query=\"人工智能最新进展\")\n\n# 创建文件工具集实例\nfile_toolkit = FileToolkit()\n\n# 读取文件\ncontent = file_toolkit.read_file(path=\"example.txt\")\n```\n\n### 自定义函数工具\n\n```python\nfrom camel.toolkits import FunctionTool\n\n# 将普通函数转换为工具\n@FunctionTool\ndef calculate(expression: str) -> float:\n \"\"\"计算数学表达式\"\"\"\n return eval(expression)\n\n# 注册到代理\nagent = ChatAgent(\n tools=[calculate]\n)\n```\n\n### 浏览器自动化\n\n```python\nfrom camel.toolkits import BrowserToolkit\n\nbrowser = BrowserToolkit()\n\n# 启动会话\nsession = await browser.create_session()\n\n# 导航到网页\nawait session.navigate(\"https://example.com\")\n\n# 填写表单\nawait session.fill(\n ref=\"search-input\",\n text=\"查询内容\",\n original_placeholder=\"搜索...\"\n)\n\n# 获取快照\nsnapshot = await session.get_snapshot()\n```\n\n## 配置与管理\n\n### 工具集注册\n\nCAMEL-AI 提供了统一的工具集注册机制，开发者可以将自定义工具集注册到全局注册表中，供整个应用使用。\n\n```python\nfrom camel.toolkits import ToolkitRegistry\n\n# 获取注册表实例\nregistry = ToolkitRegistry.get_instance()\n\n# 注册自定义工具集\nregistry.register(\"my_toolkit\", MyCustomToolkit())\n```\n\n### 环境变量配置\n\n部分工具集需要配置外部服务的API密钥或访问凭证。这些配置通常通过环境变量提供：\n\n| 环境变量 | 适用工具集 | 用途 |\n|----------|------------|------|\n| OPENAI_API_KEY | 所有工具集 | API身份验证 |\n| GITHUB_TOKEN | GitHubToolkit | GitHub API访问 |\n| SLACK_BOT_TOKEN | SlackToolkit | Slack API访问 |\n| SEARCH_API_KEY | SearchToolkit | 搜索服务访问 |\n\n## 与代理系统的集成\n\n工具集与CAMEL-AI的代理系统紧密集成，代理在初始化时可以接收一个或多个工具集作为能力扩展。\n\n```mermaid\ngraph TD\n A[Agent初始化] --> B[加载工具集]\n B --> C[工具注册]\n C --> D[函数调用接口暴露]\n D --> E[运行时调用]\n E --> F[结果返回]\n```\n\n代理系统会自动处理工具调用的路由、参数序列化和结果反序列化等细节，开发者只需关注业务逻辑的实现。\n\n## 最佳实践\n\n### 工具设计原则\n\n1. **单一职责**：每个工具应专注于完成一个特定任务\n2. **清晰的命名**：工具名应准确反映其功能\n3. **完善的文档**：提供详细的参数说明和返回值描述\n4. **错误处理**：对异常情况进行恰当处理和提示\n5. **参数验证**：在执行前验证所有输入参数的有效性\n\n### 性能优化建议\n\n- 复用工具集实例，避免重复创建\n- 对于耗时操作，考虑使用异步实现\n- 批量操作时使用事务或批处理接口\n- 合理设置超时时间，防止长时间阻塞\n\n## 扩展开发\n\n开发者可以通过继承 `BaseToolkit` 类来创建自定义工具集。标准开发流程如下：\n\n1. 创建继承自 `BaseToolkit` 的新类\n2. 在 `__init__` 方法中初始化所需的资源和配置\n3. 实现具体的功能方法\n4. 添加适当的文档字符串\n5. 在包入口文件中导出新工具集\n\n自定义工具集可以像内置工具集一样注册到代理中，实现无缝集成。\n\n## 相关资源\n\n- 基础工具类源码：[camel/toolkits/base.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/base.py)\n- 函数工具源码：[camel/toolkits/function_tool.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/function_tool.py)\n- 浏览器工具集源码：[camel/toolkits/browser_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/browser_toolkit.py)\n- 混合浏览器工具集：[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)\n- 搜索工具集源码：[camel/toolkits/search_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/search_toolkit.py)\n- 文件工具集源码：[camel/toolkits/file_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/file_toolkit.py)\n- GitHub工具集源码：[camel/toolkits/github_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/github_toolkit.py)\n- Slack工具集源码：[camel/toolkits/slack_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/slack_toolkit.py)\n\n---\n\n\n\n## MCP协议集成\n\n### 相关页面\n\n相关主题：[工具集(Toolkits)](#page-toolkits), [智能体(Agents)](#page-agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/toolkits/mcp_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/mcp_toolkit.py)\n- [camel/agents/mcp_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/mcp_agent.py)\n- [camel/parsers/mcp_tool_call_parser.py](https://github.com/camel-ai/camel/blob/main/camel/parsers/mcp_tool_call_parser.py)\n- [camel/types/mcp_registries.py](https://github.com/camel-ai/camel/blob/main/camel/types/mcp_registries.py)\n- [camel/utils/mcp_client.py](https://github.com/camel-ai/camel/blob/main/camel/utils/mcp_client.py)\n \n\n# MCP协议集成\n\n## 概述\n\nMCP（Model Context Protocol）是一种标准化协议，用于在AI代理（Agent）与外部工具、服务之间建立通信桥梁。CAMEL-AI框架通过模块化的MCP集成方案，使代理能够调用远程工具、访问外部资源，并与其他MCP兼容系统进行交互。\n\nMCP协议集成的核心目标包括：\n- 提供统一的工具调用接口\n- 支持多种MCP服务器连接\n- 实现工具解析与响应处理\n- 管理工具注册与生命周期\n\n资料来源：[camel/toolkits/mcp_toolkit.py:1-50]()\n\n## 核心组件\n\nCAMEL-AI的MCP协议集成由以下核心模块组成：\n\n| 组件 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| MCPToolkit | `camel/toolkits/mcp_toolkit.py` | MCP工具集，提供与MCP服务器交互的主要接口 |\n| MCPAgent | `camel/agents/mcp_agent.py` | MCP代理，负责处理MCP协议通信的代理实现 |\n| MCPToolCallParser | `camel/parsers/mcp_tool_call_parser.py` | 工具调用解析器，解析MCP协议消息 |\n| MCP registries | `camel/types/mcp_registries.py` | MCP类型注册表，管理MCP类型定义 |\n| MCPClient | `camel/utils/mcp_client.py` | MCP客户端工具，提供底层通信能力 |\n\n资料来源：[camel/types/mcp_registries.py:1-30]()\n\n### 组件关系图\n\n```mermaid\ngraph TD\n A[MCPAgent] --> B[MCPToolkit]\n B --> C[MCPToolCallParser]\n B --> D[MCPClient]\n D --> E[MCP Registries]\n F[MCP Servers] --> D\n A --> G[User Application]\n```\n\n## 架构设计\n\n### 系统架构\n\nMCP协议集成采用客户端-服务器架构，核心交互流程如下：\n\n```mermaid\nsequenceDiagram\n participant User as 用户应用\n participant Agent as MCPAgent\n participant Toolkit as MCPToolkit\n participant Client as MCPClient\n participant Server as MCP服务器\n\n User->>Agent: 调用工具\n Agent->>Toolkit: 解析工具请求\n Toolkit->>Client: 发起MCP调用\n Client->>Server: 发送协议消息\n Server-->>Client: 返回结果\n Client-->>Toolkit: 解析响应\n Toolkit-->>Agent: 返回工具结果\n Agent-->>User: 输出最终结果\n```\n\n### 工具调用解析\n\n`MCPToolCallParser`负责解析工具调用请求，其处理流程：\n\n```mermaid\ngraph LR\n A[MCP协议消息] --> B[解析工具名称]\n B --> C[提取参数]\n C --> D[验证参数类型]\n D --> E[生成标准化调用]\n```\n\n资料来源：[camel/parsers/mcp_tool_call_parser.py:1-40]()\n\n## MCPAgent详解\n\n`MCPAgent`是MCP协议集成的核心代理类，继承自基础代理接口，提供以下功能：\n\n### 主要职责\n\n- 初始化MCP客户端连接\n- 管理工具注册生命周期\n- 处理用户请求并转发至MCP服务器\n- 解析和返回工具执行结果\n\n### 初始化参数\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| name | str | 是 | 代理名称 |\n| mcp_servers_config | dict | 是 | MCP服务器配置 |\n| model | Model | 是 | 使用的语言模型 |\n| system_message | str | 否 | 系统提示词 |\n\n资料来源：[camel/agents/mcp_agent.py:20-60]()\n\n## MCPToolkit使用指南\n\n`MCPToolkit`提供了与MCP服务器交互的统一接口，简化了工具调用流程。\n\n### 服务器配置\n\nMCP服务器通过JSON配置文件进行定义：\n\n```json\n{\n \"mcpServers\": {\n \"airbnb\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@openbnb/mcp-server-airbnb\", \"--ignore-robots-txt\"]\n },\n \"cloudflare\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-cloudflare\"]\n }\n }\n}\n```\n\n### 工具注册流程\n\n```mermaid\ngraph TD\n A[加载MCP配置] --> B[初始化MCPClient]\n B --> C[连接MCP服务器]\n C --> D[获取可用工具列表]\n D --> E[注册工具到Toolkit]\n E --> F[返回MCPToolkit实例]\n```\n\n资料来源：[camel/toolkits/mcp_toolkit.py:50-100]()\n\n## MCPClient通信机制\n\n`MCPClient`是底层的通信客户端，负责与MCP服务器进行协议级别的交互。\n\n### 核心方法\n\n| 方法 | 说明 |\n|------|------|\n| connect | 建立与MCP服务器的连接 |\n| disconnect | 关闭连接并清理资源 |\n| call_tool | 调用远程工具 |\n| list_tools | 获取可用工具列表 |\n| get_resources | 获取服务器资源 |\n\n资料来源：[camel/utils/mcp_client.py:30-80]()\n\n### 协议消息格式\n\nMCP协议使用JSON格式进行消息传递，标准请求结构：\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"tool_name\",\n \"arguments\": {}\n }\n}\n```\n\n## 实际应用示例\n\n### 多代理研究助手\n\n在`examples/usecases/multi_agent_research_assistant`中，MCP协议用于集成外部搜索和新闻API：\n\n```python\nfrom camel.agents.mcp_agent import MCPAgent\nfrom camel.toolkits.mcp_toolkit import MCPToolkit\n\n# 初始化MCP代理\nagent = MCPAgent(\n name=\"research_assistant\",\n mcp_servers_config=mcp_config,\n model=model\n)\n```\n\n### Cloudflare MCP集成\n\n在`examples/usecases/cloudfare_mcp_camel`中，集成Cloudflare的多个MCP服务：\n\n- **Analytics MCP服务器**：提供全球互联网流量趋势分析\n- **DNS Analytics服务器**：提供DNS分析能力\n- **Browser服务器**：提供网页抓取和截图功能\n\n资料来源：[examples/usecases/cloudfare_mcp_camel/README.md]()\n\n### Airbnb房源搜索\n\n`examples/usecases/airbnb_mcp`展示了如何集成Airbnb的MCP服务器：\n\n```json\n{\n \"mcpServers\": {\n \"airbnb\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@openbnb/mcp-server-airbnb\", \"--ignore-robots-txt\"]\n }\n }\n}\n```\n\n资料来源：[examples/usecases/airbnb_mcp/README.md]()\n\n## 最佳实践\n\n### 配置管理\n\n1. **环境变量分离**：将API密钥存储在`.env`文件中，避免硬编码\n2. **配置文件版本化**：使用版本控制管理MCP服务器配置\n3. **错误处理**：实现完善的异常捕获和重试机制\n\n### 性能优化\n\n| 优化项 | 建议 |\n|--------|------|\n| 连接复用 | 保持长连接避免频繁建立TCP连接 |\n| 缓存策略 | 对不常变化的工具列表进行缓存 |\n| 并发控制 | 使用连接池管理并发请求 |\n\n### 安全考虑\n\n- 敏感信息不写入配置文件\n- 使用环境变量注入API密钥\n- 定期轮换API访问凭证\n\n## 故障排查\n\n| 常见问题 | 可能原因 | 解决方案 |\n|----------|----------|----------|\n| 连接超时 | MCP服务器未启动 | 检查`mcp-remote`安装状态 |\n| 工具调用失败 | 参数格式错误 | 检查MCP服务器返回的错误信息 |\n| 响应解析错误 | 协议版本不兼容 | 确保客户端与服务端版本匹配 |\n\n资料来源：[examples/usecases/cloudfare_mcp_camel/README.md]()\n\n## 相关资源\n\n- MCP官方文档：[Model Context Protocol](https://modelcontextprotocol.io/)\n- CAMEL-AI官方仓库：[camel-ai/camel](https://github.com/camel-ai/camel)\n- MCP Inspector工具：用于调试MCP服务器连接\n\n---\n\n*本文档由CAMEL-AI框架源码自动生成，最后更新于2024年*\n\n---\n\n\n\n## 智能体社会(Societies)\n\n### 相关页面\n\n相关主题：[智能体劳动力(Workforce)](#page-workforce), [智能体(Agents)](#page-agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/societies/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/societies/__init__.py)\n- [camel/societies/role_playing.py](https://github.com/camel-ai/camel/blob/main/camel/societies/role_playing.py)\n- [camel/societies/babyagi_playing.py](https://github.com/camel-ai/camel/blob/main/camel/societies/babyagi_playing.py)\n- [camel/personas/persona.py](https://github.com/camel-ai/camel/blob/main/camel/personas/persona.py)\n- [camel/personas/persona_hub.py](https://github.com/camel-ai/camel/blob/main/camel/personas/persona_hub.py)\n \n\n# 智能体社会(Societies)\n\n## 概述\n\nCAMEL框架中的**智能体社会(Societies)**模块是实现多智能体协作的核心基础设施。该模块提供了一套完整的多智能体交互机制，支持角色扮演、任务分解、自主执行等多种协作范式。智能体社会允许定义多个具有特定角色和能力的智能体，通过结构化的通信协议实现复杂的协作任务。\n\n智能体社会的设计理念源于社会学中的\"社会\"概念，模拟人类社会中不同角色之间的交互模式。每个智能体被赋予特定的角色身份（如\"AI助手\"、\"用户代理\"等），这些角色定义了智能体的行为模式、决策风格和通信方式。通过这种方式，CAMEL能够构建具有真实感的AI系统交互场景。\n\n## 核心架构\n\n### 模块结构\n\nCAMEL的智能体社会模块位于`camel/societies/`目录下，包含多个核心组件：\n\n| 组件文件 | 功能描述 |\n|---------|---------|\n| `__init__.py` | 模块导出接口，定义公共API |\n| `role_playing.py` | 角色扮演核心实现，支持双智能体协作 |\n| `babyagi_playing.py` | BabyAGI范式实现，支持任务分解与执行 |\n\n```\ncamel/societies/\n├── __init__.py # 模块入口\n├── role_playing.py # 角色扮演实现\n└── babyagi_playing.py # BabyAGI实现\n```\n\n### 类层次结构\n\n智能体社会模块采用面向对象设计，核心类包括：\n\n- **RolePlaying**：角色扮演主类，管理两个智能体之间的对话交互\n- **BabyAGI**：BabyAGI执行器，实现自主任务分解与执行\n- **BaseSociety**：基础抽象类（若存在），定义通用接口\n\n```mermaid\ngraph TD\n A[BaseSociety] --> B[RolePlaying]\n A --> C[BabyAGI]\n B --> D[AI Assistant Agent]\n B --> E[User Agent]\n C --> F[Task Agent]\n C --> G[Execution Agent]\n C --> H[Critique Agent]\n```\n\n## 角色扮演系统(Role Playing)\n\n### 系统设计\n\n角色扮演是CAMEL框架中最核心的智能体协作模式。该系统模拟人类社会中的角色交互场景，由两个主要智能体组成：\n\n- **AI助手智能体(AI Assistant Agent)**：扮演AI助手角色，响应用户请求\n- **用户代理智能体(User Agent)**：代表最终用户，执行用户指定的任务\n\n这种双智能体设计允许AI系统在没有人类直接干预的情况下自主协作完成任务。\n\n### RolePlaying类详解\n\n`RolePlaying`类是多智能体协作的主入口，提供完整的对话管理功能。\n\n#### 构造函数参数\n\n| 参数名 | 类型 | 必需 | 默认值 | 说明 |\n|-------|------|------|--------|------|\n| `assistant_agent` | `BaseAgent` | 是 | - | AI助手智能体实例 |\n| `user_agent` | `BaseAgent` | 是 | - | 用户代理智能体实例 |\n| `task_prompt` | `str` | 是 | - | 任务描述提示词 |\n| `task_specify_prompt` | `str` | 否 | None | 任务细化提示词 |\n| `with_task_specify` | `bool` | 否 | True | 是否进行任务细化 |\n| `max_dialogue` | `int` | 否 | 20 | 最大对话轮数 |\n| `turn_limit` | `int` | 否 | None | 单轮交互限制 |\n\n#### 核心方法\n\n| 方法名 | 返回类型 | 功能描述 |\n|-------|---------|---------|\n| `init_chat()` | `None` | 初始化对话，设置系统提示词 |\n| `step()` | `ChatAgentResponse` | 执行单步对话交互 |\n| `run()` | `List[BaseMessage]` | 运行完整的角色扮演对话 |\n| `get_info()` | `Dict` | 获取当前对话状态信息 |\n\n### 工作流程\n\n角色扮演系统遵循严格的对话协议，确保智能体之间的交互有序进行：\n\n```mermaid\ngraph TD\n A[初始化 init_chat] --> B{检查终止条件}\n B -->|未达到限制| C[AI助手生成回复]\n C --> D[消息加入对话历史]\n D --> E{检查终止条件}\n E -->|未达到限制| F[用户代理处理]\n F --> D\n E -->|达到限制| G[返回对话历史]\n B -->|达到限制| G\n G --> H[对话结束]\n```\n\n### 任务指定机制\n\n角色扮演系统包含任务指定(Task Specification)模块，用于将模糊的用户请求转化为具体的任务描述：\n\n1. **任务分析**：AI助手分析用户意图\n2. **任务细化**：将大任务分解为可执行的子任务\n3. **目标确认**：用户代理确认任务目标和范围\n4. **执行计划**：制定详细的执行步骤\n\n```mermaid\ngraph LR\n A[模糊任务请求] --> B[任务分析]\n B --> C[任务细化]\n C --> D[子任务分解]\n D --> E[执行计划制定]\n E --> F[具体可执行任务]\n```\n\n## 人物角色系统(Personas)\n\n### Persona类\n\n`Persona`类定义了智能体的身份特征和行为模式。\n\n#### 属性定义\n\n| 属性名 | 类型 | 说明 |\n|-------|------|------|\n| `name` | `str` | 角色名称 |\n| `description` | `str` | 角色描述 |\n| `system_instruction` | `str` | 系统级指令 |\n| `role_type` | `RoleType` | 角色类型枚举 |\n\n#### 核心功能\n\n- **身份塑造**：定义智能体的角色身份和背景\n- **行为约束**：通过系统指令约束智能体的行为模式\n- **交互风格**：设定智能体的沟通和响应风格\n\n### PersonaHub\n\n`PersonaHub`是角色仓库，提供预定义的角色模板和自定义接口。\n\n#### 预定义角色类型\n\n| 角色标识 | 角色名称 | 应用场景 |\n|---------|---------|---------|\n| `ASSISTANT` | AI助手 | 通用问答和任务执行 |\n| `USER` | 用户代理 | 代表用户执行任务 |\n| `CRITIC` | 批评者 | 评估和审核任务结果 |\n| `PLANNER` | 规划者 | 任务规划和分解 |\n| `RESEARCHER` | 研究者 | 信息检索和分析 |\n\n#### 角色获取接口\n\n```python\n# 从仓库获取预定义角色\npersona = PersonaHub.get_persona(persona_type=PersonaType.ASSISTANT)\n\n# 获取带自定义参数的角色\ncustom_persona = PersonaHub.get_persona(\n persona_type=PersonaType.RESEARCHER,\n custom_params={\"expertise\": \"quantum computing\"}\n)\n```\n\n## BabyAGI范式\n\n### 概述\n\nBabyAGI是另一种智能体协作范式，与角色扮演不同，它更强调任务的自动分解和迭代执行。该模式模拟了人类解决复杂问题时的思考过程。\n\n### BabyAGIPlaying类\n\n`BabyAGIPlaying`类实现了BabyAGI的核心逻辑。\n\n#### 组成结构\n\n| 组件 | 类型 | 功能 |\n|-----|------|------|\n| `task_creation_agent` | `BaseAgent` | 负责创建和分解任务 |\n| `execution_agent` | `BaseAgent` | 负责执行具体任务 |\n| `critique_agent` | `BaseAgent` | 负责评估和反馈 |\n\n#### 执行流程\n\n```mermaid\ngraph TD\n A[接收初始任务] --> B[任务创建智能体分析任务]\n B --> C[生成任务列表]\n C --> D{任务队列非空?}\n D -->|是| E[执行智能体处理任务]\n E --> F[批评智能体评估结果]\n F --> G{需要新任务?}\n G -->|是| H[创建新任务]\n H --> C\n G -->|否| I[任务完成]\n I --> D\n D -->|否| J[返回最终结果]\n```\n\n### 与角色扮演的区别\n\n| 特性 | 角色扮演 | BabyAGI |\n|------|---------|---------|\n| 智能体数量 | 2个 | 3个或更多 |\n| 通信模式 | 双向对话 | 多向协作 |\n| 任务处理 | 协作完成 | 分解执行 |\n| 反馈机制 | 有限 | 迭代改进 |\n| 适用场景 | 对话交互 | 复杂任务 |\n\n## 使用示例\n\n### 基础角色扮演\n\n```python\nfrom camel.societies import RolePlaying\nfrom camel.agents import ChatAgent\nfrom camel.personas import PersonaHub\n\n# 创建智能体\nassistant_persona = PersonaHub.get_persona(PersonaType.ASSISTANT)\nuser_persona = PersonaHub.get_persona(PersonaType.USER)\n\nassistant_agent = ChatAgent(persona=assistant_persona)\nuser_agent = ChatAgent(persona=user_persona)\n\n# 初始化角色扮演\nsociety = RolePlaying(\n assistant_agent=assistant_agent,\n user_agent=user_agent,\n task_prompt=\"帮我分析量子计算的最新发展趋势\"\n)\n\n# 执行对话\nmessages = society.run()\n```\n\n### BabyAGI任务执行\n\n```python\nfrom camel.societies import BabyAGIPlaying\n\n# 初始化BabyAGI\nbabyagi = BabyAGIPlaying(\n task=\"完成一份市场调研报告\",\n max_iterations=10\n)\n\n# 执行自主任务分解和执行\nresults = babyagi.run()\n```\n\n## 配置与扩展\n\n### 智能体配置\n\n智能体的行为可通过配置进行定制：\n\n```python\nfrom camel.config import AgentConfig\n\nconfig = AgentConfig(\n model_type=\"gpt-4\",\n temperature=0.7,\n max_tokens=2000,\n tool_use=True\n)\n```\n\n### 自定义角色创建\n\n```python\nfrom camel.personas import Persona, PersonaType\n\ncustom_persona = Persona(\n name=\"数据分析师\",\n description=\"专业的金融数据分析助手\",\n system_instruction=\"你是一位资深数据分析师，擅长从数据中发现洞见\",\n role_type=PersonaType.RESEARCHER\n)\n```\n\n## 最佳实践\n\n### 设计原则\n\n1. **角色清晰**：确保每个智能体的角色定义明确，职责单一\n2. **对话管理**：合理设置对话轮数限制，避免无限循环\n3. **错误处理**：实现健壮的错误捕获和恢复机制\n4. **资源管理**：及时释放不再使用的智能体资源\n\n### 性能优化\n\n- 合理设置`max_dialogue`参数控制对话长度\n- 使用流式输出减少响应延迟\n- 启用缓存机制避免重复计算\n\n### 安全考虑\n\n- 验证用户输入防止提示词注入攻击\n- 限制工具调用的权限范围\n- 实现对话内容审核机制\n\n## 总结\n\nCAMEL的智能体社会(Societies)模块提供了一套完整的多智能体协作框架。通过角色扮演和BabyAGI两种核心范式，开发者可以构建复杂的AI应用场景。模块化的设计使得系统易于扩展和定制，满足不同应用需求。人物角色系统为智能体提供了丰富的身份和行为特征，使多智能体交互更加真实和高效。\n\n---\n\n**相关文档**\n\n- [基础对话智能体](../agents/chat_agent.md)\n- [工具包(Toolkits)](../toolkits/README.md)\n- [模型配置](../config/README.md)\n\n---\n\n\n\n## 智能体劳动力(Workforce)\n\n### 相关页面\n\n相关主题：[智能体社会(Societies)](#page-societies), [智能体(Agents)](#page-agents), [记忆系统(Memory)](#page-memory)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/societies/workforce/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/__init__.py)\n- [camel/societies/workforce/workforce.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/workforce.py)\n- [camel/societies/workforce/worker.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/worker.py)\n- [camel/societies/workforce/task_channel.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/task_channel.py)\n- [camel/societies/workforce/role_playing_worker.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/role_playing_worker.py)\n- [camel/societies/workforce/single_agent_worker.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/single_agent_worker.py)\n- [camel/societies/workforce/events.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/events.py)\n \n\n# 智能体劳动力(Workforce)\n\n## 概述\n\nWorkforce 是 CAMEL 框架中的核心组件，用于协调和管理多个智能体(Worker)协同完成复杂任务。它提供了一个灵活的架构，使多个不同类型的 Worker 能够通过任务通道进行通信和协作，从而实现分布式问题解决和工作流自动化。\n\nWorkforce 的核心设计理念是将复杂任务分解为多个子任务，分配给专门化的 Worker 执行，并通过事件驱动的方式协调整个工作流程。资料来源：[camel/societies/workforce/__init__.py]()\n\n## 核心架构\n\nWorkforce 系统由以下核心组件构成：\n\n```mermaid\ngraph TD\n A[Workforce] --> B[TaskChannel]\n A --> C[Worker Pool]\n C --> D[RolePlayingWorker]\n C --> E[SingleAgentWorker]\n C --> F[BaseWorker]\n A --> G[EventSystem]\n G --> H[WorkforceEvent]\n B --> I[任务分发]\n D --> J[角色扮演任务]\n E --> K[单智能体任务]\n```\n\n## 目录结构\n\n```\ncamel/societies/workforce/\n├── __init__.py # 模块初始化，导出主要接口\n├── workforce.py # Workforce 主类\n├── worker.py # Worker 基类\n├── role_playing_worker.py # 角色扮演 Worker\n├── single_agent_worker.py # 单智能体 Worker\n├── task_channel.py # 任务通道实现\n└── events.py # 事件系统定义\n```\n\n## 组件详解\n\n### Workforce 主类\n\nWorkforce 是整个系统的调度中心，负责管理 Worker 生命周期、任务分发和结果收集。资料来源：[camel/societies/workforce/workforce.py]()\n\n**主要职责：**\n\n- 初始化和管理 Worker 池\n- 维护任务通道和事件系统\n- 协调多 Worker 间的通信\n- 监控任务执行状态\n- 处理异常和超时情况\n\n### Worker 基类\n\nWorker 是执行任务的基本单元，提供统一的任务执行接口。资料来源：[camel/societies/workforce/worker.py]()\n\n**Worker 类型对比：**\n\n| Worker 类型 | 说明 | 适用场景 |\n|-------------|------|----------|\n| BaseWorker | 所有 Worker 的基类，定义通用接口 | 扩展自定义 Worker |\n| RolePlayingWorker | 支持角色扮演的 Worker | 需要角色协作的任务 |\n| SingleAgentWorker | 单一智能体 Worker | 独立执行的任务 |\n\n### 任务通道 (TaskChannel)\n\nTaskChannel 负责在 Worker 之间传递任务和结果。资料来源：[camel/societies/workforce/task_channel.py]()\n\n**通道类型支持：**\n\n- 同步通道：阻塞式任务传递\n- 异步通道：非阻塞式任务传递\n- 广播通道：一对多任务分发\n\n### 事件系统 (Events)\n\n事件系统提供 Workforce 内部的通信机制，支持状态变更通知和任务进度追踪。资料来源：[camel/societies/workforce/events.py]()\n\n## 工作流程\n\n### 任务执行流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant W as Workforce\n participant TC as TaskChannel\n participant WK as Worker\n participant E as EventSystem\n\n U->>W: 提交任务\n W->>TC: 创建任务通道\n W->>WK: 分发任务\n WK->>E: 发送任务开始事件\n WK->>W: 执行任务\n W->>E: 发布进度事件\n WK->>TC: 返回结果\n TC->>W: 收集结果\n W->>U: 返回最终结果\n```\n\n### Worker 协作模式\n\n```mermaid\ngraph LR\n A[任务输入] --> B{Worker选择}\n B -->|角色扮演| C[RolePlayingWorker]\n B -->|独立执行| D[SingleAgentWorker]\n C --> E[协作处理]\n D --> F[独立处理]\n E --> G[结果聚合]\n F --> G\n G --> H[结果输出]\n```\n\n## API 参考\n\n### Workforce 初始化参数\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| workers | List[BaseWorker] | 是 | Worker 列表 |\n| task_channel_type | str | 否 | 任务通道类型，默认 \"default\" |\n| max_workers | int | 否 | 最大并发 Worker 数 |\n| timeout | int | 否 | 任务超时时间(秒) |\n\n### Worker 执行接口\n\n```python\nclass BaseWorker(ABC):\n @abstractmethod\n async def execute(self, task: Task) -> Result:\n \"\"\"执行单个任务\"\"\"\n pass\n \n @abstractmethod\n async def reset(self) -> None:\n \"\"\"重置 Worker 状态\"\"\"\n pass\n \n @property\n @abstractmethod\n def worker_id(self) -> str:\n \"\"\"获取 Worker 唯一标识\"\"\"\n pass\n```\n\n资料来源：[camel/societies/workforce/worker.py]()\n\n## Worker 类型详解\n\n### RolePlayingWorker\n\nRolePlayingWorker 支持多角色协作模式，适用于需要角色扮演和对话的任务场景。资料来源：[camel/societies/workforce/role_playing_worker.py]()\n\n**配置选项：**\n\n| 选项 | 类型 | 说明 |\n|------|------|------|\n| role_name | str | 角色名称 |\n| role_description | str | 角色描述 |\n| model | Model | 使用的语言模型 |\n| tools | List[Tool] | 可用工具列表 |\n\n### SingleAgentWorker\n\nSingleAgentWorker 是单一智能体执行器，适合不需要协作的独立任务。资料来源：[camel/societies/workforce/single_agent_worker.py]()\n\n**特点：**\n\n- 独立的执行环境\n- 无需与其他 Worker 通信\n- 更低的资源消耗\n- 适用于简单任务\n\n## 事件类型\n\nWorkforceEvent 定义了系统中的各种事件类型。资料来源：[camel/societies/workforce/events.py]()\n\n| 事件类型 | 触发时机 | 用途 |\n|----------|----------|------|\n| TASK_STARTED | 任务开始执行 | 记录任务启动 |\n| TASK_COMPLETED | 任务完成 | 收集结果 |\n| TASK_FAILED | 任务执行失败 | 错误处理 |\n| WORKER_REGISTERED | Worker 注册 | 添加到调度池 |\n| WORKER_UNREGISTERED | Worker 注销 | 清理资源 |\n\n## 使用示例\n\n### 基本使用\n\n```python\nfrom camel.societies.workforce import Workforce, SingleAgentWorker\nfrom camel.societies.workforce.task_channel import TaskChannel\n\n# 创建 Workforce\nworkforce = Workforce(\n workers=[SingleAgentWorker(...)],\n max_workers=4\n)\n\n# 提交任务\nresult = await workforce.execute_task(task)\n```\n\n### 角色协作场景\n\n```python\nfrom camel.societies.workforce import (\n Workforce,\n RolePlayingWorker,\n TaskChannel\n)\n\n# 创建多角色 Workforce\nworkforce = Workforce(\n workers=[\n RolePlayingWorker(role_name=\"研究员\", ...),\n RolePlayingWorker(role_name=\"开发者\", ...),\n ]\n)\n\n# 执行协作任务\nresult = await workforce.execute_collaborative_task(task)\n```\n\n## 最佳实践\n\n### 1. Worker 配置建议\n\n- 根据任务复杂度选择合适的 Worker 类型\n- 合理设置 Worker 数量避免资源竞争\n- 为长时间运行的任务配置超时机制\n\n### 2. 任务分发策略\n\n```mermaid\ngraph TD\n A[任务类型判断] --> B{需要协作?}\n B -->|是| C[使用 RolePlayingWorker]\n B -->|否| D[使用 SingleAgentWorker]\n C --> E[通过 TaskChannel 协调]\n D --> F[直接执行]\n```\n\n### 3. 错误处理\n\n- 监听 TASK_FAILED 事件进行错误恢复\n- 实现 Worker 重试机制\n- 设置合理的超时时间\n\n## 与其他模块的集成\n\nWorkforce 与 CAMEL 框架中的其他模块紧密集成：\n\n| 模块 | 集成方式 | 说明 |\n|------|----------|------|\n| ModelFactory | Worker 配置 | 为 Worker 提供模型支持 |\n| Toolkits | 工具扩展 | Worker 可调用各种工具 |\n| Messages | 通信协议 | Worker 间消息传递 |\n| Storage | 状态持久化 | 任务状态存储 |\n\n## 总结\n\nWorkforce 是 CAMEL 框架实现多智能体协作的核心基础设施。通过提供统一的任务分发、Worker 管理和事件驱动机制，Workforce 使得构建复杂的智能体协作系统变得简单高效。开发者可以根据具体需求选择合适的 Worker 类型，并通过灵活的配置实现各种协作模式。\n\n---\n\n\n\n## 记忆系统(Memory)\n\n### 相关页面\n\n相关主题：[智能体(Agents)](#page-agents)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/memories/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/memories/__init__.py)\n- [camel/memories/base.py](https://github.com/camel-ai/camel/blob/main/camel/memories/base.py)\n- [camel/memories/agent_memories.py](https://github.com/camel-ai/camel/blob/main/camel/memories/agent_memories.py)\n- [camel/memories/blocks/chat_history_block.py](https://github.com/camel-ai/camel/blob/main/camel/memories/blocks/chat_history_block.py)\n- [camel/memories/blocks/vectordb_block.py](https://github.com/camel-ai/camel/blob/main/camel/memories/blocks/vectordb_block.py)\n- [camel/memories/context_creators/score_based.py](https://github.com/camel-ai/camel/blob/main/camel/memories/context_creators/score_based.py)\n- [camel/memories/records.py](https://github.com/camel-ai/camel/blob/main/camel/memories/records.py)\n \n\n# 记忆系统(Memory)\n\n## 概述\n\nCAMEL记忆系统是框架中用于管理Agent对话上下文和历史信息的核心组件。该系统通过模块化的设计，支持多种记忆存储方式和上下文检索策略，使Agent能够高效地访问和利用历史交互信息。\n\n记忆系统的核心设计理念是将**记忆存储**与**上下文生成**分离，通过可插拔的Block组件和Context Creator实现灵活的内存管理机制。\n\n## 架构总览\n\n```mermaid\ngraph TB\n subgraph \"记忆系统核心组件\"\n AM[AgentMemories]\n MC[Memory]\n CC[ContextCreator]\n end\n \n subgraph \"存储块Blocks\"\n CHB[ChatHistoryBlock]\n VDB[VectorDBBlock]\n end\n \n subgraph \"上下文创建器\"\n SBC[ScoreBasedContextCreator]\n end\n \n subgraph \"记录Records\"\n CHR[ChatHistoryRecord]\n MR[MemoryRecord]\n end\n \n AM --> MC\n AM --> CC\n MC --> CHB\n MC --> VDB\n CC --> SBC\n SBC --> MC\n CHB --> CHR\n VDB --> MR\n```\n\n## 核心组件\n\n### 记忆基类 (Memory)\n\n`Memory`是所有记忆组件的抽象基类，定义了记忆系统的核心接口：\n\n```python\nclass Memory(Generic[MemoryRecord], ABC):\n @property\n @abstractmethod\n def size(self) -> int: ...\n \n @abstractmethod\n def read(self, *args, **kwargs) -> List[MemoryRecord]: ...\n \n @abstractmethod\n def write(self, *args, **kwargs) -> None: ...\n \n def clear(self) -> None: ...\n```\n\n| 方法 | 说明 | 返回值 |\n|------|------|--------|\n| `size` | 获取当前记忆存储的条目数量 | `int` |\n| `read()` | 读取记忆记录 | `List[MemoryRecord]` |\n| `write()` | 写入新的记忆记录 | `None` |\n| `clear()` | 清除所有记忆 | `None` |\n\n资料来源：[camel/memories/base.py]()\n\n### Agent记忆管理器 (AgentMemories)\n\n`AgentMemories`是Agent级别的记忆容器，负责整合多个记忆组件和上下文创建器：\n\n```python\nclass AgentMemories:\n def __init__(\n self,\n memories: List[Memory] = [],\n context_creator: Optional[ContextCreator] = None,\n ) -> None:\n self.memories: List[Memory] = memories\n self.context_creator = context_creator\n```\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `memories` | `List[Memory]` | 关联的记忆块列表 |\n| `context_creator` | `Optional[ContextCreator]` | 上下文创建器 |\n\n**核心功能**：\n- 管理多个记忆块的读写操作\n- 聚合多个Memory组件的记忆内容\n- 通过ContextCreator生成上下文摘要\n\n资料来源：[camel/memories/agent_memories.py]()\n\n## 存储块 (Blocks)\n\n存储块是实际存储记忆数据的组件，支持不同的存储后端和检索策略。\n\n### 聊天历史块 (ChatHistoryBlock)\n\n`ChatHistoryBlock`用于存储和管理Agent之间的对话历史记录：\n\n```python\nclass ChatHistoryBlock(Memory[ChatHistoryRecord]):\n def __init__(\n self,\n window_size: int = 0,\n max_tokens: int = 0,\n ) -> None:\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `window_size` | `int` | `0` | 滑动窗口大小，0表示不使用窗口 |\n| `max_tokens` | `int` | `0` | 最大token数限制 |\n\n**写入机制**：\n- 接收`ChatHistoryRecord`类型的记录\n- 支持基于窗口大小或token数量的自动截断\n- 保持对话顺序的时间序列\n\n**读取机制**：\n- 按时间顺序返回历史记录\n- 支持窗口截断和token限制\n\n资料来源：[camel/memories/blocks/chat_history_block.py]()\n\n### 向量数据库块 (VectorDBBlock)\n\n`VectorDBBlock`利用向量数据库实现语义相似度检索：\n\n```python\nclass VectorDBBlock(Memory[MemoryRecord]):\n def __init__(\n self,\n embedding_model: Optional[EmbeddingModel] = None,\n query_processor: Optional[QueryProcessor] = None,\n embedding_backend: Optional[EmbeddingModel] = None,\n storage: Optional[VectorDB] = None,\n k: int = 10,\n max_tokens: int = 0,\n ) -> None:\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `embedding_model` | `Optional[EmbeddingModel]` | 向量嵌入模型 |\n| `query_processor` | `Optional[QueryProcessor]` | 查询处理器 |\n| `storage` | `Optional[VectorDB]` | 向量数据库存储后端 |\n| `k` | `int` | 检索返回的最大结果数 |\n| `max_tokens` | `int` | 最大token数限制 |\n\n**检索流程**：\n1. 将输入查询转换为向量表示\n2. 在向量数据库中进行相似度搜索\n3. 返回Top-K个最相关的记忆记录\n\n资料来源：[camel/memories/blocks/vectordb_block.py]()\n\n## 记录类型 (Records)\n\n记录类型定义了记忆系统中各种数据的结构化格式。\n\n### ChatHistoryRecord\n\n```python\n@dataclass\nclass ChatHistoryRecord(MemoryRecord):\n role: str\n content: str\n message_type: RoleType\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `role` | `str` | 消息发送者角色 |\n| `content` | `str` | 消息内容 |\n| `message_type` | `RoleType` | 角色类型 |\n\n资料来源：[camel/memories/records.py]()\n\n## 上下文创建器 (Context Creators)\n\n上下文创建器负责从记忆系统中提取相关信息，生成供Agent使用的上下文提示。\n\n### 基于评分的上下文创建器 (ScoreBasedContextCreator)\n\n`ScoreBasedContextCreator`通过评分机制选择最相关的记忆片段：\n\n```python\nclass ScoreBasedContextCreator(ContextCreator):\n def __init__(\n self,\n model: Model,\n score_threshold: float = 0.5,\n max_context_tokens: int = 4096,\n ) -> None:\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model` | `Model` | 用于评分的语言模型 |\n| `score_threshold` | `float` | 评分阈值，默认0.5 |\n| `max_context_tokens` | `int` | 最大上下文token数 |\n\n**评分机制**：\n- 使用LLM评估每条记忆与当前查询的相关性\n- 过滤低于阈值的记忆记录\n- 按评分排序并截断至token限制\n\n资料来源：[camel/memories/context_creators/score_based.py]()\n\n## 工作流程\n\n### 记忆写入流程\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant AgentMemories\n participant Memory\n participant Block\n \n Agent->>AgentMemories: 添加新记录\n AgentMemories->>Memory: write(record)\n Memory->>Block: 存储记录\n Block->>Block: 格式化/截断\n Block-->>AgentMemories: 确认写入\n AgentMemories-->>Agent: 写入完成\n```\n\n### 上下文检索流程\n\n```mermaid\nsequenceDiagram\n participant Query\n participant ContextCreator\n participant Memory\n participant Block\n \n Query->>ContextCreator: 生成上下文请求\n ContextCreator->>Memory: read(query)\n Memory->>Block: 检索记录\n Block-->>Memory: 返回候选记录\n Memory-->>ContextCreator: 评分排序\n ContextCreator->>ContextCreator: 过滤和截断\n ContextCreator-->>Query: 返回上下文\n```\n\n## 使用示例\n\n### 基本使用\n\n```python\nfrom camel.memories import AgentMemories, ChatHistoryBlock\nfrom camel.memories.blocks import VectorDBBlock\n\n# 创建记忆块\nchat_history = ChatHistoryBlock(window_size=10)\nvector_store = VectorDBBlock(k=5)\n\n# 组合成Agent记忆\nagent_memories = AgentMemories(\n memories=[chat_history, vector_store]\n)\n\n# 写入对话记录\nagent_memories.memories[0].write(\n ChatHistoryRecord(\n role=\"user\",\n content=\"Hello, how are you?\",\n message_type=RoleType.USER\n )\n)\n\n# 读取记忆\nrecords = agent_memories.memories[0].read()\n```\n\n### 带上下文创建器的使用\n\n```python\nfrom camel.memories import AgentMemories, ContextCreator\nfrom camel.memories.context_creators import ScoreBasedContextCreator\n\n# 创建上下文创建器\ncontext_creator = ScoreBasedContextCreator(\n model=model,\n score_threshold=0.6,\n max_context_tokens=4096\n)\n\n# 创建带上下文的记忆管理\nagent_memories = AgentMemories(\n memories=[chat_history, vector_store],\n context_creator=context_creator\n)\n\n# 生成上下文\ncontext = agent_memories.context_creator.generate_context(\n query=\"What did we discuss about AI?\",\n memories=agent_memories.memories\n)\n```\n\n## 模块导出\n\n`camel/memories/__init__.py`模块导出以下公共接口：\n\n| 导出 | 说明 |\n|------|------|\n| `Memory` | 记忆抽象基类 |\n| `AgentMemories` | Agent记忆管理器 |\n| `ContextCreator` | 上下文创建器基类 |\n| `ChatHistoryRecord` | 聊天历史记录 |\n| `MemoryRecord` | 基础记忆记录 |\n\n资料来源：[camel/memories/__init__.py]()\n\n## 设计模式\n\n记忆系统采用了以下设计模式：\n\n1. **策略模式**：通过ContextCreator接口支持多种上下文生成策略\n2. **组合模式**：AgentMemories组合多个Memory组件统一管理\n3. **工厂模式**：通过参数化配置创建不同类型的存储块\n4. **适配器模式**：统一的Memory接口适配不同后端存储\n\n## 扩展指南\n\n### 自定义记忆块\n\n```python\nfrom camel.memories import Memory, MemoryRecord\n\nclass CustomMemoryBlock(Memory[CustomRecord]):\n def __init__(self, config: CustomConfig) -> None:\n self.config = config\n self._storage = []\n \n @property\n def size(self) -> int:\n return len(self._storage)\n \n def read(self, *args, **kwargs) -> List[CustomRecord]:\n # 实现读取逻辑\n return self._storage\n \n def write(self, *args, **kwargs) -> None:\n # 实现写入逻辑\n pass\n```\n\n### 自定义上下文创建器\n\n```python\nfrom camel.memories import ContextCreator\n\nclass CustomContextCreator(ContextCreator):\n def __init__(self, model: Model) -> None:\n self.model = model\n \n def generate_context(\n self,\n query: str,\n memories: List[Memory]\n ) -> str:\n # 实现自定义上下文生成逻辑\n pass\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：camel-ai/camel\n\n摘要：发现 19 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature Request] Expand WorkforceCallback to support stream chunk events。\n\n## 1. 安装坑 · 来源证据：[Feature Request] Expand WorkforceCallback to support stream chunk events\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature Request] Expand WorkforceCallback to support stream chunk events\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6e53abdf5bc6401d8d9e105ad6bc199f | https://github.com/camel-ai/camel/issues/3676 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：[Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5ca8493db7f140ca97d289664d6eb484 | https://github.com/camel-ai/camel/issues/1043 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：[Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_53427dbbe45a4c2dacf26673addcd0c4 | https://github.com/camel-ai/camel/issues/4045 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 4. 安全/权限坑 · 来源证据：[BUG] Both Bedrock options are broken\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Both Bedrock options are broken\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0dd321222ec44d14aa25d8cde3aeaef9 | https://github.com/camel-ai/camel/issues/4034 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安全/权限坑 · 来源证据：[Feature Request] Add OrcaRouter as a dedicated model platform\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Add OrcaRouter as a dedicated model platform\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9b8e4797fc294e8e8c795de01b5418da | https://github.com/camel-ai/camel/issues/4047 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 能力坑 · 社区讨论暴露的待验证问题：The best open source general AI agent is on !\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：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\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：social_signal:x | ssig_9705a4152aac4e7db1ec2472633ef681 | https://x.com/CamelAIOrg/status/1899069486587593176 | The best open source general AI agent is on !\n\n## 7. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:615510678 | https://github.com/camel-ai/camel | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 来源证据：v0.2.91a2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.2.91a2\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0c6ec0ec1a0a421a9dc7bf0e05814f20 | https://github.com/camel-ai/camel/releases/tag/v0.2.91a2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 来源证据：[Question] About the Deprecation of the `reasoning_content` Field in vLLM\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[Question] About the Deprecation of the `reasoning_content` Field in vLLM\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d44976120f444580a5a9afefb7711f0c | https://github.com/camel-ai/camel/issues/3939 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:615510678 | https://github.com/camel-ai/camel | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:615510678 | https://github.com/camel-ai/camel | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:615510678 | https://github.com/camel-ai/camel | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：v0.2.90\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_aacd3063c35745ea9cf8392274d9c53d | https://github.com/camel-ai/camel/releases/tag/v0.2.90 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：v0.2.90a4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90a4\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2c18897f1147431ea64419fef84398cc | https://github.com/camel-ai/camel/releases/tag/v0.2.90a4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：v0.2.90a5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90a5\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_defae93359fb4942a54fe8deedabdef8 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a5 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：v0.2.90a6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90a6\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a56ec216a5e84c3799b5d1a4a57ed4b3 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a6 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 18. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:615510678 | https://github.com/camel-ai/camel | issue_or_pr_quality=unknown\n\n## 19. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:615510678 | https://github.com/camel-ai/camel | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：camel-ai/camel\n\n摘要：发现 19 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature Request] Expand WorkforceCallback to support stream chunk events。\n\n## 1. 安装坑 · 来源证据：[Feature Request] Expand WorkforceCallback to support stream chunk events\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature Request] Expand WorkforceCallback to support stream chunk events\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6e53abdf5bc6401d8d9e105ad6bc199f | https://github.com/camel-ai/camel/issues/3676 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：[Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5ca8493db7f140ca97d289664d6eb484 | https://github.com/camel-ai/camel/issues/1043 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：[Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_53427dbbe45a4c2dacf26673addcd0c4 | https://github.com/camel-ai/camel/issues/4045 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 4. 安全/权限坑 · 来源证据：[BUG] Both Bedrock options are broken\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Both Bedrock options are broken\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0dd321222ec44d14aa25d8cde3aeaef9 | https://github.com/camel-ai/camel/issues/4034 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安全/权限坑 · 来源证据：[Feature Request] Add OrcaRouter as a dedicated model platform\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request] Add OrcaRouter as a dedicated model platform\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9b8e4797fc294e8e8c795de01b5418da | https://github.com/camel-ai/camel/issues/4047 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 能力坑 · 社区讨论暴露的待验证问题：The best open source general AI agent is on !\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：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\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：social_signal:x | ssig_9705a4152aac4e7db1ec2472633ef681 | https://x.com/CamelAIOrg/status/1899069486587593176 | The best open source general AI agent is on !\n\n## 7. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:615510678 | https://github.com/camel-ai/camel | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 来源证据：v0.2.91a2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.2.91a2\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0c6ec0ec1a0a421a9dc7bf0e05814f20 | https://github.com/camel-ai/camel/releases/tag/v0.2.91a2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 来源证据：[Question] About the Deprecation of the `reasoning_content` Field in vLLM\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[Question] About the Deprecation of the `reasoning_content` Field in vLLM\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d44976120f444580a5a9afefb7711f0c | https://github.com/camel-ai/camel/issues/3939 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:615510678 | https://github.com/camel-ai/camel | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:615510678 | https://github.com/camel-ai/camel | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:615510678 | https://github.com/camel-ai/camel | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：v0.2.90\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_aacd3063c35745ea9cf8392274d9c53d | https://github.com/camel-ai/camel/releases/tag/v0.2.90 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：v0.2.90a4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90a4\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2c18897f1147431ea64419fef84398cc | https://github.com/camel-ai/camel/releases/tag/v0.2.90a4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：v0.2.90a5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90a5\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_defae93359fb4942a54fe8deedabdef8 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a5 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：v0.2.90a6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.2.90a6\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a56ec216a5e84c3799b5d1a4a57ed4b3 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a6 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 18. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:615510678 | https://github.com/camel-ai/camel | issue_or_pr_quality=unknown\n\n## 19. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:615510678 | https://github.com/camel-ai/camel | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# camel - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 camel 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目简介。围绕“项目简介”模拟一次用户任务，不展示安装或运行结果。\n2. page-quickstart：快速入门指南。围绕“快速入门指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构设计。围绕“系统架构设计”模拟一次用户任务，不展示安装或运行结果。\n4. page-agents：智能体(Agents)。围绕“智能体(Agents)”模拟一次用户任务，不展示安装或运行结果。\n5. page-models：模型集成(Models)。围绕“模型集成(Models)”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quickstart\n输入：用户提供的“快速入门指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-agents\n输入：用户提供的“智能体(Agents)”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-models\n输入：用户提供的“模型集成(Models)”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quickstart：Step 2 必须围绕“快速入门指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构设计”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-agents：Step 4 必须围绕“智能体(Agents)”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-models：Step 5 必须围绕“模型集成(Models)”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/camel-ai/camel\n- https://github.com/camel-ai/camel#readme\n- .camel/skills/docs-incremental-update/SKILL.md\n- .camel/skills/skill-creator/SKILL.md\n- examples/toolkits/skill_toolkit_example/.camel/skills/code-reviewer/SKILL.md\n- examples/toolkits/skill_toolkit_example/.camel/skills/data-analyzer/SKILL.md\n- examples/toolkits/skill_toolkit_example/.camel/skills/report-writer/SKILL.md\n- README.md\n- pyproject.toml\n- camel/__init__.py\n- docs/get_started/installation.md\n- docs/get_started/setup.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 camel 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：camel-ai/camel\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install camel-ai\n```\n\n来源：https://github.com/camel-ai/camel#readme\n\n## 来源\n\n- repo: https://github.com/camel-ai/camel\n- docs: https://github.com/camel-ai/camel#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_9129c8f1f5da4fde9f5358e1caf44bf6"
}