{
"canonical_name": "camel-ai/camel",
"compilation_id": "pack_bdcf4e1aca8e4c1f983ce8704810a211",
"created_at": "2026-05-19T05:51:53.966126+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": "Structured Data Extraction",
"label_zh": "结构化数据提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-structured-data-extraction",
"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": "Developers should check this security_permissions risk before relying on the project: [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools",
"category": "安全/权限坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_5824c9dd1e33710f6821d3f625c9b2fb | https://github.com/camel-ai/camel/issues/3962 | [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools"
],
"severity": "high",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools. Context: Observed when using python, macos",
"title": "失败模式：security_permissions: [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit funct...",
"user_impact": "Developers may expose sensitive permissions or credentials: [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools"
},
{
"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 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_5736e8e2efc44fa48c0eea95b3bf0ff7 | https://github.com/camel-ai/camel/issues/4037 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary",
"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": "Developers should check this installation risk before relying on the project: [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_ac00b6564e4aa8e23d6fa0056cc45d02 | https://github.com/camel-ai/camel/issues/4037 | [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary. Context: Observed when using python",
"title": "失败模式：installation: [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter w...",
"user_impact": "Developers may fail before the first successful local run: [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary"
},
{
"body": "Developers should check this installation risk before relying on the project: [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_b869fb190d161706644bb5c7e94bff8f | https://github.com/camel-ai/camel/issues/1043 | [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators",
"failure_mode_cluster:github_issue | fmev_e2d8786f2a91f791c3d6c7a2c4207d65 | https://github.com/camel-ai/camel/issues/1043 | [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators. Context: Observed during installation or first-run setup.",
"title": "失败模式：installation: [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators",
"user_impact": "Developers may fail before the first successful local run: [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators"
},
{
"body": "Developers should check this installation risk before relying on the project: v0.2.90",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_6bc0695558dc4dc7fb064fa89c64c718 | https://github.com/camel-ai/camel/releases/tag/v0.2.90 | v0.2.90"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: v0.2.90. Context: Source discussion did not expose a precise runtime context.",
"title": "失败模式：installation: v0.2.90",
"user_impact": "Upgrade or migration may change expected behavior: v0.2.90"
},
{
"body": "Developers should check this configuration risk before relying on the project: [BUG] Both Bedrock options are broken",
"category": "配置坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_b5a875260984ae51f7f9b81869057a15 | https://github.com/camel-ai/camel/issues/4034 | [BUG] Both Bedrock options are broken"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: [BUG] Both Bedrock options are broken. Context: Observed when using python",
"title": "失败模式：configuration: [BUG] Both Bedrock options are broken",
"user_impact": "Developers may misconfigure credentials, environment, or host setup: [BUG] Both Bedrock options are broken"
},
{
"body": "Developers should check this configuration risk before relying on the project: [Feature Request] Add OrcaRouter as a dedicated model platform",
"category": "配置坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_9bce4812aa6a39fc876b639a79f00c41 | https://github.com/camel-ai/camel/issues/4047 | [Feature Request] Add OrcaRouter as a dedicated model platform",
"failure_mode_cluster:github_issue | fmev_fefb71c23b8534f3eac0377e0a8ea5b2 | https://github.com/camel-ai/camel/issues/4047 | [Feature Request] Add OrcaRouter as a dedicated model platform"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: [Feature Request] Add OrcaRouter as a dedicated model platform. Context: Source discussion did not expose a precise runtime context.",
"title": "失败模式：configuration: [Feature Request] Add OrcaRouter as a dedicated model platform",
"user_impact": "Developers may misconfigure credentials, environment, or host setup: [Feature Request] Add OrcaRouter as a dedicated model platform"
},
{
"body": "Developers should check this configuration risk before relying on the project: [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)",
"category": "配置坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_ab8611c09187bc446ab4c53a8bbcc224 | https://github.com/camel-ai/camel/issues/3997 | [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter). Context: Source discussion did not expose a precise runtime context.",
"title": "失败模式：configuration: [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)",
"user_impact": "Developers may misconfigure credentials, environment, or host setup: [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)"
},
{
"body": "Developers should check this configuration risk before relying on the project: v0.2.90a6",
"category": "配置坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_39f1f2bb3b67152c4f05563686719964 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a6 | v0.2.90a6"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: v0.2.90a6. Context: Source discussion did not expose a precise runtime context.",
"title": "失败模式：configuration: v0.2.90a6",
"user_impact": "Upgrade or migration may change expected behavior: v0.2.90a6"
},
{
"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": "假设不成立时，用户拿不到承诺的能力。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 38 个潜在踩坑项，其中 7 个为 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> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for camel-ai/camel.\n\nProject:\n- Name: camel\n- Repository: https://github.com/camel-ai/camel\n- Summary: 🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: 🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-introduction: Introduction to CAMEL. Produce one small intermediate artifact and wait for confirmation.\n2. page-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n3. page-agents: Agent Types and System. Produce one small intermediate artifact and wait for confirmation.\n4. page-models: Model Integration and Providers. Produce one small intermediate artifact and wait for confirmation.\n5. page-toolkits: Tools and Toolkits. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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- camel/__init__.py\n- camel/utils/constants.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: [BUG] CodeExecutionToolkit can run model-produced Python code through Su（https://github.com/camel-ai/camel/issues/4037）；github/github_issue: [Feature Request] Refactor to use `api_keys_required` and `dependencies_（https://github.com/camel-ai/camel/issues/1043）；github/github_issue: [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read（https://github.com/camel-ai/camel/issues/3997）；github/github_issue: [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent wit（https://github.com/camel-ai/camel/issues/3962）；github/github_issue: [Feature Request] Add OrcaRouter as a dedicated model platform（https://github.com/camel-ai/camel/issues/4047）；github/github_issue: [BUG] outdated colab notebook for workforce（https://github.com/camel-ai/camel/issues/3402）；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）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "[BUG] CodeExecutionToolkit can run model-produced Python code through Su",
"url": "https://github.com/camel-ai/camel/issues/4037"
},
{
"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": "[feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read",
"url": "https://github.com/camel-ai/camel/issues/3997"
},
{
"kind": "github_issue",
"source": "github",
"title": "[BUG] Bedrock Converse validation failure when using CAMEL ChatAgent wit",
"url": "https://github.com/camel-ai/camel/issues/3962"
},
{
"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": "[BUG] outdated colab notebook for workforce",
"url": "https://github.com/camel-ai/camel/issues/3402"
},
{
"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"
}
],
"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-15 13:08:22 UTC\n\n## 目录\n\n- [Introduction to CAMEL](#page-introduction)\n- [System Architecture](#page-architecture)\n- [Agent Types and System](#page-agents)\n- [Model Integration and Providers](#page-models)\n- [Tools and Toolkits](#page-toolkits)\n- [Multi-Agent Societies and Role Playing](#page-societies)\n- [Workforce Management](#page-workforce)\n- [Memory Management](#page-memory)\n- [Storage Systems](#page-storage)\n- [Data Generation](#page-datagen)\n\n\n\n## Introduction to CAMEL\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Model Integration and Providers](#page-models)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/camel-ai/camel/blob/main/README.md)\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/aci_mcp/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/aci_mcp/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- [apps/agents/README.md](https://github.com/camel-ai/camel/blob/main/apps/agents/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- [examples/usecases/cloudfare_mcp_camel/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/cloudfare_mcp_camel/README.md)\n \n\n# Introduction to CAMEL\n\nCAMEL (Communicative Agents for Machine Intelligence) is an open-source multi-agent reasoning framework designed to enable autonomous cooperation and communication between AI agents. The framework provides infrastructure for building, deploying, and orchestrating AI agents that can work together to solve complex tasks through role-playing, tool use, and structured dialogue protocols.\n\n## Overview\n\nCAMEL is a framework that facilitates the development of multi-agent systems where AI agents can assume specific roles, communicate with each other, and collaboratively accomplish tasks. The framework implements the concept of \"role-playing\" where agents are assigned distinct personas and responsibilities, enabling them to handle specialized aspects of complex workflows.\n\n资料来源：[README.md](https://github.com/camel-ai/camel/blob/main/README.md)\n\n## Core Architecture\n\n### Agent System Components\n\nThe CAMEL framework is built around several key components that work together to enable multi-agent cooperation:\n\n| Component | Purpose | Description |\n|-----------|---------|-------------|\n| `RolePlaying` | Orchestration | Manages the interaction between agents with different roles |\n| `ChatAgent` | Execution | Handles individual agent conversations and responses |\n| `Toolkits` | Extensibility | Provides domain-specific capabilities (PPTX, web scraping, etc.) |\n| `MCP Integration` | External Connectivity | Connects to Model Context Protocol servers for additional tools |\n| `ModelFactory` | Abstraction | Creates model instances across different providers |\n\n资料来源：[examples/usecases/aci_mcp/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/aci_mcp/README.md)\n\n### Architecture Flow\n\n```mermaid\ngraph TD\n A[User Request] --> B[RolePlaying Orchestrator]\n B --> C1[AI Assistant Agent]\n B --> C2[AI User Agent]\n C1 <--> C2[Structured Communication]\n C1 --> D1[Toolkits]\n C2 --> D2[External APIs]\n D1 --> E[Task Completion]\n D2 --> E\n```\n\n## Key Features\n\n### Role-Playing System\n\nCAMEL implements a role-playing architecture where agents are assigned specific roles and responsibilities. This enables:\n\n- **Specialized Task Handling**: Different agents handle different aspects of a complex task\n- **Structured Communication**: Agents communicate through defined protocols\n- **Collaborative Problem Solving**: Multiple agents work together to reach solutions\n\n资料来源：[apps/agents/README.md](https://github.com/camel-ai/camel/blob/main/apps/agents/README.md)\n\n### Tool Integration\n\nCAMEL provides extensive tool integration capabilities through various toolkits:\n\n| Toolkit | Use Case | External Dependency |\n|---------|----------|---------------------|\n| `PPTXToolkit` | PowerPoint generation | OpenAI API |\n| `Mistral OCR` | Document text extraction | Mistral API |\n| `Firecrawl` | Web scraping | Firecrawl API |\n| `MCP Servers` | External tool connectivity | Various MCP providers |\n\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### Multi-Agent Research Assistant\n\nOne of the primary use cases for CAMEL is the multi-agent research assistant, which demonstrates:\n\n1. **Topic Analysis**: Identifying relevant research areas\n2. **Information Retrieval**: Gathering academic papers and news\n3. **Report Generation**: Creating comprehensive research reports\n4. **Content Enhancement**: Generating illustrative images\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## Supported Platforms and Integrations\n\n### Code Platforms\n\nCAMEL integrates with popular coding platforms to solve programming problems:\n\n- **Codeforces**: Solves competitive programming problems using problem IDs\n- **LeetCode**: Handles algorithm challenges using problem slugs\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### External Services\n\nCAMEL connects to various external services through MCP (Model Context Protocol):\n\n```mermaid\ngraph LR\n A[CAMEL Framework] --> B[MCP Server Layer]\n B --> C1[Airbnb MCP]\n B --> C2[Cloudflare MCP]\n B --> C3[ACI.dev MCP]\n B --> C4[Github MCP]\n C1 --> D1[Booking Data]\n C2 --> D2[Internet Analytics]\n C3 --> D3[Search & APIs]\n C4 --> D4[Repository Data]\n```\n\n资料来源：[examples/usecases/cloudfare_mcp_camel/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/cloudfare_mcp_camel/README.md)\n\n### Runtime Environments\n\nCAMEL supports multiple runtime environments:\n\n| Environment | Description | Use Case |\n|-------------|-------------|----------|\n| Docker | Containerized execution | Scalable deployments |\n| Streamlit | Web application UI | Interactive demos |\n| Gradio | ML model interfaces | Data exploration |\n| HuggingFace Spaces | Cloud deployment | Public hosting |\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## Supported AI Models\n\nCAMEL provides flexibility in model selection through the `ModelFactory`:\n\n| Model Platform | Model Types | Configuration |\n|----------------|-------------|---------------|\n| OpenAI | GPT-4, GPT-4o | API key authentication |\n| Google Gemini | Gemini 2.5 Pro | API key authentication |\n| OpenAI Compatible | Qwen, custom models | URL + model specification |\n| Mistral | Mistral OCR | API key authentication |\n\n资料来源：[examples/usecases/aci_mcp/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/aci_mcp/README.md)\n\n## Project Structure\n\n```\ncamel/\n├── camel/ # Core framework\n│ ├── __init__.py # Main package exports\n│ └── utils/ # Utilities and constants\n├── apps/ # Standalone applications\n│ ├── agents/ # Gradio agent app\n│ └── data_explorer/ # Dataset browsing tool\n├── examples/ # Usage examples\n│ ├── runtimes/ # Runtime configurations\n│ └── usecases/ # Application use cases\n└── services/ # Backend services\n```\n\n## Installation and Setup\n\n### Basic Installation\n\n```bash\n# Install core package\npip install camel-ai\n\n# Install with all dependencies\npip install camel-ai[all]\n\n# Install specific version\npip install camel-ai[all]==0.2.61\n```\n\n### Environment Configuration\n\nRequired environment variables depend on the use case:\n\n| Variable | Purpose | Required For |\n|----------|---------|--------------|\n| `OPENAI_API_KEY` | OpenAI models | Most use cases |\n| `GEMINI_API_KEY` | Google Gemini models | ACI integration |\n| `FIRECRAWL_API_KEY` | Web scraping | Code solver |\n| `MISTRAL_API_KEY` | OCR functionality | Document processing |\n\n## Deployment Options\n\n### Streamlit Applications\n\nMany CAMEL use cases are deployed as Streamlit applications:\n\n```bash\nstreamlit run app.py\n```\n\nThis launches an interactive web interface for the specific application.\n\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### HuggingFace Spaces\n\nThe agents application can be deployed to HuggingFace Spaces for public access. The deployment process involves:\n\n1. Tagging the commit with `hf_spaces_{X+1}`\n2. Synchronizing with the HF repository\n3. Automatic deployment via HF infrastructure\n\n资料来源：[apps/agents/README.md](https://github.com/camel-ai/camel/blob/main/apps/agents/README.md)\n\n### Docker Runtime\n\nFor containerized deployments:\n\n```bash\nchmod +x manage_camel_docker.sh\n./manage_camel_docker.sh build\n```\n\n## Use Case Workflow\n\n### Multi-Agent Research Assistant Workflow\n\n```mermaid\ngraph TD\n A[User Input: Research Topic] --> B[Topic Analysis Agent]\n B --> C[Researcher Identification]\n C --> D[Paper Retrieval]\n D --> E[News Collection]\n E --> F[Report Generation]\n F --> G[Image Generation]\n G --> H[LinkedIn Preparation]\n H --> I[Final Report Output]\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### Web Content Processing Workflow\n\n```mermaid\ngraph TD\n A[URL Input] --> B[Firecrawl/MCP Browser]\n B --> C[Content Fetching]\n C --> D[Markdown Conversion]\n D --> E[AI Analysis]\n E --> F[Response Generation]\n```\n\n## Error Handling and Debugging\n\nCAMEL applications include comprehensive error handling:\n\n- **Detailed Tracebacks**: Full error context for debugging\n- **API Error Handling**: Graceful handling of external service failures\n- **Permission Checks**: Validation of file and configuration permissions\n- **Network Diagnostics**: Connectivity verification for API calls\n\n资料来源：[examples/usecases/cloudfare_mcp_camel/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/cloudfare_mcp_camel/README.md)\n\n## License\n\nCAMEL is licensed under the Apache License, Version 2.0, allowing for both commercial and open-source use with appropriate attribution.\n\n资料来源：[examples/usecases/aci_mcp/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/aci_mcp/README.md)\n\n## Community and Resources\n\nCAMEL is maintained by the CAMEL-AI.org community and provides:\n\n- Comprehensive documentation through example use cases\n- Multiple deployment options for different environments\n- Integration with popular AI services and platforms\n- Extensible architecture for custom agent implementations\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Introduction to CAMEL](#page-introduction), [Agent Types and System](#page-agents), [Workforce Management](#page-workforce)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/agents/chat_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/chat_agent.py)\n- [camel/agents/base.py](https://github.com/camel-ai/camel/blob/main/camel/agents/base.py)\n- [camel/messages/base.py](https://github.com/camel-ai/camel/blob/main/camel/messages/base.py)\n- [camel/responses/agent_responses.py](https://github.com/camel-ai/camel/blob/main/camel/responses/agent_responses.py)\n- [camel/terminators/response_terminator.py](https://github.com/camel-ai/camel/blob/main/camel/terminators/response_terminator.py)\n- [camel/terminators/token_limit_terminator.py](https://github.com/camel-ai/camel/blob/main/camel/terminators/token_limit_terminator.py)\n \n\n# System Architecture\n\n## Overview\n\nCAMEL (Communicative Agents for Multi-Agent Learning) is a foundational multi-agent framework designed to enable autonomous cooperation among LLM-based agents. The system architecture follows a modular design pattern that separates concerns between agent orchestration, message passing, response handling, and termination conditions. This architecture supports various use cases including role-playing, research assistance, web scraping, and integration with external tools through Model Context Protocol (MCP) servers. 资料来源：[examples/usecases/multi_agent_research_assistant/README.md]()\n\nThe core architectural philosophy emphasizes:\n\n- **Separation of concerns**: Agents, messages, responses, and terminators are distinct modules with well-defined responsibilities\n- **Extensibility**: The base classes allow for custom agent implementations and termination strategies\n- **Composability**: Multiple agents can collaborate in workflows while maintaining independent state\n- **Resource awareness**: Built-in token limit handling prevents excessive resource consumption\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph \"Agent Layer\"\n CA[ChatAgent]\n BA[BaseAgent]\n end\n \n subgraph \"Message Layer\"\n MB[Message Base]\n UM[UserMessage]\n AM[AssistantMessage]\n SM[SystemMessage]\n end\n \n subgraph \"Response Layer\"\n AR[AgentResponses]\n RR[ResponseTerminator]\n TL[TokenLimitTerminator]\n end\n \n subgraph \"External Integration\"\n MCP[MCP Servers]\n TOOLS[Toolkits]\n end\n \n CA --> BA\n CA --> MB\n CA --> AR\n AR --> RR\n AR --> TL\n CA --> MCP\n CA --> TOOLS\n```\n\n## Core Components\n\n### 1. Agent System\n\n#### BaseAgent\n\nThe `BaseAgent` class serves as the foundational abstraction for all agent implementations in CAMEL. It defines the core interface and lifecycle methods that derived agents must implement. The base agent handles fundamental operations such as:\n\n- Agent initialization and configuration\n- State management across conversation turns\n- Message routing and processing\n- Integration with underlying LLM backends\n\n资料来源：[camel/agents/base.py:1-50]()\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `model` | `BaseModel` | The underlying language model instance |\n| `message_history` | `List[BaseMessage]` | Accumulated conversation history |\n| `system_message` | `SystemMessage` | Agent-specific system instructions |\n| `max_retries` | `int` | Maximum retry attempts for failed operations |\n\n#### ChatAgent\n\nThe `ChatAgent` extends `BaseAgent` to provide chat-specific functionality optimized for conversational interactions. It implements the core step mechanism that processes incoming messages and generates responses.\n\n```python\nclass ChatAgent(BaseAgent):\n def __init__(self, system_message: SystemMessage, model: BaseModel, ...):\n ...\n \n def step(self, message: UserMessage) -> ChatAgentResponse:\n ...\n```\n\n资料来源：[camel/agents/chat_agent.py:50-100]()\n\n**Key Responsibilities:**\n\n1. **Step Execution**: Processes a single conversation turn by receiving a user message, updating context, and returning an agent response\n2. **History Management**: Maintains and optionally truncates conversation history to stay within token limits\n3. **Response Generation**: Orchestrates the LLM call and processes the generated response\n4. **Tool Integration**: Supports function calling and external tool execution when configured\n\n资料来源：[camel/agents/chat_agent.py:100-150]()\n\n### 2. Message System\n\n#### Message Base Structure\n\nAll messages in CAMEL inherit from `BaseMessage`, which provides a standardized structure for communication between agents and external systems.\n\n```mermaid\nclassDiagram\n class BaseMessage {\n +str role\n +str content\n +Dict metadata\n +str id\n +float token_ratio\n }\n \n class UserMessage {\n +str role = \"user\"\n }\n \n class AssistantMessage {\n +str role = \"assistant\"\n +Optional~List[FunctionCall]~ tool_calls\n }\n \n class SystemMessage {\n +str role = \"system\"\n }\n \n BaseMessage <|-- UserMessage\n BaseMessage <|-- AssistantMessage\n BaseMessage <|-- SystemMessage\n```\n\n资料来源：[camel/messages/base.py:1-80]()\n\n| Message Type | Role Value | Purpose |\n|--------------|------------|---------|\n| `UserMessage` | `\"user\"` | Input from human users or external systems |\n| `AssistantMessage` | `\"assistant\"` | Responses generated by the LLM |\n| `SystemMessage` | `\"system\"` | System-level instructions and prompts |\n| `ToolMessage` | `\"tool\"` | Results from tool executions |\n\n#### Message Flow\n\n```mermaid\ngraph LR\n UM[UserMessage] -->|Input| CA[ChatAgent]\n CA -->|Process| LLM[Language Model]\n LLM -->|Raw Response| CA\n CA -->|Parsed| AM[AssistantMessage]\n AM -->|Output| UM2[Next UserMessage]\n```\n\n### 3. Response Handling\n\n#### AgentResponses\n\nThe response system encapsulates all data returned from agent operations. `AgentResponses` provides a structured container for multiple message types and metadata generated during a single agent step.\n\n资料来源：[camel/responses/agent_responses.py:1-60]()\n\n**Response Components:**\n\n| Component | Type | Description |\n|-----------|------|-------------|\n| `msgs` | `List[BaseMessage]` | Generated messages (assistant, tool, etc.) |\n| `terminated` | `bool` | Whether the response terminated due to a condition |\n| `termination_reasons` | `List[str]` | Reasons for termination if applicable |\n| `info` | `Dict[str, Any]` | Additional metadata about the step |\n\n资料来源：[camel/responses/agent_responses.py:60-120]()\n\n### 4. Termination System\n\nThe termination system determines when an agent should stop processing or when a conversation should end. CAMEL implements a flexible terminator pattern that supports multiple termination conditions.\n\n#### ResponseTerminator\n\nThe `ResponseTerminator` evaluates response content to determine if a stop condition has been met. This includes checking for explicit stop phrases, completion markers, or other user-defined conditions.\n\n```mermaid\ngraph TD\n R[Response Received] --> C{Check Conditions}\n C -->|Stop Phrase| T[Terminate]\n C -->|Completion| T\n C -->|Token Limit| T\n C -->|Continue| P[Process Next Step]\n```\n\n资料来源：[camel/terminators/response_terminator.py:1-50]()\n\n| Terminator Type | Trigger Condition | Use Case |\n|-----------------|-------------------|----------|\n| `ResponseTerminator` | Content matches stop patterns | Custom stop phrases |\n| `TokenLimitTerminator` | Token count exceeds threshold | Resource management |\n| `MaxStepsTerminator` | Step count reaches limit | Loop prevention |\n\n#### TokenLimitTerminator\n\nThe `TokenLimitTerminator` enforces token budget constraints to prevent excessive API usage and maintain cost efficiency. It monitors cumulative token usage across the conversation.\n\n资料来源：[camel/terminators/token_limit_terminator.py:1-40]()\n\n**Configuration Options:**\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `max_tokens` | `4096` | Maximum tokens per response |\n| `max_history_tokens` | `8192` | Maximum tokens in history |\n| `token_buffer_ratio` | `0.1` | Safety buffer for token calculations |\n\n## Agent Workflow\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant CA as ChatAgent\n participant LM as Language Model\n participant RT as ResponseTerminator\n participant TL as TokenLimitTerminator\n \n U->>CA: UserMessage\n CA->>CA: Prepare Context\n CA->>LM: Generate Response\n LM-->>CA: Raw Response\n CA->>RT: Check Termination\n RT-->>CA: Continue/Terminate\n CA->>TL: Check Token Limits\n TL-->>CA: Within Limits/Exceeds\n CA->>CA: Update History\n CA-->>U: AgentResponse\n```\n\n## MCP Server Integration\n\nCAMEL agents can integrate with external systems through the Model Context Protocol (MCP). The agent server exposes tools and resources that agents can invoke during conversations.\n\n资料来源：[services/README.md:1-50]()\n\n**Available Tools:**\n\n- `step`: Execute a single conversation step with a specified agent\n- `reset`: Reset all agents to their initial state\n- `set_output_language`: Set the output language for all agents\n- `get_agents_info`: Get information about all available agents\n- `get_chat_history`: Retrieve chat history for a specific agent\n\n资料来源：[services/README.md:50-100]()\n\n**MCP Client Configuration:**\n\n```json\n{\n \"camel-agents\": {\n \"command\": \"/path/to/your/python\",\n \"args\": [\"/path/to/camel/services/agent_mcp_server.py\"],\n \"env\": {\n \"OPENAI_API_KEY\": \"...\",\n \"OPENROUTER_API_KEY\": \"...\",\n \"BRAVE_API_KEY\": \"...\"\n }\n }\n}\n```\n\n## Toolkit Architecture\n\nCAMEL provides specialized toolkits that extend agent capabilities. Each toolkit follows a consistent interface pattern for seamless integration.\n\n```mermaid\ngraph TD\n subgraph \"Toolkits\"\n PPTX[PPTXToolkit]\n BROWSER[HybridBrowserToolkit]\n SEARCH[WebSearchToolkit]\n end\n \n subgraph \"Use Cases\"\n CF[Codeforces Solver]\n RA[Research Assistant]\n YT[YouTube Chat]\n end\n \n BROWSER -->|Browser Automation| CF\n PPTX -->|Presentation Gen| RA\n SEARCH -->|Web Content| YT\n```\n\n### HybridBrowserToolkit\n\nThe browser toolkit enables agents to interact with web content through a controlled browser session. It supports complex interactions like form filling, element waiting, and snapshot comparison.\n\n资料来源：[camel/toolkits/hybrid_browser_toolkit/ts/src/browser-session.ts:1-50]()\n\n**Key Features:**\n\n- Element-based interaction with automatic retry\n- Snapshot-based change detection\n- Automatic scrolling and visibility handling\n- Support for input, textarea, and dropdown elements\n\n## State Management\n\nAgents maintain state across conversation turns through several mechanisms:\n\n| State Component | Storage | Purpose |\n|-----------------|---------|---------|\n| `message_history` | In-memory list | Conversation context |\n| `agent_info` | Dictionary | Agent metadata |\n| `chat_history` | Per-agent storage | Historical conversations |\n| `available_tools` | Dynamic list | Current toolset |\n\n## Configuration and Initialization\n\n### Agent Initialization Pattern\n\n```python\n# Create model instance\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# Initialize chat agent\nagent = ChatAgent(\n system_message=SystemMessage(content=\"You are a helpful assistant.\"),\n model=model,\n max_retries=3\n)\n```\n\n资料来源：[examples/runtimes/ubuntu_docker_runtime/README.md:1-30]()\n\n### Streamlit Application Pattern\n\nFor UI-based applications, CAMEL integrates with Streamlit to provide interactive interfaces:\n\n```bash\nstreamlit run app.py\n```\n\n资料来源：[examples/usecases/codeforces_question_solver/README.md:1-20]()\n\n## Extension Points\n\n### Custom Terminators\n\nDevelopers can create custom terminators by implementing the `ResponseTerminator` interface:\n\n1. Extend the base terminator class\n2. Implement the `should_terminate()` method\n3. Register the terminator with the agent\n\n### Custom Agents\n\nThe `BaseAgent` class provides extension points for:\n\n- Custom message processing logic\n- Specialized tool integration\n- Domain-specific response handling\n\n## Deployment Architecture\n\nCAMEL supports multiple deployment configurations:\n\n| Deployment Mode | Use Case | Configuration |\n|-----------------|----------|---------------|\n| Standalone Python | Development/Testing | Direct import |\n| Docker Runtime | Production/Cloud | Containerized execution |\n| MCP Server | External Integration | Network-accessible service |\n| Streamlit App | User-facing Interface | Web-based UI |\n\n### Docker Runtime\n\nThe Docker runtime provides isolated execution environments with consistent dependencies:\n\n```bash\n./manage_camel_docker.sh build\ndocker images | grep my-camel\n```\n\n资料来源：[examples/runtimes/ubuntu_docker_runtime/README.md:20-40]()\n\n## Security Considerations\n\n- API keys are managed through environment variables, never hardcoded\n- MCP server configurations support both local and remote execution\n- Token limit terminators prevent runaway resource consumption\n- Browser automation includes robots.txt compliance options\n\n## Performance Optimization\n\n1. **Token Budget Management**: Automatic history truncation maintains efficiency\n2. **Concurrent Execution**: Multi-agent workflows can run in parallel\n3. **Caching**: Model responses can be cached for repeated queries\n4. **Snapshot Differencing**: Browser automation uses efficient diff algorithms\n\n## Related Documentation\n\n- [Agent MCP Server](services/README.md) - External agent access via MCP\n- [Multi-Agent Research Assistant](../examples/usecases/multi_agent_research_assistant/README.md) - Production use case example\n- [Ubuntu Docker Runtime](../examples/runtimes/ubuntu_docker_runtime/README.md) - Containerized deployment\n\n---\n\n\n\n## Agent Types and System\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Model Integration and Providers](#page-models), [Tools and Toolkits](#page-toolkits), [Multi-Agent Societies and Role Playing](#page-societies)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/agents/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/agents/__init__.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/task_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/task_agent.py)\n- [camel/agents/search_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/search_agent.py)\n- [camel/agents/embodied_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/embodied_agent.py)\n- [camel/agents/knowledge_graph_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/knowledge_graph_agent.py)\n- [camel/agents/mcp_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/mcp_agent.py)\n- [camel/agents/repo_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/repo_agent.py)\n- [camel/agents/role_assignment_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/role_assignment_agent.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# Agent Types and System\n\nThe CAMEL framework provides a comprehensive multi-agent system with specialized agent types designed for different tasks and use cases. Agents are the fundamental building blocks that interact within the CAMEL ecosystem, enabling complex workflows through role-playing, task decomposition, and collaborative reasoning.\n\n## Overview\n\nCAMEL's agent architecture follows a modular design pattern where different agent types inherit from a base `ChatAgent` class and specialize for specific domains. Each agent type encapsulates particular capabilities, tools, and behaviors tailored to its intended purpose.\n\n```mermaid\ngraph TD\n Base[ChatAgent Base Class] --> ChatAgent\n Base --> TaskAgent\n Base --> CriticAgent\n Base --> SearchAgent\n Base --> EmbodiedAgent\n Base --> KnowledgeGraphAgent\n Base --> MCPAgent\n Base --> RepoAgent\n Base --> RoleAssignmentAgent\n \n ChatAgent[ChatAgent
General conversation]\n TaskAgent[TaskAgent
Task execution]\n CriticAgent[CriticAgent
Evaluation & critique]\n SearchAgent[SearchAgent
Web search]\n EmbodiedAgent[EmbodiedAgent
Browser automation]\n KnowledgeGraphAgent[KnowledgeGraphAgent
Knowledge graphs]\n MCPAgent[MCPAgent
MCP protocol]\n RepoAgent[RepoAgent
Repository analysis]\n RoleAssignmentAgent[RoleAssignmentAgent
Role assignment]\n```\n\n资料来源：[camel/agents/__init__.py:1-50]()\n\n## Agent Type Catalog\n\n### ChatAgent\n\nThe `ChatAgent` is the foundational agent class that provides general-purpose conversation and task execution capabilities. All other agent types ultimately inherit from or delegate to this base class.\n\n**Key Features:**\n- Message-based interaction with LLMs\n- Tool execution framework\n- Structured output handling\n- Conversation memory management\n\n资料来源：[camel/agents/chat_agent.py:1-100]()\n\n### TaskAgent\n\nThe `TaskAgent` specializes in decomposing and executing complex tasks. It breaks down user requests into actionable steps and coordinates execution across multiple tools.\n\n**Capabilities:**\n- Task decomposition\n- Step-by-step execution planning\n- Tool orchestration\n- Result aggregation\n\n资料来源：[camel/agents/task_agent.py:1-100]()\n\n### CriticAgent\n\nThe `CriticAgent` evaluates and critiques outputs from other agents, providing quality assurance and feedback mechanisms. It plays a crucial role in multi-agent verification workflows.\n\n**Responsibilities:**\n- Output validation\n- Quality scoring\n- Constructive feedback generation\n- Error detection\n\n资料来源：[camel/agents/critic_agent.py:1-100]()\n\n### SearchAgent\n\nThe `SearchAgent` provides web search capabilities, enabling agents to retrieve up-to-date information from the internet.\n\n**Features:**\n- Web search integration\n- Result parsing and summarization\n- Citation generation\n\n资料来源：[camel/agents/search_agent.py:1-100]()\n\n### EmbodiedAgent\n\nThe `EmbodiedAgent` extends agent capabilities to browser automation, allowing agents to interact with web pages through a structured browser toolkit.\n\n**Capabilities:**\n- Web page navigation\n- Element interaction (click, fill, scroll)\n- Screenshot capture\n- DOM snapshot analysis\n\n```python\n# EmbodiedAgent initialization example\nagent = EmbodiedAgent(\n tool_kit=[browser_toolkit],\n model=model\n)\n```\n\n资料来源：[camel/agents/embodied_agent.py:1-100]()\n\n### KnowledgeGraphAgent\n\nThe `KnowledgeGraphAgent` manages structured knowledge representations, enabling agents to work with entity relationships and graph-based data.\n\n**Features:**\n- Entity creation and management\n- Relationship modeling\n- Graph traversal\n- Query execution\n\n资料来源：[camel/agents/knowledge_graph_agent.py:1-100]()\n\n### MCPAgent\n\nThe `MCPAgent` implements the Model Context Protocol (MCP), allowing integration with external MCP servers and tools. This enables CAMEL agents to leverage a wide ecosystem of MCP-compatible tools.\n\n**Capabilities:**\n- MCP server connection\n- Tool discovery\n- Remote tool execution\n- Streaming response handling\n\n```python\n# MCPAgent configuration\nagent = MCPAgent(\n mcp_server_config=mcp_config,\n model=model\n)\n```\n\n资料来源：[camel/agents/mcp_agent.py:1-100]()\n\n### RepoAgent\n\nThe `RepoAgent` specializes in analyzing and understanding code repositories. It can inspect file structures, read code, and provide repository-level insights.\n\n**Features:**\n- Repository structure analysis\n- Code file reading and parsing\n- Git history inspection\n- Dependency analysis\n\n资料来源：[camel/agents/repo_agent.py:1-100]()\n\n### RoleAssignmentAgent\n\nThe `RoleAssignmentAgent` handles dynamic role assignment in multi-agent systems, determining which agent should handle specific tasks based on capabilities and availability.\n\n**Responsibilities:**\n- Role matching\n- Capability assessment\n- Task routing\n\n资料来源：[camel/agents/role_assignment_agent.py:1-100]()\n\n## Persona System\n\nThe persona system in CAMEL defines agent identities through the `Persona` class and `PersonaHub` repository.\n\n```mermaid\nclassDiagram\n class Persona {\n +str name\n +str description\n +str instruction\n +str example\n +to_role_playing_instruction() str\n }\n \n class PersonaHub {\n +dict personas\n +get(name: str) Persona\n +list_all() List~str~\n }\n \n PersonaHub o-- Persona : contains\n```\n\n### Persona Class\n\nRepresents an agent's identity with the following attributes:\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `name` | `str` | Unique identifier for the persona |\n| `description` | `str` | Brief description of the persona |\n| `instruction` | `str` | Core instructions for the persona |\n| `example` | `str` | Example behavior or output |\n\n资料来源：[camel/personas/persona.py:1-80]()\n\n### PersonaHub\n\nProvides a centralized repository of predefined personas for common use cases.\n\n**Usage:**\n```python\nfrom camel.personas.persona_hub import PersonaHub\n\nhub = PersonaHub()\nassistant_persona = hub.get(\"assistant\")\ncoder_persona = hub.get(\"coder\")\n```\n\n资料来源：[camel/personas/persona_hub.py:1-150]()\n\n## Agent Execution Flow\n\nAgents in CAMEL follow a standardized execution pattern:\n\n```mermaid\nsequenceDiagram\n participant User\n participant Agent\n participant ToolKit\n participant LLM\n \n User->>Agent: UserMessage\n Agent->>LLM: Process Message\n LLM-->>Agent: Reasoning Result\n Agent->>ToolKit: Execute Tool (if needed)\n ToolKit-->>Agent: Tool Result\n Agent->>LLM: Format Response\n LLM-->>Agent: Structured Output\n Agent-->>User: AgentMessage\n```\n\n## Multi-Agent Collaboration\n\nCAMEL supports complex multi-agent workflows where agents collaborate to solve problems:\n\n```mermaid\ngraph LR\n User[User Request] --> Coordinator[TaskAgent]\n Coordinator -->|Delegate| Critic1[CriticAgent]\n Coordinator -->|Delegate| Search[SearchAgent]\n Coordinator -->|Delegate| Repo[RepoAgent]\n \n Critic1 -->|Feedback| Coordinator\n Search -->|Results| Coordinator\n Repo -->|Analysis| Coordinator\n \n Coordinator -->|Final Response| User\n```\n\n## Configuration Options\n\n### Common Agent Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `model` | `Model` | Required | LLM model instance |\n| `tool_kit` | `List[BaseTool]` | `[]` | Tools available to agent |\n| `system_message` | `str` | `None` | System-level instructions |\n| `max_tokens` | `int` | `4096` | Maximum output tokens |\n| `temperature` | `float` | `0.7` | Sampling temperature |\n\n### Tool Execution Configuration\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `tool_call_limit` | `int` | Maximum tool calls per turn |\n| `tool_call_retry_limit` | `int` | Retry attempts on failure |\n| ` message_window_size` | `int` | Context window for conversation |\n\n## Extending the Agent System\n\nTo create a custom agent type, inherit from `ChatAgent`:\n\n```python\nfrom camel.agents import ChatAgent\nfrom camel.types import RoleType\n\nclass MyCustomAgent(ChatAgent):\n def __init__(self, model, custom_param, **kwargs):\n system_message = SystemMessage(\n role_name=\"Custom Agent\",\n role_type=RoleType.ASSISTANT,\n content=\"Custom instructions...\"\n )\n super().__init__(system_message, model, **kwargs)\n self.custom_param = custom_param\n```\n\n## Error Handling\n\nAgents implement comprehensive error handling for:\n\n- LLM API failures (rate limits, authentication)\n- Tool execution errors\n- Malformed responses\n- Timeout conditions\n\nEach error type triggers appropriate recovery mechanisms or returns structured error messages for debugging.\n\n## Best Practices\n\n1. **Tool Selection**: Only provide agents with tools relevant to their task to reduce complexity\n2. **System Messages**: Craft clear, specific instructions for consistent agent behavior\n3. **Memory Management**: Configure appropriate `message_window_size` for long conversations\n4. **Error Handling**: Always wrap agent calls in try-except blocks for production systems\n5. **Model Selection**: Choose models appropriate for task complexity\n\n## Summary\n\nCAMEL's agent system provides a flexible, extensible foundation for building multi-agent applications. The base `ChatAgent` class combined with specialized agent types and a robust persona system enables developers to create sophisticated AI systems that can collaborate, critique, and solve complex tasks through coordinated agent interactions.\n\n---\n\n\n\n## Model Integration and Providers\n\n### 相关页面\n\n相关主题：[Introduction to CAMEL](#page-introduction), [System Architecture](#page-architecture)\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/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/base_model.py](https://github.com/camel-ai/camel/blob/main/camel/models/base_model.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/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/configs/__init__.py)\n- [camel/embeddings/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/embeddings/__init__.py)\n- [camel/types/unified_model_type.py](https://github.com/camel-ai/camel/blob/main/camel/types/unified_model_type.py)\n \n\n# Model Integration and Providers\n\n## Overview\n\nThe CAMEL framework provides a comprehensive model integration system that abstracts over multiple AI provider APIs through a unified interface. This architecture enables developers to seamlessly switch between different model providers (OpenAI, Anthropic, Google, Azure, etc.) without modifying application code.\n\nThe model integration layer serves as the foundational component for all agent reasoning, chat interactions, and language model operations within the CAMEL ecosystem. It implements the factory pattern to handle provider-specific instantiation while maintaining a consistent API contract across all implementations.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[Application Layer] --> B[ModelFactory]\n B --> C[ModelManager]\n C --> D[Provider-Specific Models]\n \n D --> E[OpenAIModel]\n D --> F[AnthropicModel]\n D --> G[AzureAIModel]\n D --> H[GeminiModel]\n D --> I[Other Providers]\n \n J[BaseModel] --> D\n K[configs] --> B\n L[unified_model_type] --> B\n```\n\n## Core Components\n\n### Base Model Architecture\n\nThe `BaseModel` class (`camel/models/base_model.py`) defines the abstract interface that all provider-specific implementations must follow. This ensures consistency across the framework and allows dynamic model selection at runtime.\n\n**Key Responsibilities:**\n- Defines the standard interface for all model implementations\n- Provides common functionality for API communication\n- Establishes the contract for `run()` and `run_async()` methods\n\n### Model Factory Pattern\n\nThe `ModelFactory` (`camel/models/model_factory.py`) implements the factory pattern to centralize model instantiation logic.\n\n```python\nModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=OpenAIModelType.GPT_4O,\n api_key=\"...\",\n url=\"...\"\n)\n```\n\n**Factory Capabilities:**\n- Dynamic model instantiation based on provider type\n- Automatic configuration loading from environment variables\n- Support for both chat and embedding models\n- Flexible parameter passing for provider-specific options\n\n### Model Manager\n\nThe `ModelManager` (`camel/models/model_manager.py`) provides a higher-level abstraction for managing model instances, including lifecycle management and configuration caching.\n\n## Supported Model Providers\n\n### Provider Configuration Matrix\n\n| Provider | Platform Type | Model Types | API Format | Authentication |\n|----------|---------------|-------------|------------|----------------|\n| OpenAI | `OPENAI` | GPT-4o, GPT-4, GPT-3.5 | OpenAI API v1 | API Key |\n| Anthropic | `ANTHROPIC` | Claude 3.5, Claude 3 | Anthropic API | API Key |\n| Azure | `AZURE` | GPT-4, GPT-35 | Azure OpenAI API | API Key + Endpoint |\n| Google | `GOOGLE` | Gemini Pro, Gemini Ultra | Google AI API | API Key |\n| HuggingFace | `HUGGINGFACE` | Various open models | HF Inference API | API Key |\n| ModelScope | `OPENAI_COMPATIBLE_MODEL` | Qwen, Llama variants | OpenAI-compatible | API Key |\n\n### OpenAI Integration\n\nThe `OpenAIModel` (`camel/models/openai_model.py`) provides integration with OpenAI's API family.\n\n**Supported Model Types:**\n- `GPT_4O` - Latest GPT-4 optimized for speed\n- `GPT_4O_MINI` - Cost-effective GPT-4 variant\n- `GPT_4_TURBO` - High-capability GPT-4\n- `GPT_3_5_TURBO` - Legacy support model\n\n**Configuration Example:**\n```python\nmodel = OpenAIModel(\n model_type=OpenAIModelType.GPT_4O,\n api_key=os.environ.get(\"OPENAI_API_KEY\"),\n url=\"https://api.openai.com/v1\"\n)\n```\n\n### Anthropic Integration\n\nThe `AnthropicModel` (`camel/models/anthropic_model.py`) enables access to Claude models through Anthropic's API.\n\n**Supported Model Types:**\n- `CLAUDE_3_5_SONNET` - Latest Sonnet model\n- `CLAUDE_3_OPUS` - Highest capability model\n- `CLAUDE_3_HAIKU` - Fast, cost-effective option\n\n## Unified Model Type System\n\nThe `unified_model_type.py` (`camel/types/unified_model_type.py`) defines enumerations that map provider-specific model identifiers to a common type system.\n\n```mermaid\nclassDiagram\n class ModelPlatformType {\n <>\n OPENAI\n ANTHROPIC\n AZURE\n GOOGLE\n HUGGINGFACE\n MODELSCOPE\n }\n \n class ModelType {\n <>\n GPT_4O\n GPT_4_TURBO\n CLAUDE_3_5_SONNET\n GEMINI_PRO\n }\n```\n\nThis unified type system allows the framework to:\n- Map provider-specific model names to internal identifiers\n- Validate model availability before instantiation\n- Provide consistent error handling across providers\n\n## Configuration System\n\n### Config Module Structure\n\nThe `configs/__init__.py` (`camel/configs/__init__.py`) exports configuration classes used across the model integration system.\n\n**Configuration Classes:**\n- `ModelConfig` - Base configuration for model parameters\n- `OpenAIConfig` - OpenAI-specific settings\n- `AnthropicConfig` - Anthropic-specific settings\n\n### Configuration Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `temperature` | float | 0.7 | Sampling temperature for generation |\n| `max_tokens` | int | 4096 | Maximum tokens in response |\n| `top_p` | float | 1.0 | Nucleus sampling parameter |\n| `timeout` | int | 120 | Request timeout in seconds |\n| `retry_limit` | int | 2 | Number of retry attempts |\n\n## Embedding Integration\n\nThe `embeddings/__init__.py` (`camel/embeddings/__init__.py`) module provides embedding model support for vector operations.\n\n**Embedding Capabilities:**\n- Text embedding generation for semantic search\n- Support for multiple embedding providers\n- Configurable embedding dimensions\n\n## Usage Patterns\n\n### Basic Model Creation\n\n```python\nfrom camel.models import ModelFactory, ModelPlatformType, OpenAIModelType\n\n# Create OpenAI model instance\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=OpenAIModelType.GPT_4O,\n api_key=\"your-api-key\"\n)\n\n# Run inference\nresponse = model.run([{\"role\": \"user\", \"content\": \"Hello!\"}])\n```\n\n### Async Model Operations\n\n```python\nimport asyncio\nfrom camel.models import ModelFactory\n\nasync def async_inference():\n model = ModelFactory.create(...)\n response = await model.run_async([{\"role\": \"user\", \"content\": \"Hi\"}])\n return response\n\nresult = asyncio.run(async_inference())\n```\n\n### Multi-Provider Setup\n\n```python\nfrom camel.models import ModelFactory, ModelPlatformType\n\n# OpenAI for reasoning\nreasoning_model = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=OpenAIModelType.GPT_4O\n)\n\n# Anthropic for generation\ngeneration_model = ModelFactory.create(\n model_platform=ModelPlatformType.ANTHROPIC,\n model_type=AnthropicModelType.CLAUDE_3_5_SONNET\n)\n```\n\n## Error Handling\n\nThe model integration system provides consistent error handling across all providers:\n\n| Error Type | Cause | Handling Strategy |\n|------------|-------|-------------------|\n| `APIError` | Provider API issues | Automatic retry with exponential backoff |\n| `AuthenticationError` | Invalid API key | Raise with clear message |\n| `RateLimitError` | Exceeded quota | Wait and retry |\n| `TimeoutError` | Request timeout | Retry with increased timeout |\n\n## Best Practices\n\n1. **Environment Variable Configuration**: Store API keys in environment variables rather than hardcoding\n2. **Model Selection**: Choose appropriate model tiers based on task complexity\n3. **Async Operations**: Use async methods for batch processing scenarios\n4. **Error Handling**: Implement retry logic for production deployments\n5. **Resource Management**: Reuse model instances rather than creating new ones per request\n\n## Related Components\n\n- [Agent System](agents) - Uses model integration for reasoning\n- [Tool Calling](tools) - Leverages models for function execution\n- [Retrieval](retrieval) - Uses embedding models for vector operations\n\n---\n\n\n\n## Tools and Toolkits\n\n### 相关页面\n\n相关主题：[Agent Types and System](#page-agents)\n\n\nRelated Source Files
\n\nThe following source files were used to generate this page:\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/code_execution.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/code_execution.py)\n- [camel/toolkits/mcp_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/mcp_toolkit.py)\n- [camel/toolkits/retrieval_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/retrieval_toolkit.py)\n- [camel/toolkits/skill_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/skill_toolkit.py)\n- [camel/parsers/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/parsers/__init__.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 \n\n# Tools and Toolkits\n\n## Overview\n\nThe CAMEL framework provides a comprehensive Tools and Toolkits system that extends the capabilities of AI agents beyond text generation. Toolkits are modular collections of tools that agents can utilize to interact with external systems, execute code, browse the web, manage files, and perform specialized tasks.\n\nThe architecture follows a plugin-based design where each toolkit encapsulates related functionality into a cohesive unit. This design enables agents to dynamically select and invoke tools based on task requirements, facilitating multi-agent collaboration with diverse capabilities.\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n A[Agent] --> B[Toolkit Registry]\n B --> C[BaseToolkit]\n B --> D[FunctionTool]\n B --> E[MCPToolkit]\n C --> F[SearchToolkit]\n C --> G[BrowserToolkit]\n C --> H[FileToolkit]\n C --> I[RetrievalToolkit]\n C --> J[SkillToolkit]\n C --> K[CodeExecution]\n E --> L[MCP Servers]\n L --> M[External Services]\n```\n\n### Tool Classification\n\n| Category | Purpose | Examples |\n|----------|---------|----------|\n| **Search & Retrieval** | Information gathering | Web search, document retrieval |\n| **Browser Automation** | Web interaction | Page navigation, form filling |\n| **File Operations** | Local file management | Read, write, edit files |\n| **Code Execution** | Runtime code evaluation | Python sandbox, code runner |\n| **MCP Integration** | External protocol support | Cloudflare, Airbnb, ACI tools |\n| **Skills** | Complex task automation | Sequential tool execution |\n\n## Core Components\n\n### Base Toolkit Architecture\n\nAll toolkits inherit from `BaseToolkit`, which defines the common interface for tool management and invocation.\n\n资料来源：[camel/toolkits/base.py]()\n\nThe `BaseToolkit` class provides:\n\n- Tool registration and management\n- Parameter schema generation\n- Tool invocation orchestration\n- Result parsing and formatting\n\n### Function Tool\n\nThe `FunctionTool` class wraps Python functions into tool-compatible format with automatic schema generation from function signatures.\n\n资料来源：[camel/toolkits/function_tool.py]()\n\n```mermaid\ngraph LR\n A[Python Function] --> B[FunctionTool.wrap]\n B --> C[Schema Generation]\n C --> D[Tool Definition]\n D --> E[Tool Execution]\n E --> F[Result Parsing]\n```\n\n## Available Toolkits\n\n### Search Toolkit\n\nProvides web search capabilities for information retrieval tasks.\n\n资料来源：[camel/toolkits/search_toolkit.py]()\n\n| Tool | Function |\n|------|----------|\n| `GoogleSearch` | Google search with API |\n| `WebSearch` | Generic web search |\n| `WebPageScan` | Retrieve and scan web pages |\n\n### Browser Toolkit\n\nEnables agents to interact with web pages through automated browser control.\n\n资料来源：[camel/toolkits/browser_toolkit.py]()\n\n**Key Features:**\n\n- Page navigation and snapshot capture\n- Element interaction (click, fill, select)\n- Form submission automation\n- Screenshot capture\n- Intelligent element matching by placeholder, ref, or text\n\n**Browser Session Flow:**\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant BrowserToolkit\n participant Playwright\n participant WebPage\n \n Agent->>BrowserToolkit: Navigate to URL\n BrowserToolkit->>Playwright: page.goto()\n Playwright->>WebPage: HTTP Request\n WebPage-->>Playwright: HTML Response\n Playwright-->>BrowserToolkit: Page Ready\n BrowserToolkit-->>Agent: Page Snapshot\n```\n\n**Input Element Handling:**\n\nThe toolkit implements robust input element detection:\n\n```python\n# Element detection logic\nconst placeholder = await newElement.getAttribute('placeholder').catch(() => null);\nif (placeholder === originalPlaceholder) {\n await newElement.fill(text, { force: true });\n return { success: true, diffSnapshot };\n}\n```\n\n资料来源：[camel/toolkits/browser_toolkit.py]()\n\n### File Toolkit\n\nManages local file system operations with read, write, and edit capabilities.\n\n资料来源：[camel/toolkits/file_toolkit.py]()\n\n| Operation | Description |\n|-----------|-------------|\n| `Read` | Read file contents |\n| `Write` | Create or overwrite files |\n| `Edit` | Modify existing files |\n| `Glob` | Pattern-based file listing |\n| `Tree` | Directory structure visualization |\n\n### Code Execution Toolkit\n\nProvides sandboxed code execution environments for dynamic code evaluation.\n\n资料来源：[camel/toolkits/code_execution.py]()\n\n**Supported Modes:**\n\n| Mode | Use Case |\n|------|----------|\n| `JEPYTER` | Interactive notebook execution |\n| `AST` | AST-based code analysis |\n| `EXECUTOR` | Direct code execution |\n\n### Retrieval Toolkit\n\nOffers document retrieval and semantic search capabilities.\n\n资料来源：[camel/toolkits/retrieval_toolkit.py]()\n\n**Components:**\n\n- Embedding generation\n- Vector store integration\n- Similarity search\n- Document chunking\n\n### Skill Toolkit\n\nOrchestrates complex tasks by combining multiple tools into executable skill workflows.\n\n资料来源：[camel/toolkits/skill_toolkit.py]()\n\n```mermaid\ngraph TD\n A[Skill Definition] --> B[Tool Sequence]\n B --> C[Execution Plan]\n C --> D[Tool 1]\n C --> E[Tool 2]\n C --> F[Tool N]\n D --> G[Result Aggregation]\n E --> G\n F --> G\n G --> H[Final Output]\n```\n\n### MCP Toolkit\n\nIntegrates the Model Context Protocol (MCP) for connecting to external tool servers.\n\n资料来源：[camel/toolkits/mcp_toolkit.py]()\n\n**Supported MCP Integrations:**\n\n- Cloudflare (Docs, Radar, Browser)\n- Airbnb listings search\n- ACI.dev platform tools\n- GitHub repositories\n- YouTube video analysis\n\n资料来源：[camel/toolkits/__init__.py]()\n\n### Parser System\n\nThe parser system handles tool call parsing and result interpretation.\n\n资料来源：[camel/parsers/__init__.py]()\n\n| Parser | Purpose |\n|--------|---------|\n\n| `MCPToolCallParser` | Parse MCP protocol tool calls |\n\n资料来源：[camel/parsers/mcp_tool_call_parser.py]()\n\n## Tool Invocation Pattern\n\n```mermaid\ngraph TD\n A[User Task] --> B[Agent Decision]\n B --> C{Select Tool}\n C --> D[Tool Schema]\n D --> E[Parameter Construction]\n E --> F[Tool Execution]\n F --> G[Result Parsing]\n G --> H[Response to Agent]\n H --> B\n```\n\n## Integration with Agents\n\nToolkits are integrated into the agent system through the `BaseToolkit` interface:\n\n1. **Registration**: Toolkits register their available tools with the agent\n2. **Schema Generation**: Tool schemas are generated for LLM tool selection\n3. **Invocation**: Agent selects and invokes tools based on task requirements\n4. **Result Handling**: Tool results are parsed and returned to the agent\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `OPENAI_API_KEY` | Yes | API key for OpenAI models |\n| `GOOGLE_API_KEY` | No | For Google Search toolkit |\n| `FIRECRAWL_API_KEY` | No | For web scraping |\n| `MISTRAL_API_KEY` | No | For Mistral OCR |\n\n### MCP Server Configuration\n\nMCP toolkits use JSON configuration files:\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## Example Use Cases\n\n### Multi-Agent Research Assistant\n\nUses multiple toolkits for comprehensive research:\n\n1. **Search Toolkit**: Find relevant papers and researchers\n2. **Browser Toolkit**: Extract content from web pages\n3. **File Toolkit**: Save research reports locally\n4. **Skill Toolkit**: Orchestrate multi-step research workflows\n\n### Codeforces Question Solver\n\nCombines browser automation with code execution:\n\n1. **Browser Toolkit**: Navigate to problem statements\n2. **Code Execution**: Run and test solutions\n3. **File Toolkit**: Save code submissions\n\n### Document OCR and Analysis\n\nLeverages specialized OCR capabilities:\n\n1. **Mistral OCR**: Extract text from PDFs/images\n2. **Retrieval Toolkit**: Index extracted content\n3. **Agent**: Analyze and summarize documents\n\n## Best Practices\n\n1. **Tool Selection**: Choose appropriate tools based on task requirements\n2. **Error Handling**: Implement proper exception handling for tool failures\n3. **Resource Management**: Clean up resources after execution\n4. **Schema Validation**: Validate tool parameters before invocation\n5. **Security**: Use sandboxed environments for code execution\n\n## Summary\n\nThe CAMEL Tools and Toolkits system provides a flexible, extensible architecture for augmenting AI agents with external capabilities. By supporting diverse tool types—from file operations to web browsing to specialized integrations—agents can perform complex, multi-step tasks that require interaction with the real world. The modular design allows easy addition of new toolkits while maintaining a consistent interface for tool invocation and result handling.\n\n---\n\n\n\n## Multi-Agent Societies and Role Playing\n\n### 相关页面\n\n相关主题：[Agent Types and System](#page-agents), [Workforce Management](#page-workforce), [Memory Management](#page-memory)\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/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/prompts/ai_society.py](https://github.com/camel-ai/camel/blob/main/camel/prompts/ai_society.py)\n- [camel/prompts/role_description_prompt_template.py](https://github.com/camel-ai/camel/blob/main/camel/prompts/role_description_prompt_template.py)\n \n\n# Multi-Agent Societies and Role Playing\n\n## Overview\n\nCAMEL's Multi-Agent Societies provide a sophisticated framework for orchestrating multiple autonomous agents that collaborate to accomplish complex tasks. At the core of this system is the **Role Playing** paradigm, where agents are assigned specific roles with distinct responsibilities, enabling them to engage in meaningful cooperation and problem-solving.\n\nThe societies framework enables developers to create agent ecosystems where:\n\n- Multiple agents assume distinct roles (e.g., AI Assistant, Code Reviewer, Researcher)\n- Agents communicate through structured message passing\n- Collaborative tasks are completed through agent-to-agent interaction\n- Complex workflows are decomposed into manageable subtasks handled by specialized agents\n\n资料来源：[camel/societies/__init__.py:1-20]()\n\n## Architecture\n\nThe multi-agent society architecture consists of several interconnected components that work together to enable sophisticated agent collaboration.\n\n```mermaid\ngraph TD\n A[User Task] --> B[Role Playing Manager]\n B --> C[AI Society Prompt]\n B --> D[Task Specification]\n C --> E[Role Assignment]\n D --> E\n E --> F[Agent 1: Role A]\n E --> G[Agent 2: Role B]\n F <--> G[Communication]\n G --> H[Task Completion]\n F --> H\n```\n\n### Core Components\n\n| Component | Purpose | Location |\n|-----------|---------|----------|\n| `RolePlaying` | Orchestrates role-based agent interactions | `camel/societies/role_playing.py` |\n| `BabyAGIPlaying` | Implements BabyAGI-style autonomous task execution | `camel/societies/babyagi_playing.py` |\n| `Workforce` | Manages a pool of workers for parallel task execution | `camel/societies/workforce/workforce.py` |\n| `Worker` | Individual agent within a workforce | `camel/societies/workforce/worker.py` |\n| `TaskChannel` | Manages task distribution and routing | `camel/societies/workforce/task_channel.py` |\n\n资料来源：[camel/societies/__init__.py:1-30]()\n\n## Role Playing System\n\n### Purpose and Design\n\nThe Role Playing system is the foundational mechanism for enabling multiple agents to collaborate effectively. It assigns distinct roles to each agent and facilitates structured communication between them based on their assigned responsibilities.\n\n资料来源：[camel/societies/role_playing.py:1-50]()\n\n### Key Features\n\nThe role playing implementation provides several critical capabilities:\n\n- **Role Assignment**: Automatically assigns appropriate roles to agents based on task requirements\n- **Task Decomposition**: Breaks complex tasks into role-specific subtasks\n- **Communication Management**: Handles inter-agent messaging and context preservation\n- **State Management**: Maintains conversation history and agent states throughout the interaction\n\n### Role Description Prompt Templates\n\nThe system uses specialized prompt templates to define agent roles and behaviors. These templates ensure consistent role representation and guide agent responses based on their assigned responsibilities.\n\n```mermaid\ngraph LR\n A[Task Input] --> B[Role Description Template]\n B --> C[System Prompt]\n C --> D[AI Agent Behavior]\n D --> E[Role-Specific Response]\n```\n\n资料来源：[camel/prompts/role_description_prompt_template.py:1-40]()\n\n### AI Society Prompts\n\nThe `AISocietyPrompt` class provides the foundational prompt structures that define how agents in a society interact. These prompts include:\n\n- Agent role definitions\n- Task instructions and constraints\n- Communication protocols\n- Success criteria and evaluation metrics\n\n资料来源：[camel/prompts/ai_society.py:1-50]()\n\n## Workforce System\n\nThe Workforce system extends the basic role playing paradigm by introducing a more structured approach to managing multiple agents working in parallel.\n\n### Architecture Overview\n\nThe Workforce consists of three primary components that work together to manage distributed agent execution:\n\n1. **Workforce Manager**: Coordinates all workers and task distribution\n2. **Worker Agents**: Individual agents that execute assigned tasks\n3. **Task Channels**: Routes tasks to appropriate workers based on capabilities\n\n```mermaid\ngraph TD\n A[Task Queue] --> B[TaskChannel]\n B --> C[Worker 1]\n B --> D[Worker 2]\n B --> E[Worker N]\n C --> F[Result Aggregation]\n D --> F\n E --> F\n F --> G[Final Output]\n```\n\n资料来源：[camel/societies/workforce/workforce.py:1-60]()\n\n### Worker Configuration\n\nWorkers can be configured with specific capabilities and task preferences:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `name` | `str` | Unique identifier for the worker |\n| `role` | `str` | Worker's assigned role in the society |\n| `description` | `str` | Detailed description of worker's expertise |\n| `tools` | `List[Tool]` | Tools available to the worker |\n| `model` | `Model` | LLM model to use for this worker |\n\n资料来源：[camel/societies/workforce/worker.py:1-50]()\n\n### Task Channel Implementation\n\nTask channels manage the flow of tasks between the workforce and individual workers. They handle:\n\n- Task routing based on worker capabilities\n- Priority queuing for urgent tasks\n- Task state tracking and completion verification\n- Load balancing across available workers\n\n资料来源：[camel/societies/workforce/task_channel.py:1-40]()\n\n## BabyAGI Integration\n\nCAMEL provides a BabyAGI-style implementation for autonomous task-driven agent execution. This system operates on a continuous loop:\n\n```mermaid\ngraph LR\n A[Create Task] --> B[Prioritize Tasks]\n B --> C[Execute Task]\n C --> D[Complete Task]\n D --> E{More Tasks?}\n E -->|Yes| B\n E -->|No| F[Finish]\n```\n\n### Execution Flow\n\nThe BabyAGI playing system follows these steps:\n\n1. **Task Creation**: Initialize tasks based on user objectives\n2. **Task Prioritization**: Rank tasks by importance and dependencies\n3. **Task Execution**: Assign and execute tasks with appropriate agents\n4. **Result Storage**: Store completed task results for future reference\n5. **Iteration**: Repeat the cycle until all objectives are met\n\n资料来源：[camel/societies/babyagi_playing.py:1-70]()\n\n## Usage Examples\n\n### Basic Role Playing Setup\n\n```python\nfrom camel.societies import RolePlaying\nfrom camel.models import ModelFactory\nfrom camel.types import ModelPlatformType\n\n# Initialize model\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=\"gpt-4\",\n)\n\n# Create role playing session\nrole_playing = RolePlaying(\n assistant_role=\"AI Researcher\",\n assistant_description=\"An expert AI researcher specializing in ML\",\n user_role=\"Curious Student\",\n user_description=\"A student eager to learn about AI\",\n model=model,\n)\n\n# Execute role playing\nresponse = role_playing.step(task=\"Explain transformer architectures\")\n```\n\n### Workforce Configuration\n\n```python\nfrom camel.societies.workforce import Workforce, Worker\n\n# Create workers\nresearcher = Worker(\n name=\"researcher\",\n role=\"Researcher\",\n description=\"Handles research and information gathering\",\n tools=[search_tool, browse_tool],\n)\n\ncoder = Worker(\n name=\"coder\",\n role=\"Coder\",\n description=\"Handles code implementation\",\n tools=[code_tool, test_tool],\n)\n\n# Create workforce\nworkforce = Workforce(workers=[researcher, coder])\n\n# Execute task\nresult = workforce.execute_task(\"Build a web scraper\")\n```\n\n## Configuration Options\n\n### RolePlaying Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `assistant_role` | Required | Role assigned to the assistant agent |\n| `user_role` | Required | Role assigned to the user agent |\n| `model` | Required | LLM model for agent reasoning |\n| `task_specification` | `None` | Detailed task specifications |\n| `max_dialogue_length` | `20` | Maximum turns in conversation |\n| `termination_prompt` | `None` | Custom termination conditions |\n\n### Workforce Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `workers` | Required | List of Worker instances |\n| `task_channel_type` | `\"default\"` | Type of task routing channel |\n| `max_workers` | `None` | Maximum concurrent workers |\n| `timeout` | `300` | Task execution timeout in seconds |\n\n## Prompt Templates\n\n### Role Description Template\n\nThe role description prompt template defines how agent roles are communicated to the underlying language model. It includes:\n\n- Role title and purpose\n- Key responsibilities\n- Behavioral guidelines\n- Communication style preferences\n\n### Task Specification Template\n\nTask specifications provide context about what the society should accomplish:\n\n- Overall objective\n- Success criteria\n- Constraints and limitations\n- Expected deliverables\n\n资料来源：[camel/prompts/ai_society.py:1-100]()\n\n## Best Practices\n\n### Designing Effective Agent Roles\n\n1. **Clear Role Definitions**: Ensure each agent has a well-defined scope of responsibility\n2. **Complementary Capabilities**: Design roles that complement each other\n3. **Appropriate Tool Assignment**: Equip agents with tools relevant to their roles\n4. **Balanced Complexity**: Avoid overloading single agents with too many responsibilities\n\n### Workforce Optimization\n\n1. **Worker Specialization**: Create specialized workers rather than general-purpose ones\n2. **Task Channel Configuration**: Use appropriate task routing strategies\n3. **Load Balancing**: Monitor worker utilization and adjust as needed\n4. **Timeout Configuration**: Set appropriate timeouts for different task types\n\n## Related Components\n\nThe Multi-Agent Societies system integrates with several other CAMEL components:\n\n- **Models**: All agent reasoning is powered by LLM models through `ModelFactory`\n- **Tools**: Agents can utilize various toolkits for extended capabilities\n- **Memories**: Conversation history and context are maintained through memory systems\n- **Prompts**: Structured prompts guide agent behavior and communication\n\n## Summary\n\nCAMEL's Multi-Agent Societies and Role Playing framework provides a powerful foundation for building collaborative AI agent systems. By combining role-based interactions with workforce orchestration, developers can create sophisticated agent ecosystems capable of tackling complex, multi-faceted tasks through effective cooperation and specialization.\n\n---\n\n\n\n## Workforce Management\n\n### 相关页面\n\n相关主题：[Multi-Agent Societies and Role Playing](#page-societies)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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/single_agent_worker.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/single_agent_worker.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/task_channel.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/task_channel.py)\n- [camel/societies/workforce/events.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/events.py)\n- [camel/societies/workforce/workforce_metrics.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/workforce_metrics.py)\n- [camel/societies/workforce/workforce_callback.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/workforce_callback.py)\n- [camel/societies/workforce/structured_output_handler.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/structured_output_handler.py)\n \n\n# Workforce Management\n\n## Overview\n\nWorkforce Management is a core module in CAMEL that orchestrates multi-agent collaboration through a hierarchical worker system. It provides a framework for managing pools of specialized agents (workers) that can execute tasks, communicate via channels, and report metrics. The system enables scalable agent-based workflows where multiple workers operate concurrently to accomplish complex objectives.\n\n## Architecture\n\nThe Workforce Management system follows a producer-consumer pattern where tasks flow through channels and are processed by different worker types.\n\n```mermaid\ngraph TD\n A[Task Submission] --> B[Workforce Manager]\n B --> C[TaskChannel]\n C --> D[SingleAgentWorker]\n C --> E[RolePlayingWorker]\n D --> F[Worker Response]\n E --> F\n G[Events System] --> B\n H[Metrics Collection] --> B\n I[Callbacks] --> B\n```\n\n## Core Components\n\n### Workforce\n\nThe `Workforce` class serves as the central coordinator managing the entire worker ecosystem.\n\n| Component | Purpose | Key Methods |\n|-----------|---------|-------------|\n| `Workforce` | Central manager for all workers | `launch()`, `execute()`, `submit()`, `wait()` |\n| TaskChannel | Message routing between components | `put()`, `get()`, `task_done()` |\n| Worker | Base abstraction for task executors | `step()`, `reset()` |\n\n资料来源：[camel/societies/workforce/workforce.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/workforce.py)\n\n### Worker Types\n\n#### SingleAgentWorker\n\nExecutes tasks using a single AI agent without role-playing dynamics.\n\n```mermaid\nclassDiagram\n class Worker {\n <>\n +step()\n +reset()\n }\n class SingleAgentWorker {\n +agent: BaseAgent\n +toolkit: Toolkits\n +step()\n }\n Worker <|-- SingleAgentWorker\n```\n\n资料来源：[camel/societies/workforce/single_agent_worker.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/single_agent_worker.py)\n\n#### RolePlayingWorker\n\nLeverages CAMEL's role-playing framework where two agents (assistant and user) interact dynamically.\n\n资料来源：[camel/societies/workforce/role_playing_worker.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/role_playing_worker.py)\n\n### TaskChannel\n\nManages task distribution and communication between workforce components.\n\n| Method | Description |\n|--------|-------------|\n| `put(task)` | Submit a new task to the channel |\n| `get()` | Retrieve next task from queue |\n| `task_done()` | Mark task as completed |\n\n资料来源：[camel/societies/workforce/task_channel.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/task_channel.py)\n\n## Event System\n\nThe event system enables real-time monitoring and logging of workforce operations.\n\n| Event Type | Trigger | Data Captured |\n|------------|---------|---------------|\n| `WorkerStarted` | Worker begins processing | worker_id, timestamp |\n| `WorkerCompleted` | Worker finishes task | worker_id, result |\n| `TaskSubmitted` | New task enters queue | task_id, priority |\n| `TaskFailed` | Task execution error | task_id, error_info |\n\n资料来源：[camel/societies/workforce/events.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/events.py)\n\n## Metrics and Monitoring\n\n### WorkforceMetrics\n\nTracks performance indicators across the workforce execution.\n\n| Metric | Description |\n|--------|-------------|\n| `total_tasks` | Total tasks submitted |\n| `completed_tasks` | Successfully completed tasks |\n| `failed_tasks` | Tasks that encountered errors |\n| `avg_execution_time` | Mean task duration |\n\n资料来源：[camel/societies/workforce/workforce_metrics.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/workforce_metrics.py)\n\n### Callbacks\n\nThe `WorkforceCallback` interface allows custom hooks for monitoring and extending behavior.\n\n```python\nclass WorkforceCallback:\n def on_worker_start(self, worker_id: str) -> None\n def on_worker_complete(self, worker_id: str, result: Any) -> None\n def on_task_submit(self, task: Any) -> None\n def on_error(self, error: Exception) -> None\n```\n\n资料来源：[camel/societies/workforce/workforce_callback.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/workforce_callback.py)\n\n## Structured Output Handling\n\nHandles parsing and validation of structured outputs from agent responses.\n\n资料来源：[camel/societies/workforce/structured_output_handler.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/structured_output_handler.py)\n\n## Workflow Execution Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Workforce\n participant TaskChannel\n participant Worker\n \n User->>Workforce: submit(task)\n Workforce->>TaskChannel: put(task)\n TaskChannel->>Worker: deliver task\n Worker->>Worker: step()\n Worker->>TaskChannel: task_done()\n TaskChannel->>Workforce: completion event\n Workforce->>User: return result\n```\n\n## Configuration Options\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `max_workers` | int | auto | Maximum concurrent workers |\n| `timeout` | float | 300.0 | Task timeout in seconds |\n| `retry_count` | int | 3 | Number of retry attempts |\n| `enable_metrics` | bool | True | Enable metrics collection |\n\n## Integration with Toolkits\n\nWorkers can utilize CAMEL's extensive toolkit ecosystem:\n\n- **GoogleScholarToolkit**: Academic paper retrieval\n- **SemanticScholarToolkit**: Research paper search\n- **ArxivToolkit**: Preprint access\n- **AskNewsToolkit**: News article fetching\n- **FileToolkit**: Local file operations\n- **LinkedInToolkit**: Social media integration\n- **OpenAIImageToolkit**: Image generation\n\n## Best Practices\n\n1. **Task Design**: Break complex objectives into granular, independent tasks\n2. **Worker Selection**: Match task requirements to appropriate worker types\n3. **Error Handling**: Implement callbacks to capture and respond to failures\n4. **Resource Management**: Configure worker limits based on available compute\n5. **Monitoring**: Enable metrics collection for performance analysis\n\n## See Also\n\n- [Multi-Agent Research Assistant Example](../usecases/multi_agent_research_assistant/README.md)\n- [CAMEL Agents Application](../apps/agents/README.md)\n- [CAMEL Agent MCP Server](../services/README.md)\n\n---\n\n\n\n## Memory Management\n\n### 相关页面\n\n相关主题：[Storage Systems](#page-storage), [Multi-Agent Societies and Role Playing](#page-societies), [Agent Types and System](#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/agent_memories.py](https://github.com/camel-ai/camel/blob/main/camel/memories/agent_memories.py)\n- [camel/memories/base.py](https://github.com/camel-ai/camel/blob/main/camel/memories/base.py)\n- [camel/memories/records.py](https://github.com/camel-ai/camel/blob/main/camel/memories/records.py)\n- [camel/memories/blocks/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/memories/blocks/__init__.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/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/memories/context_creators/__init__.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/caches/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/caches/__init__.py)\n- [camel/caches/semantic_cache.py](https://github.com/camel-ai/camel/blob/main/camel/caches/semantic_cache.py)\n \n\n# Memory Management\n\nCAMEL's Memory Management system provides agents with persistent and contextual memory capabilities, enabling them to retain information across interactions, store conversation histories, and retrieve relevant context efficiently. This system is fundamental to building stateful, intelligent agents that maintain coherence across extended conversations and complex multi-step tasks.\n\n## Architecture Overview\n\nThe memory system is organized into three primary layers that work together to provide comprehensive memory capabilities:\n\n| Layer | Purpose | Key Components |\n|-------|---------|----------------|\n| **Records** | Data models for storing individual memory entries | `ChatRecord`, `MessageRecord`, `UidRecord` |\n| **Blocks** | Storage mechanisms with specific retrieval strategies | `ChatHistoryBlock`, `VectorDBBlock` |\n| **Context Creators** | Aggregation logic to build context from memories | `ScoreBasedContextCreator` |\n\n```mermaid\ngraph TD\n A[Agent Request] --> B[AgentMemories]\n B --> C[Context Creator]\n C --> D[Context Block]\n D --> E[LLM Response]\n \n C --> F[ChatHistoryBlock]\n C --> G[VectorDBBlock]\n \n F --> H[ChatRecord / MessageRecord]\n G --> I[Vector Store]\n \n J[New Interaction] --> K[Semantic Cache]\n K -->|Cache Hit| L[Return Cached Response]\n K -->|Cache Miss| E\n```\n\n资料来源：[camel/memories/agent_memories.py:1-50]()\n\n## Core Memory Components\n\n### Memory Records\n\nMemory records are the fundamental data structures that represent individual pieces of stored information. The CAMEL memory system defines several record types in `camel/memories/records.py`:\n\n| Record Type | Description | Usage |\n|-------------|-------------|-------|\n| `ChatRecord` | Stores a complete chat interaction with role and message | General conversation storage |\n| `MessageRecord` | Stores individual messages with metadata | Single message persistence |\n| `UidRecord` | Records with unique identifiers for referencing | Indexed memory lookups |\n\n资料来源：[camel/memories/records.py](https://github.com/camel-ai/camel/blob/main/camel/memories/records.py)\n\nThe `ChatRecord` class typically contains:\n- `role`: The sender's role (e.g., \"user\", \"assistant\", \"system\")\n- `message`: The actual content of the message\n- `timestamp`: Optional timestamp for the interaction\n\n### Base Memory Class\n\nAll memory implementations inherit from `MemoryBase`, which defines the common interface for memory operations:\n\n```python\nclass MemoryBase(Generic[RecordType]):\n def read(self) -> List[RecordType]: ...\n def write(self, record: RecordType) -> None: ...\n def clear(self) -> None: ...\n def get_size(self) -> int: ...\n```\n\n资料来源：[camel/memories/base.py](https://github.com/camel-ai/camel/blob/main/camel/memories/base.py)\n\n## Memory Blocks\n\nMemory blocks are concrete implementations of storage mechanisms, each optimized for different access patterns and use cases.\n\n### ChatHistoryBlock\n\nThe `ChatHistoryBlock` provides simple, linear storage for conversation history. It maintains messages in chronological order and supports basic read/write operations.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `max_messages` | `int` | Maximum number of messages to retain |\n| `window_size` | `int` | Number of recent messages to return on read |\n| `.chat_history` | `List[ChatRecord]` | Internal storage for chat records |\n\n**Key Features:**\n- FIFO (First-In-First-Out) eviction when capacity is exceeded\n- Configurable window size for retrieving only recent context\n- Efficient for sequential conversation patterns\n\n资料来源：[camel/memories/blocks/chat_history_block.py](https://github.com/camel-ai/camel/blob/main/camel/memories/blocks/chat_history_block.py)\n\n```mermaid\ngraph LR\n A[New Message] -->|append| B[ChatHistoryBlock]\n B --> C{Size > max_messages?}\n C -->|Yes| D[Remove Oldest]\n C -->|No| E[Store]\n F[Read Request] --> G[Return last window_size messages]\n```\n\n### VectorDBBlock\n\nThe `VectorDBBlock` enables semantic search capabilities by storing memories as vector embeddings in a vector database. This allows agents to retrieve contextually relevant memories based on meaning rather than exact matches.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `vector_db` | `VectorDB` | Backend vector database instance |\n| `embedding_model` | `EmbeddingModel` | Model for generating embeddings |\n| `top_k` | `int` | Number of top results to retrieve |\n| `score_threshold` | `float` | Minimum similarity score for inclusion |\n\n**Supported Operations:**\n- Semantic similarity search\n- Score-based filtering of results\n- Integration with various vector database backends\n\n资料来源：[camel/memories/blocks/vectordb_block.py](https://github.com/camel-ai/camel/blob/main/camel/memories/blocks/vectordb_block.py)\n\n## Context Creators\n\nContext creators aggregate memory records into a unified context format suitable for LLM consumption. They transform raw memory data into prompt-ready strings.\n\n### ScoreBasedContextCreator\n\nThe `ScoreBasedContextCreator` implements intelligent context aggregation by scoring memory entries and including only the most relevant ones:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `max_tokens` | `int` | 6000 | Maximum token budget for context |\n| `score_threshold` | `float` | 0.5 | Minimum relevance score |\n| `memory_block` | `MemoryBlock` | required | Source memory block |\n| `embedding_model` | `EmbeddingModel` | required | Model for computing relevance |\n\n**Scoring Algorithm:**\n1. Embed the current query/message\n2. Compute similarity scores against stored memories\n3. Filter entries below `score_threshold`\n4. Add highest-scoring entries until `max_tokens` is reached\n\n资料来源：[camel/memories/context_creators/score_based.py](https://github.com/camel-ai/camel/blob/main/camel/memories/context_creators/score_based.py)\n\n```mermaid\ngraph TD\n A[Query] --> B[Embedding Generation]\n B --> C[Score All Memories]\n C --> D{Score > threshold?}\n D -->|Yes| E[Add to Context]\n D -->|No| F[Discard]\n E --> G{Token Budget OK?}\n G -->|Yes| C\n G -->|No| H[Return Context]\n```\n\n## Agent Memories Integration\n\nThe `AgentMemories` class serves as the central orchestrator, combining multiple memory blocks and context creators:\n\n```python\nclass AgentMemories:\n def __init__(\n self,\n context_creator: ContextCreator,\n memory_blocks: List[MemoryBlock],\n ) -> None: ...\n \n def read(self) -> str: ...\n def write(self, record: MemoryRecord) -> None: ...\n```\n\n资料来源：[camel/memories/agent_memories.py](https://github.com/camel-ai/camel/blob/main/camel/memories/agent_memories.py)\n\n**Typical Configuration:**\n\n| Component | Selection Criteria |\n|-----------|-------------------|\n| ChatHistoryBlock | When conversation order matters, simple retrieval needed |\n| VectorDBBlock | When semantic search, long-term memory, or context relevance is critical |\n| ScoreBasedContextCreator | When token-efficient context retrieval is required |\n\n## Semantic Cache System\n\nBeyond agent memory, CAMEL provides a caching layer for optimizing repeated queries through the `SemanticCache`:\n\n| Feature | Description |\n|---------|-------------|\n| Semantic Matching | Uses embeddings to find similar queries |\n| TTL Support | Optional time-to-live for cache entries |\n| Custom Embedding | Configurable embedding model |\n| Hit/Miss Tracking | Statistics on cache performance |\n\n资料来源：[camel/caches/semantic_cache.py](https://github.com/camel-ai/camel/blob/main/camel/caches/semantic_cache.py)\n\n**Cache Workflow:**\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant Cache as SemanticCache\n participant LLM\n \n Agent->>Cache: Query Request\n Cache->>Cache: Compute Query Embedding\n Cache->>Cache: Search Similar Entries\n alt Cache Hit\n Cache-->>Agent: Return Cached Response\n else Cache Miss\n Agent->>LLM: Process Query\n LLM-->>Agent: Generate Response\n Agent->>Cache: Store Result\n Cache-->>Agent: Return Response\n end\n```\n\n## Usage Patterns\n\n### Basic Memory Setup\n\n```python\nfrom camel.memories import AgentMemories, ChatHistoryBlock\nfrom camel.memories.context_creators import ScoreBasedContextCreator\n\n# Create memory block\nchat_block = ChatHistoryBlock(max_messages=100)\n\n# Create context creator\ncontext_creator = ScoreBasedContextCreator(\n memory_block=chat_block,\n max_tokens=4000\n)\n\n# Combine into agent memories\nagent_memories = AgentMemories(\n context_creator=context_creator,\n memory_blocks=[chat_block]\n)\n```\n\n### Vector-Based Memory with Semantic Search\n\n```python\nfrom camel.memories import AgentMemories, VectorDBBlock\nfrom camel.memories.context_creators import ScoreBasedContextCreator\n\n# Create vector database block\nvector_block = VectorDBBlock(\n vector_db=your_vector_db,\n embedding_model=your_embedding_model,\n top_k=5,\n score_threshold=0.7\n)\n\n# Use with context creator\ncontext_creator = ScoreBasedContextCreator(\n memory_block=vector_block,\n score_threshold=0.7\n)\n\nagent_memories = AgentMemories(\n context_creator=context_creator,\n memory_blocks=[vector_block]\n)\n```\n\n## Module Exports\n\nThe memory system is organized under `camel.memories` and `camel.caches` packages:\n\n资料来源：[camel/memories/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/memories/__init__.py)\n\n| Export | Source Module |\n|--------|---------------|\n| `MemoryBase` | `camel.memories.base` |\n| `ChatRecord`, `MessageRecord`, `UidRecord` | `camel.memories.records` |\n| `AgentMemories` | `camel.memories.agent_memories` |\n| `ChatHistoryBlock` | `camel.memories.blocks.chat_history_block` |\n| `VectorDBBlock` | `camel.memories.blocks.vectordb_block` |\n| `ScoreBasedContextCreator` | `camel.memories.context_creators.score_based` |\n| `SemanticCache` | `camel.caches.semantic_cache` |\n\n## Best Practices\n\n| Scenario | Recommended Configuration |\n|----------|---------------------------|\n| Short conversations | `ChatHistoryBlock` with `window_size=10` |\n| Long-term knowledge | `VectorDBBlock` with high `top_k` |\n| Token-constrained contexts | `ScoreBasedContextCreator` with low `max_tokens` |\n| Repeated query optimization | `SemanticCache` with TTL enabled |\n| Balanced performance | Combined `ChatHistoryBlock` + `VectorDBBlock` |\n\n## Summary\n\nThe CAMEL Memory Management system provides a flexible, extensible architecture for agent memory capabilities:\n\n- **Modular Design**: Separate concerns through Records, Blocks, and Context Creators\n- **Multiple Storage Backends**: Support for linear history and semantic vector storage\n- **Intelligent Context**: Score-based filtering ensures relevant context within token limits\n- **Caching Layer**: Semantic cache optimizes repeated query handling\n- **Extensible**: Custom memory blocks can be implemented by extending `MemoryBase`\n\n---\n\n\n\n## Storage Systems\n\n### 相关页面\n\n相关主题：[Memory Management](#page-memory)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/storages/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/storages/__init__.py)\n- [camel/storages/vectordb_storages/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/storages/vectordb_storages/__init__.py)\n- [camel/storages/vectordb_storages/base.py](https://github.com/camel-ai/camel/blob/main/camel/storages/vectordb_storages/base.py)\n- [camel/storages/vectordb_storages/chroma.py](https://github.com/camel-ai/camel/blob/main/camel/storages/vectordb_storages/chroma.py)\n- [camel/storages/vectordb_storages/faiss.py](https://github.com/camel-ai/camel/blob/main/camel/storages/vectordb_storages/faiss.py)\n- [camel/storages/vectordb_storages/qdrant.py](https://github.com/camel-ai/camel/blob/main/camel/storages/vectordb_storages/qdrant.py)\n- [camel/storages/vectordb_storages/pgvector.py](https://github.com/camel-ai/camel/blob/main/camel/storages/vectordb_storages/pgvector.py)\n- [camel/storages/graph_storages/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/storages/graph_storages/__init__.py)\n- [camel/storages/graph_storages/neo4j_graph.py](https://github.com/camel-ai/camel/blob/main/camel/storages/graph_storages/neo4j_graph.py)\n- [camel/storages/key_value_storages/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/storages/key_value_storages/__init__.py)\n- [camel/storages/key_value_storages/redis.py](https://github.com/camel-ai/camel/blob/main/camel/storages/key_value_storages/redis.py)\n- [camel/storages/object_storages/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/storages/object_storages/__init__.py)\n \n\n# Storage Systems\n\n## Overview\n\nThe CAMEL-AI storage systems provide a unified abstraction layer for managing different types of data storage backends. The storage module enables AI agents to persist, retrieve, and manage various forms of data including embeddings, knowledge graphs, key-value caches, and object files. This architecture follows a plugin-based pattern where each storage backend implements a common interface, allowing seamless switching between different storage technologies without changing application code.\n\nThe storage subsystem is organized into four primary categories: Vector Database Storages for embedding-based similarity search, Graph Storages for relationship-based data, Key-Value Storages for fast caching, and Object Storages for file-based persistence. Each category is designed to address specific data access patterns commonly required in AI agent workflows, such as retrieval-augmented generation (RAG), memory management, and knowledge representation.\n\n## Architecture Overview\n\nThe storage architecture follows a hierarchical design with a base abstraction layer that defines common operations, followed by category-specific base classes, and finally concrete implementations for specific storage backends.\n\n```mermaid\ngraph TB\n subgraph \"Storage Module Architecture\"\n A[\"camel.storages\"]\n B[\"VectorDB Storages\"]\n C[\"Graph Storages\"]\n D[\"Key-Value Storages\"]\n E[\"Object Storages\"]\n \n A --> B\n A --> C\n A --> D\n A --> E\n \n B --> B1[\"Base VectorDB\"]\n B1 --> B2[\"Chroma\"]\n B1 --> B3[\"FAISS\"]\n B1 --> B4[\"Qdrant\"]\n B1 --> B5[\"PGVector\"]\n \n C --> C1[\"Neo4j Graph\"]\n \n D --> D1[\"Redis KV\"]\n \n E --> E1[\"Base Object Storage\"]\n end\n```\n\n## Vector Database Storages\n\n### Purpose and Scope\n\nVector database storages in CAMEL-AI provide specialized functionality for storing and querying vector embeddings. These storages are essential for implementing similarity search capabilities required by retrieval-augmented generation systems, semantic search, and any application that needs to find documents or data points based on vector similarity rather than exact matches.\n\nThe vector storage implementations support common operations including adding vectors with associated metadata, performing similarity searches to find the k-nearest neighbors to a given query vector, updating existing vector records, and deleting vectors from the database.\n\n### Base VectorDB Class\n\nThe base vector database class defines the interface that all vector storage implementations must follow. This abstraction ensures consistent API behavior across different vector database backends while allowing each implementation to leverage the specific capabilities of its underlying technology.\n\n**Core Operations:**\n\n| Operation | Description |\n|-----------|-------------|\n| `upsert` | Insert or update vectors with unique identifiers |\n| `query` | Search for similar vectors using a query vector |\n| `delete` | Remove vectors by their identifiers |\n| `clear` | Remove all vectors from the storage |\n\n资料来源：[camel/storages/vectordb_storages/base.py]()\n\n### Supported Vector Database Backends\n\nCAMEL-AI provides native implementations for four popular vector database technologies, each offering different trade-offs in terms of scalability, deployment complexity, and feature set.\n\n#### Chroma\n\nChroma is an open-source embedding database designed for AI applications. The CAMEL-AI Chroma integration provides a lightweight, easy-to-use vector storage solution suitable for development and testing environments. Chroma can run in embedded mode (within the application process) or connect to a Chroma server instance for production deployments.\n\n**Configuration Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `dimension` | int | Yes | Dimensionality of the embedding vectors |\n| `collection_name` | str | No | Name of the collection (default: \"camel\") |\n| `persist_directory` | str | No | Directory for persistent storage |\n| `client` | ChromaClient | No | Custom Chroma client instance |\n\n资料来源：[camel/storages/vectordb_storages/chroma.py]()\n\n#### FAISS\n\nFacebook AI Similarity Search (FAISS) is a library developed by Meta for efficient similarity search and clustering of dense vectors. The FAISS integration in CAMEL-AI provides a fast, memory-efficient vector storage implementation that operates entirely in-process without requiring an external database server. FAISS is particularly well-suited for applications requiring high-performance vector operations with large datasets.\n\n**Configuration Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `dimension` | int | Yes | Dimensionality of the embedding vectors |\n| `index_type` | str | No | FAISS index type (default: \"Flat\") |\n| `metric_type` | str | No | Distance metric - \"L2\" or \"IP\" for inner product |\n\n资料来源：[camel/storages/vectordb_storages/faiss.py]()\n\n#### Qdrant\n\nQdrant is a vector similarity search engine with a REST API. The CAMEL-AI Qdrant integration enables connection to Qdrant servers, supporting both local Qdrant instances and Qdrant Cloud services. Qdrant provides advanced filtering capabilities, payload storage, and horizontal scalability.\n\n**Configuration Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `collection_name` | str | No | Name of the Qdrant collection |\n| `vector_dim` | int | Yes | Dimensionality of vectors |\n| `url` | str | No | Qdrant server URL |\n| `grpc_port` | int | No | gRPC port for faster connections |\n| `distance` | str | No | Distance metric: \"Cosine\", \"Euclidean\", or \"Dot\" |\n\n资料来源：[camel/storages/vectordb_storages/qdrant.py]()\n\n#### PGVector\n\nPGVector is an extension for PostgreSQL that enables vector similarity search within the PostgreSQL database. The CAMEL-AI PGVector integration allows storing vectors alongside relational data, enabling hybrid queries that combine semantic search with traditional SQL filtering. This integration is ideal for applications already using PostgreSQL or requiring ACID compliance.\n\n**Configuration Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `dimension` | int | Yes | Dimensionality of embedding vectors |\n| `host` | str | No | PostgreSQL host |\n| `port` | int | No | PostgreSQL port (default: 5432) |\n| `database` | str | No | Database name |\n| `table_name` | str | No | Table name for vectors |\n| `pre_delete` | bool | No | Delete existing collection on init |\n\n资料来源：[camel/storages/vectordb_storages/pgvector.py]()\n\n### Vector Storage Workflow\n\n```mermaid\ngraph LR\n A[\"Embed Text\"] --> B[\"Generate Vector\"]\n B --> C[\"Upsert to VectorDB\"]\n C --> D[\"Store with Metadata\"]\n \n E[\"Query Request\"] --> F[\"Embed Query\"]\n F --> G[\"VectorDB Query\"]\n G --> H[\"Return Similar Results\"]\n \n style A fill:#e1f5fe\n style E fill:#fff3e0\n style H fill:#e8f5e9\n```\n\n## Graph Storages\n\n### Purpose and Scope\n\nGraph storages in CAMEL-AI provide capabilities for storing and querying structured data represented as graphs. These storages are designed for knowledge representation, relationship mapping, and complex queries that involve traversing connections between entities. Graph storages are particularly valuable for AI agents that need to maintain and query structured knowledge, understand entity relationships, and perform multi-hop reasoning.\n\nThe graph storage implementations support operations including adding nodes with properties, creating and managing relationships between nodes, querying the graph using pattern matching, and traversing the graph to discover connected entities.\n\n### Neo4j Graph Storage\n\nNeo4j is a leading graph database that stores data as nodes and relationships with properties. The CAMEL-AI Neo4j integration provides a comprehensive interface for managing knowledge graphs, enabling AI agents to store structured information about entities and their relationships.\n\n**Core Operations:**\n\n| Operation | Description |\n|-----------|-------------|\n| `upsert_node` | Create or update a node with properties |\n| `create_relationship` | Establish a relationship between two nodes |\n| `query` | Execute Cypher queries against the graph |\n| `delete` | Remove nodes or relationships |\n\n**Node Structure:**\n- Unique identifier for each node\n- Label for categorization\n- Properties as key-value pairs\n- Timestamp metadata for tracking\n\n**Relationship Structure:**\n- Source and target node references\n- Relationship type\n- Properties for additional context\n\n资料来源：[camel/storages/graph_storages/neo4j_graph.py]()\n\n### Graph Storage Data Model\n\n```mermaid\ngraph TD\n A[\"Entity Node\"] -->|\"HAS_PROPERTY\"| B[\"Property\"]\n A -->|\"RELATES_TO\"| C[\"Entity Node\"]\n C -->|\"RELATES_TO\"| D[\"Entity Node\"]\n \n style A fill:#bbdefb\n style C fill:#c8e6c9\n style D fill:#ffccbc\n```\n\n## Key-Value Storages\n\n### Purpose and Scope\n\nKey-value storages provide fast, in-memory or disk-backed storage for simple data that can be accessed using unique keys. These storages are optimized for caching, session management, and temporary data storage where the overhead of complex queries is not required. CAMEL-AI's key-value storage implementation supports rapid read and write operations essential for maintaining agent state and caching frequently accessed data.\n\n### Redis Key-Value Storage\n\nRedis is an open-source, in-memory data structure store used as a database, cache, and message broker. The CAMEL-AI Redis integration provides a high-performance key-value storage solution suitable for caching agent responses, storing session data, and maintaining temporary state information.\n\n**Core Operations:**\n\n| Operation | Description |\n|-----------|-------------|\n| `read` | Retrieve a value by key |\n| `write` | Store a value with optional TTL |\n| `delete` | Remove a key-value pair |\n| `exists` | Check if a key exists |\n| `clear` | Remove all keys in the namespace |\n\n**Configuration Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `host` | str | No | Redis host (default: \"localhost\") |\n| `port` | int | No | Redis port (default: 6379) |\n| `db` | int | No | Database number (default: 0) |\n| `password` | str | No | Authentication password |\n| `key_prefix` | str | No | Prefix for all keys |\n\n资料来源：[camel/storages/key_value_storages/redis.py]()\n\n## Object Storages\n\n### Purpose and Scope\n\nObject storages provide file-based persistence capabilities for storing and retrieving arbitrary objects, documents, and binary data. These storages complement the other storage types by handling data that is best managed as files rather than structured records. Object storages are used for persisting agent outputs, storing documents, and managing file-based artifacts generated during agent workflows.\n\nThe object storage module provides a base interface that can be implemented by various backends depending on deployment requirements. This abstraction allows applications to store objects locally during development while supporting cloud-based object storage in production environments.\n\n资料来源：[camel/storages/object_storages/__init__.py]()\n\n## Common Patterns and Usage\n\n### Storage Selection Guide\n\nSelecting the appropriate storage type depends on your application's specific requirements. The following guidelines help determine which storage solution best fits different use cases.\n\n| Use Case | Recommended Storage | Rationale |\n|----------|---------------------|-----------|\n| Semantic Search / RAG | VectorDB (Chroma/FAISS) | Optimized for similarity search on embeddings |\n| Knowledge Graphs | Neo4j | Graph traversal and relationship queries |\n| Session Caching | Redis | Sub-millisecond latency for key access |\n| Document Storage | Object Storage | File-based persistence with metadata |\n| Hybrid Search | PGVector | Combines vector search with SQL filtering |\n\n### Initialization Pattern\n\nAll storage implementations follow a consistent initialization pattern that allows for both required and optional configuration parameters. The typical workflow involves creating a storage instance with necessary parameters, optionally verifying connectivity, and then using the storage for data operations.\n\n```python\n# Example: Initialize a vector storage\nfrom camel.storages import VectorDBStorage\n\nstorage = VectorDBStorage(\n dimension=1536,\n collection_name=\"knowledge_base\"\n)\n\n# Perform operations\nstorage.upsert(vectors, ids, metadata)\nresults = storage.query(query_vector, top_k=5)\n```\n\n## Module Exports\n\nThe storage module exports all storage implementations through its public API, allowing imports from a central location rather than individual modules.\n\n**Public Exports:**\n\n```python\nfrom camel.storages import (\n # VectorDB Storage\n VectorDBStorage,\n ChromaStorage,\n FAISSStorage,\n QdrantStorage,\n PGVectorStorage,\n \n # Graph Storage\n Neo4jGraphStorage,\n \n # Key-Value Storage\n RedisKeyValueStorage,\n)\n```\n\n资料来源：[camel/storages/__init__.py]()\n资料来源：[camel/storages/vectordb_storages/__init__.py]()\n资料来源：[camel/storages/graph_storages/__init__.py]()\n资料来源：[camel/storages/key_value_storages/__init__.py]()\n\n## Integration with Agent Systems\n\nThe storage systems are designed to integrate seamlessly with CAMEL-AI's agent framework. Agents can utilize storage backends for various purposes including:\n\n- **Memory Management**: Storing conversation history and context\n- **Knowledge Retrieval**: Accessing persistent knowledge bases\n- **Result Caching**: Preventing redundant computations\n- **State Persistence**: Maintaining agent state across sessions\n\nThe unified interface design ensures that agents can switch between storage backends without code changes, enabling flexibility in deployment configurations and supporting different scalability requirements.\n\n## Summary\n\nCAMEL-AI's Storage Systems provide a comprehensive, modular approach to data persistence for AI agent applications. By offering specialized implementations for vector databases, graph databases, key-value stores, and object storage, the framework enables developers to choose the most appropriate storage technology for their specific use case while maintaining a consistent programming interface. The plugin-based architecture facilitates extensibility, allowing new storage backends to be added without modifying existing application code.\n\n---\n\n\n\n## Data Generation\n\n### 相关页面\n\n相关主题：[Introduction to CAMEL](#page-introduction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/datagen/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/datagen/__init__.py)\n- [camel/datagen/self_instruct/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/datagen/self_instruct/__init__.py)\n- [camel/datagen/self_instruct/self_instruct.py](https://github.com/camel-ai/camel/blob/main/camel/datagen/self_instruct/self_instruct.py)\n- [camel/datagen/cot_datagen.py](https://github.com/camel-ai/camel/blob/main/camel/datagen/cot_datagen.py)\n- [camel/datagen/evol_instruct/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/datagen/evol_instruct/__init__.py)\n- [camel/datagen/evol_instruct/evol_instruct.py](https://github.com/camel-ai/camel/blob/main/camel/datagen/evol_instruct/evol_instruct.py)\n- [camel/datagen/evol_instruct/scorer.py](https://github.com/camel-ai/camel/blob/main/camel/datagen/evol_instruct/scorer.py)\n- [camel/datagen/self_improving_cot.py](https://github.com/camel-ai/camel/blob/main/camel/datagen/self_improving_cot.py)\n- [camel/datagen/source2synth/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/datagen/source2synth/__init__.py)\n- [camel/datasets/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/datasets/__init__.py)\n- [camel/datasets/static_dataset.py](https://github.com/camel-ai/camel/blob/main/camel/datasets/static_dataset.py)\n \n\n# Data Generation\n\n## Overview\n\nThe Data Generation module in CAMEL-AI provides a comprehensive framework for synthetic data creation to train and improve large language models (LLMs). This module implements multiple data generation strategies including Self-Instruct, Evolution Instruct, Chain-of-Thought (CoT) generation, and source-to-synthesis pipelines.\n\nThe data generation system enables developers to:\n- Generate instruction-following datasets from seed examples\n- Evolve existing instructions to increase complexity and diversity\n- Create chain-of-thought reasoning datasets\n- Synthesize data from various source formats into structured datasets\n\n资料来源：[camel/datagen/__init__.py]()\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"Data Generation Core\"\n SI[Self-Instruct]\n EI[Evolution Instruct]\n COT[Chain-of-Thought]\n S2S[Source2Synth]\n end\n \n subgraph \"Supporting Components\"\n SC[Scorer]\n SD[Static Dataset]\n end\n \n subgraph \"Data Sources\"\n Seed[Seed Examples]\n Raw[Raw Sources]\n Existing[Existing Datasets]\n end\n \n subgraph \"Outputs\"\n Instructions[Instruction Datasets]\n CoT_Data[CoT Datasets]\n Synth[Synthetic Datasets]\n end\n \n Seed --> SI\n Seed --> EI\n Raw --> S2S\n Existing --> COT\n \n SI --> Instructions\n EI --> Instructions\n COT --> CoT_Data\n S2S --> Synth\n \n SC --> EI\n SD --> COT\n```\n\n## Core Components\n\n### Self-Instruct Module\n\nThe Self-Instruct module generates instruction-following data by prompting an LLM to produce new instructions based on a set of seed examples. This approach reduces the need for manual annotation while maintaining instruction diversity.\n\n资料来源：[camel/datagen/self_instruct/__init__.py]()\n\n#### SelfInstruct Class\n\n```python\nclass SelfInstruct(BaseSelfInstruct):\n def run(\n num_instructions: int = 100,\n seed_task_path: str = \"seed_task.txt\"\n ) -> List[Dict[str, Any]]\n```\n\n**Key Features:**\n- Generates new instructions from seed task examples\n- Uses LLM to produce diverse instruction variants\n- Filters generated instructions for quality\n- Supports batch processing for scalability\n\n资料来源：[camel/datagen/self_instruct/self_instruct.py]()\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `num_instructions` | `int` | Number of instructions to generate (default: 100) |\n| `seed_task_path` | `str` | Path to seed task examples file |\n| `model` | `Model` | LLM model instance for generation |\n| `batch_size` | `int` | Number of instructions per batch |\n\n### Evolution Instruct Module\n\nThe Evolution Instruct module enhances existing instructions by progressively increasing their complexity. It generates multiple variants at different difficulty levels and evaluates them using a scoring mechanism.\n\n资料来源：[camel/datagen/evol_instruct/__init__.py]()\n\n#### Evolution Workflow\n\n```mermaid\ngraph LR\n A[Original Instructions] --> B[Level 1 - Simpler]\n A --> C[Level 2 - Moderate]\n A --> D[Level 3 - Complex]\n A --> E[Level N - Expert]\n \n B --> F[Scorer Evaluation]\n C --> F\n D --> F\n E --> F\n \n F --> G[Evolved Dataset]\n```\n\n**Evolution Levels:**\n- **Level 1 (Simpler)**: Reduce complexity, add constraints\n- **Level 2 (Moderate)**: Maintain similar complexity with variations\n- **Level 3 (Complex)**: Add multi-step reasoning requirements\n- **Level N (Expert)**: Expert-level domain-specific challenges\n\n资料来源：[camel/datagen/evol_instruct/evol_instruct.py]()\n\n| Evolution Level | Description | Use Case |\n|-----------------|-------------|----------|\n| 1 | Simpler tasks | Beginner training |\n| 2 | Moderate complexity | General training |\n| 3 | Complex reasoning | Advanced tasks |\n| N | Expert level | Specialized domains |\n\n#### Scorer Component\n\nThe Scorer evaluates evolved instructions based on quality metrics, ensuring the generated data meets relevance and complexity thresholds.\n\n资料来源：[camel/datagen/evol_instruct/scorer.py]()\n\n| Score Aspect | Metric | Threshold |\n|--------------|--------|-----------|\n| Relevance | Semantic similarity | ≥ 0.7 |\n| Complexity | Token count increase | ≥ 1.2x |\n| Diversity | Unique n-grams | ≥ 0.5 |\n\n## Chain-of-Thought Data Generation\n\nThe CoT Data Generation module creates reasoning chains that demonstrate step-by-step problem solving. This is essential for training models that require logical reasoning capabilities.\n\n资料来源：[camel/datagen/cot_datagen.py]()\n\n### Self-Improving CoT\n\nThe Self-Improving Chain-of-Thought component implements a self-reflection and improvement loop for reasoning chains:\n\n```mermaid\ngraph TD\n A[Initial Query] --> B[Generate Reasoning]\n B --> C[Execute Steps]\n C --> D[Validate Results]\n D -->|Valid| E[Accept Solution]\n D -->|Invalid| F[Identify Errors]\n F --> G[Regenerate Reasoning]\n G --> B\n E --> H[Store in Dataset]\n```\n\n**Process Flow:**\n1. Generate initial reasoning chain from query\n2. Execute each step of the reasoning\n3. Validate intermediate and final results\n4. If invalid, identify error points and regenerate\n5. Store successful chains in dataset\n\n资料来源：[camel/datagen/self_improving_cot.py]()\n\n### CoT Data Generation Configuration\n\n```python\nclass CoTDataGen:\n def __init__(\n self,\n model: Model,\n num_reasoning_steps: int = 5,\n max_retries: int = 3,\n temperature: float = 0.7\n )\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `model` | `Model` | Required | LLM for reasoning generation |\n| `num_reasoning_steps` | `int` | 5 | Maximum steps in reasoning chain |\n| `max_retries` | `int` | 3 | Retry attempts for invalid chains |\n| `temperature` | `float` | 0.7 | Sampling temperature |\n\n## Source-to-Synthesis Pipeline\n\nThe Source2Synth module converts raw data from various formats into structured synthetic datasets. This enables integration of heterogeneous data sources into the training pipeline.\n\n资料来源：[camel/datagen/source2synth/__init__.py]()\n\n### Supported Source Formats\n\n| Source Type | Input Format | Processing |\n|-------------|--------------|------------|\n| Text Files | `.txt`, `.md` | Direct parsing |\n| JSON | `.json` | Structured extraction |\n| CSV | `.csv` | Tabular conversion |\n| XML | `.xml` | Hierarchical parsing |\n| HTML | `.html` | Web content extraction |\n\n### Synthesis Process\n\n```mermaid\ngraph TD\n subgraph \"Ingestion\"\n R1[Raw Source 1]\n R2[Raw Source 2]\n R3[Raw Source N]\n end\n \n subgraph \"Processing\"\n P1[Parse & Extract]\n P2[Normalize]\n P3[Validate]\n end\n \n subgraph \"Synthesis\"\n S1[Transform]\n S2[Augment]\n S3[Format]\n end\n \n R1 --> P1\n R2 --> P2\n R3 --> P3\n \n P1 --> S1\n P2 --> S2\n P3 --> S3\n \n S1 --> O[Synthetic Dataset]\n S2 --> O\n S3 --> O\n```\n\n## Dataset Integration\n\n### Static Dataset Module\n\nThe Static Dataset module provides utilities for managing and accessing pre-built datasets used in data generation pipelines.\n\n资料来源：[camel/datasets/__init__.py]()\n\n```python\nclass StaticDataset:\n def __init__(self, name: str, data_path: str)\n def load(self) -> List[Dict]\n def filter(self, predicate: Callable) -> \"StaticDataset\"\n def sample(self, n: int) -> List[Dict]\n```\n\n| Method | Return Type | Description |\n|--------|-------------|-------------|\n| `load()` | `List[Dict]` | Load all data from source |\n| `filter(predicate)` | `StaticDataset` | Filter by condition |\n| `sample(n)` | `List[Dict]` | Random sample of n items |\n\n资料来源：[camel/datasets/static_dataset.py]()\n\n### Dataset Loading Example\n\n```python\nfrom camel.datasets import StaticDataset\n\n# Load a static dataset\ndataset = StaticDataset(\n name=\"reasoning_benchmarks\",\n data_path=\"path/to/data.json\"\n)\n\n# Filter and sample\nfiltered = dataset.filter(lambda x: x[\"difficulty\"] >= 3)\nsamples = filtered.sample(n=100)\n```\n\n## Usage Patterns\n\n### Basic Self-Instruct Pipeline\n\n```python\nfrom camel.datagen.self_instruct import SelfInstruct\nfrom camel.models import ModelFactory\nfrom camel.types import ModelPlatformType\n\n# Initialize model\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=\"gpt-4\"\n)\n\n# Run self-instruct\ngenerator = SelfInstruct(model=model)\nresults = generator.run(\n num_instructions=100,\n seed_task_path=\"seed_tasks.txt\"\n)\n```\n\n### Evolution Instruct Pipeline\n\n```python\nfrom camel.datagen.evol_instruct import EvolutionInstruct\nfrom camel.datagen.evol_instruct.scorer import Scorer\n\n# Initialize scorer\nscorer = Scorer(threshold=0.7)\n\n# Run evolution\nevolver = EvolutionInstruct(\n model=model,\n scorer=scorer\n)\nevolved = evolver.evolve(instructions, target_level=3)\n```\n\n### Chain-of-Thought Generation\n\n```python\nfrom camel.datagen.cot_datagen import CoTDataGen\nfrom camel.datagen.self_improving_cot import SelfImprovingCoT\n\n# Initialize CoT generator\ncot_gen = CoTDataGen(\n model=model,\n num_reasoning_steps=7\n)\n\n# Generate reasoning chain\nquery = \"Calculate the compound interest for $1000 at 5% for 3 years\"\nchain = cot_gen.generate(query)\n```\n\n## Configuration Options\n\n### Global Configuration\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `output_dir` | `str` | `\"./output\"` | Directory for generated data |\n| `batch_size` | `int` | 10 | Processing batch size |\n| `max_tokens` | `int` | 2048 | Maximum tokens per generation |\n| `temperature` | `float` | 0.8 | Sampling temperature |\n| `seed` | `int` | 42 | Random seed for reproducibility |\n\n### Provider-Specific Settings\n\n```python\n@dataclass\nclass DataGenConfig:\n # OpenAI\n api_base: Optional[str] = None\n api_version: Optional[str] = None\n \n # Model settings\n model: str = \"gpt-4\"\n max_retries: int = 3\n timeout: int = 60\n \n # Output settings\n save_intermediate: bool = True\n format: str = \"json\" # json, csv, parquet\n```\n\n## Best Practices\n\n1. **Seed Selection**: Choose diverse, high-quality seed examples to ensure variety in generated data\n2. **Quality Filtering**: Always apply scorer-based filtering to maintain instruction quality\n3. **Batch Processing**: Use appropriate batch sizes to balance memory usage and throughput\n4. **Validation**: Implement result validation before storing in final datasets\n5. **Iteration**: Use self-improving loops for complex reasoning tasks\n\n## Error Handling\n\n| Error Type | Cause | Resolution |\n|------------|-------|------------|\n| `GenerationError` | LLM fails to generate | Increase temperature, check API |\n| `ValidationError` | Output format invalid | Add post-processing, retry |\n| `TimeoutError` | Request takes too long | Increase timeout, reduce batch |\n| `QuotaError` | API quota exceeded | Implement backoff, use caching |\n\n## Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `camel-ai` | ≥ 0.2.x | Core framework |\n| `openai` | Latest | API access |\n| `tqdm` | Latest | Progress bars |\n| `pydantic` | Latest | Data validation |\n\n## Summary\n\nThe Data Generation module provides a comprehensive toolkit for creating synthetic training data:\n\n- **Self-Instruct**: Generate instruction-following data from seeds\n- **Evolution Instruct**: Progressively increase instruction complexity\n- **Chain-of-Thought**: Create reasoning chains with validation\n- **Source2Synth**: Convert heterogeneous sources to structured datasets\n\nThese components work together to enable scalable, high-quality data generation for training and fine-tuning language models.\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：camel-ai/camel\n\n摘要：发现 38 个潜在踩坑项，其中 7 个为 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. 安全/权限坑 · 失败模式：security_permissions: [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit funct...\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：Developers should check this security_permissions risk before relying on the project: [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools\n- 对用户的影响：Developers may expose sensitive permissions or credentials: [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools. Context: Observed when using python, macos\n- 防护动作：Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/camel-ai/camel/issues/3962\n- 证据：failure_mode_cluster:github_issue | fmev_5824c9dd1e33710f6821d3f625c9b2fb | https://github.com/camel-ai/camel/issues/3962 | [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools\n\n## 5. 安全/权限坑 · 来源证据：[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## 6. 安全/权限坑 · 来源证据：[BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5736e8e2efc44fa48c0eea95b3bf0ff7 | https://github.com/camel-ai/camel/issues/4037 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安全/权限坑 · 来源证据：[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## 8. 安装坑 · 失败模式：installation: [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter w...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary\n- 对用户的影响：Developers may fail before the first successful local run: [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary. Context: Observed when using python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_ac00b6564e4aa8e23d6fa0056cc45d02 | https://github.com/camel-ai/camel/issues/4037 | [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary\n\n## 9. 安装坑 · 失败模式：installation: [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators\n- 对用户的影响：Developers may fail before the first successful local run: [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators. Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_b869fb190d161706644bb5c7e94bff8f | https://github.com/camel-ai/camel/issues/1043 | [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators, failure_mode_cluster:github_issue | fmev_e2d8786f2a91f791c3d6c7a2c4207d65 | https://github.com/camel-ai/camel/issues/1043 | [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators\n\n## 10. 安装坑 · 失败模式：installation: v0.2.90\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v0.2.90\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.2.90\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.2.90. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_6bc0695558dc4dc7fb064fa89c64c718 | https://github.com/camel-ai/camel/releases/tag/v0.2.90 | v0.2.90\n\n## 11. 配置坑 · 失败模式：configuration: [BUG] Both Bedrock options are broken\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: [BUG] Both Bedrock options are broken\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [BUG] Both Bedrock options are broken\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] Both Bedrock options are broken. Context: Observed when using python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_b5a875260984ae51f7f9b81869057a15 | https://github.com/camel-ai/camel/issues/4034 | [BUG] Both Bedrock options are broken\n\n## 12. 配置坑 · 失败模式：configuration: [Feature Request] Add OrcaRouter as a dedicated model platform\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: [Feature Request] Add OrcaRouter as a dedicated model platform\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Feature Request] Add OrcaRouter as a dedicated model platform\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature Request] Add OrcaRouter as a dedicated model platform. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_9bce4812aa6a39fc876b639a79f00c41 | https://github.com/camel-ai/camel/issues/4047 | [Feature Request] Add OrcaRouter as a dedicated model platform, failure_mode_cluster:github_issue | fmev_fefb71c23b8534f3eac0377e0a8ea5b2 | https://github.com/camel-ai/camel/issues/4047 | [Feature Request] Add OrcaRouter as a dedicated model platform\n\n## 13. 配置坑 · 失败模式：configuration: [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter). Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_ab8611c09187bc446ab4c53a8bbcc224 | https://github.com/camel-ai/camel/issues/3997 | [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)\n\n## 14. 配置坑 · 失败模式：configuration: v0.2.90a6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: v0.2.90a6\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.2.90a6\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.2.90a6. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_39f1f2bb3b67152c4f05563686719964 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a6 | v0.2.90a6\n\n## 15. 能力坑 · 社区讨论暴露的待验证问题：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## 16. 能力坑 · 能力判断依赖假设\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## 17. 运行坑 · 失败模式：runtime: [BUG] outdated colab notebook for workforce\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: [BUG] outdated colab notebook for workforce\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [BUG] outdated colab notebook for workforce\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] outdated colab notebook for workforce. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_3ea7bee5bfb83c37e4330b7761951754 | https://github.com/camel-ai/camel/issues/3402 | [BUG] outdated colab notebook for workforce\n\n## 18. 运行坑 · 失败模式：runtime: v0.2.91a2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: v0.2.91a2\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.2.91a2\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.2.91a2. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_0446994fae1af587527e35be6a08cbd5 | https://github.com/camel-ai/camel/releases/tag/v0.2.91a2 | v0.2.91a2\n\n## 19. 运行坑 · 来源证据：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## 20. 维护坑 · 失败模式：migration: [Question] About the Deprecation of the `reasoning_content` Field in vLLM\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: [Question] About the Deprecation of the `reasoning_content` Field in vLLM\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [Question] About the Deprecation of the `reasoning_content` Field in vLLM\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Question] About the Deprecation of the `reasoning_content` Field in vLLM. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_b64551687144d0e563078a212537da6a | https://github.com/camel-ai/camel/issues/3939 | [Question] About the Deprecation of the `reasoning_content` Field in vLLM\n\n## 21. 维护坑 · 来源证据：[BUG] outdated colab notebook for workforce\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[BUG] outdated colab notebook for workforce\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0d22381ba8a94b30ab0aff9599be8202 | https://github.com/camel-ai/camel/issues/3402 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 22. 维护坑 · 来源证据：[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## 23. 维护坑 · 维护活跃度未知\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## 24. 安全/权限坑 · 下游验证发现风险项\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## 25. 安全/权限坑 · 存在评分风险\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## 26. 安全/权限坑 · 来源证据：[BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3cc4f8df85fe4b1ebc26d3477bd4ad1d | https://github.com/camel-ai/camel/issues/3962 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 27. 安全/权限坑 · 来源证据：[feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_abab965da9ee45c0af51f9d4bd294bfe | https://github.com/camel-ai/camel/issues/3997 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 28. 安全/权限坑 · 来源证据：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## 29. 安全/权限坑 · 来源证据：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## 30. 安全/权限坑 · 来源证据：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## 31. 安全/权限坑 · 来源证据：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## 32. 能力坑 · 失败模式：conceptual: [Feature Request] Expand WorkforceCallback to support stream chunk events\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this conceptual risk before relying on the project: [Feature Request] Expand WorkforceCallback to support stream chunk events\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [Feature Request] Expand WorkforceCallback to support stream chunk events\n- 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_5c8a43fe428bd06c588a897fec9e5f46 | https://github.com/camel-ai/camel/issues/3676 | [Feature Request] Expand WorkforceCallback to support stream chunk events\n\n## 33. 能力坑 · 失败模式：conceptual: [Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got prob...\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this conceptual risk before relying on the project: [Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls\n- 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_f160cb19b4b146ff4d9530da5c4ebe6d | https://github.com/camel-ai/camel/issues/4045 | [Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls\n\n## 34. 维护坑 · 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## 35. 维护坑 · 发布节奏不明确\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## 36. 维护坑 · 失败模式：maintenance: v0.2.90a4\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: v0.2.90a4\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.2.90a4\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.2.90a4. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_bfdefa69f610e48e209896526275a8b1 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a4 | v0.2.90a4\n\n## 37. 维护坑 · 失败模式：maintenance: v0.2.90a5\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: v0.2.90a5\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.2.90a5\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.2.90a5. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_2ee088361f2e44b420faa3e982ec9e81 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a5 | v0.2.90a5\n\n## 38. 维护坑 · 失败模式：maintenance: v0.2.91a0\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: v0.2.91a0\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.2.91a0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.2.91a0. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_ac76756c522679a553aa6056ac6118a0 | https://github.com/camel-ai/camel/releases/tag/v0.2.91a0 | v0.2.91a0\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 项目说明书",
"目录",
"Introduction to CAMEL",
"Overview",
"Core Architecture",
"Key Features",
"Supported Platforms and Integrations",
"Supported AI Models",
"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": "0d917c0f9dd61d96850a7e0438c0d9d4ed325c02",
"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- 文件总数：2048\n- 重要文件覆盖：40/2048\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[RolePlaying Orchestrator]\n B --> C1[AI Assistant Agent]\n B --> C2[AI User Agent]\n C1 <--> C2[Structured Communication]\n C1 --> D1[Toolkits]\n C2 --> D2[External APIs]\n D1 --> E[Task Completion]\n D2 --> E\n```\n\n## Key Features\n\n### Role-Playing System\n\nCAMEL implements a role-playing architecture where agents are assigned specific roles and responsibilities. This enables:\n\n- **Specialized Task Handling**: Different agents handle different aspects of a complex task\n- **Structured Communication**: Agents communicate through defined protocols\n- **Collaborative Problem Solving**: Multiple agents work together to reach solutions\n\n资料来源：[apps/agents/README.md](https://github.com/camel-ai/camel/blob/main/apps/agents/README.md)\n\n### Tool Integration\n\nCAMEL provides extensive tool integration capabilities through various toolkits:\n\n| Toolkit | Use Case | External Dependency |\n|---------|----------|---------------------|\n| `PPTXToolkit` | PowerPoint generation | OpenAI API |\n| `Mistral OCR` | Document text extraction | Mistral API |\n| `Firecrawl` | Web scraping | Firecrawl API |\n| `MCP Servers` | External tool connectivity | Various MCP providers |\n\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### Multi-Agent Research Assistant\n\nOne of the primary use cases for CAMEL is the multi-agent research assistant, which demonstrates:\n\n1. **Topic Analysis**: Identifying relevant research areas\n2. **Information Retrieval**: Gathering academic papers and news\n3. **Report Generation**: Creating comprehensive research reports\n4. **Content Enhancement**: Generating illustrative images\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## Supported Platforms and Integrations\n\n### Code Platforms\n\nCAMEL integrates with popular coding platforms to solve programming problems:\n\n- **Codeforces**: Solves competitive programming problems using problem IDs\n- **LeetCode**: Handles algorithm challenges using problem slugs\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### External Services\n\nCAMEL connects to various external services through MCP (Model Context Protocol):\n\n```mermaid\ngraph LR\n A[CAMEL Framework] --> B[MCP Server Layer]\n B --> C1[Airbnb MCP]\n B --> C2[Cloudflare MCP]\n B --> C3[ACI.dev MCP]\n B --> C4[Github MCP]\n C1 --> D1[Booking Data]\n C2 --> D2[Internet Analytics]\n C3 --> D3[Search & APIs]\n C4 --> D4[Repository Data]\n```\n\n资料来源：[examples/usecases/cloudfare_mcp_camel/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/cloudfare_mcp_camel/README.md)\n\n### Runtime Environments\n\nCAMEL supports multiple runtime environments:\n\n| Environment | Description | Use Case |\n|-------------|-------------|----------|\n| Docker | Containerized execution | Scalable deployments |\n| Streamlit | Web application UI | Interactive demos |\n| Gradio | ML model interfaces | Data exploration |\n| HuggingFace Spaces | Cloud deployment | Public hosting |\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## Supported AI Models\n\nCAMEL provides flexibility in model selection through the `ModelFactory`:\n\n| Model Platform | Model Types | Configuration |\n|----------------|-------------|---------------|\n| OpenAI | GPT-4, GPT-4o | API key authentication |\n| Google Gemini | Gemini 2.5 Pro | API key authentication |\n| OpenAI Compatible | Qwen, custom models | URL + model specification |\n| Mistral | Mistral OCR | API key authentication |\n\n资料来源：[examples/usecases/aci_mcp/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/aci_mcp/README.md)\n\n## Project Structure\n\n```\ncamel/\n├── camel/ # Core framework\n│ ├── __init__.py # Main package exports\n│ └── utils/ # Utilities and constants\n├── apps/ # Standalone applications\n│ ├── agents/ # Gradio agent app\n│ └── data_explorer/ # Dataset browsing tool\n├── examples/ # Usage examples\n│ ├── runtimes/ # Runtime configurations\n│ └── usecases/ # Application use cases\n└── services/ # Backend services\n```\n\n## Installation and Setup\n\n### Basic Installation\n\n```bash\n# Install core package\npip install camel-ai\n\n# Install with all dependencies\npip install camel-ai[all]\n\n# Install specific version\npip install camel-ai[all]==0.2.61\n```\n\n### Environment Configuration\n\nRequired environment variables depend on the use case:\n\n| Variable | Purpose | Required For |\n|----------|---------|--------------|\n| `OPENAI_API_KEY` | OpenAI models | Most use cases |\n| `GEMINI_API_KEY` | Google Gemini models | ACI integration |\n| `FIRECRAWL_API_KEY` | Web scraping | Code solver |\n| `MISTRAL_API_KEY` | OCR functionality | Document processing |\n\n## Deployment Options\n\n### Streamlit Applications\n\nMany CAMEL use cases are deployed as Streamlit applications:\n\n```bash\nstreamlit run app.py\n```\n\nThis launches an interactive web interface for the specific application.\n\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### HuggingFace Spaces\n\nThe agents application can be deployed to HuggingFace Spaces for public access. The deployment process involves:\n\n1. Tagging the commit with `hf_spaces_{X+1}`\n2. Synchronizing with the HF repository\n3. Automatic deployment via HF infrastructure\n\n资料来源：[apps/agents/README.md](https://github.com/camel-ai/camel/blob/main/apps/agents/README.md)\n\n### Docker Runtime\n\nFor containerized deployments:\n\n```bash\nchmod +x manage_camel_docker.sh\n./manage_camel_docker.sh build\n```\n\n## Use Case Workflow\n\n### Multi-Agent Research Assistant Workflow\n\n```mermaid\ngraph TD\n A[User Input: Research Topic] --> B[Topic Analysis Agent]\n B --> C[Researcher Identification]\n C --> D[Paper Retrieval]\n D --> E[News Collection]\n E --> F[Report Generation]\n F --> G[Image Generation]\n G --> H[LinkedIn Preparation]\n H --> I[Final Report Output]\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### Web Content Processing Workflow\n\n```mermaid\ngraph TD\n A[URL Input] --> B[Firecrawl/MCP Browser]\n B --> C[Content Fetching]\n C --> D[Markdown Conversion]\n D --> E[AI Analysis]\n E --> F[Response Generation]\n```\n\n## Error Handling and Debugging\n\nCAMEL applications include comprehensive error handling:\n\n- **Detailed Tracebacks**: Full error context for debugging\n- **API Error Handling**: Graceful handling of external service failures\n- **Permission Checks**: Validation of file and configuration permissions\n- **Network Diagnostics**: Connectivity verification for API calls\n\n资料来源：[examples/usecases/cloudfare_mcp_camel/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/cloudfare_mcp_camel/README.md)\n\n## License\n\nCAMEL is licensed under the Apache License, Version 2.0, allowing for both commercial and open-source use with appropriate attribution.\n\n资料来源：[examples/usecases/aci_mcp/README.md](https://github.com/camel-ai/camel/blob/main/examples/usecases/aci_mcp/README.md)\n\n## Community and Resources\n\nCAMEL is maintained by the CAMEL-AI.org community and provides:\n\n- Comprehensive documentation through example use cases\n- Multiple deployment options for different environments\n- Integration with popular AI services and platforms\n- Extensible architecture for custom agent implementations\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Introduction to CAMEL](#page-introduction), [Agent Types and System](#page-agents), [Workforce Management](#page-workforce)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/agents/chat_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/chat_agent.py)\n- [camel/agents/base.py](https://github.com/camel-ai/camel/blob/main/camel/agents/base.py)\n- [camel/messages/base.py](https://github.com/camel-ai/camel/blob/main/camel/messages/base.py)\n- [camel/responses/agent_responses.py](https://github.com/camel-ai/camel/blob/main/camel/responses/agent_responses.py)\n- [camel/terminators/response_terminator.py](https://github.com/camel-ai/camel/blob/main/camel/terminators/response_terminator.py)\n- [camel/terminators/token_limit_terminator.py](https://github.com/camel-ai/camel/blob/main/camel/terminators/token_limit_terminator.py)\n \n\n# System Architecture\n\n## Overview\n\nCAMEL (Communicative Agents for Multi-Agent Learning) is a foundational multi-agent framework designed to enable autonomous cooperation among LLM-based agents. The system architecture follows a modular design pattern that separates concerns between agent orchestration, message passing, response handling, and termination conditions. This architecture supports various use cases including role-playing, research assistance, web scraping, and integration with external tools through Model Context Protocol (MCP) servers. 资料来源：[examples/usecases/multi_agent_research_assistant/README.md]()\n\nThe core architectural philosophy emphasizes:\n\n- **Separation of concerns**: Agents, messages, responses, and terminators are distinct modules with well-defined responsibilities\n- **Extensibility**: The base classes allow for custom agent implementations and termination strategies\n- **Composability**: Multiple agents can collaborate in workflows while maintaining independent state\n- **Resource awareness**: Built-in token limit handling prevents excessive resource consumption\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph \"Agent Layer\"\n CA[ChatAgent]\n BA[BaseAgent]\n end\n \n subgraph \"Message Layer\"\n MB[Message Base]\n UM[UserMessage]\n AM[AssistantMessage]\n SM[SystemMessage]\n end\n \n subgraph \"Response Layer\"\n AR[AgentResponses]\n RR[ResponseTerminator]\n TL[TokenLimitTerminator]\n end\n \n subgraph \"External Integration\"\n MCP[MCP Servers]\n TOOLS[Toolkits]\n end\n \n CA --> BA\n CA --> MB\n CA --> AR\n AR --> RR\n AR --> TL\n CA --> MCP\n CA --> TOOLS\n```\n\n## Core Components\n\n### 1. Agent System\n\n#### BaseAgent\n\nThe `BaseAgent` class serves as the foundational abstraction for all agent implementations in CAMEL. It defines the core interface and lifecycle methods that derived agents must implement. The base agent handles fundamental operations such as:\n\n- Agent initialization and configuration\n- State management across conversation turns\n- Message routing and processing\n- Integration with underlying LLM backends\n\n资料来源：[camel/agents/base.py:1-50]()\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `model` | `BaseModel` | The underlying language model instance |\n| `message_history` | `List[BaseMessage]` | Accumulated conversation history |\n| `system_message` | `SystemMessage` | Agent-specific system instructions |\n| `max_retries` | `int` | Maximum retry attempts for failed operations |\n\n#### ChatAgent\n\nThe `ChatAgent` extends `BaseAgent` to provide chat-specific functionality optimized for conversational interactions. It implements the core step mechanism that processes incoming messages and generates responses.\n\n```python\nclass ChatAgent(BaseAgent):\n def __init__(self, system_message: SystemMessage, model: BaseModel, ...):\n ...\n \n def step(self, message: UserMessage) -> ChatAgentResponse:\n ...\n```\n\n资料来源：[camel/agents/chat_agent.py:50-100]()\n\n**Key Responsibilities:**\n\n1. **Step Execution**: Processes a single conversation turn by receiving a user message, updating context, and returning an agent response\n2. **History Management**: Maintains and optionally truncates conversation history to stay within token limits\n3. **Response Generation**: Orchestrates the LLM call and processes the generated response\n4. **Tool Integration**: Supports function calling and external tool execution when configured\n\n资料来源：[camel/agents/chat_agent.py:100-150]()\n\n### 2. Message System\n\n#### Message Base Structure\n\nAll messages in CAMEL inherit from `BaseMessage`, which provides a standardized structure for communication between agents and external systems.\n\n```mermaid\nclassDiagram\n class BaseMessage {\n +str role\n +str content\n +Dict metadata\n +str id\n +float token_ratio\n }\n \n class UserMessage {\n +str role = \"user\"\n }\n \n class AssistantMessage {\n +str role = \"assistant\"\n +Optional~List[FunctionCall]~ tool_calls\n }\n \n class SystemMessage {\n +str role = \"system\"\n }\n \n BaseMessage <|-- UserMessage\n BaseMessage <|-- AssistantMessage\n BaseMessage <|-- SystemMessage\n```\n\n资料来源：[camel/messages/base.py:1-80]()\n\n| Message Type | Role Value | Purpose |\n|--------------|------------|---------|\n| `UserMessage` | `\"user\"` | Input from human users or external systems |\n| `AssistantMessage` | `\"assistant\"` | Responses generated by the LLM |\n| `SystemMessage` | `\"system\"` | System-level instructions and prompts |\n| `ToolMessage` | `\"tool\"` | Results from tool executions |\n\n#### Message Flow\n\n```mermaid\ngraph LR\n UM[UserMessage] -->|Input| CA[ChatAgent]\n CA -->|Process| LLM[Language Model]\n LLM -->|Raw Response| CA\n CA -->|Parsed| AM[AssistantMessage]\n AM -->|Output| UM2[Next UserMessage]\n```\n\n### 3. Response Handling\n\n#### AgentResponses\n\nThe response system encapsulates all data returned from agent operations. `AgentResponses` provides a structured container for multiple message types and metadata generated during a single agent step.\n\n资料来源：[camel/responses/agent_responses.py:1-60]()\n\n**Response Components:**\n\n| Component | Type | Description |\n|-----------|------|-------------|\n| `msgs` | `List[BaseMessage]` | Generated messages (assistant, tool, etc.) |\n| `terminated` | `bool` | Whether the response terminated due to a condition |\n| `termination_reasons` | `List[str]` | Reasons for termination if applicable |\n| `info` | `Dict[str, Any]` | Additional metadata about the step |\n\n资料来源：[camel/responses/agent_responses.py:60-120]()\n\n### 4. Termination System\n\nThe termination system determines when an agent should stop processing or when a conversation should end. CAMEL implements a flexible terminator pattern that supports multiple termination conditions.\n\n#### ResponseTerminator\n\nThe `ResponseTerminator` evaluates response content to determine if a stop condition has been met. This includes checking for explicit stop phrases, completion markers, or other user-defined conditions.\n\n```mermaid\ngraph TD\n R[Response Received] --> C{Check Conditions}\n C -->|Stop Phrase| T[Terminate]\n C -->|Completion| T\n C -->|Token Limit| T\n C -->|Continue| P[Process Next Step]\n```\n\n资料来源：[camel/terminators/response_terminator.py:1-50]()\n\n| Terminator Type | Trigger Condition | Use Case |\n|-----------------|-------------------|----------|\n| `ResponseTerminator` | Content matches stop patterns | Custom stop phrases |\n| `TokenLimitTerminator` | Token count exceeds threshold | Resource management |\n| `MaxStepsTerminator` | Step count reaches limit | Loop prevention |\n\n#### TokenLimitTerminator\n\nThe `TokenLimitTerminator` enforces token budget constraints to prevent excessive API usage and maintain cost efficiency. It monitors cumulative token usage across the conversation.\n\n资料来源：[camel/terminators/token_limit_terminator.py:1-40]()\n\n**Configuration Options:**\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `max_tokens` | `4096` | Maximum tokens per response |\n| `max_history_tokens` | `8192` | Maximum tokens in history |\n| `token_buffer_ratio` | `0.1` | Safety buffer for token calculations |\n\n## Agent Workflow\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant CA as ChatAgent\n participant LM as Language Model\n participant RT as ResponseTerminator\n participant TL as TokenLimitTerminator\n \n U->>CA: UserMessage\n CA->>CA: Prepare Context\n CA->>LM: Generate Response\n LM-->>CA: Raw Response\n CA->>RT: Check Termination\n RT-->>CA: Continue/Terminate\n CA->>TL: Check Token Limits\n TL-->>CA: Within Limits/Exceeds\n CA->>CA: Update History\n CA-->>U: AgentResponse\n```\n\n## MCP Server Integration\n\nCAMEL agents can integrate with external systems through the Model Context Protocol (MCP). The agent server exposes tools and resources that agents can invoke during conversations.\n\n资料来源：[services/README.md:1-50]()\n\n**Available Tools:**\n\n- `step`: Execute a single conversation step with a specified agent\n- `reset`: Reset all agents to their initial state\n- `set_output_language`: Set the output language for all agents\n- `get_agents_info`: Get information about all available agents\n- `get_chat_history`: Retrieve chat history for a specific agent\n\n资料来源：[services/README.md:50-100]()\n\n**MCP Client Configuration:**\n\n```json\n{\n \"camel-agents\": {\n \"command\": \"/path/to/your/python\",\n \"args\": [\"/path/to/camel/services/agent_mcp_server.py\"],\n \"env\": {\n \"OPENAI_API_KEY\": \"...\",\n \"OPENROUTER_API_KEY\": \"...\",\n \"BRAVE_API_KEY\": \"...\"\n }\n }\n}\n```\n\n## Toolkit Architecture\n\nCAMEL provides specialized toolkits that extend agent capabilities. Each toolkit follows a consistent interface pattern for seamless integration.\n\n```mermaid\ngraph TD\n subgraph \"Toolkits\"\n PPTX[PPTXToolkit]\n BROWSER[HybridBrowserToolkit]\n SEARCH[WebSearchToolkit]\n end\n \n subgraph \"Use Cases\"\n CF[Codeforces Solver]\n RA[Research Assistant]\n YT[YouTube Chat]\n end\n \n BROWSER -->|Browser Automation| CF\n PPTX -->|Presentation Gen| RA\n SEARCH -->|Web Content| YT\n```\n\n### HybridBrowserToolkit\n\nThe browser toolkit enables agents to interact with web content through a controlled browser session. It supports complex interactions like form filling, element waiting, and snapshot comparison.\n\n资料来源：[camel/toolkits/hybrid_browser_toolkit/ts/src/browser-session.ts:1-50]()\n\n**Key Features:**\n\n- Element-based interaction with automatic retry\n- Snapshot-based change detection\n- Automatic scrolling and visibility handling\n- Support for input, textarea, and dropdown elements\n\n## State Management\n\nAgents maintain state across conversation turns through several mechanisms:\n\n| State Component | Storage | Purpose |\n|-----------------|---------|---------|\n| `message_history` | In-memory list | Conversation context |\n| `agent_info` | Dictionary | Agent metadata |\n| `chat_history` | Per-agent storage | Historical conversations |\n| `available_tools` | Dynamic list | Current toolset |\n\n## Configuration and Initialization\n\n### Agent Initialization Pattern\n\n```python\n# Create model instance\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# Initialize chat agent\nagent = ChatAgent(\n system_message=SystemMessage(content=\"You are a helpful assistant.\"),\n model=model,\n max_retries=3\n)\n```\n\n资料来源：[examples/runtimes/ubuntu_docker_runtime/README.md:1-30]()\n\n### Streamlit Application Pattern\n\nFor UI-based applications, CAMEL integrates with Streamlit to provide interactive interfaces:\n\n```bash\nstreamlit run app.py\n```\n\n资料来源：[examples/usecases/codeforces_question_solver/README.md:1-20]()\n\n## Extension Points\n\n### Custom Terminators\n\nDevelopers can create custom terminators by implementing the `ResponseTerminator` interface:\n\n1. Extend the base terminator class\n2. Implement the `should_terminate()` method\n3. Register the terminator with the agent\n\n### Custom Agents\n\nThe `BaseAgent` class provides extension points for:\n\n- Custom message processing logic\n- Specialized tool integration\n- Domain-specific response handling\n\n## Deployment Architecture\n\nCAMEL supports multiple deployment configurations:\n\n| Deployment Mode | Use Case | Configuration |\n|-----------------|----------|---------------|\n| Standalone Python | Development/Testing | Direct import |\n| Docker Runtime | Production/Cloud | Containerized execution |\n| MCP Server | External Integration | Network-accessible service |\n| Streamlit App | User-facing Interface | Web-based UI |\n\n### Docker Runtime\n\nThe Docker runtime provides isolated execution environments with consistent dependencies:\n\n```bash\n./manage_camel_docker.sh build\ndocker images | grep my-camel\n```\n\n资料来源：[examples/runtimes/ubuntu_docker_runtime/README.md:20-40]()\n\n## Security Considerations\n\n- API keys are managed through environment variables, never hardcoded\n- MCP server configurations support both local and remote execution\n- Token limit terminators prevent runaway resource consumption\n- Browser automation includes robots.txt compliance options\n\n## Performance Optimization\n\n1. **Token Budget Management**: Automatic history truncation maintains efficiency\n2. **Concurrent Execution**: Multi-agent workflows can run in parallel\n3. **Caching**: Model responses can be cached for repeated queries\n4. **Snapshot Differencing**: Browser automation uses efficient diff algorithms\n\n## Related Documentation\n\n- [Agent MCP Server](services/README.md) - External agent access via MCP\n- [Multi-Agent Research Assistant](../examples/usecases/multi_agent_research_assistant/README.md) - Production use case example\n- [Ubuntu Docker Runtime](../examples/runtimes/ubuntu_docker_runtime/README.md) - Containerized deployment\n\n---\n\n\n\n## Agent Types and System\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Model Integration and Providers](#page-models), [Tools and Toolkits](#page-toolkits), [Multi-Agent Societies and Role Playing](#page-societies)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/agents/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/agents/__init__.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/task_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/task_agent.py)\n- [camel/agents/search_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/search_agent.py)\n- [camel/agents/embodied_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/embodied_agent.py)\n- [camel/agents/knowledge_graph_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/knowledge_graph_agent.py)\n- [camel/agents/mcp_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/mcp_agent.py)\n- [camel/agents/repo_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/repo_agent.py)\n- [camel/agents/role_assignment_agent.py](https://github.com/camel-ai/camel/blob/main/camel/agents/role_assignment_agent.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# Agent Types and System\n\nThe CAMEL framework provides a comprehensive multi-agent system with specialized agent types designed for different tasks and use cases. Agents are the fundamental building blocks that interact within the CAMEL ecosystem, enabling complex workflows through role-playing, task decomposition, and collaborative reasoning.\n\n## Overview\n\nCAMEL's agent architecture follows a modular design pattern where different agent types inherit from a base `ChatAgent` class and specialize for specific domains. Each agent type encapsulates particular capabilities, tools, and behaviors tailored to its intended purpose.\n\n```mermaid\ngraph TD\n Base[ChatAgent Base Class] --> ChatAgent\n Base --> TaskAgent\n Base --> CriticAgent\n Base --> SearchAgent\n Base --> EmbodiedAgent\n Base --> KnowledgeGraphAgent\n Base --> MCPAgent\n Base --> RepoAgent\n Base --> RoleAssignmentAgent\n \n ChatAgent[ChatAgent
General conversation]\n TaskAgent[TaskAgent
Task execution]\n CriticAgent[CriticAgent
Evaluation & critique]\n SearchAgent[SearchAgent
Web search]\n EmbodiedAgent[EmbodiedAgent
Browser automation]\n KnowledgeGraphAgent[KnowledgeGraphAgent
Knowledge graphs]\n MCPAgent[MCPAgent
MCP protocol]\n RepoAgent[RepoAgent
Repository analysis]\n RoleAssignmentAgent[RoleAssignmentAgent
Role assignment]\n```\n\n资料来源：[camel/agents/__init__.py:1-50]()\n\n## Agent Type Catalog\n\n### ChatAgent\n\nThe `ChatAgent` is the foundational agent class that provides general-purpose conversation and task execution capabilities. All other agent types ultimately inherit from or delegate to this base class.\n\n**Key Features:**\n- Message-based interaction with LLMs\n- Tool execution framework\n- Structured output handling\n- Conversation memory management\n\n资料来源：[camel/agents/chat_agent.py:1-100]()\n\n### TaskAgent\n\nThe `TaskAgent` specializes in decomposing and executing complex tasks. It breaks down user requests into actionable steps and coordinates execution across multiple tools.\n\n**Capabilities:**\n- Task decomposition\n- Step-by-step execution planning\n- Tool orchestration\n- Result aggregation\n\n资料来源：[camel/agents/task_agent.py:1-100]()\n\n### CriticAgent\n\nThe `CriticAgent` evaluates and critiques outputs from other agents, providing quality assurance and feedback mechanisms. It plays a crucial role in multi-agent verification workflows.\n\n**Responsibilities:**\n- Output validation\n- Quality scoring\n- Constructive feedback generation\n- Error detection\n\n资料来源：[camel/agents/critic_agent.py:1-100]()\n\n### SearchAgent\n\nThe `SearchAgent` provides web search capabilities, enabling agents to retrieve up-to-date information from the internet.\n\n**Features:**\n- Web search integration\n- Result parsing and summarization\n- Citation generation\n\n资料来源：[camel/agents/search_agent.py:1-100]()\n\n### EmbodiedAgent\n\nThe `EmbodiedAgent` extends agent capabilities to browser automation, allowing agents to interact with web pages through a structured browser toolkit.\n\n**Capabilities:**\n- Web page navigation\n- Element interaction (click, fill, scroll)\n- Screenshot capture\n- DOM snapshot analysis\n\n```python\n# EmbodiedAgent initialization example\nagent = EmbodiedAgent(\n tool_kit=[browser_toolkit],\n model=model\n)\n```\n\n资料来源：[camel/agents/embodied_agent.py:1-100]()\n\n### KnowledgeGraphAgent\n\nThe `KnowledgeGraphAgent` manages structured knowledge representations, enabling agents to work with entity relationships and graph-based data.\n\n**Features:**\n- Entity creation and management\n- Relationship modeling\n- Graph traversal\n- Query execution\n\n资料来源：[camel/agents/knowledge_graph_agent.py:1-100]()\n\n### MCPAgent\n\nThe `MCPAgent` implements the Model Context Protocol (MCP), allowing integration with external MCP servers and tools. This enables CAMEL agents to leverage a wide ecosystem of MCP-compatible tools.\n\n**Capabilities:**\n- MCP server connection\n- Tool discovery\n- Remote tool execution\n- Streaming response handling\n\n```python\n# MCPAgent configuration\nagent = MCPAgent(\n mcp_server_config=mcp_config,\n model=model\n)\n```\n\n资料来源：[camel/agents/mcp_agent.py:1-100]()\n\n### RepoAgent\n\nThe `RepoAgent` specializes in analyzing and understanding code repositories. It can inspect file structures, read code, and provide repository-level insights.\n\n**Features:**\n- Repository structure analysis\n- Code file reading and parsing\n- Git history inspection\n- Dependency analysis\n\n资料来源：[camel/agents/repo_agent.py:1-100]()\n\n### RoleAssignmentAgent\n\nThe `RoleAssignmentAgent` handles dynamic role assignment in multi-agent systems, determining which agent should handle specific tasks based on capabilities and availability.\n\n**Responsibilities:**\n- Role matching\n- Capability assessment\n- Task routing\n\n资料来源：[camel/agents/role_assignment_agent.py:1-100]()\n\n## Persona System\n\nThe persona system in CAMEL defines agent identities through the `Persona` class and `PersonaHub` repository.\n\n```mermaid\nclassDiagram\n class Persona {\n +str name\n +str description\n +str instruction\n +str example\n +to_role_playing_instruction() str\n }\n \n class PersonaHub {\n +dict personas\n +get(name: str) Persona\n +list_all() List~str~\n }\n \n PersonaHub o-- Persona : contains\n```\n\n### Persona Class\n\nRepresents an agent's identity with the following attributes:\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `name` | `str` | Unique identifier for the persona |\n| `description` | `str` | Brief description of the persona |\n| `instruction` | `str` | Core instructions for the persona |\n| `example` | `str` | Example behavior or output |\n\n资料来源：[camel/personas/persona.py:1-80]()\n\n### PersonaHub\n\nProvides a centralized repository of predefined personas for common use cases.\n\n**Usage:**\n```python\nfrom camel.personas.persona_hub import PersonaHub\n\nhub = PersonaHub()\nassistant_persona = hub.get(\"assistant\")\ncoder_persona = hub.get(\"coder\")\n```\n\n资料来源：[camel/personas/persona_hub.py:1-150]()\n\n## Agent Execution Flow\n\nAgents in CAMEL follow a standardized execution pattern:\n\n```mermaid\nsequenceDiagram\n participant User\n participant Agent\n participant ToolKit\n participant LLM\n \n User->>Agent: UserMessage\n Agent->>LLM: Process Message\n LLM-->>Agent: Reasoning Result\n Agent->>ToolKit: Execute Tool (if needed)\n ToolKit-->>Agent: Tool Result\n Agent->>LLM: Format Response\n LLM-->>Agent: Structured Output\n Agent-->>User: AgentMessage\n```\n\n## Multi-Agent Collaboration\n\nCAMEL supports complex multi-agent workflows where agents collaborate to solve problems:\n\n```mermaid\ngraph LR\n User[User Request] --> Coordinator[TaskAgent]\n Coordinator -->|Delegate| Critic1[CriticAgent]\n Coordinator -->|Delegate| Search[SearchAgent]\n Coordinator -->|Delegate| Repo[RepoAgent]\n \n Critic1 -->|Feedback| Coordinator\n Search -->|Results| Coordinator\n Repo -->|Analysis| Coordinator\n \n Coordinator -->|Final Response| User\n```\n\n## Configuration Options\n\n### Common Agent Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `model` | `Model` | Required | LLM model instance |\n| `tool_kit` | `List[BaseTool]` | `[]` | Tools available to agent |\n| `system_message` | `str` | `None` | System-level instructions |\n| `max_tokens` | `int` | `4096` | Maximum output tokens |\n| `temperature` | `float` | `0.7` | Sampling temperature |\n\n### Tool Execution Configuration\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `tool_call_limit` | `int` | Maximum tool calls per turn |\n| `tool_call_retry_limit` | `int` | Retry attempts on failure |\n| ` message_window_size` | `int` | Context window for conversation |\n\n## Extending the Agent System\n\nTo create a custom agent type, inherit from `ChatAgent`:\n\n```python\nfrom camel.agents import ChatAgent\nfrom camel.types import RoleType\n\nclass MyCustomAgent(ChatAgent):\n def __init__(self, model, custom_param, **kwargs):\n system_message = SystemMessage(\n role_name=\"Custom Agent\",\n role_type=RoleType.ASSISTANT,\n content=\"Custom instructions...\"\n )\n super().__init__(system_message, model, **kwargs)\n self.custom_param = custom_param\n```\n\n## Error Handling\n\nAgents implement comprehensive error handling for:\n\n- LLM API failures (rate limits, authentication)\n- Tool execution errors\n- Malformed responses\n- Timeout conditions\n\nEach error type triggers appropriate recovery mechanisms or returns structured error messages for debugging.\n\n## Best Practices\n\n1. **Tool Selection**: Only provide agents with tools relevant to their task to reduce complexity\n2. **System Messages**: Craft clear, specific instructions for consistent agent behavior\n3. **Memory Management**: Configure appropriate `message_window_size` for long conversations\n4. **Error Handling**: Always wrap agent calls in try-except blocks for production systems\n5. **Model Selection**: Choose models appropriate for task complexity\n\n## Summary\n\nCAMEL's agent system provides a flexible, extensible foundation for building multi-agent applications. The base `ChatAgent` class combined with specialized agent types and a robust persona system enables developers to create sophisticated AI systems that can collaborate, critique, and solve complex tasks through coordinated agent interactions.\n\n---\n\n\n\n## Model Integration and Providers\n\n### 相关页面\n\n相关主题：[Introduction to CAMEL](#page-introduction), [System Architecture](#page-architecture)\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/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/base_model.py](https://github.com/camel-ai/camel/blob/main/camel/models/base_model.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/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/configs/__init__.py)\n- [camel/embeddings/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/embeddings/__init__.py)\n- [camel/types/unified_model_type.py](https://github.com/camel-ai/camel/blob/main/camel/types/unified_model_type.py)\n \n\n# Model Integration and Providers\n\n## Overview\n\nThe CAMEL framework provides a comprehensive model integration system that abstracts over multiple AI provider APIs through a unified interface. This architecture enables developers to seamlessly switch between different model providers (OpenAI, Anthropic, Google, Azure, etc.) without modifying application code.\n\nThe model integration layer serves as the foundational component for all agent reasoning, chat interactions, and language model operations within the CAMEL ecosystem. It implements the factory pattern to handle provider-specific instantiation while maintaining a consistent API contract across all implementations.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[Application Layer] --> B[ModelFactory]\n B --> C[ModelManager]\n C --> D[Provider-Specific Models]\n \n D --> E[OpenAIModel]\n D --> F[AnthropicModel]\n D --> G[AzureAIModel]\n D --> H[GeminiModel]\n D --> I[Other Providers]\n \n J[BaseModel] --> D\n K[configs] --> B\n L[unified_model_type] --> B\n```\n\n## Core Components\n\n### Base Model Architecture\n\nThe `BaseModel` class (`camel/models/base_model.py`) defines the abstract interface that all provider-specific implementations must follow. This ensures consistency across the framework and allows dynamic model selection at runtime.\n\n**Key Responsibilities:**\n- Defines the standard interface for all model implementations\n- Provides common functionality for API communication\n- Establishes the contract for `run()` and `run_async()` methods\n\n### Model Factory Pattern\n\nThe `ModelFactory` (`camel/models/model_factory.py`) implements the factory pattern to centralize model instantiation logic.\n\n```python\nModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=OpenAIModelType.GPT_4O,\n api_key=\"...\",\n url=\"...\"\n)\n```\n\n**Factory Capabilities:**\n- Dynamic model instantiation based on provider type\n- Automatic configuration loading from environment variables\n- Support for both chat and embedding models\n- Flexible parameter passing for provider-specific options\n\n### Model Manager\n\nThe `ModelManager` (`camel/models/model_manager.py`) provides a higher-level abstraction for managing model instances, including lifecycle management and configuration caching.\n\n## Supported Model Providers\n\n### Provider Configuration Matrix\n\n| Provider | Platform Type | Model Types | API Format | Authentication |\n|----------|---------------|-------------|------------|----------------|\n| OpenAI | `OPENAI` | GPT-4o, GPT-4, GPT-3.5 | OpenAI API v1 | API Key |\n| Anthropic | `ANTHROPIC` | Claude 3.5, Claude 3 | Anthropic API | API Key |\n| Azure | `AZURE` | GPT-4, GPT-35 | Azure OpenAI API | API Key + Endpoint |\n| Google | `GOOGLE` | Gemini Pro, Gemini Ultra | Google AI API | API Key |\n| HuggingFace | `HUGGINGFACE` | Various open models | HF Inference API | API Key |\n| ModelScope | `OPENAI_COMPATIBLE_MODEL` | Qwen, Llama variants | OpenAI-compatible | API Key |\n\n### OpenAI Integration\n\nThe `OpenAIModel` (`camel/models/openai_model.py`) provides integration with OpenAI's API family.\n\n**Supported Model Types:**\n- `GPT_4O` - Latest GPT-4 optimized for speed\n- `GPT_4O_MINI` - Cost-effective GPT-4 variant\n- `GPT_4_TURBO` - High-capability GPT-4\n- `GPT_3_5_TURBO` - Legacy support model\n\n**Configuration Example:**\n```python\nmodel = OpenAIModel(\n model_type=OpenAIModelType.GPT_4O,\n api_key=os.environ.get(\"OPENAI_API_KEY\"),\n url=\"https://api.openai.com/v1\"\n)\n```\n\n### Anthropic Integration\n\nThe `AnthropicModel` (`camel/models/anthropic_model.py`) enables access to Claude models through Anthropic's API.\n\n**Supported Model Types:**\n- `CLAUDE_3_5_SONNET` - Latest Sonnet model\n- `CLAUDE_3_OPUS` - Highest capability model\n- `CLAUDE_3_HAIKU` - Fast, cost-effective option\n\n## Unified Model Type System\n\nThe `unified_model_type.py` (`camel/types/unified_model_type.py`) defines enumerations that map provider-specific model identifiers to a common type system.\n\n```mermaid\nclassDiagram\n class ModelPlatformType {\n <>\n OPENAI\n ANTHROPIC\n AZURE\n GOOGLE\n HUGGINGFACE\n MODELSCOPE\n }\n \n class ModelType {\n <>\n GPT_4O\n GPT_4_TURBO\n CLAUDE_3_5_SONNET\n GEMINI_PRO\n }\n```\n\nThis unified type system allows the framework to:\n- Map provider-specific model names to internal identifiers\n- Validate model availability before instantiation\n- Provide consistent error handling across providers\n\n## Configuration System\n\n### Config Module Structure\n\nThe `configs/__init__.py` (`camel/configs/__init__.py`) exports configuration classes used across the model integration system.\n\n**Configuration Classes:**\n- `ModelConfig` - Base configuration for model parameters\n- `OpenAIConfig` - OpenAI-specific settings\n- `AnthropicConfig` - Anthropic-specific settings\n\n### Configuration Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `temperature` | float | 0.7 | Sampling temperature for generation |\n| `max_tokens` | int | 4096 | Maximum tokens in response |\n| `top_p` | float | 1.0 | Nucleus sampling parameter |\n| `timeout` | int | 120 | Request timeout in seconds |\n| `retry_limit` | int | 2 | Number of retry attempts |\n\n## Embedding Integration\n\nThe `embeddings/__init__.py` (`camel/embeddings/__init__.py`) module provides embedding model support for vector operations.\n\n**Embedding Capabilities:**\n- Text embedding generation for semantic search\n- Support for multiple embedding providers\n- Configurable embedding dimensions\n\n## Usage Patterns\n\n### Basic Model Creation\n\n```python\nfrom camel.models import ModelFactory, ModelPlatformType, OpenAIModelType\n\n# Create OpenAI model instance\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=OpenAIModelType.GPT_4O,\n api_key=\"your-api-key\"\n)\n\n# Run inference\nresponse = model.run([{\"role\": \"user\", \"content\": \"Hello!\"}])\n```\n\n### Async Model Operations\n\n```python\nimport asyncio\nfrom camel.models import ModelFactory\n\nasync def async_inference():\n model = ModelFactory.create(...)\n response = await model.run_async([{\"role\": \"user\", \"content\": \"Hi\"}])\n return response\n\nresult = asyncio.run(async_inference())\n```\n\n### Multi-Provider Setup\n\n```python\nfrom camel.models import ModelFactory, ModelPlatformType\n\n# OpenAI for reasoning\nreasoning_model = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=OpenAIModelType.GPT_4O\n)\n\n# Anthropic for generation\ngeneration_model = ModelFactory.create(\n model_platform=ModelPlatformType.ANTHROPIC,\n model_type=AnthropicModelType.CLAUDE_3_5_SONNET\n)\n```\n\n## Error Handling\n\nThe model integration system provides consistent error handling across all providers:\n\n| Error Type | Cause | Handling Strategy |\n|------------|-------|-------------------|\n| `APIError` | Provider API issues | Automatic retry with exponential backoff |\n| `AuthenticationError` | Invalid API key | Raise with clear message |\n| `RateLimitError` | Exceeded quota | Wait and retry |\n| `TimeoutError` | Request timeout | Retry with increased timeout |\n\n## Best Practices\n\n1. **Environment Variable Configuration**: Store API keys in environment variables rather than hardcoding\n2. **Model Selection**: Choose appropriate model tiers based on task complexity\n3. **Async Operations**: Use async methods for batch processing scenarios\n4. **Error Handling**: Implement retry logic for production deployments\n5. **Resource Management**: Reuse model instances rather than creating new ones per request\n\n## Related Components\n\n- [Agent System](agents) - Uses model integration for reasoning\n- [Tool Calling](tools) - Leverages models for function execution\n- [Retrieval](retrieval) - Uses embedding models for vector operations\n\n---\n\n\n\n## Tools and Toolkits\n\n### 相关页面\n\n相关主题：[Agent Types and System](#page-agents)\n\n\nRelated Source Files
\n\nThe following source files were used to generate this page:\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/code_execution.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/code_execution.py)\n- [camel/toolkits/mcp_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/mcp_toolkit.py)\n- [camel/toolkits/retrieval_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/retrieval_toolkit.py)\n- [camel/toolkits/skill_toolkit.py](https://github.com/camel-ai/camel/blob/main/camel/toolkits/skill_toolkit.py)\n- [camel/parsers/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/parsers/__init__.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 \n\n# Tools and Toolkits\n\n## Overview\n\nThe CAMEL framework provides a comprehensive Tools and Toolkits system that extends the capabilities of AI agents beyond text generation. Toolkits are modular collections of tools that agents can utilize to interact with external systems, execute code, browse the web, manage files, and perform specialized tasks.\n\nThe architecture follows a plugin-based design where each toolkit encapsulates related functionality into a cohesive unit. This design enables agents to dynamically select and invoke tools based on task requirements, facilitating multi-agent collaboration with diverse capabilities.\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n A[Agent] --> B[Toolkit Registry]\n B --> C[BaseToolkit]\n B --> D[FunctionTool]\n B --> E[MCPToolkit]\n C --> F[SearchToolkit]\n C --> G[BrowserToolkit]\n C --> H[FileToolkit]\n C --> I[RetrievalToolkit]\n C --> J[SkillToolkit]\n C --> K[CodeExecution]\n E --> L[MCP Servers]\n L --> M[External Services]\n```\n\n### Tool Classification\n\n| Category | Purpose | Examples |\n|----------|---------|----------|\n| **Search & Retrieval** | Information gathering | Web search, document retrieval |\n| **Browser Automation** | Web interaction | Page navigation, form filling |\n| **File Operations** | Local file management | Read, write, edit files |\n| **Code Execution** | Runtime code evaluation | Python sandbox, code runner |\n| **MCP Integration** | External protocol support | Cloudflare, Airbnb, ACI tools |\n| **Skills** | Complex task automation | Sequential tool execution |\n\n## Core Components\n\n### Base Toolkit Architecture\n\nAll toolkits inherit from `BaseToolkit`, which defines the common interface for tool management and invocation.\n\n资料来源：[camel/toolkits/base.py]()\n\nThe `BaseToolkit` class provides:\n\n- Tool registration and management\n- Parameter schema generation\n- Tool invocation orchestration\n- Result parsing and formatting\n\n### Function Tool\n\nThe `FunctionTool` class wraps Python functions into tool-compatible format with automatic schema generation from function signatures.\n\n资料来源：[camel/toolkits/function_tool.py]()\n\n```mermaid\ngraph LR\n A[Python Function] --> B[FunctionTool.wrap]\n B --> C[Schema Generation]\n C --> D[Tool Definition]\n D --> E[Tool Execution]\n E --> F[Result Parsing]\n```\n\n## Available Toolkits\n\n### Search Toolkit\n\nProvides web search capabilities for information retrieval tasks.\n\n资料来源：[camel/toolkits/search_toolkit.py]()\n\n| Tool | Function |\n|------|----------|\n| `GoogleSearch` | Google search with API |\n| `WebSearch` | Generic web search |\n| `WebPageScan` | Retrieve and scan web pages |\n\n### Browser Toolkit\n\nEnables agents to interact with web pages through automated browser control.\n\n资料来源：[camel/toolkits/browser_toolkit.py]()\n\n**Key Features:**\n\n- Page navigation and snapshot capture\n- Element interaction (click, fill, select)\n- Form submission automation\n- Screenshot capture\n- Intelligent element matching by placeholder, ref, or text\n\n**Browser Session Flow:**\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant BrowserToolkit\n participant Playwright\n participant WebPage\n \n Agent->>BrowserToolkit: Navigate to URL\n BrowserToolkit->>Playwright: page.goto()\n Playwright->>WebPage: HTTP Request\n WebPage-->>Playwright: HTML Response\n Playwright-->>BrowserToolkit: Page Ready\n BrowserToolkit-->>Agent: Page Snapshot\n```\n\n**Input Element Handling:**\n\nThe toolkit implements robust input element detection:\n\n```python\n# Element detection logic\nconst placeholder = await newElement.getAttribute('placeholder').catch(() => null);\nif (placeholder === originalPlaceholder) {\n await newElement.fill(text, { force: true });\n return { success: true, diffSnapshot };\n}\n```\n\n资料来源：[camel/toolkits/browser_toolkit.py]()\n\n### File Toolkit\n\nManages local file system operations with read, write, and edit capabilities.\n\n资料来源：[camel/toolkits/file_toolkit.py]()\n\n| Operation | Description |\n|-----------|-------------|\n| `Read` | Read file contents |\n| `Write` | Create or overwrite files |\n| `Edit` | Modify existing files |\n| `Glob` | Pattern-based file listing |\n| `Tree` | Directory structure visualization |\n\n### Code Execution Toolkit\n\nProvides sandboxed code execution environments for dynamic code evaluation.\n\n资料来源：[camel/toolkits/code_execution.py]()\n\n**Supported Modes:**\n\n| Mode | Use Case |\n|------|----------|\n| `JEPYTER` | Interactive notebook execution |\n| `AST` | AST-based code analysis |\n| `EXECUTOR` | Direct code execution |\n\n### Retrieval Toolkit\n\nOffers document retrieval and semantic search capabilities.\n\n资料来源：[camel/toolkits/retrieval_toolkit.py]()\n\n**Components:**\n\n- Embedding generation\n- Vector store integration\n- Similarity search\n- Document chunking\n\n### Skill Toolkit\n\nOrchestrates complex tasks by combining multiple tools into executable skill workflows.\n\n资料来源：[camel/toolkits/skill_toolkit.py]()\n\n```mermaid\ngraph TD\n A[Skill Definition] --> B[Tool Sequence]\n B --> C[Execution Plan]\n C --> D[Tool 1]\n C --> E[Tool 2]\n C --> F[Tool N]\n D --> G[Result Aggregation]\n E --> G\n F --> G\n G --> H[Final Output]\n```\n\n### MCP Toolkit\n\nIntegrates the Model Context Protocol (MCP) for connecting to external tool servers.\n\n资料来源：[camel/toolkits/mcp_toolkit.py]()\n\n**Supported MCP Integrations:**\n\n- Cloudflare (Docs, Radar, Browser)\n- Airbnb listings search\n- ACI.dev platform tools\n- GitHub repositories\n- YouTube video analysis\n\n资料来源：[camel/toolkits/__init__.py]()\n\n### Parser System\n\nThe parser system handles tool call parsing and result interpretation.\n\n资料来源：[camel/parsers/__init__.py]()\n\n| Parser | Purpose |\n|--------|---------|\n\n| `MCPToolCallParser` | Parse MCP protocol tool calls |\n\n资料来源：[camel/parsers/mcp_tool_call_parser.py]()\n\n## Tool Invocation Pattern\n\n```mermaid\ngraph TD\n A[User Task] --> B[Agent Decision]\n B --> C{Select Tool}\n C --> D[Tool Schema]\n D --> E[Parameter Construction]\n E --> F[Tool Execution]\n F --> G[Result Parsing]\n G --> H[Response to Agent]\n H --> B\n```\n\n## Integration with Agents\n\nToolkits are integrated into the agent system through the `BaseToolkit` interface:\n\n1. **Registration**: Toolkits register their available tools with the agent\n2. **Schema Generation**: Tool schemas are generated for LLM tool selection\n3. **Invocation**: Agent selects and invokes tools based on task requirements\n4. **Result Handling**: Tool results are parsed and returned to the agent\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `OPENAI_API_KEY` | Yes | API key for OpenAI models |\n| `GOOGLE_API_KEY` | No | For Google Search toolkit |\n| `FIRECRAWL_API_KEY` | No | For web scraping |\n| `MISTRAL_API_KEY` | No | For Mistral OCR |\n\n### MCP Server Configuration\n\nMCP toolkits use JSON configuration files:\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## Example Use Cases\n\n### Multi-Agent Research Assistant\n\nUses multiple toolkits for comprehensive research:\n\n1. **Search Toolkit**: Find relevant papers and researchers\n2. **Browser Toolkit**: Extract content from web pages\n3. **File Toolkit**: Save research reports locally\n4. **Skill Toolkit**: Orchestrate multi-step research workflows\n\n### Codeforces Question Solver\n\nCombines browser automation with code execution:\n\n1. **Browser Toolkit**: Navigate to problem statements\n2. **Code Execution**: Run and test solutions\n3. **File Toolkit**: Save code submissions\n\n### Document OCR and Analysis\n\nLeverages specialized OCR capabilities:\n\n1. **Mistral OCR**: Extract text from PDFs/images\n2. **Retrieval Toolkit**: Index extracted content\n3. **Agent**: Analyze and summarize documents\n\n## Best Practices\n\n1. **Tool Selection**: Choose appropriate tools based on task requirements\n2. **Error Handling**: Implement proper exception handling for tool failures\n3. **Resource Management**: Clean up resources after execution\n4. **Schema Validation**: Validate tool parameters before invocation\n5. **Security**: Use sandboxed environments for code execution\n\n## Summary\n\nThe CAMEL Tools and Toolkits system provides a flexible, extensible architecture for augmenting AI agents with external capabilities. By supporting diverse tool types—from file operations to web browsing to specialized integrations—agents can perform complex, multi-step tasks that require interaction with the real world. The modular design allows easy addition of new toolkits while maintaining a consistent interface for tool invocation and result handling.\n\n---\n\n\n\n## Multi-Agent Societies and Role Playing\n\n### 相关页面\n\n相关主题：[Agent Types and System](#page-agents), [Workforce Management](#page-workforce), [Memory Management](#page-memory)\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/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/prompts/ai_society.py](https://github.com/camel-ai/camel/blob/main/camel/prompts/ai_society.py)\n- [camel/prompts/role_description_prompt_template.py](https://github.com/camel-ai/camel/blob/main/camel/prompts/role_description_prompt_template.py)\n \n\n# Multi-Agent Societies and Role Playing\n\n## Overview\n\nCAMEL's Multi-Agent Societies provide a sophisticated framework for orchestrating multiple autonomous agents that collaborate to accomplish complex tasks. At the core of this system is the **Role Playing** paradigm, where agents are assigned specific roles with distinct responsibilities, enabling them to engage in meaningful cooperation and problem-solving.\n\nThe societies framework enables developers to create agent ecosystems where:\n\n- Multiple agents assume distinct roles (e.g., AI Assistant, Code Reviewer, Researcher)\n- Agents communicate through structured message passing\n- Collaborative tasks are completed through agent-to-agent interaction\n- Complex workflows are decomposed into manageable subtasks handled by specialized agents\n\n资料来源：[camel/societies/__init__.py:1-20]()\n\n## Architecture\n\nThe multi-agent society architecture consists of several interconnected components that work together to enable sophisticated agent collaboration.\n\n```mermaid\ngraph TD\n A[User Task] --> B[Role Playing Manager]\n B --> C[AI Society Prompt]\n B --> D[Task Specification]\n C --> E[Role Assignment]\n D --> E\n E --> F[Agent 1: Role A]\n E --> G[Agent 2: Role B]\n F <--> G[Communication]\n G --> H[Task Completion]\n F --> H\n```\n\n### Core Components\n\n| Component | Purpose | Location |\n|-----------|---------|----------|\n| `RolePlaying` | Orchestrates role-based agent interactions | `camel/societies/role_playing.py` |\n| `BabyAGIPlaying` | Implements BabyAGI-style autonomous task execution | `camel/societies/babyagi_playing.py` |\n| `Workforce` | Manages a pool of workers for parallel task execution | `camel/societies/workforce/workforce.py` |\n| `Worker` | Individual agent within a workforce | `camel/societies/workforce/worker.py` |\n| `TaskChannel` | Manages task distribution and routing | `camel/societies/workforce/task_channel.py` |\n\n资料来源：[camel/societies/__init__.py:1-30]()\n\n## Role Playing System\n\n### Purpose and Design\n\nThe Role Playing system is the foundational mechanism for enabling multiple agents to collaborate effectively. It assigns distinct roles to each agent and facilitates structured communication between them based on their assigned responsibilities.\n\n资料来源：[camel/societies/role_playing.py:1-50]()\n\n### Key Features\n\nThe role playing implementation provides several critical capabilities:\n\n- **Role Assignment**: Automatically assigns appropriate roles to agents based on task requirements\n- **Task Decomposition**: Breaks complex tasks into role-specific subtasks\n- **Communication Management**: Handles inter-agent messaging and context preservation\n- **State Management**: Maintains conversation history and agent states throughout the interaction\n\n### Role Description Prompt Templates\n\nThe system uses specialized prompt templates to define agent roles and behaviors. These templates ensure consistent role representation and guide agent responses based on their assigned responsibilities.\n\n```mermaid\ngraph LR\n A[Task Input] --> B[Role Description Template]\n B --> C[System Prompt]\n C --> D[AI Agent Behavior]\n D --> E[Role-Specific Response]\n```\n\n资料来源：[camel/prompts/role_description_prompt_template.py:1-40]()\n\n### AI Society Prompts\n\nThe `AISocietyPrompt` class provides the foundational prompt structures that define how agents in a society interact. These prompts include:\n\n- Agent role definitions\n- Task instructions and constraints\n- Communication protocols\n- Success criteria and evaluation metrics\n\n资料来源：[camel/prompts/ai_society.py:1-50]()\n\n## Workforce System\n\nThe Workforce system extends the basic role playing paradigm by introducing a more structured approach to managing multiple agents working in parallel.\n\n### Architecture Overview\n\nThe Workforce consists of three primary components that work together to manage distributed agent execution:\n\n1. **Workforce Manager**: Coordinates all workers and task distribution\n2. **Worker Agents**: Individual agents that execute assigned tasks\n3. **Task Channels**: Routes tasks to appropriate workers based on capabilities\n\n```mermaid\ngraph TD\n A[Task Queue] --> B[TaskChannel]\n B --> C[Worker 1]\n B --> D[Worker 2]\n B --> E[Worker N]\n C --> F[Result Aggregation]\n D --> F\n E --> F\n F --> G[Final Output]\n```\n\n资料来源：[camel/societies/workforce/workforce.py:1-60]()\n\n### Worker Configuration\n\nWorkers can be configured with specific capabilities and task preferences:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `name` | `str` | Unique identifier for the worker |\n| `role` | `str` | Worker's assigned role in the society |\n| `description` | `str` | Detailed description of worker's expertise |\n| `tools` | `List[Tool]` | Tools available to the worker |\n| `model` | `Model` | LLM model to use for this worker |\n\n资料来源：[camel/societies/workforce/worker.py:1-50]()\n\n### Task Channel Implementation\n\nTask channels manage the flow of tasks between the workforce and individual workers. They handle:\n\n- Task routing based on worker capabilities\n- Priority queuing for urgent tasks\n- Task state tracking and completion verification\n- Load balancing across available workers\n\n资料来源：[camel/societies/workforce/task_channel.py:1-40]()\n\n## BabyAGI Integration\n\nCAMEL provides a BabyAGI-style implementation for autonomous task-driven agent execution. This system operates on a continuous loop:\n\n```mermaid\ngraph LR\n A[Create Task] --> B[Prioritize Tasks]\n B --> C[Execute Task]\n C --> D[Complete Task]\n D --> E{More Tasks?}\n E -->|Yes| B\n E -->|No| F[Finish]\n```\n\n### Execution Flow\n\nThe BabyAGI playing system follows these steps:\n\n1. **Task Creation**: Initialize tasks based on user objectives\n2. **Task Prioritization**: Rank tasks by importance and dependencies\n3. **Task Execution**: Assign and execute tasks with appropriate agents\n4. **Result Storage**: Store completed task results for future reference\n5. **Iteration**: Repeat the cycle until all objectives are met\n\n资料来源：[camel/societies/babyagi_playing.py:1-70]()\n\n## Usage Examples\n\n### Basic Role Playing Setup\n\n```python\nfrom camel.societies import RolePlaying\nfrom camel.models import ModelFactory\nfrom camel.types import ModelPlatformType\n\n# Initialize model\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=\"gpt-4\",\n)\n\n# Create role playing session\nrole_playing = RolePlaying(\n assistant_role=\"AI Researcher\",\n assistant_description=\"An expert AI researcher specializing in ML\",\n user_role=\"Curious Student\",\n user_description=\"A student eager to learn about AI\",\n model=model,\n)\n\n# Execute role playing\nresponse = role_playing.step(task=\"Explain transformer architectures\")\n```\n\n### Workforce Configuration\n\n```python\nfrom camel.societies.workforce import Workforce, Worker\n\n# Create workers\nresearcher = Worker(\n name=\"researcher\",\n role=\"Researcher\",\n description=\"Handles research and information gathering\",\n tools=[search_tool, browse_tool],\n)\n\ncoder = Worker(\n name=\"coder\",\n role=\"Coder\",\n description=\"Handles code implementation\",\n tools=[code_tool, test_tool],\n)\n\n# Create workforce\nworkforce = Workforce(workers=[researcher, coder])\n\n# Execute task\nresult = workforce.execute_task(\"Build a web scraper\")\n```\n\n## Configuration Options\n\n### RolePlaying Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `assistant_role` | Required | Role assigned to the assistant agent |\n| `user_role` | Required | Role assigned to the user agent |\n| `model` | Required | LLM model for agent reasoning |\n| `task_specification` | `None` | Detailed task specifications |\n| `max_dialogue_length` | `20` | Maximum turns in conversation |\n| `termination_prompt` | `None` | Custom termination conditions |\n\n### Workforce Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `workers` | Required | List of Worker instances |\n| `task_channel_type` | `\"default\"` | Type of task routing channel |\n| `max_workers` | `None` | Maximum concurrent workers |\n| `timeout` | `300` | Task execution timeout in seconds |\n\n## Prompt Templates\n\n### Role Description Template\n\nThe role description prompt template defines how agent roles are communicated to the underlying language model. It includes:\n\n- Role title and purpose\n- Key responsibilities\n- Behavioral guidelines\n- Communication style preferences\n\n### Task Specification Template\n\nTask specifications provide context about what the society should accomplish:\n\n- Overall objective\n- Success criteria\n- Constraints and limitations\n- Expected deliverables\n\n资料来源：[camel/prompts/ai_society.py:1-100]()\n\n## Best Practices\n\n### Designing Effective Agent Roles\n\n1. **Clear Role Definitions**: Ensure each agent has a well-defined scope of responsibility\n2. **Complementary Capabilities**: Design roles that complement each other\n3. **Appropriate Tool Assignment**: Equip agents with tools relevant to their roles\n4. **Balanced Complexity**: Avoid overloading single agents with too many responsibilities\n\n### Workforce Optimization\n\n1. **Worker Specialization**: Create specialized workers rather than general-purpose ones\n2. **Task Channel Configuration**: Use appropriate task routing strategies\n3. **Load Balancing**: Monitor worker utilization and adjust as needed\n4. **Timeout Configuration**: Set appropriate timeouts for different task types\n\n## Related Components\n\nThe Multi-Agent Societies system integrates with several other CAMEL components:\n\n- **Models**: All agent reasoning is powered by LLM models through `ModelFactory`\n- **Tools**: Agents can utilize various toolkits for extended capabilities\n- **Memories**: Conversation history and context are maintained through memory systems\n- **Prompts**: Structured prompts guide agent behavior and communication\n\n## Summary\n\nCAMEL's Multi-Agent Societies and Role Playing framework provides a powerful foundation for building collaborative AI agent systems. By combining role-based interactions with workforce orchestration, developers can create sophisticated agent ecosystems capable of tackling complex, multi-faceted tasks through effective cooperation and specialization.\n\n---\n\n\n\n## Workforce Management\n\n### 相关页面\n\n相关主题：[Multi-Agent Societies and Role Playing](#page-societies)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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/single_agent_worker.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/single_agent_worker.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/task_channel.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/task_channel.py)\n- [camel/societies/workforce/events.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/events.py)\n- [camel/societies/workforce/workforce_metrics.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/workforce_metrics.py)\n- [camel/societies/workforce/workforce_callback.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/workforce_callback.py)\n- [camel/societies/workforce/structured_output_handler.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/structured_output_handler.py)\n \n\n# Workforce Management\n\n## Overview\n\nWorkforce Management is a core module in CAMEL that orchestrates multi-agent collaboration through a hierarchical worker system. It provides a framework for managing pools of specialized agents (workers) that can execute tasks, communicate via channels, and report metrics. The system enables scalable agent-based workflows where multiple workers operate concurrently to accomplish complex objectives.\n\n## Architecture\n\nThe Workforce Management system follows a producer-consumer pattern where tasks flow through channels and are processed by different worker types.\n\n```mermaid\ngraph TD\n A[Task Submission] --> B[Workforce Manager]\n B --> C[TaskChannel]\n C --> D[SingleAgentWorker]\n C --> E[RolePlayingWorker]\n D --> F[Worker Response]\n E --> F\n G[Events System] --> B\n H[Metrics Collection] --> B\n I[Callbacks] --> B\n```\n\n## Core Components\n\n### Workforce\n\nThe `Workforce` class serves as the central coordinator managing the entire worker ecosystem.\n\n| Component | Purpose | Key Methods |\n|-----------|---------|-------------|\n| `Workforce` | Central manager for all workers | `launch()`, `execute()`, `submit()`, `wait()` |\n| TaskChannel | Message routing between components | `put()`, `get()`, `task_done()` |\n| Worker | Base abstraction for task executors | `step()`, `reset()` |\n\n资料来源：[camel/societies/workforce/workforce.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/workforce.py)\n\n### Worker Types\n\n#### SingleAgentWorker\n\nExecutes tasks using a single AI agent without role-playing dynamics.\n\n```mermaid\nclassDiagram\n class Worker {\n <>\n +step()\n +reset()\n }\n class SingleAgentWorker {\n +agent: BaseAgent\n +toolkit: Toolkits\n +step()\n }\n Worker <|-- SingleAgentWorker\n```\n\n资料来源：[camel/societies/workforce/single_agent_worker.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/single_agent_worker.py)\n\n#### RolePlayingWorker\n\nLeverages CAMEL's role-playing framework where two agents (assistant and user) interact dynamically.\n\n资料来源：[camel/societies/workforce/role_playing_worker.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/role_playing_worker.py)\n\n### TaskChannel\n\nManages task distribution and communication between workforce components.\n\n| Method | Description |\n|--------|-------------|\n| `put(task)` | Submit a new task to the channel |\n| `get()` | Retrieve next task from queue |\n| `task_done()` | Mark task as completed |\n\n资料来源：[camel/societies/workforce/task_channel.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/task_channel.py)\n\n## Event System\n\nThe event system enables real-time monitoring and logging of workforce operations.\n\n| Event Type | Trigger | Data Captured |\n|------------|---------|---------------|\n| `WorkerStarted` | Worker begins processing | worker_id, timestamp |\n| `WorkerCompleted` | Worker finishes task | worker_id, result |\n| `TaskSubmitted` | New task enters queue | task_id, priority |\n| `TaskFailed` | Task execution error | task_id, error_info |\n\n资料来源：[camel/societies/workforce/events.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/events.py)\n\n## Metrics and Monitoring\n\n### WorkforceMetrics\n\nTracks performance indicators across the workforce execution.\n\n| Metric | Description |\n|--------|-------------|\n| `total_tasks` | Total tasks submitted |\n| `completed_tasks` | Successfully completed tasks |\n| `failed_tasks` | Tasks that encountered errors |\n| `avg_execution_time` | Mean task duration |\n\n资料来源：[camel/societies/workforce/workforce_metrics.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/workforce_metrics.py)\n\n### Callbacks\n\nThe `WorkforceCallback` interface allows custom hooks for monitoring and extending behavior.\n\n```python\nclass WorkforceCallback:\n def on_worker_start(self, worker_id: str) -> None\n def on_worker_complete(self, worker_id: str, result: Any) -> None\n def on_task_submit(self, task: Any) -> None\n def on_error(self, error: Exception) -> None\n```\n\n资料来源：[camel/societies/workforce/workforce_callback.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/workforce_callback.py)\n\n## Structured Output Handling\n\nHandles parsing and validation of structured outputs from agent responses.\n\n资料来源：[camel/societies/workforce/structured_output_handler.py](https://github.com/camel-ai/camel/blob/main/camel/societies/workforce/structured_output_handler.py)\n\n## Workflow Execution Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Workforce\n participant TaskChannel\n participant Worker\n \n User->>Workforce: submit(task)\n Workforce->>TaskChannel: put(task)\n TaskChannel->>Worker: deliver task\n Worker->>Worker: step()\n Worker->>TaskChannel: task_done()\n TaskChannel->>Workforce: completion event\n Workforce->>User: return result\n```\n\n## Configuration Options\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `max_workers` | int | auto | Maximum concurrent workers |\n| `timeout` | float | 300.0 | Task timeout in seconds |\n| `retry_count` | int | 3 | Number of retry attempts |\n| `enable_metrics` | bool | True | Enable metrics collection |\n\n## Integration with Toolkits\n\nWorkers can utilize CAMEL's extensive toolkit ecosystem:\n\n- **GoogleScholarToolkit**: Academic paper retrieval\n- **SemanticScholarToolkit**: Research paper search\n- **ArxivToolkit**: Preprint access\n- **AskNewsToolkit**: News article fetching\n- **FileToolkit**: Local file operations\n- **LinkedInToolkit**: Social media integration\n- **OpenAIImageToolkit**: Image generation\n\n## Best Practices\n\n1. **Task Design**: Break complex objectives into granular, independent tasks\n2. **Worker Selection**: Match task requirements to appropriate worker types\n3. **Error Handling**: Implement callbacks to capture and respond to failures\n4. **Resource Management**: Configure worker limits based on available compute\n5. **Monitoring**: Enable metrics collection for performance analysis\n\n## See Also\n\n- [Multi-Agent Research Assistant Example](../usecases/multi_agent_research_assistant/README.md)\n- [CAMEL Agents Application](../apps/agents/README.md)\n- [CAMEL Agent MCP Server](../services/README.md)\n\n---\n\n\n\n## Memory Management\n\n### 相关页面\n\n相关主题：[Storage Systems](#page-storage), [Multi-Agent Societies and Role Playing](#page-societies), [Agent Types and System](#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/agent_memories.py](https://github.com/camel-ai/camel/blob/main/camel/memories/agent_memories.py)\n- [camel/memories/base.py](https://github.com/camel-ai/camel/blob/main/camel/memories/base.py)\n- [camel/memories/records.py](https://github.com/camel-ai/camel/blob/main/camel/memories/records.py)\n- [camel/memories/blocks/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/memories/blocks/__init__.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/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/memories/context_creators/__init__.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/caches/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/caches/__init__.py)\n- [camel/caches/semantic_cache.py](https://github.com/camel-ai/camel/blob/main/camel/caches/semantic_cache.py)\n \n\n# Memory Management\n\nCAMEL's Memory Management system provides agents with persistent and contextual memory capabilities, enabling them to retain information across interactions, store conversation histories, and retrieve relevant context efficiently. This system is fundamental to building stateful, intelligent agents that maintain coherence across extended conversations and complex multi-step tasks.\n\n## Architecture Overview\n\nThe memory system is organized into three primary layers that work together to provide comprehensive memory capabilities:\n\n| Layer | Purpose | Key Components |\n|-------|---------|----------------|\n| **Records** | Data models for storing individual memory entries | `ChatRecord`, `MessageRecord`, `UidRecord` |\n| **Blocks** | Storage mechanisms with specific retrieval strategies | `ChatHistoryBlock`, `VectorDBBlock` |\n| **Context Creators** | Aggregation logic to build context from memories | `ScoreBasedContextCreator` |\n\n```mermaid\ngraph TD\n A[Agent Request] --> B[AgentMemories]\n B --> C[Context Creator]\n C --> D[Context Block]\n D --> E[LLM Response]\n \n C --> F[ChatHistoryBlock]\n C --> G[VectorDBBlock]\n \n F --> H[ChatRecord / MessageRecord]\n G --> I[Vector Store]\n \n J[New Interaction] --> K[Semantic Cache]\n K -->|Cache Hit| L[Return Cached Response]\n K -->|Cache Miss| E\n```\n\n资料来源：[camel/memories/agent_memories.py:1-50]()\n\n## Core Memory Components\n\n### Memory Records\n\nMemory records are the fundamental data structures that represent individual pieces of stored information. The CAMEL memory system defines several record types in `camel/memories/records.py`:\n\n| Record Type | Description | Usage |\n|-------------|-------------|-------|\n| `ChatRecord` | Stores a complete chat interaction with role and message | General conversation storage |\n| `MessageRecord` | Stores individual messages with metadata | Single message persistence |\n| `UidRecord` | Records with unique identifiers for referencing | Indexed memory lookups |\n\n资料来源：[camel/memories/records.py](https://github.com/camel-ai/camel/blob/main/camel/memories/records.py)\n\nThe `ChatRecord` class typically contains:\n- `role`: The sender's role (e.g., \"user\", \"assistant\", \"system\")\n- `message`: The actual content of the message\n- `timestamp`: Optional timestamp for the interaction\n\n### Base Memory Class\n\nAll memory implementations inherit from `MemoryBase`, which defines the common interface for memory operations:\n\n```python\nclass MemoryBase(Generic[RecordType]):\n def read(self) -> List[RecordType]: ...\n def write(self, record: RecordType) -> None: ...\n def clear(self) -> None: ...\n def get_size(self) -> int: ...\n```\n\n资料来源：[camel/memories/base.py](https://github.com/camel-ai/camel/blob/main/camel/memories/base.py)\n\n## Memory Blocks\n\nMemory blocks are concrete implementations of storage mechanisms, each optimized for different access patterns and use cases.\n\n### ChatHistoryBlock\n\nThe `ChatHistoryBlock` provides simple, linear storage for conversation history. It maintains messages in chronological order and supports basic read/write operations.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `max_messages` | `int` | Maximum number of messages to retain |\n| `window_size` | `int` | Number of recent messages to return on read |\n| `.chat_history` | `List[ChatRecord]` | Internal storage for chat records |\n\n**Key Features:**\n- FIFO (First-In-First-Out) eviction when capacity is exceeded\n- Configurable window size for retrieving only recent context\n- Efficient for sequential conversation patterns\n\n资料来源：[camel/memories/blocks/chat_history_block.py](https://github.com/camel-ai/camel/blob/main/camel/memories/blocks/chat_history_block.py)\n\n```mermaid\ngraph LR\n A[New Message] -->|append| B[ChatHistoryBlock]\n B --> C{Size > max_messages?}\n C -->|Yes| D[Remove Oldest]\n C -->|No| E[Store]\n F[Read Request] --> G[Return last window_size messages]\n```\n\n### VectorDBBlock\n\nThe `VectorDBBlock` enables semantic search capabilities by storing memories as vector embeddings in a vector database. This allows agents to retrieve contextually relevant memories based on meaning rather than exact matches.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `vector_db` | `VectorDB` | Backend vector database instance |\n| `embedding_model` | `EmbeddingModel` | Model for generating embeddings |\n| `top_k` | `int` | Number of top results to retrieve |\n| `score_threshold` | `float` | Minimum similarity score for inclusion |\n\n**Supported Operations:**\n- Semantic similarity search\n- Score-based filtering of results\n- Integration with various vector database backends\n\n资料来源：[camel/memories/blocks/vectordb_block.py](https://github.com/camel-ai/camel/blob/main/camel/memories/blocks/vectordb_block.py)\n\n## Context Creators\n\nContext creators aggregate memory records into a unified context format suitable for LLM consumption. They transform raw memory data into prompt-ready strings.\n\n### ScoreBasedContextCreator\n\nThe `ScoreBasedContextCreator` implements intelligent context aggregation by scoring memory entries and including only the most relevant ones:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `max_tokens` | `int` | 6000 | Maximum token budget for context |\n| `score_threshold` | `float` | 0.5 | Minimum relevance score |\n| `memory_block` | `MemoryBlock` | required | Source memory block |\n| `embedding_model` | `EmbeddingModel` | required | Model for computing relevance |\n\n**Scoring Algorithm:**\n1. Embed the current query/message\n2. Compute similarity scores against stored memories\n3. Filter entries below `score_threshold`\n4. Add highest-scoring entries until `max_tokens` is reached\n\n资料来源：[camel/memories/context_creators/score_based.py](https://github.com/camel-ai/camel/blob/main/camel/memories/context_creators/score_based.py)\n\n```mermaid\ngraph TD\n A[Query] --> B[Embedding Generation]\n B --> C[Score All Memories]\n C --> D{Score > threshold?}\n D -->|Yes| E[Add to Context]\n D -->|No| F[Discard]\n E --> G{Token Budget OK?}\n G -->|Yes| C\n G -->|No| H[Return Context]\n```\n\n## Agent Memories Integration\n\nThe `AgentMemories` class serves as the central orchestrator, combining multiple memory blocks and context creators:\n\n```python\nclass AgentMemories:\n def __init__(\n self,\n context_creator: ContextCreator,\n memory_blocks: List[MemoryBlock],\n ) -> None: ...\n \n def read(self) -> str: ...\n def write(self, record: MemoryRecord) -> None: ...\n```\n\n资料来源：[camel/memories/agent_memories.py](https://github.com/camel-ai/camel/blob/main/camel/memories/agent_memories.py)\n\n**Typical Configuration:**\n\n| Component | Selection Criteria |\n|-----------|-------------------|\n| ChatHistoryBlock | When conversation order matters, simple retrieval needed |\n| VectorDBBlock | When semantic search, long-term memory, or context relevance is critical |\n| ScoreBasedContextCreator | When token-efficient context retrieval is required |\n\n## Semantic Cache System\n\nBeyond agent memory, CAMEL provides a caching layer for optimizing repeated queries through the `SemanticCache`:\n\n| Feature | Description |\n|---------|-------------|\n| Semantic Matching | Uses embeddings to find similar queries |\n| TTL Support | Optional time-to-live for cache entries |\n| Custom Embedding | Configurable embedding model |\n| Hit/Miss Tracking | Statistics on cache performance |\n\n资料来源：[camel/caches/semantic_cache.py](https://github.com/camel-ai/camel/blob/main/camel/caches/semantic_cache.py)\n\n**Cache Workflow:**\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant Cache as SemanticCache\n participant LLM\n \n Agent->>Cache: Query Request\n Cache->>Cache: Compute Query Embedding\n Cache->>Cache: Search Similar Entries\n alt Cache Hit\n Cache-->>Agent: Return Cached Response\n else Cache Miss\n Agent->>LLM: Process Query\n LLM-->>Agent: Generate Response\n Agent->>Cache: Store Result\n Cache-->>Agent: Return Response\n end\n```\n\n## Usage Patterns\n\n### Basic Memory Setup\n\n```python\nfrom camel.memories import AgentMemories, ChatHistoryBlock\nfrom camel.memories.context_creators import ScoreBasedContextCreator\n\n# Create memory block\nchat_block = ChatHistoryBlock(max_messages=100)\n\n# Create context creator\ncontext_creator = ScoreBasedContextCreator(\n memory_block=chat_block,\n max_tokens=4000\n)\n\n# Combine into agent memories\nagent_memories = AgentMemories(\n context_creator=context_creator,\n memory_blocks=[chat_block]\n)\n```\n\n### Vector-Based Memory with Semantic Search\n\n```python\nfrom camel.memories import AgentMemories, VectorDBBlock\nfrom camel.memories.context_creators import ScoreBasedContextCreator\n\n# Create vector database block\nvector_block = VectorDBBlock(\n vector_db=your_vector_db,\n embedding_model=your_embedding_model,\n top_k=5,\n score_threshold=0.7\n)\n\n# Use with context creator\ncontext_creator = ScoreBasedContextCreator(\n memory_block=vector_block,\n score_threshold=0.7\n)\n\nagent_memories = AgentMemories(\n context_creator=context_creator,\n memory_blocks=[vector_block]\n)\n```\n\n## Module Exports\n\nThe memory system is organized under `camel.memories` and `camel.caches` packages:\n\n资料来源：[camel/memories/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/memories/__init__.py)\n\n| Export | Source Module |\n|--------|---------------|\n| `MemoryBase` | `camel.memories.base` |\n| `ChatRecord`, `MessageRecord`, `UidRecord` | `camel.memories.records` |\n| `AgentMemories` | `camel.memories.agent_memories` |\n| `ChatHistoryBlock` | `camel.memories.blocks.chat_history_block` |\n| `VectorDBBlock` | `camel.memories.blocks.vectordb_block` |\n| `ScoreBasedContextCreator` | `camel.memories.context_creators.score_based` |\n| `SemanticCache` | `camel.caches.semantic_cache` |\n\n## Best Practices\n\n| Scenario | Recommended Configuration |\n|----------|---------------------------|\n| Short conversations | `ChatHistoryBlock` with `window_size=10` |\n| Long-term knowledge | `VectorDBBlock` with high `top_k` |\n| Token-constrained contexts | `ScoreBasedContextCreator` with low `max_tokens` |\n| Repeated query optimization | `SemanticCache` with TTL enabled |\n| Balanced performance | Combined `ChatHistoryBlock` + `VectorDBBlock` |\n\n## Summary\n\nThe CAMEL Memory Management system provides a flexible, extensible architecture for agent memory capabilities:\n\n- **Modular Design**: Separate concerns through Records, Blocks, and Context Creators\n- **Multiple Storage Backends**: Support for linear history and semantic vector storage\n- **Intelligent Context**: Score-based filtering ensures relevant context within token limits\n- **Caching Layer**: Semantic cache optimizes repeated query handling\n- **Extensible**: Custom memory blocks can be implemented by extending `MemoryBase`\n\n---\n\n\n\n## Storage Systems\n\n### 相关页面\n\n相关主题：[Memory Management](#page-memory)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/storages/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/storages/__init__.py)\n- [camel/storages/vectordb_storages/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/storages/vectordb_storages/__init__.py)\n- [camel/storages/vectordb_storages/base.py](https://github.com/camel-ai/camel/blob/main/camel/storages/vectordb_storages/base.py)\n- [camel/storages/vectordb_storages/chroma.py](https://github.com/camel-ai/camel/blob/main/camel/storages/vectordb_storages/chroma.py)\n- [camel/storages/vectordb_storages/faiss.py](https://github.com/camel-ai/camel/blob/main/camel/storages/vectordb_storages/faiss.py)\n- [camel/storages/vectordb_storages/qdrant.py](https://github.com/camel-ai/camel/blob/main/camel/storages/vectordb_storages/qdrant.py)\n- [camel/storages/vectordb_storages/pgvector.py](https://github.com/camel-ai/camel/blob/main/camel/storages/vectordb_storages/pgvector.py)\n- [camel/storages/graph_storages/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/storages/graph_storages/__init__.py)\n- [camel/storages/graph_storages/neo4j_graph.py](https://github.com/camel-ai/camel/blob/main/camel/storages/graph_storages/neo4j_graph.py)\n- [camel/storages/key_value_storages/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/storages/key_value_storages/__init__.py)\n- [camel/storages/key_value_storages/redis.py](https://github.com/camel-ai/camel/blob/main/camel/storages/key_value_storages/redis.py)\n- [camel/storages/object_storages/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/storages/object_storages/__init__.py)\n \n\n# Storage Systems\n\n## Overview\n\nThe CAMEL-AI storage systems provide a unified abstraction layer for managing different types of data storage backends. The storage module enables AI agents to persist, retrieve, and manage various forms of data including embeddings, knowledge graphs, key-value caches, and object files. This architecture follows a plugin-based pattern where each storage backend implements a common interface, allowing seamless switching between different storage technologies without changing application code.\n\nThe storage subsystem is organized into four primary categories: Vector Database Storages for embedding-based similarity search, Graph Storages for relationship-based data, Key-Value Storages for fast caching, and Object Storages for file-based persistence. Each category is designed to address specific data access patterns commonly required in AI agent workflows, such as retrieval-augmented generation (RAG), memory management, and knowledge representation.\n\n## Architecture Overview\n\nThe storage architecture follows a hierarchical design with a base abstraction layer that defines common operations, followed by category-specific base classes, and finally concrete implementations for specific storage backends.\n\n```mermaid\ngraph TB\n subgraph \"Storage Module Architecture\"\n A[\"camel.storages\"]\n B[\"VectorDB Storages\"]\n C[\"Graph Storages\"]\n D[\"Key-Value Storages\"]\n E[\"Object Storages\"]\n \n A --> B\n A --> C\n A --> D\n A --> E\n \n B --> B1[\"Base VectorDB\"]\n B1 --> B2[\"Chroma\"]\n B1 --> B3[\"FAISS\"]\n B1 --> B4[\"Qdrant\"]\n B1 --> B5[\"PGVector\"]\n \n C --> C1[\"Neo4j Graph\"]\n \n D --> D1[\"Redis KV\"]\n \n E --> E1[\"Base Object Storage\"]\n end\n```\n\n## Vector Database Storages\n\n### Purpose and Scope\n\nVector database storages in CAMEL-AI provide specialized functionality for storing and querying vector embeddings. These storages are essential for implementing similarity search capabilities required by retrieval-augmented generation systems, semantic search, and any application that needs to find documents or data points based on vector similarity rather than exact matches.\n\nThe vector storage implementations support common operations including adding vectors with associated metadata, performing similarity searches to find the k-nearest neighbors to a given query vector, updating existing vector records, and deleting vectors from the database.\n\n### Base VectorDB Class\n\nThe base vector database class defines the interface that all vector storage implementations must follow. This abstraction ensures consistent API behavior across different vector database backends while allowing each implementation to leverage the specific capabilities of its underlying technology.\n\n**Core Operations:**\n\n| Operation | Description |\n|-----------|-------------|\n| `upsert` | Insert or update vectors with unique identifiers |\n| `query` | Search for similar vectors using a query vector |\n| `delete` | Remove vectors by their identifiers |\n| `clear` | Remove all vectors from the storage |\n\n资料来源：[camel/storages/vectordb_storages/base.py]()\n\n### Supported Vector Database Backends\n\nCAMEL-AI provides native implementations for four popular vector database technologies, each offering different trade-offs in terms of scalability, deployment complexity, and feature set.\n\n#### Chroma\n\nChroma is an open-source embedding database designed for AI applications. The CAMEL-AI Chroma integration provides a lightweight, easy-to-use vector storage solution suitable for development and testing environments. Chroma can run in embedded mode (within the application process) or connect to a Chroma server instance for production deployments.\n\n**Configuration Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `dimension` | int | Yes | Dimensionality of the embedding vectors |\n| `collection_name` | str | No | Name of the collection (default: \"camel\") |\n| `persist_directory` | str | No | Directory for persistent storage |\n| `client` | ChromaClient | No | Custom Chroma client instance |\n\n资料来源：[camel/storages/vectordb_storages/chroma.py]()\n\n#### FAISS\n\nFacebook AI Similarity Search (FAISS) is a library developed by Meta for efficient similarity search and clustering of dense vectors. The FAISS integration in CAMEL-AI provides a fast, memory-efficient vector storage implementation that operates entirely in-process without requiring an external database server. FAISS is particularly well-suited for applications requiring high-performance vector operations with large datasets.\n\n**Configuration Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `dimension` | int | Yes | Dimensionality of the embedding vectors |\n| `index_type` | str | No | FAISS index type (default: \"Flat\") |\n| `metric_type` | str | No | Distance metric - \"L2\" or \"IP\" for inner product |\n\n资料来源：[camel/storages/vectordb_storages/faiss.py]()\n\n#### Qdrant\n\nQdrant is a vector similarity search engine with a REST API. The CAMEL-AI Qdrant integration enables connection to Qdrant servers, supporting both local Qdrant instances and Qdrant Cloud services. Qdrant provides advanced filtering capabilities, payload storage, and horizontal scalability.\n\n**Configuration Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `collection_name` | str | No | Name of the Qdrant collection |\n| `vector_dim` | int | Yes | Dimensionality of vectors |\n| `url` | str | No | Qdrant server URL |\n| `grpc_port` | int | No | gRPC port for faster connections |\n| `distance` | str | No | Distance metric: \"Cosine\", \"Euclidean\", or \"Dot\" |\n\n资料来源：[camel/storages/vectordb_storages/qdrant.py]()\n\n#### PGVector\n\nPGVector is an extension for PostgreSQL that enables vector similarity search within the PostgreSQL database. The CAMEL-AI PGVector integration allows storing vectors alongside relational data, enabling hybrid queries that combine semantic search with traditional SQL filtering. This integration is ideal for applications already using PostgreSQL or requiring ACID compliance.\n\n**Configuration Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `dimension` | int | Yes | Dimensionality of embedding vectors |\n| `host` | str | No | PostgreSQL host |\n| `port` | int | No | PostgreSQL port (default: 5432) |\n| `database` | str | No | Database name |\n| `table_name` | str | No | Table name for vectors |\n| `pre_delete` | bool | No | Delete existing collection on init |\n\n资料来源：[camel/storages/vectordb_storages/pgvector.py]()\n\n### Vector Storage Workflow\n\n```mermaid\ngraph LR\n A[\"Embed Text\"] --> B[\"Generate Vector\"]\n B --> C[\"Upsert to VectorDB\"]\n C --> D[\"Store with Metadata\"]\n \n E[\"Query Request\"] --> F[\"Embed Query\"]\n F --> G[\"VectorDB Query\"]\n G --> H[\"Return Similar Results\"]\n \n style A fill:#e1f5fe\n style E fill:#fff3e0\n style H fill:#e8f5e9\n```\n\n## Graph Storages\n\n### Purpose and Scope\n\nGraph storages in CAMEL-AI provide capabilities for storing and querying structured data represented as graphs. These storages are designed for knowledge representation, relationship mapping, and complex queries that involve traversing connections between entities. Graph storages are particularly valuable for AI agents that need to maintain and query structured knowledge, understand entity relationships, and perform multi-hop reasoning.\n\nThe graph storage implementations support operations including adding nodes with properties, creating and managing relationships between nodes, querying the graph using pattern matching, and traversing the graph to discover connected entities.\n\n### Neo4j Graph Storage\n\nNeo4j is a leading graph database that stores data as nodes and relationships with properties. The CAMEL-AI Neo4j integration provides a comprehensive interface for managing knowledge graphs, enabling AI agents to store structured information about entities and their relationships.\n\n**Core Operations:**\n\n| Operation | Description |\n|-----------|-------------|\n| `upsert_node` | Create or update a node with properties |\n| `create_relationship` | Establish a relationship between two nodes |\n| `query` | Execute Cypher queries against the graph |\n| `delete` | Remove nodes or relationships |\n\n**Node Structure:**\n- Unique identifier for each node\n- Label for categorization\n- Properties as key-value pairs\n- Timestamp metadata for tracking\n\n**Relationship Structure:**\n- Source and target node references\n- Relationship type\n- Properties for additional context\n\n资料来源：[camel/storages/graph_storages/neo4j_graph.py]()\n\n### Graph Storage Data Model\n\n```mermaid\ngraph TD\n A[\"Entity Node\"] -->|\"HAS_PROPERTY\"| B[\"Property\"]\n A -->|\"RELATES_TO\"| C[\"Entity Node\"]\n C -->|\"RELATES_TO\"| D[\"Entity Node\"]\n \n style A fill:#bbdefb\n style C fill:#c8e6c9\n style D fill:#ffccbc\n```\n\n## Key-Value Storages\n\n### Purpose and Scope\n\nKey-value storages provide fast, in-memory or disk-backed storage for simple data that can be accessed using unique keys. These storages are optimized for caching, session management, and temporary data storage where the overhead of complex queries is not required. CAMEL-AI's key-value storage implementation supports rapid read and write operations essential for maintaining agent state and caching frequently accessed data.\n\n### Redis Key-Value Storage\n\nRedis is an open-source, in-memory data structure store used as a database, cache, and message broker. The CAMEL-AI Redis integration provides a high-performance key-value storage solution suitable for caching agent responses, storing session data, and maintaining temporary state information.\n\n**Core Operations:**\n\n| Operation | Description |\n|-----------|-------------|\n| `read` | Retrieve a value by key |\n| `write` | Store a value with optional TTL |\n| `delete` | Remove a key-value pair |\n| `exists` | Check if a key exists |\n| `clear` | Remove all keys in the namespace |\n\n**Configuration Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `host` | str | No | Redis host (default: \"localhost\") |\n| `port` | int | No | Redis port (default: 6379) |\n| `db` | int | No | Database number (default: 0) |\n| `password` | str | No | Authentication password |\n| `key_prefix` | str | No | Prefix for all keys |\n\n资料来源：[camel/storages/key_value_storages/redis.py]()\n\n## Object Storages\n\n### Purpose and Scope\n\nObject storages provide file-based persistence capabilities for storing and retrieving arbitrary objects, documents, and binary data. These storages complement the other storage types by handling data that is best managed as files rather than structured records. Object storages are used for persisting agent outputs, storing documents, and managing file-based artifacts generated during agent workflows.\n\nThe object storage module provides a base interface that can be implemented by various backends depending on deployment requirements. This abstraction allows applications to store objects locally during development while supporting cloud-based object storage in production environments.\n\n资料来源：[camel/storages/object_storages/__init__.py]()\n\n## Common Patterns and Usage\n\n### Storage Selection Guide\n\nSelecting the appropriate storage type depends on your application's specific requirements. The following guidelines help determine which storage solution best fits different use cases.\n\n| Use Case | Recommended Storage | Rationale |\n|----------|---------------------|-----------|\n| Semantic Search / RAG | VectorDB (Chroma/FAISS) | Optimized for similarity search on embeddings |\n| Knowledge Graphs | Neo4j | Graph traversal and relationship queries |\n| Session Caching | Redis | Sub-millisecond latency for key access |\n| Document Storage | Object Storage | File-based persistence with metadata |\n| Hybrid Search | PGVector | Combines vector search with SQL filtering |\n\n### Initialization Pattern\n\nAll storage implementations follow a consistent initialization pattern that allows for both required and optional configuration parameters. The typical workflow involves creating a storage instance with necessary parameters, optionally verifying connectivity, and then using the storage for data operations.\n\n```python\n# Example: Initialize a vector storage\nfrom camel.storages import VectorDBStorage\n\nstorage = VectorDBStorage(\n dimension=1536,\n collection_name=\"knowledge_base\"\n)\n\n# Perform operations\nstorage.upsert(vectors, ids, metadata)\nresults = storage.query(query_vector, top_k=5)\n```\n\n## Module Exports\n\nThe storage module exports all storage implementations through its public API, allowing imports from a central location rather than individual modules.\n\n**Public Exports:**\n\n```python\nfrom camel.storages import (\n # VectorDB Storage\n VectorDBStorage,\n ChromaStorage,\n FAISSStorage,\n QdrantStorage,\n PGVectorStorage,\n \n # Graph Storage\n Neo4jGraphStorage,\n \n # Key-Value Storage\n RedisKeyValueStorage,\n)\n```\n\n资料来源：[camel/storages/__init__.py]()\n资料来源：[camel/storages/vectordb_storages/__init__.py]()\n资料来源：[camel/storages/graph_storages/__init__.py]()\n资料来源：[camel/storages/key_value_storages/__init__.py]()\n\n## Integration with Agent Systems\n\nThe storage systems are designed to integrate seamlessly with CAMEL-AI's agent framework. Agents can utilize storage backends for various purposes including:\n\n- **Memory Management**: Storing conversation history and context\n- **Knowledge Retrieval**: Accessing persistent knowledge bases\n- **Result Caching**: Preventing redundant computations\n- **State Persistence**: Maintaining agent state across sessions\n\nThe unified interface design ensures that agents can switch between storage backends without code changes, enabling flexibility in deployment configurations and supporting different scalability requirements.\n\n## Summary\n\nCAMEL-AI's Storage Systems provide a comprehensive, modular approach to data persistence for AI agent applications. By offering specialized implementations for vector databases, graph databases, key-value stores, and object storage, the framework enables developers to choose the most appropriate storage technology for their specific use case while maintaining a consistent programming interface. The plugin-based architecture facilitates extensibility, allowing new storage backends to be added without modifying existing application code.\n\n---\n\n\n\n## Data Generation\n\n### 相关页面\n\n相关主题：[Introduction to CAMEL](#page-introduction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [camel/datagen/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/datagen/__init__.py)\n- [camel/datagen/self_instruct/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/datagen/self_instruct/__init__.py)\n- [camel/datagen/self_instruct/self_instruct.py](https://github.com/camel-ai/camel/blob/main/camel/datagen/self_instruct/self_instruct.py)\n- [camel/datagen/cot_datagen.py](https://github.com/camel-ai/camel/blob/main/camel/datagen/cot_datagen.py)\n- [camel/datagen/evol_instruct/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/datagen/evol_instruct/__init__.py)\n- [camel/datagen/evol_instruct/evol_instruct.py](https://github.com/camel-ai/camel/blob/main/camel/datagen/evol_instruct/evol_instruct.py)\n- [camel/datagen/evol_instruct/scorer.py](https://github.com/camel-ai/camel/blob/main/camel/datagen/evol_instruct/scorer.py)\n- [camel/datagen/self_improving_cot.py](https://github.com/camel-ai/camel/blob/main/camel/datagen/self_improving_cot.py)\n- [camel/datagen/source2synth/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/datagen/source2synth/__init__.py)\n- [camel/datasets/__init__.py](https://github.com/camel-ai/camel/blob/main/camel/datasets/__init__.py)\n- [camel/datasets/static_dataset.py](https://github.com/camel-ai/camel/blob/main/camel/datasets/static_dataset.py)\n \n\n# Data Generation\n\n## Overview\n\nThe Data Generation module in CAMEL-AI provides a comprehensive framework for synthetic data creation to train and improve large language models (LLMs). This module implements multiple data generation strategies including Self-Instruct, Evolution Instruct, Chain-of-Thought (CoT) generation, and source-to-synthesis pipelines.\n\nThe data generation system enables developers to:\n- Generate instruction-following datasets from seed examples\n- Evolve existing instructions to increase complexity and diversity\n- Create chain-of-thought reasoning datasets\n- Synthesize data from various source formats into structured datasets\n\n资料来源：[camel/datagen/__init__.py]()\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"Data Generation Core\"\n SI[Self-Instruct]\n EI[Evolution Instruct]\n COT[Chain-of-Thought]\n S2S[Source2Synth]\n end\n \n subgraph \"Supporting Components\"\n SC[Scorer]\n SD[Static Dataset]\n end\n \n subgraph \"Data Sources\"\n Seed[Seed Examples]\n Raw[Raw Sources]\n Existing[Existing Datasets]\n end\n \n subgraph \"Outputs\"\n Instructions[Instruction Datasets]\n CoT_Data[CoT Datasets]\n Synth[Synthetic Datasets]\n end\n \n Seed --> SI\n Seed --> EI\n Raw --> S2S\n Existing --> COT\n \n SI --> Instructions\n EI --> Instructions\n COT --> CoT_Data\n S2S --> Synth\n \n SC --> EI\n SD --> COT\n```\n\n## Core Components\n\n### Self-Instruct Module\n\nThe Self-Instruct module generates instruction-following data by prompting an LLM to produce new instructions based on a set of seed examples. This approach reduces the need for manual annotation while maintaining instruction diversity.\n\n资料来源：[camel/datagen/self_instruct/__init__.py]()\n\n#### SelfInstruct Class\n\n```python\nclass SelfInstruct(BaseSelfInstruct):\n def run(\n num_instructions: int = 100,\n seed_task_path: str = \"seed_task.txt\"\n ) -> List[Dict[str, Any]]\n```\n\n**Key Features:**\n- Generates new instructions from seed task examples\n- Uses LLM to produce diverse instruction variants\n- Filters generated instructions for quality\n- Supports batch processing for scalability\n\n资料来源：[camel/datagen/self_instruct/self_instruct.py]()\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `num_instructions` | `int` | Number of instructions to generate (default: 100) |\n| `seed_task_path` | `str` | Path to seed task examples file |\n| `model` | `Model` | LLM model instance for generation |\n| `batch_size` | `int` | Number of instructions per batch |\n\n### Evolution Instruct Module\n\nThe Evolution Instruct module enhances existing instructions by progressively increasing their complexity. It generates multiple variants at different difficulty levels and evaluates them using a scoring mechanism.\n\n资料来源：[camel/datagen/evol_instruct/__init__.py]()\n\n#### Evolution Workflow\n\n```mermaid\ngraph LR\n A[Original Instructions] --> B[Level 1 - Simpler]\n A --> C[Level 2 - Moderate]\n A --> D[Level 3 - Complex]\n A --> E[Level N - Expert]\n \n B --> F[Scorer Evaluation]\n C --> F\n D --> F\n E --> F\n \n F --> G[Evolved Dataset]\n```\n\n**Evolution Levels:**\n- **Level 1 (Simpler)**: Reduce complexity, add constraints\n- **Level 2 (Moderate)**: Maintain similar complexity with variations\n- **Level 3 (Complex)**: Add multi-step reasoning requirements\n- **Level N (Expert)**: Expert-level domain-specific challenges\n\n资料来源：[camel/datagen/evol_instruct/evol_instruct.py]()\n\n| Evolution Level | Description | Use Case |\n|-----------------|-------------|----------|\n| 1 | Simpler tasks | Beginner training |\n| 2 | Moderate complexity | General training |\n| 3 | Complex reasoning | Advanced tasks |\n| N | Expert level | Specialized domains |\n\n#### Scorer Component\n\nThe Scorer evaluates evolved instructions based on quality metrics, ensuring the generated data meets relevance and complexity thresholds.\n\n资料来源：[camel/datagen/evol_instruct/scorer.py]()\n\n| Score Aspect | Metric | Threshold |\n|--------------|--------|-----------|\n| Relevance | Semantic similarity | ≥ 0.7 |\n| Complexity | Token count increase | ≥ 1.2x |\n| Diversity | Unique n-grams | ≥ 0.5 |\n\n## Chain-of-Thought Data Generation\n\nThe CoT Data Generation module creates reasoning chains that demonstrate step-by-step problem solving. This is essential for training models that require logical reasoning capabilities.\n\n资料来源：[camel/datagen/cot_datagen.py]()\n\n### Self-Improving CoT\n\nThe Self-Improving Chain-of-Thought component implements a self-reflection and improvement loop for reasoning chains:\n\n```mermaid\ngraph TD\n A[Initial Query] --> B[Generate Reasoning]\n B --> C[Execute Steps]\n C --> D[Validate Results]\n D -->|Valid| E[Accept Solution]\n D -->|Invalid| F[Identify Errors]\n F --> G[Regenerate Reasoning]\n G --> B\n E --> H[Store in Dataset]\n```\n\n**Process Flow:**\n1. Generate initial reasoning chain from query\n2. Execute each step of the reasoning\n3. Validate intermediate and final results\n4. If invalid, identify error points and regenerate\n5. Store successful chains in dataset\n\n资料来源：[camel/datagen/self_improving_cot.py]()\n\n### CoT Data Generation Configuration\n\n```python\nclass CoTDataGen:\n def __init__(\n self,\n model: Model,\n num_reasoning_steps: int = 5,\n max_retries: int = 3,\n temperature: float = 0.7\n )\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `model` | `Model` | Required | LLM for reasoning generation |\n| `num_reasoning_steps` | `int` | 5 | Maximum steps in reasoning chain |\n| `max_retries` | `int` | 3 | Retry attempts for invalid chains |\n| `temperature` | `float` | 0.7 | Sampling temperature |\n\n## Source-to-Synthesis Pipeline\n\nThe Source2Synth module converts raw data from various formats into structured synthetic datasets. This enables integration of heterogeneous data sources into the training pipeline.\n\n资料来源：[camel/datagen/source2synth/__init__.py]()\n\n### Supported Source Formats\n\n| Source Type | Input Format | Processing |\n|-------------|--------------|------------|\n| Text Files | `.txt`, `.md` | Direct parsing |\n| JSON | `.json` | Structured extraction |\n| CSV | `.csv` | Tabular conversion |\n| XML | `.xml` | Hierarchical parsing |\n| HTML | `.html` | Web content extraction |\n\n### Synthesis Process\n\n```mermaid\ngraph TD\n subgraph \"Ingestion\"\n R1[Raw Source 1]\n R2[Raw Source 2]\n R3[Raw Source N]\n end\n \n subgraph \"Processing\"\n P1[Parse & Extract]\n P2[Normalize]\n P3[Validate]\n end\n \n subgraph \"Synthesis\"\n S1[Transform]\n S2[Augment]\n S3[Format]\n end\n \n R1 --> P1\n R2 --> P2\n R3 --> P3\n \n P1 --> S1\n P2 --> S2\n P3 --> S3\n \n S1 --> O[Synthetic Dataset]\n S2 --> O\n S3 --> O\n```\n\n## Dataset Integration\n\n### Static Dataset Module\n\nThe Static Dataset module provides utilities for managing and accessing pre-built datasets used in data generation pipelines.\n\n资料来源：[camel/datasets/__init__.py]()\n\n```python\nclass StaticDataset:\n def __init__(self, name: str, data_path: str)\n def load(self) -> List[Dict]\n def filter(self, predicate: Callable) -> \"StaticDataset\"\n def sample(self, n: int) -> List[Dict]\n```\n\n| Method | Return Type | Description |\n|--------|-------------|-------------|\n| `load()` | `List[Dict]` | Load all data from source |\n| `filter(predicate)` | `StaticDataset` | Filter by condition |\n| `sample(n)` | `List[Dict]` | Random sample of n items |\n\n资料来源：[camel/datasets/static_dataset.py]()\n\n### Dataset Loading Example\n\n```python\nfrom camel.datasets import StaticDataset\n\n# Load a static dataset\ndataset = StaticDataset(\n name=\"reasoning_benchmarks\",\n data_path=\"path/to/data.json\"\n)\n\n# Filter and sample\nfiltered = dataset.filter(lambda x: x[\"difficulty\"] >= 3)\nsamples = filtered.sample(n=100)\n```\n\n## Usage Patterns\n\n### Basic Self-Instruct Pipeline\n\n```python\nfrom camel.datagen.self_instruct import SelfInstruct\nfrom camel.models import ModelFactory\nfrom camel.types import ModelPlatformType\n\n# Initialize model\nmodel = ModelFactory.create(\n model_platform=ModelPlatformType.OPENAI,\n model_type=\"gpt-4\"\n)\n\n# Run self-instruct\ngenerator = SelfInstruct(model=model)\nresults = generator.run(\n num_instructions=100,\n seed_task_path=\"seed_tasks.txt\"\n)\n```\n\n### Evolution Instruct Pipeline\n\n```python\nfrom camel.datagen.evol_instruct import EvolutionInstruct\nfrom camel.datagen.evol_instruct.scorer import Scorer\n\n# Initialize scorer\nscorer = Scorer(threshold=0.7)\n\n# Run evolution\nevolver = EvolutionInstruct(\n model=model,\n scorer=scorer\n)\nevolved = evolver.evolve(instructions, target_level=3)\n```\n\n### Chain-of-Thought Generation\n\n```python\nfrom camel.datagen.cot_datagen import CoTDataGen\nfrom camel.datagen.self_improving_cot import SelfImprovingCoT\n\n# Initialize CoT generator\ncot_gen = CoTDataGen(\n model=model,\n num_reasoning_steps=7\n)\n\n# Generate reasoning chain\nquery = \"Calculate the compound interest for $1000 at 5% for 3 years\"\nchain = cot_gen.generate(query)\n```\n\n## Configuration Options\n\n### Global Configuration\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `output_dir` | `str` | `\"./output\"` | Directory for generated data |\n| `batch_size` | `int` | 10 | Processing batch size |\n| `max_tokens` | `int` | 2048 | Maximum tokens per generation |\n| `temperature` | `float` | 0.8 | Sampling temperature |\n| `seed` | `int` | 42 | Random seed for reproducibility |\n\n### Provider-Specific Settings\n\n```python\n@dataclass\nclass DataGenConfig:\n # OpenAI\n api_base: Optional[str] = None\n api_version: Optional[str] = None\n \n # Model settings\n model: str = \"gpt-4\"\n max_retries: int = 3\n timeout: int = 60\n \n # Output settings\n save_intermediate: bool = True\n format: str = \"json\" # json, csv, parquet\n```\n\n## Best Practices\n\n1. **Seed Selection**: Choose diverse, high-quality seed examples to ensure variety in generated data\n2. **Quality Filtering**: Always apply scorer-based filtering to maintain instruction quality\n3. **Batch Processing**: Use appropriate batch sizes to balance memory usage and throughput\n4. **Validation**: Implement result validation before storing in final datasets\n5. **Iteration**: Use self-improving loops for complex reasoning tasks\n\n## Error Handling\n\n| Error Type | Cause | Resolution |\n|------------|-------|------------|\n| `GenerationError` | LLM fails to generate | Increase temperature, check API |\n| `ValidationError` | Output format invalid | Add post-processing, retry |\n| `TimeoutError` | Request takes too long | Increase timeout, reduce batch |\n| `QuotaError` | API quota exceeded | Implement backoff, use caching |\n\n## Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `camel-ai` | ≥ 0.2.x | Core framework |\n| `openai` | Latest | API access |\n| `tqdm` | Latest | Progress bars |\n| `pydantic` | Latest | Data validation |\n\n## Summary\n\nThe Data Generation module provides a comprehensive toolkit for creating synthetic training data:\n\n- **Self-Instruct**: Generate instruction-following data from seeds\n- **Evolution Instruct**: Progressively increase instruction complexity\n- **Chain-of-Thought**: Create reasoning chains with validation\n- **Source2Synth**: Convert heterogeneous sources to structured datasets\n\nThese components work together to enable scalable, high-quality data generation for training and fine-tuning language models.\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：camel-ai/camel\n\n摘要：发现 38 个潜在踩坑项，其中 7 个为 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. 安全/权限坑 · 失败模式：security_permissions: [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit funct...\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：Developers should check this security_permissions risk before relying on the project: [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools\n- 对用户的影响：Developers may expose sensitive permissions or credentials: [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools. Context: Observed when using python, macos\n- 防护动作：Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/camel-ai/camel/issues/3962\n- 证据：failure_mode_cluster:github_issue | fmev_5824c9dd1e33710f6821d3f625c9b2fb | https://github.com/camel-ai/camel/issues/3962 | [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools\n\n## 5. 安全/权限坑 · 来源证据：[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## 6. 安全/权限坑 · 来源证据：[BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5736e8e2efc44fa48c0eea95b3bf0ff7 | https://github.com/camel-ai/camel/issues/4037 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安全/权限坑 · 来源证据：[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## 8. 安装坑 · 失败模式：installation: [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter w...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary\n- 对用户的影响：Developers may fail before the first successful local run: [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary. Context: Observed when using python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_ac00b6564e4aa8e23d6fa0056cc45d02 | https://github.com/camel-ai/camel/issues/4037 | [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary\n\n## 9. 安装坑 · 失败模式：installation: [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators\n- 对用户的影响：Developers may fail before the first successful local run: [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators. Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_b869fb190d161706644bb5c7e94bff8f | https://github.com/camel-ai/camel/issues/1043 | [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators, failure_mode_cluster:github_issue | fmev_e2d8786f2a91f791c3d6c7a2c4207d65 | https://github.com/camel-ai/camel/issues/1043 | [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators\n\n## 10. 安装坑 · 失败模式：installation: v0.2.90\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v0.2.90\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.2.90\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.2.90. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_6bc0695558dc4dc7fb064fa89c64c718 | https://github.com/camel-ai/camel/releases/tag/v0.2.90 | v0.2.90\n\n## 11. 配置坑 · 失败模式：configuration: [BUG] Both Bedrock options are broken\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: [BUG] Both Bedrock options are broken\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [BUG] Both Bedrock options are broken\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] Both Bedrock options are broken. Context: Observed when using python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_b5a875260984ae51f7f9b81869057a15 | https://github.com/camel-ai/camel/issues/4034 | [BUG] Both Bedrock options are broken\n\n## 12. 配置坑 · 失败模式：configuration: [Feature Request] Add OrcaRouter as a dedicated model platform\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: [Feature Request] Add OrcaRouter as a dedicated model platform\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Feature Request] Add OrcaRouter as a dedicated model platform\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature Request] Add OrcaRouter as a dedicated model platform. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_9bce4812aa6a39fc876b639a79f00c41 | https://github.com/camel-ai/camel/issues/4047 | [Feature Request] Add OrcaRouter as a dedicated model platform, failure_mode_cluster:github_issue | fmev_fefb71c23b8534f3eac0377e0a8ea5b2 | https://github.com/camel-ai/camel/issues/4047 | [Feature Request] Add OrcaRouter as a dedicated model platform\n\n## 13. 配置坑 · 失败模式：configuration: [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter). Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_ab8611c09187bc446ab4c53a8bbcc224 | https://github.com/camel-ai/camel/issues/3997 | [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)\n\n## 14. 配置坑 · 失败模式：configuration: v0.2.90a6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: v0.2.90a6\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.2.90a6\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.2.90a6. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_39f1f2bb3b67152c4f05563686719964 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a6 | v0.2.90a6\n\n## 15. 能力坑 · 社区讨论暴露的待验证问题：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## 16. 能力坑 · 能力判断依赖假设\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## 17. 运行坑 · 失败模式：runtime: [BUG] outdated colab notebook for workforce\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: [BUG] outdated colab notebook for workforce\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [BUG] outdated colab notebook for workforce\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] outdated colab notebook for workforce. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_3ea7bee5bfb83c37e4330b7761951754 | https://github.com/camel-ai/camel/issues/3402 | [BUG] outdated colab notebook for workforce\n\n## 18. 运行坑 · 失败模式：runtime: v0.2.91a2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: v0.2.91a2\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.2.91a2\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.2.91a2. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_0446994fae1af587527e35be6a08cbd5 | https://github.com/camel-ai/camel/releases/tag/v0.2.91a2 | v0.2.91a2\n\n## 19. 运行坑 · 来源证据：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## 20. 维护坑 · 失败模式：migration: [Question] About the Deprecation of the `reasoning_content` Field in vLLM\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: [Question] About the Deprecation of the `reasoning_content` Field in vLLM\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [Question] About the Deprecation of the `reasoning_content` Field in vLLM\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Question] About the Deprecation of the `reasoning_content` Field in vLLM. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_b64551687144d0e563078a212537da6a | https://github.com/camel-ai/camel/issues/3939 | [Question] About the Deprecation of the `reasoning_content` Field in vLLM\n\n## 21. 维护坑 · 来源证据：[BUG] outdated colab notebook for workforce\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[BUG] outdated colab notebook for workforce\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0d22381ba8a94b30ab0aff9599be8202 | https://github.com/camel-ai/camel/issues/3402 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 22. 维护坑 · 来源证据：[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## 23. 维护坑 · 维护活跃度未知\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## 24. 安全/权限坑 · 下游验证发现风险项\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## 25. 安全/权限坑 · 存在评分风险\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## 26. 安全/权限坑 · 来源证据：[BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3cc4f8df85fe4b1ebc26d3477bd4ad1d | https://github.com/camel-ai/camel/issues/3962 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 27. 安全/权限坑 · 来源证据：[feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_abab965da9ee45c0af51f9d4bd294bfe | https://github.com/camel-ai/camel/issues/3997 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 28. 安全/权限坑 · 来源证据：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## 29. 安全/权限坑 · 来源证据：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## 30. 安全/权限坑 · 来源证据：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## 31. 安全/权限坑 · 来源证据：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## 32. 能力坑 · 失败模式：conceptual: [Feature Request] Expand WorkforceCallback to support stream chunk events\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this conceptual risk before relying on the project: [Feature Request] Expand WorkforceCallback to support stream chunk events\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [Feature Request] Expand WorkforceCallback to support stream chunk events\n- 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_5c8a43fe428bd06c588a897fec9e5f46 | https://github.com/camel-ai/camel/issues/3676 | [Feature Request] Expand WorkforceCallback to support stream chunk events\n\n## 33. 能力坑 · 失败模式：conceptual: [Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got prob...\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this conceptual risk before relying on the project: [Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls\n- 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_f160cb19b4b146ff4d9530da5c4ebe6d | https://github.com/camel-ai/camel/issues/4045 | [Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls\n\n## 34. 维护坑 · 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## 35. 维护坑 · 发布节奏不明确\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## 36. 维护坑 · 失败模式：maintenance: v0.2.90a4\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: v0.2.90a4\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.2.90a4\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.2.90a4. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_bfdefa69f610e48e209896526275a8b1 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a4 | v0.2.90a4\n\n## 37. 维护坑 · 失败模式：maintenance: v0.2.90a5\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: v0.2.90a5\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.2.90a5\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.2.90a5. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_2ee088361f2e44b420faa3e982ec9e81 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a5 | v0.2.90a5\n\n## 38. 维护坑 · 失败模式：maintenance: v0.2.91a0\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: v0.2.91a0\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.2.91a0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.2.91a0. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_ac76756c522679a553aa6056ac6118a0 | https://github.com/camel-ai/camel/releases/tag/v0.2.91a0 | v0.2.91a0\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摘要：发现 38 个潜在踩坑项，其中 7 个为 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. 安全/权限坑 · 失败模式：security_permissions: [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit funct...\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：Developers should check this security_permissions risk before relying on the project: [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools\n- 对用户的影响：Developers may expose sensitive permissions or credentials: [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools. Context: Observed when using python, macos\n- 防护动作：Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/camel-ai/camel/issues/3962\n- 证据：failure_mode_cluster:github_issue | fmev_5824c9dd1e33710f6821d3f625c9b2fb | https://github.com/camel-ai/camel/issues/3962 | [BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools\n\n## 5. 安全/权限坑 · 来源证据：[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## 6. 安全/权限坑 · 来源证据：[BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5736e8e2efc44fa48c0eea95b3bf0ff7 | https://github.com/camel-ai/camel/issues/4037 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安全/权限坑 · 来源证据：[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## 8. 安装坑 · 失败模式：installation: [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter w...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary\n- 对用户的影响：Developers may fail before the first successful local run: [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary. Context: Observed when using python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_ac00b6564e4aa8e23d6fa0056cc45d02 | https://github.com/camel-ai/camel/issues/4037 | [BUG] CodeExecutionToolkit can run model-produced Python code through SubprocessInterpreter without an approval boundary\n\n## 9. 安装坑 · 失败模式：installation: [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators\n- 对用户的影响：Developers may fail before the first successful local run: [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators. Context: Observed during installation or first-run setup.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_b869fb190d161706644bb5c7e94bff8f | https://github.com/camel-ai/camel/issues/1043 | [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators, failure_mode_cluster:github_issue | fmev_e2d8786f2a91f791c3d6c7a2c4207d65 | https://github.com/camel-ai/camel/issues/1043 | [Feature Request] Refactor to use `api_keys_required` and `dependencies_required` decorators\n\n## 10. 安装坑 · 失败模式：installation: v0.2.90\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: v0.2.90\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.2.90\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.2.90. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_6bc0695558dc4dc7fb064fa89c64c718 | https://github.com/camel-ai/camel/releases/tag/v0.2.90 | v0.2.90\n\n## 11. 配置坑 · 失败模式：configuration: [BUG] Both Bedrock options are broken\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: [BUG] Both Bedrock options are broken\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [BUG] Both Bedrock options are broken\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] Both Bedrock options are broken. Context: Observed when using python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_b5a875260984ae51f7f9b81869057a15 | https://github.com/camel-ai/camel/issues/4034 | [BUG] Both Bedrock options are broken\n\n## 12. 配置坑 · 失败模式：configuration: [Feature Request] Add OrcaRouter as a dedicated model platform\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: [Feature Request] Add OrcaRouter as a dedicated model platform\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Feature Request] Add OrcaRouter as a dedicated model platform\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature Request] Add OrcaRouter as a dedicated model platform. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_9bce4812aa6a39fc876b639a79f00c41 | https://github.com/camel-ai/camel/issues/4047 | [Feature Request] Add OrcaRouter as a dedicated model platform, failure_mode_cluster:github_issue | fmev_fefb71c23b8534f3eac0377e0a8ea5b2 | https://github.com/camel-ai/camel/issues/4047 | [Feature Request] Add OrcaRouter as a dedicated model platform\n\n## 13. 配置坑 · 失败模式：configuration: [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter). Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_ab8611c09187bc446ab4c53a8bbcc224 | https://github.com/camel-ai/camel/issues/3997 | [feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)\n\n## 14. 配置坑 · 失败模式：configuration: v0.2.90a6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: v0.2.90a6\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.2.90a6\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.2.90a6. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_39f1f2bb3b67152c4f05563686719964 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a6 | v0.2.90a6\n\n## 15. 能力坑 · 社区讨论暴露的待验证问题：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## 16. 能力坑 · 能力判断依赖假设\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## 17. 运行坑 · 失败模式：runtime: [BUG] outdated colab notebook for workforce\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: [BUG] outdated colab notebook for workforce\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [BUG] outdated colab notebook for workforce\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] outdated colab notebook for workforce. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_3ea7bee5bfb83c37e4330b7761951754 | https://github.com/camel-ai/camel/issues/3402 | [BUG] outdated colab notebook for workforce\n\n## 18. 运行坑 · 失败模式：runtime: v0.2.91a2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: v0.2.91a2\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.2.91a2\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.2.91a2. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_0446994fae1af587527e35be6a08cbd5 | https://github.com/camel-ai/camel/releases/tag/v0.2.91a2 | v0.2.91a2\n\n## 19. 运行坑 · 来源证据：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## 20. 维护坑 · 失败模式：migration: [Question] About the Deprecation of the `reasoning_content` Field in vLLM\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this migration risk before relying on the project: [Question] About the Deprecation of the `reasoning_content` Field in vLLM\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [Question] About the Deprecation of the `reasoning_content` Field in vLLM\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Question] About the Deprecation of the `reasoning_content` Field in vLLM. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_b64551687144d0e563078a212537da6a | https://github.com/camel-ai/camel/issues/3939 | [Question] About the Deprecation of the `reasoning_content` Field in vLLM\n\n## 21. 维护坑 · 来源证据：[BUG] outdated colab notebook for workforce\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[BUG] outdated colab notebook for workforce\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0d22381ba8a94b30ab0aff9599be8202 | https://github.com/camel-ai/camel/issues/3402 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 22. 维护坑 · 来源证据：[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## 23. 维护坑 · 维护活跃度未知\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## 24. 安全/权限坑 · 下游验证发现风险项\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## 25. 安全/权限坑 · 存在评分风险\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## 26. 安全/权限坑 · 来源证据：[BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Bedrock Converse validation failure when using CAMEL ChatAgent with PubMedToolkit function tools\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3cc4f8df85fe4b1ebc26d3477bd4ad1d | https://github.com/camel-ai/camel/issues/3962 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 27. 安全/权限坑 · 来源证据：[feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[feat] Add search_tweets to TwitterToolkit (or add XquikToolkit for read-only X/Twitter)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_abab965da9ee45c0af51f9d4bd294bfe | https://github.com/camel-ai/camel/issues/3997 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 28. 安全/权限坑 · 来源证据：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## 29. 安全/权限坑 · 来源证据：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## 30. 安全/权限坑 · 来源证据：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## 31. 安全/权限坑 · 来源证据：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## 32. 能力坑 · 失败模式：conceptual: [Feature Request] Expand WorkforceCallback to support stream chunk events\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this conceptual risk before relying on the project: [Feature Request] Expand WorkforceCallback to support stream chunk events\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [Feature Request] Expand WorkforceCallback to support stream chunk events\n- 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_5c8a43fe428bd06c588a897fec9e5f46 | https://github.com/camel-ai/camel/issues/3676 | [Feature Request] Expand WorkforceCallback to support stream chunk events\n\n## 33. 能力坑 · 失败模式：conceptual: [Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got prob...\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this conceptual risk before relying on the project: [Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls\n- 对用户的影响：Developers may hit a documented source-backed failure mode: [Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls\n- 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_f160cb19b4b146ff4d9530da5c4ebe6d | https://github.com/camel-ai/camel/issues/4045 | [Question] when using VLLM / gemma4 / unsloath studio and the right jinja template i got problems with tool calls\n\n## 34. 维护坑 · 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## 35. 维护坑 · 发布节奏不明确\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## 36. 维护坑 · 失败模式：maintenance: v0.2.90a4\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: v0.2.90a4\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.2.90a4\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.2.90a4. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_bfdefa69f610e48e209896526275a8b1 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a4 | v0.2.90a4\n\n## 37. 维护坑 · 失败模式：maintenance: v0.2.90a5\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: v0.2.90a5\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.2.90a5\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.2.90a5. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_2ee088361f2e44b420faa3e982ec9e81 | https://github.com/camel-ai/camel/releases/tag/v0.2.90a5 | v0.2.90a5\n\n## 38. 维护坑 · 失败模式：maintenance: v0.2.91a0\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：Developers should check this maintenance risk before relying on the project: v0.2.91a0\n- 对用户的影响：Upgrade or migration may change expected behavior: v0.2.91a0\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v0.2.91a0. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_ac76756c522679a553aa6056ac6118a0 | https://github.com/camel-ai/camel/releases/tag/v0.2.91a0 | v0.2.91a0\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# camel - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for camel-ai/camel.\n\nProject:\n- Name: camel\n- Repository: https://github.com/camel-ai/camel\n- Summary: 🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: 🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-introduction: Introduction to CAMEL. Produce one small intermediate artifact and wait for confirmation.\n2. page-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n3. page-agents: Agent Types and System. Produce one small intermediate artifact and wait for confirmation.\n4. page-models: Model Integration and Providers. Produce one small intermediate artifact and wait for confirmation.\n5. page-toolkits: Tools and Toolkits. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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- camel/__init__.py\n- camel/utils/constants.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\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"
}