← 返回目录

CUGA Generalist Agent Harness

社区

框架 / SDK

面向企业的可配置通用智能体框架

这是用于开发 MCP Server 或 Agent 的框架，不是可以直接连接到客户端的 Server。

查看安装方法 ↓ 横向对比 GitHub 源仓库 ↗

分类: 其他第 158 / 230
Stars: ★ 1.0k 非常热门
传输方式: stdio（本地进程） · SSE · Streamable HTTP
运行环境: Python 3.12+ · Node.js · Docker
凭据: 需要 API Key / 凭据
许可证: Apache-2.0
最近提交: 6 天前
工具数: 2

49FMRS · D

CUGA 是 IBM 相关团队开源的通用智能体框架，重点在企业级可治理性：策略系统、沙箱执行、多智能体监督与知识库。它本身可配置为 MCP 客户端并可作为 MCP 暴露给其他智能体，适合需要把领域工具与策略接入通用智能体的团队。使用前需自备 LLM 密钥并明确沙箱与策略边界，本地执行默认隔离较弱。

最强项 · 文档质量 13/20 最弱项 · 安全与权限 7/20

可靠性

8/20

安全与权限

7/20

维护活跃度

12/20

文档质量

13/20

安装易用性

9/20

查看各项评分依据

可靠性 8/20: 仅凭 README 与描述做静态评估，未执行任何代码。README 声称在 AppWorld 与 WebArena 排行榜取得第一，但排行榜徽章属于外部声明，无法在此复核；仓库自述为大型企业级 agent harness（含 demo、supervisor、knowledge、events service、Helm 部署），规模与复杂度较高，服务器初始化与工具列表握手路径未在材料中明确展示。README 引用了测试矩阵（单元、策略集成、SDK、stability 门限 87%），但未提供可核验的 CI 工作流文件内容或已提交测试的确切覆盖证据，故不能据此上浮。依据静态校准，可靠性上限 12；因关键路径未见可复现证据、工具行为与声明一致性无法验证、依赖面广（Python 3.12、uv、可选 extras、浏览器扩展、容器/E2B 沙箱），扣分较多。
安全与权限 7/20: 材料显示存在多项安全设计：policies 体系（Intent Guard、Tool Approval 人工确认、Tool Guide、Output Formatter）、HITL 审批、代码沙箱（local/Docker-Podman/E2B 隔离）与工具调用预算，属于正向的最小权限与确认机制证据。但亦有多处需谨慎：文档示例内含真实形式的密钥赋值（如 .env 中 OPENAI_API_KEY=...，虽为占位）、E2B 场景要求用 ngrok 将本地注册表/服务暴露到公网、MCP 服务器以 stdio 命令（uvx --from altk-evolve）方式启动、final_answer.function 会导入并调用点分路径函数（README 自述须指向可信代码），这些都扩大了数据边界与远程执行面。未见凭据窃取、隐蔽外传或默认不可逆删除等红线信号，故不判 0-4；但因权限范围、确认流程完整性与外部网络暴露未见端到端可核验证据，扣分至中位偏下。
维护活跃度 12/20: 证据有限：仓库描述含 876 stars、177 open issues、未归档，README 展示了持续的功能矩阵与路线图，说明项目活跃；但 license 字段为 NOASSERTION，即许可证未在材料中明确识别，这是治理层面的实质缺口。缺少发布记录、提交节奏、依赖更新政策与安全响应通道的可核验细节，issues 数量较高亦无响应时效证据。故按“活跃但治理/版本信息有缺口”锚点给定，不做上浮。
文档质量 13/20: 文档层次较丰富：快速开始、多 LLM 提供方配置（OpenAI/WatsonX/Azure/Groq/RITS/OpenRouter/wxO）、模式与配置项表格、沙箱与知识库、supervisor、shortlister、工具接入示例等，且大量指向 docs.cuga.dev 与仓库内路径，示例可读性尚可；显式披露了部分限制（如 run receipt 只统计 token 不统计成本、final_answer instructions 在默认 Lite 模式被忽略、supervisor 答案不做 shaping）。但关键项存在告知缺口：许可证未明确、server manifest 未缓存、成本/限额与故障排查覆盖不均，且许多细节依赖外部站点而非可在此审阅的内容，故未达更高档。
安装易用性 9/20: 提供明确的入门步骤：git clone、uv venv --python=3.12、uv sync、写入 .env、cuga start demo_crm --read-only，并给出多个可选路径（沙箱、E2B、supervisor、knowledge、skills、Helm）。平台兼容性与容器运行时（Rancher Desktop/Docker/E2B CLI/ngrok）等前置条件带来一定复杂度，且混合/浏览器模式需额外安装 Chromium 与浏览器扩展。静态证据未包含可核验的安装验证输出或 CI 配置正文，按校准上限 15，并因多分支、多依赖、非单一步骤的脆弱性扣分。

