XAgent 平台使用指南

一、平台介绍

1. 核心理念：倡导“描述结果，而非工作流（Describe tasks. Not workflows.）”。
2. 差异化特点：区别于 Dify / Coze 等依赖硬编码拖拽式 Flowchart（工作流）的平台，Xagent 强调自主规划（Dynamic Planning）与工具调度。用户只需输入最终目标，平台即可自动进行任务分解、工具调用、自我评估与迭代交付。
3. 核心定义：由 Xorbits 团队开源的面向个人、团队与企业的动态任务执行引擎与 AI Agent 协作平台。

二、主要功能

1. 动态任务规划 (Dynamic Planning)根据目标在运行时（Runtime）自动拆解多步骤子任务。
2. 支持自动反射机制，遵循“计划→执行→反思”的流程逻辑。
3. 支持条件分支执行，适应复杂场景。
4. 工具与能力集成 (Tools & Knowledge Integration)模型支持：原生对接 OpenAI、Claude、DeepSeek、通义千问、Zhipu 等主流 API。
5. 私有化部署：无缝集成自建的 Xinference 本地/私有化模型。
6. 知识库与扩展：内置 RAG 知识库检索，支持文件读写分析及分析能力。
7. 插件规范：支持 MCP (Model Context Protocol) 插件规范及自定义 API 扩展。
8. 多 Agent 协作工作流 (Workforces Pattern)支持构建复杂的分布式 Agent 团队（如：规划者 + 调研员 + 程序员 + 审核员）。
9. 实现多角色协同分工，处理复杂业务逻辑。
10. 可复用 Agent 模版可将探索成功的单次任务模式（提示词、特定工具链、知识库权限）打包发布为模版。
11. 供团队内复用，降低重复开发成本。
12. 全流程可观测性 (Observability)实时跟踪 Agent 执行状态。
13. 提供思考日志、工具调用详情及 Token 消耗统计视图。

三、适用人群

1. 个人开发者 / AI 玩家：需要比纯 Chat 界面更强的本地自动化 Agent 工具，适用于长文本处理、复杂数据分析及自主调研场景。
2. 团队 / 研发小组：需要将日常重复的业务逻辑打包成固定的 Agent 工具链，从而提升协作效率。
3. 企业级开发者：基于私有模型（如通过 Xinference 部署）搭建企业内部知识库、合规工具链与多 Agent 业务系统的专业团队。

四、免费与付费情况

1. 开源状态：Xagent 核心代码完全开源，基于标准开源协议开放，个人与企业均可免费自建部署。
2. 社区自建版：免费。支持使用全量功能，仅需自行承担模型 API 消耗或本地显卡算力费用。
3. 商业服务与定价：关于 SaaS 云服务、企业级 SSO 或专属服务支持的最新动态。建议随时查看官方定价页面（[https://docs.xagent.co/](https://docs.xagent.co/)）获取最新信息。

五、如何使用

1. 方式 1：单机快速安装（推荐体验）确保环境满足 Python 3.11+ 要求。
2. 执行安装命令：pip install xagent-ai （或使用 uv tool install xagent-ai）。
3. 启动服务：运行 xagent 命令。
4. 浏览器访问 http://127.0.0.1:8000。
5. 在 /setup 页面创建管理员账号，并配置 LLM Provider 即可开始使用。
6. 方式 2：Docker 容器化部署（适合团队/服务器部署）克隆仓库并配置环境变量：

运行 git clone https://github.com/xorbitsai/xagent.git 后进入目录 cd xagent。

1. 复制示例环境文件：执行 cp example.env .env。
2. 一键启动 Docker 服务：运行 docker compose up -d。
3. 浏览器访问 http://localhost:80 进入 Web UI 管理界面。

六、注意事项

1. 模型能力要求：由于采用动态规划（Dynamic Task Planning）模式，Agent 的逻辑推理与工具调用非常依赖底层 LLM 的质量。建议优先选用 Reasoning 能力强或 Tool Call 效果好的模型（如 Claude 3.5 Sonnet、GPT-4o、DeepSeek-V3/R1）。
2. 死循环与 API 消耗：Dynamic Engine 在无法完成任务时可能会自主尝试多次重试。建议在后台系统设置中配置单次任务的最大步数（Max Steps）与 Token 阈值，避免无限循环导致 API 账单超支。
3. 环境隔离与安全：若允许 Agent 执行 Code/Bash 工具，请确保运行在 Docker 或隔离的虚拟环境中，避免对宿主机敏感数据产生潜在风险。