CUGA: an enterprise agent harness you configure instead of build

The build-versus-configure problem CUGA targets

The README frames the problem directly: building a domain-specific enterprise agent from scratch means writing agent and tool orchestration, planning logic, safety and alignment policies, and evaluation for performance and cost tradeoffs. CUGA's answer is to ship the generalist part and leave the domain part to configuration. The intended user is a platform or integration team that already owns HTTP APIs or MCP servers and wants an agent in front of them without writing a planner. The README's own framing is "Start with a generalist. Customize for your domain." That is a specific bet: the orchestration is treated as commodity, and the tools, policies and workflow are treated as the differentiator. If your value is in a novel planning algorithm, this harness is the wrong layer to start from. If your value is in the ten internal services the agent has to call correctly, it fits.

How tools get in: OpenAPI specs, MCP servers, LangChain

Tool ingestion is the mechanism the rest of the harness hangs off. The README lists three routes: OpenAPI specs, MCP servers declared in src/cuga/backend/tools_env/registry/config/mcp_servers.yaml, and LangChain tools passed in Python via CugaAgent(tools=[...]). That is a registry, not a plugin protocol you implement. The practical consequence is that the quality of your OpenAPI descriptions becomes the quality of the agent's tool selection, because there is no separate hand-written tool schema layer described in the material. MCP entries are YAML, so adding a server is a config edit rather than a code change, which is the main reason to prefer this over assembling a framework yourself. The README also states that CUGA can be exposed as a tool to other agents, which is how nested reasoning and multi-agent collaboration are described. Treat that as an architectural claim from the documentation rather than something the README demonstrates with a worked example.

Code generation profiles and the accuracy cost curve

CUGA's execution model is code-act style: the agent writes code that calls your tools rather than emitting one tool call per turn. The README exposes this as three profiles, fast, balanced and accurate, selected through [features] cuga_mode in src/cuga/settings.toml, with the mode definitions living under configurations/modes/. This is the most interesting design decision in the project, because it turns the usual accuracy-versus-latency tradeoff into a config key you can change per deployment instead of a rewrite. The limitation is equally clear: the README does not state what each profile changes internally, so you are choosing between three named settings whose behaviour you have to observe yourself. Budget controls sit alongside this. The [advanced_features] section carries max_tool_calls_per_block, max_tool_calls_per_run and max_tool_calls_per_thread, and reflection_enabled toggles a reflection step. Those three budgets are the practical guardrail against a code-generating agent looping on a flaky endpoint, and they are the first thing to tune after the mode.

Policies, approval gates and where the harness stops

The policy layer is what separates CUGA from a bare agent loop. The README names five policy types: Intent Guard, Playbook, Tool Approval, Tool Guide and Output Formatter, configurable through the Policies SDK or a standalone UI in demo mode, with human-in-the-loop approval gates described as part of the design. Read the names literally. Tool Approval is an interception point before a call executes, Intent Guard is a check on what the user is asking for, and Output Formatter shapes what comes back. That is a governance surface, and it is the part an enterprise reviewer will actually read. The honest limitation is that the README describes the policy types but does not document their evaluation order or what happens when two policies conflict. Until you read the Policies SDK documentation, assume the composition semantics are unspecified and test them. The other boundary is the events service: the README says event-driven agents run as a second service beside CUGA on ports 7860 and 8100, and that CUGA itself is unchanged when that service is not deployed. So triggers, cron and Slack or Discord connectors are an adjacent deployment, not a feature of the core runtime.

Getting it running: the actual commands and config keys

The README's entry points are the cuga CLI and the Python SDK. For a first look, cuga start demo brings up the demo, and cuga start manager opens the web UI where you draft tools, MCP servers, LLM settings and policies and then publish a versioned config for production chat. For the more specialised demos the README lists cuga start demo_knowledge, cuga start demo_skills and cuga start demo_supervisor for the multi-agent CugaSupervisor path. Agent skills are SKILL.md files under .cuga/skills by default, discovered by the agent and loaded on demand through a load_skill tool; demo_skills runs with sandbox_mode set to native by default, with opensandbox as the alternative, and demo --sandbox turns skills on through the [skills] section. Knowledge is on by default via enable_knowledge=True and ingests PDFs, Office files, HTML and Markdown through Docling, with agent-level and session-level scopes. Hybrid API plus browser work is switched on with [advanced_features] mode = 'hybrid', which pulls in Playwright and a browser extension. Python 3.12 is the stated requirement. Self-hosting is a Helm chart and deploy scripts under deployment/, with the Kubernetes guide covering local kind or minikube and registry push for cloud clusters.

What the material does not settle

Several things a reviewer needs are absent. The licence field on the repository reads NOASSERTION, which means the metadata does not resolve to a recognised identifier; the README does not name a licence either. For a component that sits next to internal APIs and handles credentials for MCP servers, that is a blocker to resolve before adoption, not a footnote. The README also does not state a Python dependency footprint, so the cost of pulling in Playwright, Docling and the frontend workspaces is unknown from this material. On maintenance, the release cadence visible in the supplied data is v0.3.0 in June 2026, v0.3.1 in August and v0.3.2 later in August, with the last push in September 2026. Three point releases in roughly three months on a 0.x line means the configuration surface, including settings.toml keys and the modes directory, is still moving. Anyone pinning to a version should expect to re-read the release notes on each bump rather than assume the keys are stable.

The alternative: LangGraph or a hand-rolled loop

The obvious comparison is a general agent framework such as LangGraph, where you define the graph, the state and the control flow yourself and bring your own policy layer. The difference is where the work lands. With LangGraph you write the orchestration and get exact control over retries, branching and state; with CUGA the README's claim is that orchestration, planning, tool budgets and policy types are already there, and your work moves into mcp_servers.yaml, settings.toml and the policies you author. That trade is real in both directions. A hand-rolled loop gives you a dependency tree you can audit line by line; CUGA gives you a manager UI and a published config artifact, which is a different kind of operational maturity. If your team already has a graph-based agent in production and only needs better tool governance, adding CUGA's policy SDK to the existing loop is a smaller change than replacing the runtime. If you have no orchestration at all and your tools are already described by OpenAPI, the harness saves the largest chunk of work.

Who should take this on, and what to check first

CUGA fits teams with a concrete tool surface (OpenAPI specs or MCP servers), a Python 3.12 runtime, and a compliance requirement that shows up as approval gates rather than as a written policy document. It does not fit teams that need a small library to embed in an existing service, teams that cannot accept a 0.x config surface that changed three times in three months, or anyone who needs the licence question answered before the first commit. Three things to verify before committing. First, run cuga start manager, publish a config, and confirm the published artifact is something your deployment pipeline can consume. Second, set max_tool_calls_per_run to a number you can defend and check that the accurate mode in [features] cuga_mode stays inside it on your slowest API. Third, read the licence text behind the NOASSERTION field and the dependency list that Playwright, Docling and the browser extension bring in, because those are the parts you inherit permanently.

Editorial conclusion

Adopt CUGA if you have a set of REST or MCP services and want a prebuilt planner-executor runtime with policy gates and a versioned config you can publish. Do not adopt it if you need a small embeddable library or a permissively licensed dependency you can vendor without review: the licence field reads NOASSERTION, so check the actual licence text and the transitive dependency set before shipping. Verify first that your tool surface survives the code generation path, that the tool-call budgets in settings.toml match your cost ceiling, and that the sandbox backend you intend to use (native or opensandbox) is the one your deployment can actually run.

Official sources

1. cuga-project/cuga-agent on GitHub
2. Issues
3. Project website
4. README
5. Releases