CUGA
面向企业的通用智能体框架，可组合 API、MCP、浏览器与策略执行复杂任务。
这个 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 并启用浏览器扩展。