CUGA Generalist Agent Harness

Community

A configurable generalist agent harness for the enterprise

★ 876 Stars Category · Other Very popular

49FMRS · D

CUGA is an open-source generalist agent harness focused on enterprise governance: policy system, sandboxed execution, multi-agent supervision, and a knowledge engine. It can act as an MCP client and be exposed to other agents as MCP, making it suited to teams that want to plug domain tools and policies into a generalist agent. Budget for your own LLM credentials and define sandbox and policy boundaries before use, since default local execution offers weaker isolation.

Reliability

8/20

Security and permissions

7/20

Maintenance

12/20

Documentation

13/20

Setup experience

9/20

Read the FMRS scoring method →

CUGA (Configurable Generalist Agent) is an open-source generalist agent harness for the enterprise, supporting complex task execution on the web and over APIs. It integrates tools through OpenAPI specs, MCP servers, and LangChain, and ships with a composable architecture, selectable reasoning and code-generation modes (fast / balanced / accurate), API/web/hybrid task modes, multi-agent supervision via CugaSupervisor (including remote A2A agents), a five-type policy system (Intent Guard, Playbook, Tool Approval, Tool Guide, Output Formatter) with human-in-the-loop approvals, a built-in Docling-based RAG knowledge engine with agent- and session-level scopes, agent skills loaded on demand from SKILL.md files, tool-call budgets, reflection, and sandboxed code execution via Docker/Podman or E2B. It offers a Python SDK, a web manage-and-publish UI for versioned configuration, and a Helm chart for self-hosting on Kubernetes.

Tools

load_skill

Loads the full instruction body of a matching SKILL.md on demand when a task matches that skill.

find_tools

Searches a large tool catalogue and lists the tools relevant to the current task.

Setup

Ensure Python 3.12+ and the uv package manager are installed.
Clone and enter the repository: git clone https://github.com/cuga-project/cuga-agent.git && cd cuga-agent
Create and activate a virtual environment: uv venv --python=3.12 && source .venv/bin/activate
Install dependencies: uv sync
Configure model credentials, e.g. write OPENAI_API_KEY=your-key to .env and point AGENT_SETTING_CONFIG at the matching settings.*.toml.
Start a demo: cuga start demo_crm --read-only; Chrome opens at https://localhost:7860.
Optional: run cuga viz to inspect agent trajectories; configure custom tools and MCP servers in src/cuga/backend/tools_env/registry/config/mcp_servers.yaml.

Fit and risk

Best for

Enterprise agent teams that need governable, auditable policies
Developers who want a generalist agent they only configure with domain tools and policies
Hybrid workflows that must combine browser interaction with API calls
Teams using the Python SDK or self-hosting on Kubernetes

Not for

Lightweight scenarios that only need a single simple tool call
Offline users who cannot supply any LLM API key or self-hosted model
End users expecting zero-configuration out-of-the-box use

Required permissions

Reading the repository and local workspace files (e.g. files under cuga_workspace)
Network access to LLM providers, OpenAPI services, and MCP servers
In hybrid/web mode, controlling browser pages through the browser extension and Playwright
Accessing Docker/Podman or E2B cloud execution environments when sandboxing is enabled
In manage mode, drafting and publishing agent configuration (tools, MCP, LLM, policies)

Risks and side effects

The agent can call real APIs and act on web pages on the user's behalf, so mistakes can have real business impact
Misconfigured policies or sandboxes weaken isolation; local Python execution is the default and is less isolated
Exposing the local registry to E2B via tunnels such as ngrok increases the attack surface
The knowledge base and saved trajectories may contain sensitive enterprise data that you must store and access-control yourself
Runs against self-hosted or internal models, so token and cost accounting must be converted with your own rates

Troubleshooting

If startup fails, confirm Python 3.12+ and that uv sync completed
If model calls fail, check the API keys in .env and that AGENT_SETTING_CONFIG points at a matching TOML file
If E2B reports 'function_call_host not configured', set a public ngrok URL under server_ports in settings.toml
If sandboxing is unavailable, run cuga test-sandbox or cuga test-sandbox --remote to verify the environment
If skills are not discovered, check the [skills] root setting, confirm SKILL.md has name and description frontmatter, and restart the service to rescan
If a large tool catalogue makes prompts too long, adjust [shortlister] strategy and threshold settings

Use cases

Orchestrating complex tasks that span web pages and REST APIs in an enterprise setting

Connecting self-hosted MCP servers and OpenAPI services via mcp_servers.yaml

Constraining agent behaviour with policies and human-in-the-loop approvals

Building multi-agent supervision and delegating to remote A2A agents

Running RAG question answering over internal documents

Packaging domain workflows as SKILL.md skills loaded on demand

Supported clients

CUGA SDKFull support

MCPPartial support

Related MCP servers

Compare with other MCP servers