CUGA
An enterprise generalist-agent harness for combining APIs, MCP, browser actions, and policy-governed execution.
- Source repo
- cuga-project/cuga-agent
- Stars
- ★ 1.1k
- Last updated
- 2d ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 51/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesOpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- An enterprise application developer needs one execution layer for existing REST APIs, MCP servers, and Python LangChain functions.
- Not a fit if
- Teams unwilling to verify licensing terms themselves, since the repo license is NOASSERTION
- Users wanting a zero-config experience without model keys and dependency setup
- Source review
- 51/100 · Major gaps
What does this agent do, and when should you use it?
CUGA is a configurable enterprise generalist-agent harness whose SDK centers on CugaAgent and the multi-agent CugaSupervisor. It connects OpenAPI specifications, MCP servers, and LangChain tools, and offers API, web, and hybrid task modes; hybrid mode combines Playwright and a browser extension with tool execution. CugaAgent runs work through invoke or stream and supports session isolation through thread_id. Its built-in knowledge base ingests documents through Docling and its policy system includes Intent Guard, Playbook, Tool Approval, Tool Guide, and Output Formatter. The project can be embedded as a Python library, run through local demos and a management/publishing UI, or self-hosted on Kubernetes with Helm.
Developers create CugaAgent(tools=[...]) with LangChain tools or configure OpenAPI and MCP services in mcp_servers.yaml. After await agent.invoke(message), the agent plans and executes configured tool or web tasks; agent.stream() exposes execution in real time. With knowledge enabled, agent.knowledge.ingest() accepts PDFs, Office files, HTML, Markdown, images, and other Docling-supported inputs, while agent.knowledge.search() and injected knowledge tools retrieve them. CugaSupervisor coordinates local CugaAgent instances or remote agents configured through A2A and can pass variables between agents. Manage mode lets teams edit tools, MCP servers, LLM selection, and policies as a draft, test them in draft chat, then publish a versioned configuration.
- An enterprise application developer needs one execution layer for existing REST APIs, MCP servers, and Python LangChain functions.
- A CRM or operations team needs a task to query a business API and then add the result to the current browser page.
- A team handling sensitive business actions needs Tool Approval to obtain a human decision before a tool runs.
- An internal-assistant builder needs to search PDFs, Office files, HTML, or Markdown while separating permanent agent knowledge from per-conversation uploads.
- An automation team needs a supervisor to delegate CRM lookup and email-sending work to local or A2A-connected remote agents.
- A platform team wants to self-host an agent stack on Kubernetes and supply deployment secrets through Kubernetes Secrets.
How do you install or deploy this agent?
Prerequisites are Python 3.12+ and uv. Run:
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-onlyThis quick-start path requires an OpenAI API key. The documented alternatives are WatsonX, Azure OpenAI, Groq, OpenRouter, RITS, and LiteLLM through an OpenAI configuration with an overridden base URL.
How do you use this agent?
For the minimum SDK flow, create CugaAgent(tools=[...]), run await agent.invoke("your task"), and read result.answer. For document retrieval, use CugaAgent(enable_knowledge=True) and call await agent.knowledge.ingest("/path/to/file.pdf"). For multi-agent work, construct CugaSupervisor(agents={...}) and call await supervisor.invoke("your task"). For browser-only or combined API/browser tasks, set mode = 'web' or mode = 'hybrid' under [advanced_features] in settings.toml; hybrid mode also requires playwright install chromium and the browser extension.
What are this agent's strengths and limitations?
- It explicitly supports three tool-integration paths in one harness: OpenAPI, MCP, and LangChain.
- API, web, and hybrid modes are documented, with hybrid workflows combining Playwright browser interaction and API/tool calls.
- The policy system has five concrete policy types and includes Tool Approval gates for human review.
- Its knowledge engine ingests several file types through Docling and separates durable agent-scoped material from thread-scoped session material.
- CugaSupervisor can coordinate local sub-agents and A2A remote agents while passing variables between them.
- Quick start requires Python 3.12+, uv, and credentials for a configured model provider; the example defaults to an OpenAI API key.
- Hybrid browser tasks add setup requirements for Playwright, Chromium, and a browser extension.
- Default local Python execution offers less isolation; Docker/Podman sandboxing requires an additional dependency group and a container runtime.
- The E2B cloud-sandbox path requires an E2B API key, an E2B template, extra dependencies, and a public tunnel such as ngrok for the local registry.
- Repository metadata lists the license as NOASSERTION, so adopters need to establish acceptable licensing terms independently.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| CUGA This agent | 51 · Major gaps | CLIFree + model costs | ★ 1.1k | 2d ago | Python | OpenAI API |
| Dive into LangGraph | 69 · Some gaps | Library / SDKFree + model costs | ★ 468 | 1mo ago | Jupyter Notebook | Claude Code |
| ReachAI Enterprise Agent Platform | 60 · Some gaps | Self-hosted serviceFree + model costs | ★ 1k | 2d ago | Java | OpenAI API |
| AI Agent Engineering Textbook | 55 · Major gaps | FrameworkFree | ★ 651 | 13d ago | HTML | — |
How does FollowAgents rate this agent?
Why each dimension lost points
least_privilege: Evidence shows policy system (Intent Guard, Tool Approval) and sandbox modes, but no explicit default least-privilege principle; permissions depend on configuration, so 1. user_confirmation: Explicit HITL approval gates and api_planner_hitl config, well-evidenced, so 2. data_flow_transparency: Trajectory visualization and published version tracking exist, but no explicit data flow transparency mechanism, so 1. sensitive_data_handling: API key management (.env, Kubernetes secrets) and policies exist, but no detailed sensitive data handling measures, so 1. dependency_security: Extensive security fix comments and version constraints in pyproject.toml (e.g., aiohttp>=3.14.3, cryptography>=50.0.0), well-evidenced, so 3. external_effects: Browser extension and API calls exist, but no explicit control measures for external effects, so 1. rollback: Published version tracking and roll forward capability, but no explicit rollback mechanism, so 1. source_attribution: LICENSE clearly lists third-party code sources (BrowserGym, browser-use, LangChain), so 2.
self_consistency: README and pyproject.toml descriptions align, version 0.3.1, features match, so 2. dependency_availability: Complete dependency list with version constraints, but no lock file or image availability evidence, so 2. failure_messages: Error handling code exists (e.g., Invalid last_n in variables manager), but not systematic, so 1.
audience_and_scenarios: Clearly targets enterprise, provides multiple scenarios (web, API, hybrid, HITL), so 2. capability_boundaries: Policy system defines boundaries, but no explicit default limits, so 2. trigger_precision: Natural language triggers (playbook) and skill loading exist, but no explicit trigger precision control, so 1. environment_fit: Supports multiple LLM providers and deployment methods (Kubernetes, Docker), so 2.
information_architecture: README well-structured with TOC and feature tables, so 2. install_notes: Quick Start and detailed configuration provided, so 2. naming_stability: Version 0.3.1, but no explicit naming stability policy, so 1. examples_and_faq: Multiple examples (SDK, demo), but no FAQ, so 2. known_limitations: Experimental features marked (save_reuse), but no systematic limitations list, so 1. license: LICENSE file is Apache-2.0, but metadata is NOASSERTION, so 2. versioning_changelog: Version number exists, but no CHANGELOG file, so 1. maintenance_responsibility: GitHub Actions and release workflow exist, but no explicit maintenance responsibility, so 1.
output_usability: SDK and CLI provided, output format documented, so 2. marginal_value: Multiple integrations and policies, clear value, so 2. cost_benefit: Benchmark performance claims, but no cost analysis, so 1.
claim_traceability: Benchmark links provided, but no reproduction method, so 1. cross_source_corroboration: External links (AppWorld, WebArena) exist, but not independently verified, so 1. fact_inference_separation: Documentation distinguishes features and experimental labels, but not explicit fact vs inference, so 1.
- Dependency security is good, but note the risk acceptance of graphql-core pre-release.
- Publisher identity is unverified; treat with caution.
- Static review cannot verify benchmark performance claims.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
What's Changed * fix(knowledge): restore SDK automatic RAG citations by @sami-marreed in https://github.com/cuga-project/cuga-agent/pull/915 * docs(contributing): accurately describe the PR templates by @ShryukGrandhi in https://github.com/cuga-project/cuga-agent/pull/1010 * fix(cli): list all services in start/stop/status help and support status demo_knowledge by @ruben-salas20 in https://github.com/cuga-project/cuga-agent/pull/983 * docs(config): correct cuga-apps MCP server descriptions by @ShryukGrandhi in https://github.com/cuga-project/cuga-agent/pull/1011 …View on GitHub ↗ -
Release notes excerpt
What's Changed * chore: move internal notes and small config files out of the repo root by @segevshlomovIBM in https://github.com/cuga-project/cuga-agent/pull/967 * fix(deps): address open Dependabot alerts (docling, langgraph-sdk, datasets, shell-quote, and others) by @haroldship in https://github.com/cuga-project/cuga-agent/pull/971 * docs(readme): modernize enterprise automation overview by @sami-marreed in https://github.com/cuga-project/cuga-agent/pull/913 * docs(readme): link apps harness kit and Discord by @sami-marreed in https://github.com/cuga-project/cuga-agent/pull/974 …View on GitHub ↗ -
Release notes excerpt
Summary Release v0.4.0 is a large feature release. CUGA now supports multi-agent work through a new supervisor runtime with an agent registry and a composition UI. The full CugaAgent graph is retired; CugaLite and CugaSupervisor are the two supported agents. Event-driven agents arrive with channels, triggers and NL→Flow arming, including WhatsApp as a direct channel. The supported container image now includes an experimental memory workspace built on Evolve, with retention controls and a management API. CUGA can also run over the Agent Client Protocol (ACP) via stdio. We welcome first-time …View on GitHub ↗