适合谁
- 需要可治理、可审计策略的企业智能体团队
- 希望复用通用智能体而只配置领域工具与策略的开发者
- 需要同时操作 Web 页面与 API 的混合任务场景
- 使用 Python SDK 或自托管 Kubernetes 的团队
C
49FMRS · D
CUGA 是 IBM 相关团队开源的通用智能体框架，重点在企业级可治理性：策略系统、沙箱执行、多智能体监督与知识库。它本身可配置为 MCP 客户端并可作为 MCP 暴露给其他智能体，适合需要把领域工具与策略接入通用智能体的团队。使用前需自备 LLM 密钥并明确沙箱与策略边界，本地执行默认隔离较弱。
CUGA（Configurable Generalist Agent）是一个开源的企业级通用智能体框架（agent harness），支持在 Web 与 API 上执行复杂任务，并可通过 OpenAPI 规范、MCP 服务器和 LangChain 工具进行集成。它提供可组合架构、多种推理与代码生成模式（fast / balanced / accurate）、API、Web 与 hybrid 三种任务模式、多智能体监督（CugaSupervisor，含 A2A 远程智能体）、策略系统（Intent Guard、Playbook、Tool Approval、Tool Guide、Output Formatter）、人类在环审批、内置知识库（基于 Docling 的 RAG，支持 agent 级与会话级作用域）、Agent 技能（SKILL.md + load_skill）、工具调用预算、反思模式以及 Docker/Podman 与 E2B 沙箱代码执行。项目同时提供 Python SDK、Web 管理界面（可发布版本化配置）以及 Kubernetes Helm 部署方案。
工具能力
load_skill
按需加载匹配任务的 SKILL.md 技能完整指令内容。
find_tools
在大型工具目录中检索并列出与当前任务相关的可用工具。
安装接入
- 确认已安装 Python 3.12+ 与 uv 包管理器。
- 克隆仓库并进入目录：git clone https://github.com/cuga-project/cuga-agent.git && cd cuga-agent
- 创建并激活虚拟环境：uv venv --python=3.12 && source .venv/bin/activate
- 安装依赖：uv sync
- 配置模型密钥，例如在 .env 中写入 OPENAI_API_KEY=your-key，并通过 AGENT_SETTING_CONFIG 选择对应的 settings.*.toml。
- 启动演示：cuga start demo_crm --read-only，浏览器将打开 https://localhost:7860。
- 可选：运行 cuga viz 查看智能体执行轨迹；自定义工具/MCP 服务器可编辑 src/cuga/backend/tools_env/registry/config/mcp_servers.yaml。
选型与风险
不适合谁
- 只需要单一简单工具调用的轻量场景
- 无法提供任何 LLM API 密钥或自托管模型的离线用户
- 期望零配置开箱即用的终端用户
所需权限
- 读取仓库与本地工作区文件（如 cuga_workspace 下的文件）
- 网络访问以调用 LLM 提供商、OpenAPI 服务与 MCP 服务器
- 在 hybrid/web 模式下通过浏览器扩展与 Playwright 控制浏览器页面
- 在启用沙箱时访问 Docker/Podman 或 E2B 云端执行环境
- 管理模式下对智能体配置（工具、MCP、LLM、策略）进行草稿编辑与发布
风险与副作用
- 智能体可代表用户调用真实 API 与操作网页，误操作可能产生实际业务影响
- 策略与沙箱配置不当会削弱隔离性，本地 Python 执行为默认且隔离较弱
- 将工具接入 E2B 云端时需通过 ngrok 等隧道暴露本地 registry，增加暴露面
- 知识库与轨迹可能包含敏感企业数据，需要自行管理存储与访问控制
- 运行时加载 self-host或内部模型，token 与成本核算需用户自行换算
常见排障
- 启动失败时确认 Python 版本为 3.12+ 且已执行 uv sync
- 模型调用报错时检查 .env 中的 API 密钥与 AGENT_SETTING_CONFIG 指向的 TOML 文件是否匹配
- E2B 报错 function_call_host not configured 时，需在 settings.toml 的 server_ports 中配置 ngrok 公网地址
- 沙箱不可用时运行 cuga test-sandbox 或 cuga test-sandbox --remote 验证环境
- 技能未被识别时检查 [skills] root 配置与 SKILL.md 是否含 name 与 description 前置字段，并重启服务以重新扫描
- 大规模工具目录导致提示过长时可调整 [shortlister] 的 strategy 与 threshold 设置
使用场景
在企业环境中编排跨 Web 与 REST API 的复杂任务
通过 mcp_servers.yaml 接入自建 MCP 服务器与 OpenAPI 服务
用策略系统与人类在环审批约束智能体行为
构建多智能体监督架构并向 A2A 远程智能体委派任务
基于内部文档构建 RAG 知识库问答
将领域工作流打包为 SKILL.md 技能按需加载
支持客户端
CUGA SDK完整支持
MCP部分支持