CUGA
面向企业的通用智能体框架，可组合 API、MCP、浏览器与策略执行复杂任务。
按维度查看评分与理由
least_privilege: 证据显示有策略系统（Intent Guard, Tool Approval）和沙箱模式（sandbox_mode），但未明确默认最小权限原则，权限控制依赖配置，故1分。user_confirmation: 明确支持HITL（human-in-the-loop）审批门，有api_planner_hitl配置，证据充分，故2分。data_flow_transparency: 有轨迹可视化（cuga viz）和发布版本追踪，但未明确数据流透明度的具体机制，故1分。sensitive_data_handling: 有API密钥管理（.env, Kubernetes secrets）和策略，但未明确敏感数据处理的详细措施，故1分。dependency_security: pyproject.toml中大量安全修复注释和版本约束，如aiohttp>=3.14.3, cryptography>=50.0.0等，证据充分，故3分。external_effects: 有浏览器扩展和API调用，但未明确外部影响的控制措施，故1分。rollback: 有发布版本追踪和回滚能力（roll forward），但未明确具体回滚机制，故1分。source_attribution: LICENSE中明确列出第三方代码来源（BrowserGym, browser-use, LangChain），故2分。
self_consistency: README和pyproject.toml描述一致，版本号0.3.1，功能描述匹配，故2分。dependency_availability: 依赖列表完整，有版本约束，但未提供锁文件或镜像可用性证据，故2分。failure_messages: 有错误处理相关代码（如变量管理器的Invalid last_n），但未系统化，故1分。
audience_and_scenarios: 明确面向企业，提供多种场景（web, API, hybrid, HITL），故2分。capability_boundaries: 有策略系统定义边界，但未明确默认限制，故2分。trigger_precision: 有自然语言触发（playbook）和技能加载，但未明确触发精度控制，故1分。environment_fit: 支持多种LLM提供商和部署方式（Kubernetes, Docker），故2分。
information_architecture: README结构清晰，有目录和功能表格，故2分。install_notes: 提供Quick Start和详细配置说明，故2分。naming_stability: 版本号0.3.1，但未明确命名稳定性策略，故1分。examples_and_faq: 有多个示例（SDK, demo），但无FAQ，故2分。known_limitations: 有实验性功能标注（save_reuse），但未系统列出限制，故1分。license: LICENSE文件为Apache-2.0，但元数据为NOASSERTION，故2分。versioning_changelog: 有版本号，但无CHANGELOG文件，故1分。maintenance_responsibility: 有GitHub Actions和发布流程，但未明确维护责任，故1分。
output_usability: 提供SDK和CLI，输出格式有文档，故2分。marginal_value: 提供多种集成和策略，价值明显，故2分。cost_benefit: 有基准性能声明，但未提供成本分析，故1分。
claim_traceability: 有基准链接，但未提供复现方法，故1分。cross_source_corroboration: 有外部链接（AppWorld, WebArena），但未独立验证，故1分。fact_inference_separation: 文档中区分了功能描述和实验性标注，但未明确区分事实和推断，故1分。
- 依赖安全虽好，但需注意graphql-core预发布版本的风险接受。
- 发布者身份未验证，需谨慎对待。
- 静态审查无法验证基准性能声明。
这个 Agent 能做什么，适合哪些场景？
CUGA 是一个可配置的企业通用智能体框架，核心 SDK 包括 CugaAgent 和用于编排多个智能体的 CugaSupervisor。它可接入 OpenAPI、MCP 服务器和 LangChain 工具，并提供 API、Web 与混合任务模式；混合模式通过 Playwright 和浏览器扩展结合网页操作与工具调用。CugaAgent 可通过 invoke 或 stream 执行任务，并支持按 thread_id 隔离会话状态。内置知识库可用 Docling 摄取多种文档并进行检索，策略系统则提供 Intent Guard、Playbook、Tool Approval、Tool Guide 与 Output Formatter。项目既可作为 Python 库嵌入应用，也提供本地演示、管理发布界面和 Kubernetes Helm 部署路径。
开发者以 CugaAgent(tools=[...]) 创建智能体，向其提供 LangChain 工具，或通过 mcp_servers.yaml 配置 OpenAPI 与 MCP 服务。调用 await agent.invoke(message) 后，智能体会按配置规划并执行工具或网页任务；agent.stream() 可用于实时观察执行。启用知识功能时，可用 agent.knowledge.ingest() 摄取 PDF、Office、HTML、Markdown、图片等内容，再由 agent.knowledge.search() 或智能体自动注入的知识工具检索。CugaSupervisor 可协调本地 CugaAgent，或根据 A2A 配置调用远程智能体，并在智能体之间传递变量。管理模式允许将工具、MCP、模型和策略作为草稿测试后发布为版本化配置。
- 企业应用开发者需要把现有 REST API、MCP 服务和 Python LangChain 函数接入同一个任务执行层时。
- CRM 或运营团队需要在一次任务中查询业务 API，再通过浏览器扩展把结果写入当前网页时。
- 处理受控业务操作的团队需要用 Tool Approval 在工具执行前要求人工批准时。
- 需要让智能体检索内部 PDF、Office 文档、HTML 或 Markdown，并区分长期智能体知识与会话上传资料时。
- 需要由主管智能体把 CRM 查询和邮件发送等步骤分派给本地或 A2A 远程子智能体时。
- 计划在 Kubernetes 集群中自托管智能体，并通过 Helm 与 Kubernetes Secrets 配置部署凭据时。
这个 Agent 有哪些优点和局限？
- 同一框架明确支持 OpenAPI、MCP 与 LangChain 三类工具接入，覆盖 REST 服务、MCP 服务和 Python 函数。
- 提供 API、Web 和 hybrid 三种任务模式；hybrid 模式可将 Playwright 浏览器操作与 API 工具调用放在同一工作流中。
- 策略系统包含五种具体策略类型，并支持 Tool Approval 人工审批门槛。
- 知识引擎可通过 Docling 摄取多类文件，并区分智能体级长期资料与 thread_id 关联的会话级资料。
- 可通过 CugaSupervisor 编排本地子智能体和 A2A 远程智能体，并支持变量传递。
- 快速启动要求 Python 3.12+、uv 和至少一个已配置的模型提供商凭据；示例默认使用 OpenAI API 密钥。
- 混合网页任务依赖 Playwright、Chromium 和浏览器扩展，增加桌面浏览器环境配置成本。
- 默认本地 Python 执行的隔离较弱；Docker/Podman 远程沙箱需要额外安装 sandbox 依赖和容器运行时。
- E2B 云沙箱需要 E2B API 密钥、E2B 模板、额外依赖及 ngrok 等公网隧道来暴露本地工具注册表。
- 仓库元数据中的许可证为 NOASSERTION，采用前需要自行确认可接受的授权条件。
如何安装或部署这个 Agent？
前提是 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
echo "OPENAI_API_KEY=your-openai-api-key-here" > .env
cuga start demo_crm --read-only该快速启动路径需要 OpenAI API 密钥。模型也可改用 README 列出的 WatsonX、Azure OpenAI、Groq、OpenRouter、RITS，或通过 OpenAI 配置的 base URL 使用 LiteLLM。
如何使用这个 Agent？
最小 SDK 用法是创建 CugaAgent(tools=[...])，然后执行 await agent.invoke("任务描述") 并读取 result.answer。需要文档检索时使用 CugaAgent(enable_knowledge=True)，再调用 await agent.knowledge.ingest("/path/to/file.pdf")。多智能体场景用 CugaSupervisor(agents={...})，然后 await supervisor.invoke("任务描述")。网页或 API+网页任务可在 settings.toml 的 [advanced_features] 中设置 mode = 'web' 或 mode = 'hybrid'；混合模式还需执行 playwright install chromium 并启用浏览器扩展。