CUGA
An enterprise generalist-agent harness for combining APIs, MCP, browser actions, and policy-governed execution.
Per-dimension scores and reasoning
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.
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.
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 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.