静态评测 · 未实际运行收录于 2026-09-10

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件写入 / 删除本地文件执行命令或代码访问网络控制浏览器连接数据库

适合谁

需要可治理、可审计策略的企业智能体团队
希望复用通用智能体而只配置领域工具与策略的开发者
需要同时操作 Web 页面与 API 的混合任务场景
使用 Python SDK 或自托管 Kubernetes 的团队

不适合谁

只需要单一简单工具调用的轻量场景
无法提供任何 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+ · Node.js · Docker

OPENAI_API_KEY 必填密钥 OpenAI API 密钥，在 platform.openai.com 的 API keys 页面创建。

WATSONX_API_KEY 可选密钥 IBM WatsonX API 密钥，在 IBM WatsonX 项目/空间中获取。

AZURE_OPENAI_API_KEY 可选密钥 Azure OpenAI 服务的 API 密钥，来自 Azure 门户。

GROQ_API_KEY 可选密钥 Groq 平台密钥，在 console.groq.com/keys 生成。

OPENROUTER_API_KEY 可选密钥 OpenRouter 网关密钥，在 openrouter.ai 账户设置中获取。

RITS_API_KEY 可选密钥 IBM 内部 RITS 推理平台的密钥，需向 RITS 平台管理员索取。

WXO_API_KEY 可选密钥 watsonx Orchestrate 租户 API 密钥，在 Settings -> API details 中生成。

E2B_API_KEY 可选密钥 E2B 云沙箱密钥，在 e2b.dev/dashboard 创建（仅 E2B 沙箱模式需要）。

其他可选配置项（1 个）

AGENT_SETTING_CONFIG 可选选择 LLM 配置文件（如 settings.openai.toml、settings.watsonx.toml），无需凭据。

确认已安装 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。

验证是否装好

运行 `cuga start demo_crm --read-only` 后访问 https://localhost:7860，向 agent 发送 'from contacts.txt show me which users belong to the crm system'；若 find_tools 和 load_skill 出现在可用工具列表且能返回工具/技能内容，说明运行正常。

常见排障

启动失败时确认 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 设置

试试这样问

连接成功后，可以直接对 AI 助手这样说：

帮我找一个能发送邮件的工具
列出你当前可用的技能并加载相关的那个
从 contacts.txt 显示属于 CRM 系统的用户
从数字销售获取收入最高的客户并添加到当前页面

工具能力 2

load_skill 只读

按需加载匹配任务的 SKILL.md 技能完整指令内容。

find_tools 只读

在大型工具目录中检索并列出与当前任务相关的可用工具。

使用场景

在企业环境中编排跨 Web 与 REST API 的复杂任务

通过 mcp_servers.yaml 接入自建 MCP 服务器与 OpenAPI 服务

用策略系统与人类在环审批约束智能体行为

构建多智能体监督架构并向 A2A 远程智能体委派任务

基于内部文档构建 RAG 知识库问答

将领域工作流打包为 SKILL.md 技能按需加载

支持客户端

CUGA SDK

MCP部分支持

依据项目文档列出，未经本站实测。

详细介绍

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 部署方案。